1. 从单打独斗到小队作战AgentTeams 多智能体协作到底解决什么问题如果你已经用过 Claude Code 的 subAgents大概会有一种感觉主 agent 派几个分身出去干活分身干完回来汇报主 agent 再汇总。这个模式在任务明确、彼此独立的时候很好用但它有个天花板——分身之间不能直接对话所有协调都得经过主 agent 中转。一旦任务需要「前端改完告诉后端接口变了」「安全审查发现的问题要性能组一起评估」这种横向沟通subAgents 就开始力不从心。AgentTeams 就是冲着这个痛点来的。它让多个 Claude Code 实例组成一个真正的团队一个 team lead 负责拆解任务、分配工作、汇总结果若干个 teammate 各自拥有独立的上下文窗口而且队友之间可以直接发消息、协调进度。你可以把它理解成一个小型 AI 开发小组而不是一次工具调用。这篇文章面向的是已经能跑通 Claude Code、想进一步落地多智能体工作流的开发者。我会从环境准备讲到可复制的配置片段再给出一套 teammate 与 team lead 的编排示例最后演示一次完整协作任务的验证过程并把常见的报错排查一并整理出来。核心检索词就是 AgentTeams、Claude Code、subAgents、teammate、team lead全文围绕这几个概念展开。先说清楚它和 subAgents 的本质区别这决定了你什么时候该用它对比项subAgentsAgentTeams工作方式主 agent 派发任务team lead 组织团队上下文子代理独立结果回到主 agent每个 teammate 都是独立 Claude Code 实例沟通方式子代理向主 agent 汇报队友可以互相发消息协调协调方式主 agent 统一管理共享任务列表队友可协作成本相对低更高多个实例同时工作适合任务明确、短小、只需结果复杂、多角度、需互相讨论一句话总结subAgents 是「分身术」AgentTeams 是「AI 小队」。分身术适合并行处理独立子任务小队适合需要横向沟通的复杂协作。但这里必须泼一盆冷水。AgentTeams 会明显增加 token 消耗也会带来协调成本。不是人越多越快任务拆得清楚才有意义。我见过有人拿它去改一个单文件的小 bug结果三个 teammate 抢着改同一个文件冲突不断还不如一个 Claude 直接干。所以下面的内容我会重点讲清楚「什么场景值得上团队」以及「怎么把职责边界划干净」。适合的场景大致有这么几类多角度代码审查安全、性能、测试覆盖分别由不同 teammate 负责、复杂 bug 排查多个 teammate 分别验证不同假设、跨层功能开发前端、后端、测试分开负责、技术方案评审架构、成本、风险、反对意见分别分析、大型重构前调研每个 teammate 负责一个模块或目录。不适合的场景也很明确简单改一个小 bug一个 Claude 就够了多个 teammate 都要改同一个文件容易产生冲突任务强依赖顺序前一步不完成后一步无法开始只是快速查一个问题用 subAgents 就够了。理解了这层边界我们再进入实操。下一节先把前置环境和 TaoToken 的接入准备好因为多实例协作对模型调用的稳定性要求比单 agent 高得多。2. 前置准备TaoToken 接入与 Claude Code 环境配置AgentTeams 目前属于实验功能默认关闭。要开启它前置条件是你的 Claude Code 版本至少为 v2.1.32。先检查版本claude --version如果版本偏低先升级。升级完成后我们还需要解决模型调用的问题。多智能体协作意味着同一时间可能有多个 Claude Code 实例在发请求如果底层调用不稳定team lead 汇总到一半掉线整个团队就散了。我实测下来用 TaoToken 作为统一的模型接入层比较省心它提供兼容 Anthropic 的 API 端点多个实例共享同一个 Base URL 和 Key配置一次就能复用。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 注意 API 地址不加 UTM 参数。你需要先在控制台创建一个 API Key控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 Key 的页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后先放一边下面配置会用到。这里要强调一个三件套的概念无论你用的是 Claude Code、Cline 还是 Codex接入任何兼容 Anthropic 的服务都需要三样东西——Base URL、API Key、Model ID。缺一不可后面排查报错时也主要围绕这三项。接下来配置 Claude Code 的环境变量。在~/.claude/settings.json中写入以下内容注意路径要和你的实际环境一致{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 }, teammateMode: in-process }逐项说明一下。ANTHROPIC_BASE_URL指向 TaoToken 的 API 端点ANTHROPIC_API_KEY填你在控制台创建的密钥ANTHROPIC_MODEL填你要用的模型 IDCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS设为1就是开启 AgentTeams 实验功能。teammateMode设为in-process表示所有 teammate 都在当前终端里运行兼容性最好适合新手先体验。如果你更习惯用环境变量而不是 settings.json也可以在 shell 里导出export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥 export ANTHROPIC_MODELclaude-sonnet-4-5-20250929 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS1两种方式选一种即可settings.json 的好处是持久化不用每次开终端都重新导出。配置完成后重启终端再进入你的项目目录启动 Claude Code。关于显示模式AgentTeams 有两种常见选择。in-process模式下所有 teammate 都在当前终端里运行你可以用Shift ↓在 lead 和 teammate 之间切换兼容性最好。split panes模式让每个 teammate 在独立 pane 里显示适合同时观察多个 agent 的输出但它依赖 tmux 或 iTerm2环境要求更高。在 Windows Terminal、VS Code 集成终端中不建议强行使用 split panes。如果你只是想先跑通老老实实用 in-process。配置好之后建议先做一次最小验证确认模型调用是通的。可以用模型对话页面快速测一下 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。如果那边能正常返回说明 Key 和端点没问题再回到 Claude Code 里跑团队任务就稳了。3. 可复制的 AgentTeams 配置片段与 subAgents 编排示例这一节是全文的核心我会给出可以直接复制的配置片段以及一套 teammate 与 team lead 的编排示例。先说配置再说编排。3.1 settings.json 完整配置片段把下面这段写进~/.claude/settings.json路径和字段名保持原样不要自己改键名{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-5-20250929, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 }, teammateMode: in-process, permissions: { allow: [ Read, Edit, Bash(git status), Bash(git diff), Bash(npm test) ] } }permissions.allow这一段是可选的但强烈建议加上。多智能体协作时每个 teammate 都可能触发工具调用如果权限没配好team lead 汇总到一半被权限弹窗卡住体验会很差。把常用的读、改、测试命令提前放行能省掉大量打断。如果你用的是项目级配置也可以放在项目根目录的.claude/settings.json里字段结构完全一样。项目级配置的好处是不同项目可以用不同的模型和权限团队协作时更容易统一。3.2 用自然语言创建 Agent Team开启之后不需要记复杂命令直接用自然语言告诉 Claude 就行。下面是一个代码审查团队的编排示例你可以直接复制到 Claude Code 里创建一个 agent team 来审查这个项目 1. 一个 teammate 负责安全风险重点看认证、输入校验、依赖漏洞 2. 一个 teammate 负责性能问题重点看数据库查询、循环嵌套、内存占用 3. 一个 teammate 负责测试覆盖重点看未覆盖的分支和边界条件 让他们分别检查最后由 team lead 汇总成一份报告按严重程度排序。再给一个功能开发的编排示例创建一个 agent team 来实现用户设置页 1. 前端 teammate 负责页面和交互只改 src/pages/settings 目录 2. 后端 teammate 负责接口和数据结构只改 src/api/settings 目录 3. 测试 teammate 负责单测和集成测试只改 tests/settings 目录 每个 teammate 只修改自己负责的文件完成后由 lead 汇总并运行测试。注意第二个示例里我特意强调了「只改自己负责的目录」。这是踩过的坑——如果不划定文件边界两个 teammate 同时改同一个文件后写的会覆盖先写的team lead 汇总时看到的是残缺版本。把目录级边界写进指令里冲突概率会大幅下降。3.3 teammate 与 team lead 的角色分工team lead 的职责是拆解任务、分配任务、汇总结果。它不直接写业务代码而是像一个项目经理把大目标拆成可并行的子任务分给合适的 teammate最后把各方的产出合并成一份完整交付物。teammate 的职责是执行自己那一块任务并且可以和其他 teammate 直接沟通。比如前端 teammate 发现接口字段对不上可以直接给后端 teammate 发消息确认不需要经过 lead 中转。这是 AgentTeams 相比 subAgents 最大的优势。一个实用的分工原则是按「关注点」拆而不是按「文件数量」拆。安全、性能、测试覆盖是三个不同的关注点各自独立又能互补适合分给三个 teammate。如果你按「前 10 个文件给 A后 10 个文件给 B」来拆两个 teammate 的关注点重叠汇总时反而要花更多精力去重。3.4 共享任务列表的用法AgentTeams 内部维护一个共享任务列表team lead 把任务写进去teammate 认领并更新状态。你不需要手动操作这个列表但可以在指令里要求 lead 显式列出任务创建 agent team 前先把任务拆成清单标注每个任务的负责人和验收标准 写进共享任务列表再开始分配。这样做的好处是任务流转可视化你能清楚看到哪个 teammate 在做什么、卡在哪一步。任务完成后记得让 lead 清理团队避免残留进程占用资源所有任务完成后请 team lead 清理团队并输出最终报告。4. 验证一次完整协作任务从发起到汇总的全流程光看配置不够我们跑一次完整任务来验证。我选一个典型的跨层场景给一个已有的 Node 项目加一个「用户偏好设置」功能涉及前端页面、后端接口、测试三块。4.1 发起任务进入项目目录启动 Claude Code然后输入创建一个 agent team 来实现用户偏好设置功能 1. 前端 teammate在 src/pages/preferences 下新增设置页面包含主题切换和通知开关 2. 后端 teammate在 src/api/preferences 下新增 GET/PUT 接口数据存到现有 user 表 3. 测试 teammate在 tests/preferences 下补充接口单测和页面集成测试 每个 teammate 只改自己负责的目录。完成后由 lead 运行 npm test 并汇总结果。4.2 观察任务流转在 in-process 模式下你可以用Shift ↓在 lead 和各个 teammate 之间切换观察它们各自在做什么。正常情况下你会看到lead 先把任务拆成清单写进共享列表然后三个 teammate 分别认领各自在自己的上下文里工作。如果前端 teammate 发现后端接口的字段命名和自己预期不一致它会直接给后端 teammate 发消息两边对齐后再继续。这一步的关键验证点是teammate 之间是否真的能直接沟通。如果发现所有消息都要经过 lead 中转说明你的指令里没有明确授权队友互发消息可以在指令里补一句「队友之间可以直接沟通协调不必都经过 lead」。4.3 验证产出任务完成后lead 会运行测试并汇总。你需要检查三件事第一各目录的改动是否只落在自己负责的范围。用git status看一下git status如果发现前端 teammate 改了后端目录的文件说明边界没划住下次指令里要把目录路径写得更死。第二测试是否真的跑通。lead 汇总时会输出npm test的结果重点看有没有失败用例。如果测试 teammate 写的用例自己没跑过就交给 leadlead 运行时会暴露出来。第三汇总报告是否覆盖了三个关注点。一份合格的汇总报告应该包含前端改了什么、后端改了什么、测试覆盖了哪些场景、还有哪些遗留问题。4.4 清理团队任务结束后让 lead 清理团队任务已完成请清理团队并确认没有残留进程。这一步别省。多个 Claude Code 实例同时运行会占用内存和 API 配额任务做完不清理下次启动可能遇到端口或会话冲突。整个流程跑下来你会发现 AgentTeams 的价值在于「并行 横向沟通」。三个关注点同时推进前端和后端在接口字段上直接对齐测试同步跟上最后由 lead 统一验收。这套流程如果换成单 agent 串行做时间会拉长不少。5. 常见报错排查401、local proxy failed、reading choices、OAuth多智能体协作对配置的容错率比单 agent 低因为任何一个 teammate 的调用失败都可能拖垮整个团队。下面整理几类高频报错和排查思路。5.1 401 Unauthorized这是最常见的报错基本都出在 Key 上。排查顺序先确认ANTHROPIC_API_KEY填的是 TaoToken 控制台创建的 Key没有多余空格再确认这个 Key 没有过期或被禁用最后确认ANTHROPIC_BASE_URL指向的是https://taotoken.net/api而不是官网首页地址。很多人会把 Base URL 误填成https://taotoken.net少了/api路径结果就是 401。如果你在多个 teammate 之间共享配置确认它们读的是同一份 settings.json。有时候项目级配置覆盖了全局配置Key 不一致就会报 401。5.2 local proxy failed这个报错通常和网络环境有关。先检查你的终端能不能正常访问https://taotoken.net/api可以用 curl 测一下curl -I https://taotoken.net/api如果连不通检查本机的网络设置和防火墙规则。如果公司网络有出口限制需要联系网络管理员放行。注意不要使用任何非正规的网络代理工具这类工具本身就不合规也会让排查变得更复杂。5.3 reading choices 相关报错这类报错一般出现在模型返回格式不符合预期的时候。常见原因是ANTHROPIC_MODEL填的模型 ID 不对或者该模型不支持当前请求的参数。解决办法是回到模型对话页面确认可用的模型 ID https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。把 settings.json 里的ANTHROPIC_MODEL改成页面上列出的准确 ID重启终端再试。如果换了模型 ID 还报错检查是不是某个 teammate 的上下文太长导致请求被截断。AgentTeams 里每个 teammate 都有独立上下文任务拆得太碎反而会让单个 teammate 的上下文里塞满无关信息适当合并子任务能缓解。5.4 OAuth 相关报错如果你之前用官方账号登录过 Claude Code本地可能残留 OAuth 凭证和 API Key 模式冲突。解决办法是清理旧的登录状态确保走的是 API Key 认证。检查~/.claude/目录下有没有残留的凭证文件必要时备份后删除然后重新用 settings.json 里的 Key 启动。5.5 三件套自查清单遇到任何接入类报错先按这个清单过一遍检查项正确值常见错误Base URLhttps://taotoken.net/api漏掉 /api 路径API Key控制台创建的 sk- 开头密钥填了官网登录密码Model ID模型页面列出的准确 ID自己拼写模型名这三项对齐了绝大多数接入报错都能解决。如果还有问题去接入文档页面查更详细的说明 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。6. 把 AgentTeams 用顺手成本控制与长期协作建议跑通一次不难难的是长期用得住。最后分享几条实战经验。第一任务拆得清楚比人多更重要。AgentTeams 的成本和 teammate 数量正相关三个 teammate 同时工作token 消耗大致是单 agent 的三倍。如果任务本身不需要横向沟通用 subAgents 更划算。判断标准很简单如果子任务之间需要互相确认信息用 AgentTeams如果各自独立、只需最后汇总用 subAgents。第二职责边界写进指令里。不要指望 lead 自己猜出边界直接在指令里写「前端只改 src/pages后端只改 src/api测试只改 tests」。目录级边界比文件级边界好维护文件级边界比函数级边界好维护。第三先学走路再跑步。新手先从单个 Claude Code 开始把 CLAUDE.md、rules、Skill 这些基础能力用熟再上 subAgents最后才上 AgentTeams。跳过前面的阶段直接上团队遇到问题会不知道从哪查起。第四任务完成后清理团队。这一步前面提过但值得再强调一次。残留的 teammate 进程会占用资源也会让下一次启动的会话状态变得混乱。第五长期编码和 Agent 场景可以考虑用 Coding Plan。如果你打算把 AgentTeams 用在日常开发里按量计费可能不如套餐划算具体可以看 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。对于需要频繁跑多智能体协作的团队套餐能更好地控制成本。第六把配置沉淀成模板。每次创建团队都手写指令很累可以把常用的编排指令存成文件比如~/.claude/teams/code-review.md下次直接引用。团队协作的配置和指令越标准化落地成本越低。到这里从环境准备、配置片段、编排示例到验证流程和排错一套完整的 AgentTeams 多智能体协作工作流就齐了。核心就三件事把 Base URL、Key、Model ID 三件套配对把 teammate 的职责边界划清把 team lead 的汇总职责交给它自己。剩下的就是在真实项目里多跑几次慢慢找到适合你团队的拆分粒度。