1. 从 Claude Code 源码看 Multi-Agent 派活为什么单 Agent 会把自己累死先说结论Claude Code 的多 Agent 设计本质上就是一套「老板带团队」的工程实现。你如果正在自己搭 Multi-Agent 系统或者想用 Claude Code 的 Subagent 机制做任务拆分这篇文章会给你一份能直接抄的配置骨架。单 Agent 干复杂任务问题特别明显。我拿一个真实场景举例你让它「调研 React 18 的 useTransition在项目里实现一个过渡动画然后做代码评审」。一个 Agent 从头做到尾会发生三件事。第一上下文爆炸——调研阶段的文档、实现阶段的代码细节、评审阶段的挑错清单全塞在一个对话历史里到后面它自己都记不清前面查了什么。第二角色混乱——它一边调研一边开始写代码写到一半又回头翻文档效率极低。第三没法并行——调研的时候代码和测试只能干等。Claude Code 的解法不是搞一个更聪明的单 Agent而是拆成「一个老板 Agent 一堆专家 Subagent」。老板负责拆任务、派活、收结果、做决策Subagent 负责各自领域的执行。源码里这套机制分三层常规 Subagent父子型派完就回来、Fork Subagent派一个字节级克隆的分身复用缓存省钱、Coordinator 模式老板彻底不干活纯当项目经理带一帮 Worker 并行冲锋。这篇文章不讲空理论。我会先带你看懂这三种派活模式的源码逻辑然后重点交付两样东西一份可复制的settings.json和config.toml骨架以及通过 TaoToken 统一 Key 接入 Claude Code 的完整配置步骤。最后给你一套验证 Subagent 调用链是否真正生效的具体动作包括怎么在日志里确认 Fork 缓存命中了、怎么确认 Coordinator 的 Worker 是并发而不是串行。适合谁看想复刻多智能体协作的开发者、正在用 Claude Code 但只会单 Agent 干活的人、以及需要给团队搭一套统一 API 通道的工程师。前置知识只需要你会改 JSON 配置文件、能跑命令行就行。2. TaoToken 前置准备统一 Key 打通 Claude Code 的 API 通道在配 Subagent 之前得先把 API 通道理顺。Claude Code 默认走 Anthropic 官方通道但如果你要跑多 Agent尤其是 Coordinator 模式下同时派十几个 WorkerKey 的管理和成本控制就成了问题。TaoToken 在这里的作用是提供一个统一的 API 入口你只需要一个 Key就能让主 Agent 和所有 Subagent 走同一条通道不用每个 Agent 单独配 Key。先拿 Key。打开 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册后在控制台里找到 API Keys 页面创建一个新 Key。这个 Key 就是后面所有配置里要填的东西。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Keys 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。拿到 Key 之后你需要确认两件事。第一Base URL 填什么。TaoToken 的 API 端点是https://taotoken.net/api注意这个地址不带 UTM 参数直接写进配置就行。第二Model ID 填什么。Claude Code 默认用claude-sonnet-4-20250514这类模型 ID你在 TaoToken 的模型列表里找到对应的 Claude 系列模型 ID填进去。这三个东西——Base URL、Key、Model ID——就是后面所有配置的核心三件套缺一不可。为什么多 Agent 场景下统一 Key 特别重要因为 Coordinator 模式下主 Agent 会并发派出多个 Worker每个 Worker 都是一次独立的 API 请求。如果每个 Worker 用不同的 Key你没法统一看调用量、没法统一限流、也没法统一做成本核算。用 TaoToken 统一 Key 之后所有 Subagent 的请求都走同一个入口你在控制台里能看到总的调用次数和 Token 消耗排查问题也方便——哪个 Worker 报错了日志里一眼就能看到。还有一个实际的好处Fork Subagent 依赖 Prompt 缓存来降成本而缓存命中的前提是请求前缀字节级一致。如果主 Agent 和 Fork 走的是不同通道、不同 Key缓存策略可能不一致命中率会掉。统一走 TaoToken 之后通道一致缓存行为也可预期。配置之前建议先确认你的 Claude Code 版本。跑claude --version看一下建议用 1.x 以上的版本Subagent 和 Fork 相关的配置项在旧版本里可能不存在。另外如果你之前配过 Anthropic 官方通道先把旧的ANTHROPIC_API_KEY环境变量清掉避免冲突。可以用echo $ANTHROPIC_API_KEY检查一下有输出就先unset掉。3. 可复制配置settings.json 与 config.toml 骨架这一节是全文的核心直接给你能抄的配置。Claude Code 的配置分两块一块是settings.json管 Agent 定义、工具权限、Subagent 行为另一块是config.toml管 API 通道和模型参数。两个文件配合使用。先看settings.json。这个文件一般放在项目根目录的.claude/文件夹下路径是.claude/settings.json。如果你要全局生效放在~/.claude/settings.json。骨架如下{ apiProvider: custom, apiKey: sk-你的TaoTokenKey, baseUrl: https://taotoken.net/api, model: claude-sonnet-4-20250514, agents: { researcher: { description: 负责调研和技术方案搜索, prompt: 你是一个技术调研专家负责搜索代码库和文档输出结构化的调研结论。, tools: [Read, Grep, Glob, WebSearch], model: claude-sonnet-4-20250514 }, implementer: { description: 负责代码实现, prompt: 你是一个实现工程师根据调研结论写代码不负责评审。, tools: [Read, Write, Edit, Bash], model: claude-sonnet-4-20250514 }, reviewer: { description: 负责代码评审, prompt: 你是一个严格的代码评审员只挑错不改代码。, tools: [Read, Grep], model: claude-sonnet-4-20250514 } }, subagent: { enableFork: true, forkCacheStrategy: prefix-match, maxDepth: 3, asyncByDefault: false }, coordinator: { enabled: true, maxWorkers: 10, parallelLaunch: true } }这里有几个关键点要解释。apiProvider设为custom表示走自定义通道配合baseUrl指向 TaoToken。agents里定义了三个 Subagentresearcher、implementer、reviewer每个都有自己的tools白名单。注意 researcher 没有Write和Editreviewer 连Bash都没有——这就是源码里说的「工具箱分级发放」防止 Subagent 越权。subagent.enableFork打开 Fork 机制forkCacheStrategy设为prefix-match表示按前缀匹配复用缓存。maxDepth设为 3防止 Subagent 无限嵌套派活。coordinator.enabled打开 Coordinator 模式maxWorkers限制最多 10 个并发 WorkerparallelLaunch打开并行派发。再看config.toml。这个文件一般放在~/.claude/config.toml或者项目级的.claude/config.toml。骨架如下[api] provider custom base_url https://taotoken.net/api api_key sk-你的TaoTokenKey timeout 120 [model] default claude-sonnet-4-20250514 max_tokens 8192 temperature 0.7 [subagent] enable_fork true fork_cache_strategy prefix-match max_depth 3 async_by_default false [coordinator] enabled true max_workers 10 parallel_launch true synthesize_mode strict [cache] enable_prompt_cache true cache_ttl 300config.toml和settings.json有重叠的部分实际使用时以settings.json为准config.toml作为补充。cache.enable_prompt_cache打开 Prompt 缓存这是 Fork Subagent 省钱的关键。coordinator.synthesize_mode设为strict表示老板必须自己合成结果不能直接转发 Worker 的输出。如果你用的是 Cline 或者 CC Switch 这类工具配置方式略有不同。Cline 的 MCP 配置里Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填claude-sonnet-4-20250514。CC Switch 的话在它的配置文件里把 provider 指向 TaoToken 的端点就行。Codex 的auth.json里api_key字段填 TaoToken Keybase_url填https://taotoken.net/api。配好之后跑一下claude config validate确认配置格式没问题。如果有报错大概率是 JSON 语法问题或者 Key 没填对。4. 验证请求确认 Subagent 调用链真正生效配置写完不代表生效得验证。这一节给你一套具体的验证动作从简单到复杂一步步确认 Subagent 调用链是通的。第一步验证基础 API 通道。跑一个最简单的请求确认 TaoToken 通道能通curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的TaoTokenKey \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复 OK}] }如果返回里有content字段且内容是OK说明通道没问题。如果返回 401说明 Key 不对如果返回 404说明 Base URL 或路径不对。第二步验证 Subagent 是否被正确加载。在 Claude Code 里跑claude agents list你应该能看到 researcher、implementer、reviewer 三个 Agent。如果列表是空的说明settings.json里的agents字段没被读到检查文件路径和 JSON 格式。第三步触发一次 Subagent 调用。在 Claude Code 对话里输入请派 researcher 去调研一下当前项目里有没有用到 useTransition然后让 reviewer 检查调研结论。观察输出。如果 Subagent 生效你会看到 Claude Code 先调用 researcher等它返回后再调用 reviewer。日志里会出现类似task-notification的 XML 结构这就是源码里说的「完成通知伪装成用户消息」。第四步验证 Fork 缓存命中。跑一个会触发 Fork 的任务比如「生成 PR 描述」。然后在 TaoToken 控制台的调用日志里看这次请求的缓存命中情况。如果cache_read_input_tokens有值且接近 System Prompt 的长度说明缓存命中了。如果这个值是 0说明 Fork 没生效或者前缀不一致。第五步验证 Coordinator 并行。输入一个需要并发的大任务请用 Coordinator 模式同时派 3 个 Worker 分别调研 src/auth、src/api、src/utils 三个目录的代码结构然后合成一份报告。观察日志里的时间戳。如果三个 Worker 的启动时间几乎相同说明是并行派发如果是一个接一个说明parallelLaunch没生效。另外看总耗时并行的话应该在 1 分钟左右串行的话要 3 分钟以上。第六步检查 Subagent 的工具权限是否被正确限制。让 researcher 尝试写文件请让 researcher 在项目根目录创建一个 test.txt。如果配置正确researcher 应该拒绝这个操作因为它没有Write工具。如果它真的创建了文件说明工具白名单没生效回去检查settings.json里 researcher 的tools字段。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置和验证过程中最容易踩的坑集中在这几类报错。我按出现频率从高到低排一下每个都给你排查路径。401 Unauthorized。这是最常见的。原因通常有三个Key 填错了、Key 过期了、或者 Key 前面多了空格。先检查settings.json和config.toml里的apiKey字段确认没有多余空格。然后去 TaoToken 控制台确认这个 Key 还在有效期内。如果都没问题用第 4 节的 curl 命令单独测一下 Key排除是 Claude Code 配置的问题还是 Key 本身的问题。local proxy failed。这个报错通常出现在你之前配过本地代理然后切到 TaoToken 通道时旧配置没清干净。检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY、ALL_PROXY这些有的话先unset掉。另外检查~/.claude/config.toml里有没有残留的proxy字段有的话删掉。Claude Code 的配置优先级是环境变量 项目级配置 全局配置所以环境变量里的代理设置会覆盖配置文件。reading choices 报错。这个通常出现在 API 返回格式不符合预期时。Claude Code 期望的响应格式里有choices字段OpenAI 兼容格式或者content字段Anthropic 格式。如果 TaoToken 返回的格式和 Claude Code 期望的不一致就会报这个错。排查方法用 curl 直接请求 TaoToken 的/v1/messages端点看返回的 JSON 结构。如果返回的是 Anthropic 格式有content字段那 Claude Code 的apiProvider要设为anthropic而不是custom。如果返回的是 OpenAI 格式有choices字段那apiProvider设为openai。OAuth 相关报错。如果你之前用 Claude Code 登录过 Anthropic 账号本地会存 OAuth token。切到 TaoToken 通道后这个 token 可能还在被使用导致冲突。解决方法找到~/.claude/目录下的auth.json或credentials.json把里面的 OAuth token 删掉或者直接重命名这个文件。然后重新用 API Key 方式配置。Subagent 不生效。配置里写了 agents 但调用时没反应。检查三件事第一settings.json的路径对不对项目级是.claude/settings.json全局是~/.claude/settings.json。第二JSON 格式有没有语法错误用python -m json.tool settings.json验证一下。第三Claude Code 版本是否支持 Subagent跑claude --version确认版本号。Fork 缓存不命中。cache_read_input_tokens一直是 0。原因通常是主 Agent 和 Fork 的 System Prompt 前缀不一致。检查settings.json里 Fork 相关的配置确认forkCacheStrategy设为prefix-match。另外确认主 Agent 和 Fork 用的是同一个 Model ID不同模型的缓存是分开的。Coordinator 并行变串行。parallelLaunch设为 true 但实际还是串行。检查maxWorkers是不是设得太小比如设成 1 就退化成串行了。另外确认 Claude Code 版本支持并行派发旧版本可能不支持这个特性。6. 从配置到落地把 Subagent 派活机制用起来配置跑通之后真正要思考的是怎么把这套机制用到实际工作里。我按三个场景给你落地建议。第一个场景代码调研。这是 Subagent 最直接的应用。主 Agent 收到「调研这个项目的认证模块」的任务后派 researcher 去搜代码researcher 返回结构化的调研结论主 Agent 再决定下一步。这里的关键是 researcher 的工具白名单要限制在Read、Grep、Glob这几个不要给它Write和Bash防止它乱改代码。第二个场景并行实现。一个大任务拆成多个独立子任务用 Coordinator 模式同时派多个 implementer。比如「给三个模块分别加日志」可以同时派三个 Worker 各改一个模块。这里要注意maxWorkers别设太大10 个左右比较合适太多的话 API 限流和成本都会成问题。第三个场景Fork 省钱。对于「生成 PR 描述」「做 post-turn 总结」这类需要继承主 Agent 完整上下文的任务用 Fork Subagent。它的 System Prompt 直接复用主 Agent 的缓存命中后成本降到 10%。但要注意Fork 不适合需要专业分工的任务比如专门搜代码的 researcher因为它的定制 prompt 无法复用缓存。最后说一个实际经验Subagent 的 prompt 要写得具体。不要写「你是一个助手」要写「你是一个技术调研专家负责搜索代码库和文档输出结构化的调研结论不负责写代码」。prompt 越具体Subagent 的行为越可控。另外maxDepth别设太大3 层足够了再深的话调用链太长排查问题很麻烦。如果你还没配 TaoToken 的 Key现在可以去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建一个。配好之后先跑第 4 节的验证步骤确认通道通了、Subagent 加载了、Fork 缓存命中了再开始跑实际任务。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content遇到配置问题可以先翻文档。如果你主要做长期编码和 Agent 任务可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。想先试试模型对话效果的话模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。