1. 为什么单会话跑复杂任务总会卡住如果你用 Claude Code 做过稍微大一点的需求大概率遇到过这种局面一个会话里既要读架构、又要改后端、还要顺手补测试上下文越滚越长前面聊过的约束到后面就被稀释了。你让它先看 A 模块它改着改着又去动 B 模块最后你不得不反复贴同一段背景说明。这不是模型不行而是单会话的注意力带宽被摊薄了。Agent Teams 想解决的就是这件事。它把一个大任务拆成若干角色每个角色是一个独立的 Claude Code 实例拥有自己的上下文窗口彼此之间还能直接发消息、共享任务列表。一个会话当负责人Team lead负责拆活、卡依赖、汇总结果其余队友Teammates各自认领任务并行推进。和 Subagent 最大的区别在于Subagent 只向主代理汇报结果队友之间不通信而 Agent Teams 的成员可以互相质疑、交叉验证适合需要讨论和协作的复杂工作。这篇面向需要多个 Subagent 分工并行推进任务的开发者给出可复制的settings.json配置骨架、Subagent 角色划分示例以及如何通过统一 Key/API 通道接入 TaoToken最后用一次并行任务验证多智能体是否按预期分工执行。适合已经用过 Claude Code、想往多智能体协作方向走一步的人。2. 前置准备开启 Agent Teams 并接入 TaoTokenAgent Teams 目前是实验特性默认关闭必须显式打开。同时多智能体并行会显著放大 Token 消耗所以统一走一个稳定的 API 通道比单会话时更重要。我这边习惯把模型请求统一收敛到 TaoToken好处是 Key 管理集中、切换模型不用改一堆环境变量团队里每个队友读到的都是同一套配置。2.1 开启实验开关在项目或用户级的settings.json里加环境变量这是最省事的方式{ env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 } }也可以走系统环境变量名称CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS值1。改完记得重开终端或 Claude Code让配置生效。版本要求 v2.1.32 及以上先用claude --version确认一下。2.2 配置统一 API 通道TaoToken 的 API 入口是https://taotoken.net/apiKey 在控制台的 API Keys 页面生成。把下面这段合并进你的settings.json注意env里可以同时放实验开关和通道配置{ env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1, ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 }, teammateMode: in-process }teammateMode建议先设in-process任意终端都能用不依赖 tmux。等团队跑顺了再考虑分屏。Key 的生成入口在控制台文档在接入文档页两个地址都放在文末 CTA 里这里先记住路径即可。注意不要把 Key 硬编码进会提交到 Git 的文件。用环境变量注入或者放在被.gitignore忽略的本地配置里。2.3 确认工作目录上下文队友启动时会加载项目上下文包括CLAUDE.md、MCP、Skills。所以先在项目根目录把CLAUDE.md写清楚常用命令、目录边界、禁区、验收标准。单 agent 时它是加分项多智能体下它更像团队操作系统全队默认遵守。这一步偷懒后面队友就会各写各的。3. 可复制的 settings.json 骨架与 Subagent 角色划分这一节是全文的核心。配置骨架可以直接抄角色划分按你的项目改。3.1 完整 settings.json 骨架{ env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1, ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥 }, teammateMode: in-process, permissions: { allow: [ Read, Glob, Grep, Edit, Bash(git status), Bash(git diff:*), Bash(npm test:*) ] } }permissions.allow里预批准常用只读和测试命令能明显减少队友跑一半停下来等授权的次数。写操作按需放开别一上来就全开。3.2 角色划分示例一个在真实项目里比较稳的链路是 Architect → 规格广播 → Backend / Frontend → QA。对应到 Subagent 角色角色职责边界Architect出接口规格、数据流、依赖顺序只读 写规格文档不改业务代码Backend按规格实现服务端只动server/目录Frontend按规格实现页面与联调只动web/目录QA写测试、跑回归、报缺陷只动tests/不改实现关键原则Lead 只做编排不做主力实现。拆角色、卡依赖、批计划、收敛结果写码交给队友。这条建议直接写进你的 spawn 提示词里否则 Lead 很容易和队友抢同一条路。3.3 自然语言建队话术启用后不需要记命令用自然语言向主会话说明即可。指定人数和模型创建一个 agent team4 名队友并行重构这些模块。 Architect 先出接口规格Backend 和 Frontend 等规格确认后再动手 QA 最后跑回归。每个队友用 Sonnet。高风险任务可以要求先计划再实施Spawn an architect teammate to refactor the authentication module. Require plan approval before they make any changes.负责人会自动审批你可以在提示里写标准比如「仅批准含测试覆盖的计划」。3.4 任务列表与依赖团队用共享任务列表任务有待处理 / 进行中 / 完成状态可设依赖未完成的依赖会阻止认领下游任务。认领侧有文件锁降低多人抢同一任务的竞态。在终端里按CtrlT可以打开或关闭任务列表视图ShiftDown在负责人和队友之间循环切换切到某个队友后直接输入就能单独下指令。4. 验证请求跑一次并行任务看分工是否生效配置写完不验证等于没配。下面用一个最小可复现的任务确认多智能体确实按角色并行执行。4.1 准备一个可拆分的任务在项目根目录启动 Claude Code然后输入创建一个 agent team3 名队友。 任务审查当前仓库的登录模块。 队友 A 看安全性队友 B 看性能队友 C 看测试覆盖。 各自输出一份结论最后由你汇总成一份对比报告。 等所有队友完成后再汇总。最后那句「等所有队友完成后再汇总」很重要能避免负责人提前抢活收尾。4.2 观察执行过程按ShiftDown逐个切到队友会话你应该能看到三路输出在各自推进而不是串行排队。按CtrlT打开任务列表能看到任务被分别认领、状态从待处理变为进行中再到完成。如果三个队友的输出内容高度雷同说明角色边界没写清回到 spawn 提示词里补上「只看 X 维度」。4.3 确认结果收敛负责人汇总后检查报告是否包含三份独立结论而不是一份被复制三遍。这一步是判断并行是否真的生效的关键。如果报告里只有安全维度多半是另外两个队友的任务没被正确认领去任务列表里看依赖是否卡住。4.4 收工与清理结束某个队友对负责人说Ask the researcher teammate to shut down.全部结束后让负责人执行Clean up the team释放资源。如果还有队友在跑清理会失败先关队友。务必由负责人执行清理队友自行清理可能导致团队上下文解析失败。5. 本篇常见错误排查多智能体踩坑集中在配置、权限、终端三块按现象对照处理。5.1 看不到队友in-process 模式下用ShiftDown切换。如果切不出来先确认任务是否复杂到值得建队简单任务建队反而更乱。分屏模式下检查 tmux 或 it2 是否装好、iTerm2 Python API 是否启用。5.2 权限提示过多队友启动时权限和负责人一致负责人用什么权限策略全队天花板就由谁定。事先在permissions.allow里预批准常见只读和测试操作能大幅减少中断。注意无法在创建时为每名队友设不同初始权限创建后可单独调整某个队友的模式。5.3 队友遇错就停直接对该队友下新指令或换新队友接手。任务状态可能更新滞后如果依赖链卡住检查实际是否已完成必要时人工改状态或让负责人催促。5.4 负责人提前收尾要求继续或明确要求「等队友完成后再推进」。这条在长任务里出现频率很高写进 spawn 提示词能省不少事。5.5 tmux 会话残留tmux ls tmux kill-session -t session-nameWindows 原生终端不支持基于 tmux 的分屏团队功能请用 in-process不必为 Agent Teams 单独装 tmux。5.6 接入通道报错如果队友启动后请求失败先确认ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN是否写对、Key 是否有效。多智能体会放大请求量Key 额度不足时表现为部分队友静默失败去控制台看用量最直接。6. 把通道和团队一起管起来多智能体并行协作真正难的不是开开关而是让每个队友读到同一套配置、走同一个通道、遵守同一份CLAUDE.md。我试过把 Key 分散在多个环境变量里队友一多就乱后来统一收敛到 TaoToken改一处全队生效排查问题时也只需要看一个入口。如果你还在单会话阶段先把settings.json里的通道配好再去开 Agent Teams 开关顺序反了容易在排障时分不清是团队配置问题还是通道问题。Key 在控制台的 API Keys 页面生成接入细节看接入文档想先验证模型通不通用模型对话页发一条请求最快长期跑编码和 Agent 任务Coding Plan 在成本上更可控。三个入口按你的阶段选一个先跑通再回来扩团队规模。