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 的本质区别，这决定了你什么时候该用它：
| 对比项 | subAgents | AgentTeams |
|---|---|---|
| 工作方式 | 主 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api （注意 API 地址不加 UTM 参数）。你需要先在控制台创建一个 API Key，控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，创建 Key 的页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。拿到 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填你要用的模型 ID，CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS设为1就是开启 AgentTeams 实验功能。teammateMode设为in-process表示所有 teammate 都在当前终端里运行，兼容性最好，适合新手先体验。
如果你更习惯用环境变量而不是 settings.json，也可以在 shell 里导出：
export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的TaoToken密钥" export ANTHROPIC_MODEL="claude-sonnet-4-5-20250929" export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1两种方式选一种即可，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_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。如果那边能正常返回，说明 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 写的用例自己没跑过就交给 lead，lead 运行时会暴露出来。
第三，汇总报告是否覆盖了三个关注点。一份合格的汇总报告应该包含：前端改了什么、后端改了什么、测试覆盖了哪些场景、还有哪些遗留问题。
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_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。把 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 URL | https://taotoken.net/api | 漏掉 /api 路径 |
| API Key | 控制台创建的 sk- 开头密钥 | 填了官网登录密码 |
| Model ID | 模型页面列出的准确 ID | 自己拼写模型名 |
这三项对齐了，绝大多数接入报错都能解决。如果还有问题，去接入文档页面查更详细的说明： https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
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_source=taotoken_aicg_blog_end&utm_content=coding-plan&utm_campaign=rewrite 。对于需要频繁跑多智能体协作的团队，套餐能更好地控制成本。
第六，把配置沉淀成模板。每次创建团队都手写指令很累，可以把常用的编排指令存成文件，比如~/.claude/teams/code-review.md，下次直接引用。团队协作的配置和指令越标准化，落地成本越低。
到这里，从环境准备、配置片段、编排示例到验证流程和排错，一套完整的 AgentTeams 多智能体协作工作流就齐了。核心就三件事：把 Base URL、Key、Model ID 三件套配对，把 teammate 的职责边界划清，把 team lead 的汇总职责交给它自己。剩下的，就是在真实项目里多跑几次，慢慢找到适合你团队的拆分粒度。
