Claude Code Agent Teams 教程：多智能体并行开发实战（2026）

Claude Code Agent Teams 是 Anthropic 在 2026 年推出的实验性多智能体功能：你的当前会话变成「队长」，可以一次开出好几个完全独立的 Claude Code 实例当「队友」，每个队友有自己的上下文窗口，彼此之间还能直接发消息、抢同一份任务清单里的活。它解决的是 Subagents 解决不了的问题——让多个 AI 互相讨论、互相质疑，而不是各干各的然后把结果丢回主会话。这篇 Agent Teams 教程从开启开关讲到成本控制，把官方文档里散落的关键设置和已知限制一次讲透。

Agent Teams 是什么

一个 agent team 由四部分组成：队长（team lead），也就是你正在敲字的这个主会话，负责拆任务、分配、汇总；队友（teammates），每个都是一个独立完整的 Claude Code 实例；任务清单（task list），一份共享的待办，队友可以被指派、也可以自己认领；邮箱（mailbox），队友之间直接通信的消息系统。团队在你第一次让 Claude 开出队友时自动成立，会话结束时自动清理，不需要手动建团队、也没有 TeamCreate 之类的命令了。

Agent Teams 和 Subagents 有什么区别

这是最容易混淆的一点。两者都能并行，但通信模型完全不同——Subagents 只能向主会话汇报，队友之间互不知道对方存在；Agent Teams 的队友能直接互发消息、共享任务板。

选择判据很简单：worker 之间需不需要说话。需要讨论、需要互相挑刺、需要按共享任务板自己领活的，用 Agent Teams；只是想把「跑测试」「读一堆日志」这类脏活外包出去、只要个摘要的，Subagents 更省钱也更稳。顺带一提，Claude 有时候你要团队它却给你开了 Subagents——两者在同一个 agent 面板里显示，光看面板分不出来，这时候明确再说一次「用 agent team」即可。

怎么开启：一个环境变量的事

Agent Teams 默认是关闭的。不设这个开关，Claude 不会开队友、也不会向你提议开队友。在 settings.json 里加上环境变量即可：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

也可以直接在 shell 里 export 这个变量再启动 claude。配置文件位置和其他 Claude Code 设置一样：用户级 ~/.claude/settings.json，项目级 .claude/settings.json。开完之后不需要任何初始化步骤，直接用自然语言描述任务和你想要的队友角色就行：

我要重构这个项目的登录模块，开三个队友并行推进：
一个负责后端 API 和 session 逻辑，
一个负责前端表单和错误提示，
一个专门写测试并挑前两个人的毛病。
分别叫 api、ui、qa。

队友开出来后，会出现在输入框下方的 agent 面板里。面板操作是纯键盘的：

• 上下方向键：在队友之间移动选择
• Enter：打开选中队友的完整会话，直接跟它对话下指令
• Esc：打断选中队友当前这一轮
• x：停掉选中的队友
• Ctrl+T：切换任务清单显示

注意一个细节：当你正在「看」某个队友的会话时，你打的普通文字和技能会发给这个队友，但内建斜杠命令仍然作用在队长会话上。队友的模型和 fast 模式在它被创建那一刻就固定了，/model、/fast 改的都是队长；只有 /effort 会作用到你正在看的这个队友的后续轮次。

显示模式：同终端 vs 分屏

Agent Teams 有两种显示模式。默认是 in-process（同终端）：所有队友跑在你当前这个终端里，靠上面那套方向键切换。另一种是 split panes（分屏）：每个队友一个独立窗格，能同时看到所有人的输出，可以直接点进去交互——但它需要 tmux 或者 iTerm2。

{
  "teammateMode": "auto"
}

写在 ~/.claude/settings.json 里。可选值："in-process"（默认，任何终端都能用）、"auto"（已经在 tmux 里、或终端是装了 it2 CLI 的 iTerm2 时启用分屏，否则退回同终端）、"tmux"（强制分屏，自动判断走 tmux 还是 iTerm2）、"iterm2"（明确走 iTerm2 原生分屏）。只想临时试一次的话用命令行参数：

claude --teammate-mode auto

队友之间怎么协作：任务板 + 邮箱

共享任务清单是团队协调的核心。任务有三种状态：待处理、进行中、已完成，任务之间还能声明依赖——被依赖的任务没完成前，后置任务锁着不让认领，前置一完成自动解锁。认领用文件锁做互斥，避免两个队友同时抢同一张卡。

• 队长指派：你告诉队长把哪个任务交给谁
• 自主认领：队友干完手上的活，自己去捡下一个没人领、没被阻塞的任务
• 消息投递：队友发的消息自动送达，队长不需要轮询
• 空闲通知：队友干完停下来时会自动通知队长；如果它是因为 API 报错停的，也会把错误文本一起报上去

这些状态都落在本地文件里：团队配置在 ~/.claude/teams/{team-name}/config.json，每个 agent 的邮箱是 ~/.claude/teams/{team-name}/inboxes/{agent-name}.json，任务清单在 ~/.claude/tasks/{team-name}/。团队名由会话 ID 派生（session- 加上会话 ID 前八位）。会话结束时团队配置目录被删掉，任务目录会留着，所以 resume 回来任务还在。别手动改 config.json，它存的是运行时状态，下次状态更新就被覆盖了。

三个进阶用法

指定队友数量和模型。 队友默认不继承队长的 /model 选择，可以在提示词里直接说，也可以在 /config 里设「Default teammate model」，选「Default (leader's model)」让队友跟随队长。

开 4 个队友并行重构这几个模块，每个队友都用 Sonnet。

要求队友先出方案再动手。 高风险改动建议加这句，队友会先在只读的 plan 模式里做调研出方案，交给队长审批；被打回就带着反馈改了再交，通过后才开始写代码。队长是自主决策的，你想影响它的判断就在提示词里给标准，比如「只批准包含测试覆盖的方案」。

开一个架构师队友重构认证模块，要求先出方案经审批后再动手。

复用已有的 subagent 角色定义。 你在 .claude/agents/ 里定义过的 subagent（比如 security-reviewer、test-runner），可以直接拿来当队友的角色模板，点名即可。队友会遵守该定义的 tools 白名单和 model，定义正文被追加进队友的系统提示词。注意 subagent 定义里的 skills 和 mcpServers 字段在当队友时不生效，队友是按你的项目/用户设置去加载技能和 MCP 的。

用 security-reviewer 这个 agent 类型开一个队友，审计 auth 模块。

成本：这是个实打实烧 token 的功能

必须把丑话说前面。官方文档明确写着：队友在 plan 模式下运行时，agent teams 大约消耗标准会话 7 倍的 token。原因很直白——每个队友都是一个独立的 Claude 实例，各自维护完整上下文窗口，token 用量大致和队友数量成正比。订阅制用户会更快撞 5 小时窗口和周限额，API 用户就是真金白银。

• 队友统一用 Sonnet，协调类任务它的性价比最好，Opus 留给队长做架构决策
• 团队规模控制在 3-5 人，官方推荐这个区间；三个专注的队友通常打得过五个散的
• 每个队友配 5-6 个任务，太少了协调开销不划算，太多了容易长时间没有检查点
• spawn 提示词写精准。队友会自动加载 CLAUDE.md、MCP、技能，你在提示词里堆的每一句都是它开局就带上的额外上下文
• 干完的队友及时让它下线，只要还活着就一直在消耗 token
• 拆任务时让每个队友负责不同的文件集，两个队友改同一个文件必然互相覆盖

关掉队友的方式是点名让队长发关闭请求：「让 researcher 队友下线」。队友可以同意（优雅退出）也可以带理由拒绝。团队的共享目录在会话结束时自动清理，不用手动收尾。

国内用户：接国产模型能用 Agent Teams 吗

Agent Teams 是 Claude Code 客户端侧的功能——团队协调、任务板、邮箱都是本地文件加客户端逻辑，模型只是被调用的后端。所以理论上你把 ANTHROPIC_BASE_URL 指向 GLM、DeepSeek、Kimi 的 Anthropic 兼容网关之后，这个开关照样能打开，队友照样能开出来。但有两个现实问题要预期：

1. 1多 agent 场景对模型的稳定性要求更高。 已有开发者实测反馈，用国产模型搭多 Agent 协作时更容易出现上下文记忆串台、逻辑漂移；简单并行任务问题不大，复杂的跨模块协作要多盯着。
2. 2「用 Sonnet 当队友」这条建议要重新翻译。 走第三方网关时，模型名是被网关映射的，你说的 Sonnet 实际落到哪个模型取决于网关配置。想省钱就直接在网关侧把小模型映射过去。

已知限制与常见踩坑

这个功能还挂着 experimental 标签，官方列出的限制值得先看一遍再上手：

• 恢复会话丢队友：/resume 和 /rewind 不会恢复 in-process 队友。恢复后队长可能还去给已经不存在的队友发消息，遇到就告诉它重新开队友
• 任务状态会滞后：队友有时忘了把任务标完成，导致依赖它的任务一直卡着。看着卡住就手动改状态，或者让队长去催
• 关闭比较慢：队友要跑完当前请求或工具调用才退出
• 一个会话只有一个团队：不能建多个命名团队，也不能跨会话共享
• 不能套娃：队友不能再开自己的队友，只有队长能管理团队
• 队长身份固定：主会话终身是队长，不能把队友提拔成队长
• 权限在创建时定死：所有队友继承队长的权限模式（队长开了 --dangerously-skip-permissions，队友全都跟着开），创建后可以单独改，但创建时不能分别设
• 权限弹窗都在队长这里：队友的权限请求会冒泡到队长会话，你得在那儿批。队友之间不能互相代批权限

另外两个高频问题：队友没出现——先确认面板里翻一下，空闲的队友行会在整个面板都空闲 30 秒后隐藏（它还活着，发个消息就回来）；超过三个空闲队友时，多出来的会折叠成一行「N idle agents」，选中按 Enter 展开。队长自己动手干活了——直接跟它说「等你的队友完成任务后再继续」。

什么时候该用、什么时候别用

新手建议从只读任务开始：审 PR、调研一个库、查一个 bug。这类任务边界清楚、不写代码，能让你直观感受到并行探索的价值，又不用一上来就处理并行写代码的冲突问题。

Agent Teams 把「一个人指挥一个 AI」变成了「一个人指挥一支 AI 团队」，但它放大的不只是产能，还有你拆任务的能力和上下文管理的水平——任务拆不干净，五个队友只会更快地把项目搞乱。想系统地把 Claude Code 的 Subagents、Hooks、Skills、上下文工程这一整套用法练成肌肉记忆，欢迎来 IMAI 看看我们的实战课程。