1. 单 Agent 撞墙之后为什么需要子代理系统如果你已经用 Claude Code 写过一段时间代码大概率遇到过这种场景让它调研一个模块的认证逻辑它读了十几个文件然后你让它接着改代码它开始忘事——前面读过的文件路径记不清了改到一半又回头重新搜索。这不是模型变笨了而是单 Agent 模式的固有瓶颈。单 Agent 一次只能想一件事、做一件事。面对宽任务时问题会被放大串行阻塞让调研阶段你只能干等上下文污染让调研、实现、验证互相干扰每一步都在消耗同一个上下文窗口能力错配则更隐蔽——探索代码库只需要快速只读模型实现功能却需要强推理模型加全量工具权限单 Agent 只能选一套配置硬扛。Claude Code 的解法是子代理Subagent系统让主 Agent 像调用普通工具一样生出子 Agent每个子 Agent 拥有独立的对话循环、独立的上下文窗口、裁剪后的工具集甚至可以用不同的模型。这套系统里最值得拆的是三种协作机制——Fork、SwarmAgent Teams、Coordinator Mode它们分别对应分身组队编排三种拓扑。这篇指南面向多代理协作开发场景我会把三种机制的配置片段、统一 Key 接入步骤、以及可复现的验证动作都写清楚。你不需要改 Claude Code 源码只需要准备好配置文件和一个能统一管理模型调用的入口。我实测下来把 Key 接入这一步做扎实后面切换模型、跑并行任务会省掉大量重复配置的麻烦。先说清楚适合谁如果你只是偶尔让 Claude Code 补个函数单 Agent 够用但如果你在做跨模块重构、多假设调试、或者需要研究→实现→验证流水线的工程任务子代理系统能明显改变你的工作方式。下面从统一入口 AgentTool 讲起再逐个拆三种模式。2. TaoToken 前置统一 Key 接入与 settings.json 配置在动子代理之前得先把模型调用入口理顺。Claude Code 的子代理系统允许不同子 Agent 用不同模型——Fork 建议不换模型以复用 Prompt CacheExplore 默认走轻量模型实现类任务走强推理模型。如果每个模型都要单独配一套 Key 和 Base URL配置文件会迅速失控。TaoToken 在这里的角色是统一入口一个 Key、一个 Base URL背后可以路由到不同模型。这样你在 settings.json 里只需要维护一份凭证子代理切换模型时改 Model ID 即可。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数。接入分三步拿 Key、写配置、验证连通。先到控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在 API Keys 页面生成地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。生成的 Key 形如sk-开头的一串字符复制后先存到环境变量里别直接写进会提交到 Git 的文件。Claude Code 读取配置的优先级是环境变量 项目级.claude/settings.json 用户级~/.claude/settings.json。我建议把 Key 放环境变量把模型和 Base URL 放项目级配置这样团队协作时配置文件可以进版本库Key 不会泄露。环境变量这样设Linux/macOS 写进~/.zshrc或~/.bashrcWindows 用系统环境变量面板export TAOTOKEN_API_KEYsk-你的Key export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKEN$TAOTOKEN_API_KEY注意ANTHROPIC_BASE_URL不要带末尾斜杠也不要带 UTM 参数否则部分客户端会拼接出错误路径。设完执行source ~/.zshrc让配置生效然后用echo $ANTHROPIC_BASE_URL确认输出是https://taotoken.net/api。项目级settings.json负责声明模型和子代理行为。在项目根目录建.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key }, model: claude-sonnet-4-5, permissions: { allow: [Bash(git:*), Read, Grep, Glob], deny: [Bash(rm -rf:*)] }, subagents: { explore: { model: claude-haiku-4-5 }, implement: { model: claude-sonnet-4-5 } } }这里subagents字段是示意结构不同 Claude Code 版本字段名可能略有差异以你本地claude --version对应的文档为准。核心思路是Base URL 和 Key 全局统一模型按子代理角色分配。如果你用的是 Codex 系客户端配置落在~/.codex/auth.json结构是{ OPENAI_API_KEY: sk-你的Key, OPENAI_BASE_URL: https://taotoken.net/api }三件套记牢Base URL 填https://taotoken.net/apiKey 填控制台生成的sk-串Model ID 填你要用的模型名如claude-sonnet-4-5。这三样在任何客户端里都是必填项缺一个就会报认证或路由错误。配置写完先别急着跑子代理用一次最小请求验证连通。模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以在网页里直接发一条消息确认 Key 有效。命令行侧用 curl 验证curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-5,max_tokens:64,messages:[{role:user,content:ping}]}返回 JSON 里带content字段就说明链路通了。这一步过了再进子代理配置否则后面报错你分不清是 Key 问题还是子代理配置问题。3. 可复制配置Fork、Swarm、Coordinator 三套片段这一节给可直接粘贴的配置。三种模式互斥关系要先记住Coordinator 和 Fork 互斥开启 Coordinator 会自动禁用 ForkSwarm 是独立实验特性需要单独开关。3.1 Fork 配置共享 Prompt Cache 的轻量分身Fork 是默认路径——调用 AgentTool 时不指定subagent_type就走 Fork。它的核心是 Prompt Cache 共享所有 Fork 子 Agent 共享父 Agent 的完整 assistant 消息前缀字节完全一致只有最后一个 text 块携带各自指令。官方明确说Forks are cheap because they share your prompt cache。Fork 的配置重点在不要换模型。在settings.json里给 Fork 显式锁定与父 Agent 相同的模型{ subagents: { fork: { model: claude-sonnet-4-5, inheritContext: true, tools: [Read, Grep, Glob] } } }inheritContext: true表示继承父对话上下文。Fork 之间没有横向通信只向父进程返回结果字符串。运行时每个 Fork 有独立的消息历史、文件状态缓存、中断控制器和工具权限上下文互不干扰。调用 Fork 的 AgentTool 请求长这样{ name: Agent, input: { description: 并行搜索三个模块的认证逻辑, prompt: 在 src/auth、src/api、src/middleware 三个目录下分别找出所有与 token 校验相关的函数返回文件路径和行号, run_in_background: true } }不写subagent_type就是 Fork。run_in_background: true让它异步执行主对话继续。3.2 Swarm 配置Mailbox 与共享任务列表Swarm 官方名 Agent Teams默认禁用需要把CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS加进 settings.json 或环境变量{ env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 }, agentTeams: { backend: auto, maxTeammates: 4, mailboxDir: .claude/teams } }backend有三个值tmux/iTerm2分屏让每个队友占一个窗格in-process让队友跑在同一 Node.js 进程走 leader queue 同步auto自动检测——已在 tmux 会话里就分屏否则 in-process。Swarm 的关键不是多进程而是 team file、mailbox、SendMessage 这套团队协议。队友之间可以直接 SendMessage不需要经过负责人中转但团队创建、清理、成员发现、权限聚合、UI 呈现仍然围着 lead 转。消息传递通过基于文件的 Mailbox 系统实现带锁文件做并发控制。一个关键约束你的文本输出别人看不到必须通过 SendMessage 工具通信。模型必须明确知道直接写回复文本不会让队友看到。创建队友的调用{ name: Agent, input: { team_name: refactor-team, name: backend-worker, prompt: 负责 src/backend 下的接口重构完成后用 SendMessage 通知 lead, subagent_type: GeneralPurpose } }共享任务列表协调整个团队。任务有三种状态待处理、进行中、已完成任务之间可以有依赖——有未解决依赖的待处理任务无法被认领依赖完成后自动解除阻止。3.3 Coordinator 配置零上下文 worker 编排Coordinator Mode 藏在编译时功能标志后面通过环境变量激活CLAUDE_CODE_COORDINATOR_MODE1 claude写进 settings.json{ env: { CLAUDE_CODE_COORDINATOR_MODE: 1 }, coordinator: { maxWorkers: 6, workerTools: [Read, Write, Edit, Bash, Grep], notificationFormat: xml } }Coordinator 模式下协调者的工具集被严格限制只有 Agent生成 worker、SendMessage向现有 worker 发后续消息、TaskStop终止 worker、SyntheticOutput合成输出、subscribe_pr_activity/unsubscribe_pr_activityGitHub PR 事件订阅。注意缺失了什么——BashTool、FileReadTool、FileWriteTool、GrepTool 全都没有协调者把所有实际工作委托给 workers。核心原则工作 Agent 无法看到协调者的对话每个 worker 都以零上下文启动。协调者必须编写自包含提示词包含文件路径、行号、错误信息、什么算完成。这不是约定是架构层面的强制隔离。Worker 输出通过 XMLtask-notification在 user-role 消息中回传。四阶段工作流是 Research多 worker 并发调研→ Synthesis协调者综合成实现规格→ Implementation派实现者多个实现者不能同时编辑同一文件→ Verification派验证者跑测试、查类型、质疑实现。4. 验证请求跑通 Fork 分支、Swarm 并行、Coordinator 调度配置写完必须验证否则你不知道子代理是真跑起来了还是静默失败。这一节给三个可复现的验证动作。4.1 验证 Fork 分支Fork 的验证点是共享缓存 独立返回。在 Claude Code 里发一条会触发并行探索的指令帮我同时调研 src/auth 和 src/payment 两个模块的错误处理逻辑分别列出所有 try-catch 块的位置观察输出主 Agent 应该调用 AgentTool 两次或一次带多个 Fork每个 Fork 返回独立结果。验证缓存命中的方法是看响应延迟——第二个 Fork 的启动延迟应明显低于第一个因为共享了 Prompt Cache 前缀。命令行侧可以用/tasks查看后台任务列表。如果 Fork 设了run_in_background: true你应该看到local_agent类型的任务在跑。任务类型有七种local_bash、local_agent、remote_agent、in_process_teammate、local_workflow、monitor_mcp、dream每种有单字符 ID 前缀用于视觉识别。4.2 验证 Swarm 并行Swarm 验证点是队友互发消息 共享任务列表。先确认实验开关生效echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS输出1才算开启。然后创建团队并派两个队友创建一个团队派两个队友分别检查前端和后端的类型定义是否一致让他们直接互相沟通确认如果 backend 是 tmux 分屏你应该看到新窗格弹出每个队友一个窗格可以点击窗格直接交互。如果是 in-process队友跑在同一进程里通过 leader queue 同步。验证消息传递让一个队友用 SendMessage 给另一个队友发消息观察对方是否收到并响应。记住文本输出别人看不到必须走 SendMessage 工具。任务依赖验证创建一个任务 B 依赖任务 A确认 B 在 A 完成前无法被认领A 完成后 B 自动解除阻止。4.3 验证 Coordinator 调度Coordinator 验证点是零上下文 worker XML 回传。启动CLAUDE_CODE_COORDINATOR_MODE1 claude发一条需要多阶段的任务调研这个项目的数据库层然后实现一个带重试的连接池最后跑测试验证观察协调者行为它应该先派多个 Research worker 并发调研各自聚焦数据模型、API 层、测试套件然后综合成实现规格再派 Implementation worker 写代码最后派 Verification worker 跑测试。协调者自己不调用 Bash/Read/Write/Grep——如果你看到协调者直接读文件说明模式没生效。Worker 输出通过 XMLtask-notification回传。你可以在日志里搜这个标签确认。信息漏斗是这套模式的核心用户只跟协调者对话协调者把几千 token 的 worker 输出压缩成人能理解的摘要。三个验证都过了说明你的统一 Key 接入和子代理配置都正确。如果某个模式没跑起来进下一节排查。5. 常见报错排查401、local proxy failed、reading choices、OAuth子代理系统的报错往往跨越多层——可能是 Key 问题、可能是配置字段名不对、可能是模式互斥。这一节对照真实报错给排查路径。5.1 401 Unauthorized最常见。报错形如API Error: 401 {type:error,error:{type:authentication_error,message:invalid x-api-key}}排查顺序先确认ANTHROPIC_AUTH_TOKEN或x-api-key头带的是控制台生成的sk-串不是别的。然后确认 Base URL 是https://taotoken.net/api不带末尾斜杠、不带 UTM。再确认环境变量真的生效了——echo $ANTHROPIC_AUTH_TOKEN看输出。如果用了项目级 settings.json注意环境变量优先级高于配置文件两边都设了且值不同会以环境变量为准。还有一种隐蔽情况Key 复制时带了首尾空格或换行。用echo -n $TAOTOKEN_API_KEY | wc -c数一下长度和预期对比。5.2 local proxy failed报错形如Error: local proxy failed to connect: ECONNREFUSED 127.0.0.1:xxxx这通常出现在客户端配置了本地代理端口但代理没起来。检查你的客户端配置里有没有HTTP_PROXY/HTTPS_PROXY指向本地端口。如果有要么启动对应服务要么清掉这两个环境变量让请求直连。Claude Code 子代理在 in-process 模式下共享主进程的网络配置主进程代理不通所有子代理都会失败。5.3 reading choices 报错报错形如TypeError: Cannot read properties of undefined (reading choices)这是响应格式不匹配。choices是 OpenAI 兼容格式的字段如果你用的是 Anthropic 原生格式的客户端却收到了 OpenAI 格式响应或反过来就会解析失败。检查你的客户端走的是/v1/messagesAnthropic 格式还是/v1/chat/completionsOpenAI 格式。TaoToken 的 Base URL 是https://taotoken.net/api具体路径按客户端要求拼接。Codex 系客户端走 OpenAI 格式Claude Code 走 Anthropic 格式别混。5.4 OAuth 相关报错报错形如OAuth token expired or invalid如果你用的是 API Key 模式不应该出现 OAuth 报错。出现说明客户端还在尝试 OAuth 流程。检查配置里有没有残留的 OAuth 凭证文件如~/.claude/credentials.json里的旧 token清掉后强制走 API Key。Claude Code 的认证优先级是 API Key OAuth但如果 API Key 没设对它会回落到 OAuth 然后失败。5.5 模式互斥导致的静默失败Coordinator 和 Fork 互斥。如果你同时设了CLAUDE_CODE_COORDINATOR_MODE1和 Fork 相关配置Fork 会被自动禁用表现为Fork 不生效但不报错。排查时先确认当前模式echo $CLAUDE_CODE_COORDINATOR_MODE如果是1Fork 配置就是无效的。Swarm 的CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS没设或设成非1值时创建团队会静默失败或报agent teams not enabled。先确认开关。5.6 三件套自查清单任何认证/路由类报错先过一遍三件套Base URL 是不是https://taotoken.net/apiKey 是不是控制台生成的sk-串且无空格Model ID 是不是客户端支持的模型名。这三样对了90% 的报错会消失。剩下 10% 看模式互斥和代理配置。如果排查完还是不通接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各客户端的完整配置示例。API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以重新生成 Key 排除 Key 本身的问题。6. 按场景选模式从轻量分身到项目编排三种模式不是替代关系是不同形状工作的不同工具。选错了要么浪费 token要么根本跑不动。Fork 适合快速并行探索和微任务。成本极低是因为共享 Prompt Cache启动多个 Fork 的开销远低于启动多个独立子 Agent。典型场景同时搜索三个不同模块的代码、并行读取多个文件做初步分析、快速验证多个假设。限制是上下文继承父对话可能受无关信息干扰且 Fork 之间无横向通信。记住不要在 Fork 上换模型换了就复用不了缓存。Swarm 适合需要讨论和协作的复杂工作。队友有独立 context window可以直接互发消息共享任务列表支持依赖管理。典型场景多个队友同时调查问题不同方面然后互相质疑发现、新模块各占一块互不干扰、竞争假设调试并行测试不同理论、跨前端后端测试的协调改动。代价是每个队友是独立 Claude 实例token 消耗随活跃队友数增加且不共享 Prompt Cache。Coordinator 适合需要全局视野、多阶段流水线的大型任务。协调者自己不执行工具只拆任务、派活、综合结果。典型场景研究→综合→实现→验证的复杂工程任务。worker 零上下文启动协调者必须写自包含提示词。这是最彻底的自动化编排也是最重的模式。一个实用的选择流程任务能在一次对话里说清且只需要结果 → Fork任务需要多个角色讨论、有共享状态 → Swarm任务有明确阶段划分、需要协调者做信息漏斗 → Coordinator。长期跑编码和 Agent 任务的话Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 适合把统一 Key 接入后的多模型调用集中管理。Claude Code 专项接入参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有 Anthropic 格式的完整配置。最后给一个我踩过的坑Swarm 的 tmux 分屏模式下如果你在非 tmux 环境里设了backend: tmux队友窗格不会弹出任务会卡住。用backend: auto让它自动检测或者显式设in-process。这个坑不报错只是没反应排查起来很费时间。