1. 为什么我最后用 Claude Code 搭 Deep Research 工作流
Deep Research 这个词现在被用得很泛，但真正落到工程上，它其实就是一个典型的 Agent 应用：接收一个模糊问题，自己拆解、自己检索、自己交叉验证、最后自己写出一份带引用的报告。过去我用过不少编排框架来做这件事，配置链路长、调试成本高，一个环节出错要翻好几层日志。后来我把整套流程搬到了 Claude Code 上，用它的 Agent 框架来做，核心就三样东西：commands、skills、subagent。这三样全是 Markdown 加少量 JSON，改起来跟改文档一样快。
Claude Code 在这里扮演的角色不是「代码补全」，而是一个能调用工具、能派发子任务、能读写文件的运行时。你给它一个/deep-research命令，它会按你写好的 workflow 一步步走：先澄清问题，再拆子主题，再并行派发检索任务，最后汇总成报告。整个过程你不需要盯着，它自己决定什么时候上网、什么时候读文件、什么时候调子代理。
这套东西适合谁？适合已经会用命令行、想让 AI 干「多步骤研究类」活的人。比如你要调研一个技术选型、整理一个行业的公开资料、给新项目做竞品分析，这些都属于 Deep Research 的范畴。它不适合那种一问一答的简单查询，那种直接对话就够了。
我先把结论放前面：Claude Code 的 Agent 框架之所以好用，是因为它把「编排」和「执行」放在同一个上下文里，skills 负责单步逻辑，subagent 负责并行分工，command 负责串流程。下面我一步步拆给你看，包括可复制的配置片段和一轮真实检索任务的验证过程。
2. TaoToken 前置准备：把 Base URL、Key、Model ID 三件套配好
在写 agent 配置之前，得先让 Claude Code 能稳定调用模型。我这边用的是 TaoToken 的接口，它兼容 Anthropic 的调用格式，所以 Claude Code 可以直接对接。你需要准备三样东西：Base URL、API Key、Model ID。这三件套缺一不可，后面所有配置都围绕它们展开。
Base URL 用https://taotoken.net/api，注意这个地址后面不加任何多余路径。API Key 去控制台生成，路径是 API Keys 页面。Model ID 填你实际要用的模型标识，比如claude-sonnet-4-5这类，具体以你账号里可用的为准。
先设置环境变量，这是最省事的方式，Claude Code 启动时会自动读取：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的key" export ANTHROPIC_MODEL="claude-sonnet-4-5"如果你不想每次开终端都 export，可以写进 shell 配置文件，比如~/.zshrc或~/.bashrc。写完之后source一下，再echo $ANTHROPIC_BASE_URL确认生效。
注意：Base URL 和 API Key 是两个独立的东西，别把 Key 拼到 URL 后面，那样会直接 401。Key 只放在
ANTHROPIC_API_KEY里。
如果你用的是 Claude Code 的 settings 文件方式，也可以在项目根目录建.claude/settings.json，把环境变量固化进去：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的key", "ANTHROPIC_MODEL": "claude-sonnet-4-5" } }这个文件的好处是跟着项目走，团队里其他人 clone 下来改一下 Key 就能用。实测下来，settings.json 的优先级比 shell 环境变量高，两个都配了以 settings 为准。
配好之后先别急着写 agent，先跑一个最小验证，确认模型能通。这一步很关键，很多人后面报错其实是 Key 或 Base URL 没配对，却以为是 agent 配置的问题。验证命令我放在第 4 节，你可以先跳到那里跑通再回来。
另外提一句，如果你后面要做长期编码或者跑 Agent 类的持续任务，可以考虑用 Coding Plan，额度更划算；只是临时验证模型通不通，用模型对话页面就够了。这两个入口我放在文末 CTA 里。
3. 可复制配置：command、skill、subagent 三件套怎么写
这一节是核心，我把三个层次的配置都给你，路径和原文保持一致，你直接复制到对应目录就能用。先看目录结构，这是整个项目的骨架：
claude-code-deep-research/ ├── .claude/ │ ├── skills/ │ │ ├── question-refiner/ │ │ │ ├── skill.json │ │ │ ├── instructions.md │ │ │ └── examples.md │ │ ├── research-executor/ │ │ │ ├── skill.json │ │ │ ├── instructions.md │ │ │ └── examples.md │ │ ├── got-controller/ │ │ │ ├── skill.json │ │ │ ├── instructions.md │ │ │ └── examples.md │ │ ├── citation-validator/ │ │ │ ├── skill.json │ │ │ ├── instructions.md │ │ │ └── examples.md │ │ └── synthesizer/ │ │ ├── skill.json │ │ ├── instructions.md │ │ └── examples.md │ └── commands/ │ ├── deep-research.md │ ├── refine-question.md │ ├── plan-research.md │ ├── validate-citations.md │ └── synthesize-findings.md3.1 command：定义整个 workflow 的入口
command 就是你在 Claude Code 里敲/deep-research时触发的东西。它负责告诉 AI「按什么顺序、调哪些工具、用哪些 skill」。文件放在.claude/commands/deep-research.md：
--- description: 对指定主题执行完整的深度研究流程，从问题细化到最终报告生成 argument-hint: [研究主题或问题] allowed-tools: Task, WebSearch, WebFetch, Read, Write, TodoWrite --- # Deep Research Execute comprehensive deep research on the given topic using the 7-phase research methodology and Graph of Thoughts framework. ## Topic $ARGUMENTS ## Research Workflow ### Step 1: Question Refinement Use the **question-refiner** skill to ask clarifying questions and generate a structured research prompt. ### Step 2: Research Planning Break down the research topic into 3-7 subtopics and create a detailed execution plan. ### Step 3: Multi-Agent Research Deploy multiple parallel research agents to gather information from different sources: - Web Research Agents (3-5 agents): Current information, trends, news - Academic/Technical Agent (1-2 agents): Research papers, technical specifications - Cross-Reference Agent (1 agent): Fact-checking and verification ### Step 4: Citation Validation Use the **citation-validator** skill to rate each source A-E and verify claims. ### Step 5: Synthesis Use the **synthesizer** skill to produce the final report with full citations.这里allowed-tools是关键，它限定了这个 command 能调用的工具范围。Task用来派发 subagent，WebSearch和WebFetch用来上网，Read/Write用来读写文件，TodoWrite用来维护任务清单。你不需要把工具写全，按需给就行，给多了反而容易让 AI 乱调。
3.2 skill：单步逻辑的具体实现
skill 是每个步骤的「大脑」，它告诉 AI 这一步具体怎么做。以research-executor为例，.claude/skills/research-executor/skill.json：
{ "name": "research-executor", "description": "执行完整的 7 阶段深度研究流程。接收结构化研究任务，自动部署多个并行研究智能体，生成带完整引用的综合研究报告。当用户有结构化的研究提示词时使用此技能。", "version": "1.0.0", "entry": "instructions.md" }instructions.md里写具体的方法论，比如 Graph of Thoughts 的推理路径管理、7 阶段流程的每一步输入输出。这部分内容越长越细，AI 执行时越稳。我建议你把「什么算完成」「什么情况要重试」都写清楚，别指望 AI 自己猜。
3.3 subagent：并行分工的定义
当任务复杂到需要多个「AI 员工」同时干活时，就用 subagent。每个 subagent 有自己的角色、工具权限和输出格式。定义放在.claude/agents/下，比如一个 web 检索子代理：
--- name: web-researcher description: 负责从公开网页检索指定子主题的最新信息 tools: WebSearch, WebFetch, Read model: claude-sonnet-4-5 --- 你是一个专注的网页检索代理。收到一个子主题后： 1. 用 WebSearch 找到 5-8 个高相关来源 2. 用 WebFetch 抓取正文，提取关键事实和数据 3. 每条事实标注来源 URL 和抓取时间 4. 输出结构化 JSON：{subtopic, findings[], sources[]}subagent 的好处是并行，坏处是沟通成本。我自己的经验是：子主题之间如果高度独立，用 subagent 划算；如果互相依赖、需要频繁对齐，那还不如一个 agent 串行做。原文作者也提到他这里没上多 subagent，就是因为沟通成本，这个取舍你要根据任务来定。
提示：subagent 的
tools字段要收窄，检索代理只给检索工具，别给它 Write，否则它可能乱写文件。
4. 验证请求：跑一轮真实检索任务看输出
配置写完，先验证模型通不通，再验证 agent 跑不跑得起来。第一步用 curl 打一个最小请求：
curl https://taotoken.net/api/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "max_tokens": 128, "messages": [{"role": "user", "content": "回复两个字：通了"}] }'返回里能看到content数组和文本，就说明 Base URL、Key、Model ID 三件套没问题。如果这里就报错，先别往下走，去第 5 节对照排查。
模型通了之后，进 Claude Code 跑 command。启动后敲：
/deep-research 2024 年开源向量数据库的选型对比正常的话，AI 会先反问你几个澄清问题，比如「你更关注性能还是生态」「是否需要支持混合检索」。这一步就是question-refinerskill 在起作用。你回答完，它会进入 planning，把主题拆成 3-7 个子主题，然后开始并行检索。
我实测下来，一轮中等复杂度的研究，它会派发 4-6 个并行任务，每个任务调 3-5 次 WebSearch 加若干次 WebFetch。过程中你能看到 TodoWrite 维护的任务清单在实时更新。最后它会输出一份带引用的报告，每个来源有 A-E 的质量评级。
验证成功的标志有三个：一是报告里每条关键结论都有可点击的来源；二是来源评级不是清一色 A，有区分度；三是报告结构跟你在 skill 里定义的 7 阶段对得上。如果这三点都满足，说明你的 command、skill、subagent 三层是打通的。
如果你只是想先看看模型对话效果，不想配整套 agent，可以直接去模型对话页面试；要长期跑这类研究任务，再考虑 Coding Plan。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
这一节我按真实报错来对，你遇到哪个直接查哪个。
401 Unauthorized：九成是 Key 或 Base URL 的问题。先确认ANTHROPIC_API_KEY是不是完整的sk-开头，再确认ANTHROPIC_BASE_URL是https://taotoken.net/api而不是别的路径。如果两个都对还 401，检查 settings.json 里是不是有旧的 Key 覆盖了环境变量。
local proxy failed / connection refused：这个通常是你本地配了某个转发端口，但那个服务没起来。检查你的 shell 里有没有残留的HTTP_PROXY、HTTPS_PROXY环境变量，有的话先 unset 掉再试。Claude Code 直连taotoken.net/api就行，不需要中间层。
reading 'choices' of undefined：这个报错一般出现在你把 OpenAI 格式的响应解析套到 Anthropic 格式上。Anthropic 的返回是content数组，不是choices。检查你的调用代码或中间脚本，是不是混用了两套格式。用 curl 直接打的时候不会出现这个，出现基本是二次封装的问题。
OAuth / authentication failed：Claude Code 有时会走 OAuth 流程，如果你用的是 API Key 方式，确保没有同时启用 OAuth 登录态。清理一下~/.claude下的凭据缓存，重新用 Key 方式启动。
subagent 不触发：command 里写了Task工具但没派发子代理，通常是allowed-tools里漏了Task，或者 subagent 定义文件的name和 command 里引用的名字对不上。名字必须完全一致，大小写敏感。
skill 不生效：检查skill.json的entry指向的文件是否存在，以及instructions.md是不是空文件。skill 的description也很关键，AI 是靠 description 来判断「什么时候该用这个 skill」的，写得太泛它就不调。
排查顺序建议：先 curl 验证三件套，再跑单 command，再上 subagent。一层层来，别一上来就全套跑，出错你都不知道是哪层的问题。
6. 从 Deep Research 到通用 Agent：这套配置还能怎么用
Deep Research 只是这套框架的一个应用。你把 command 换掉、skill 换掉，同样的结构可以做很多事。比如全自动数据分析，核心也是 command 串流程、skill 写分析逻辑、subagent 并行处理不同数据源。命令可能就变成/do-more，但底层机制一模一样。
我自己的判断是：Claude Code 作为 Agent 框架，最大的优势是「编排即文档」。你不需要学一套新的 DSL，不需要记框架特有的 API，写 Markdown 就是在写 agent 逻辑。这对快速迭代特别友好，改一版 skill 就是改一个文件，不用重新编译、不用重启服务。
如果你要开始动手，建议从最小的 command 开始，先跑通一个单步 skill，确认模型调用没问题，再往上加 subagent。别一上来就抄一整套复杂配置，那样出错很难定位。先把/deep-research跑通一轮，再按自己的场景改 skill 里的方法论，这套东西就真正变成你自己的了。
需要 Key 和接入文档的，去 API Keys 页面生成，接入细节看接入文档；想先验证模型效果的，用模型对话；准备长期跑编码或 Agent 任务的，看 Coding Plan。三个入口按你的阶段选就行。
