目录

当你想在 Claude Code 中让多个 AI 分工协作时，存在两个相似却不同的机制——Subagents 和 Agent Teams。名称容易混淆，但它们的角色和协调方式有着根本性的不同。本文将基于官方文档，梳理两者各自的本质、决定性的差异、该用哪一个，以及如何使用。

先说最关键的三点。（1）Subagents 是内置功能——主智能体把一个专注的子任务委派给「拥有全新上下文的助手」，并只取回一份摘要（层级式、用完即弃）。（2）Agent Teams 是实验性的、需主动开启的功能，默认关闭。只有当你设置了 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 之后才能使用——多个独立会话通过共享任务列表「对等地」协作（点对点、持久化）。（3）「嵌套 5 层」是 Subagents 的特性；Agent Teams 无法嵌套（它们是扁平的）——不要把两者混为一谈。

CLAUDE CODE · SUBAGENTS vs TEAMS

层级式，还是对等？

— 委派并取回摘要，还是作为同伴对等协作

Subagents（内置）
主智能体
↓ 委派 / ↑ 仅摘要
助手
助手
助手
层级式 · 用完即弃 · 彼此不交流
Agent Teams（实验性）
team lead
同伴
同伴
↔ 共享任务列表 ＋ 消息传递 ↔
对等 · 持久 · 可分别操控（需标志）

Subagents：主智能体把任务交给助手并取回结果。Agent Teams：对等的同伴通过共享任务列表协作。
Teams 是默认关闭的实验性功能——必须设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。

1. 什么是 Subagents

Subagents 是在单个会话内处理特定类型工作的专用智能体。根据官方文档，「每个 subagent 都运行在自己的上下文窗口中，拥有自定义系统提示词和特定的工具权限。」主智能体会基于每个 subagent 的 description 自动委派，subagent 独立完成工作，并只向主对话返回一份摘要。

关键在于「每个 subagent 都运行在全新的、独立的上下文中」——它看不到你的对话历史，也看不到你已经读过的文件。因此你可以让它在「外部」完成繁重的查找工作，只取回结论，而不会让日志或测试输出淹没你的主上下文。用 /agents（Running / Library 标签页）来管理它们。在 .claude/agents/<name>.md 中以 YAML 前置元数据（name / description / tools / model）来定义它们。内置的有 Explore（Haiku、只读）、Plan 和 general-purpose。Subagents 可以嵌套，最多 5 层（在第 5 层时不会再传入 Agent tool，因此无法继续派生）。要了解更宏观的图景，请参阅什么是多智能体系统。

2. 什么是 Agent Teams（实验性、需开启标志）

Agent Teams 让你把多个 Claude Code 会话作为一个「团队」来协作。其中一个是 team lead（负责协调、分配、汇总）；其余的是 teammates（同伴）——每一个都是自己独立的会话和上下文——它们通过共享任务列表和一个 mailbox（信箱）彼此直接通信。与 subagents 不同，你可以直接和单个 teammate 对话。

重要：Agent Teams 是默认关闭的实验性功能

官方文档明确指出「Agent Teams 是实验性的，默认关闭。」要使用它，需设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1（或通过 settings.json 的 env）。否则，启动时不会创建任何团队，Claude 也不会提议或派生 teammates。

需要注意，v2.1.178 的变更只是「移除了 TeamCreate/TeamDelete 这一设置步骤，因此在设置了标志的情况下，每个会话都会隐式拥有一个团队」——它并没有「默认启用团队」。标志仍然是必需的。

3. 决定性的差异

并排来看，两者的协调方式完全不同。

SubagentsAgent Teams
协调方式层级式（主智能体委派、汇总结果）点对点（通过共享任务列表自主协调）
通信方式仅向调用方回报（彼此从不交流）teammates 通过 mailbox 彼此直接传消息
持久性用完即弃（任务后返回一份摘要）持久的独立会话（可直接操控）
上下文各自的全新上下文；摘要返回给主智能体完全独立（不会自动汇总回去）
Token 成本相对较低高（每个 teammate 都是独立的 Claude 实例）
状态内置、始终可用实验性、需开启标志、默认关闭
嵌套Subagents 可嵌套最多 5 层不可嵌套（teammates 无法派生 teammates）

一句话概括：Subagents ＝「主智能体把一个专注的任务交给拥有全新上下文的助手，并取回结论（层级式、用完即弃、仅摘要）。」 Agent Teams ＝「多个持久会话通过共享任务列表和消息传递协作，且你可以分别操控每一个（对等、独立）。」一个常见的误解：「5 层嵌套」是 Subagents 的特性，而 Teams 是扁平的（不可嵌套）。

4. 你该用哪一个

按用途来挑，就不会纠结。大多数日常工作用 subagents（或单个会话）就足够了。

WHICH TO USE

按用途选择

适合用 Subagents 的场景
· 副任务会淹没你的主上下文（测试/日志/调研）
· 工作自成一体，只有结果重要
· 你想限制工具或用更便宜的模型
· 工作者之间无需交流
适合用 Agent Teams 的场景
· 工作者必须共享发现、相互质疑、自主协调
· 并行探索有回报（并行评审 / 对立假设调试 / 多模块）
· 你想分别操控每个工作者
（接受更高成本 ＋ 需开启标志）
单个会话就够用的场景
· 任务是顺序进行的
· 你需要频繁来回沟通
· 它触及同一批文件
· 它是个快速的本地改动

默认遵循「拿不准时，就用单个会话或 subagents。」
只有当并行工作真正需要对等协调时，才动用 Agent Teams。

5. 使用速查表

命令与配置的快速参考。

# --- Subagents (built-in) ---
/agents                      # 管理界面（Running / Library）
.claude/agents/<name>.md      # 项目定义（name/description/tools/model）
~/.claude/agents/<name>.md    # 用户定义（所有项目）
claude --agent code-reviewer # 将整个会话作为某个特定 subagent 运行
@agent-<name>                 # 用 @ 提及来显式调用

# --- Agent Teams (experimental, flag-gated) ---
# 通过 env（或 settings.json 的 env）启用；默认关闭
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
# 然后用自然语言描述，例如：「派出三个 teammates 来评审 PR #142：
#   一个看安全，一个看性能，一个看测试覆盖率。」
# 通过 teammateMode 显示（默认 in-process；分屏需要 tmux/iTerm2）

在 subagent 的定义文件中，你可以用 tools 限制工具，或用 model 把任务路由到像 haiku 这样更轻量的模型。关于构建和设计智能体，请参阅如何构建多智能体系统和如何构建 AI 智能体。

6. Agent Teams 的注意事项

Agent Teams 很强大，但带有实验阶段的限制和成本。在采用它之前，先了解这些。

（1） 每个会话一个团队，不可嵌套——teammates 无法派生 teammates，且 lead 是固定的。（2） Token 用量高（每个 teammate 都是独立的 Claude 实例）；推荐为 3-5 个 teammates。 （3） teammates 不会在 worktree 中隔离，所以如果它们触及同一批文件就会互相覆盖——需手动划分文件。 （4） 作为实验性功能，存在一些限制，比如 /resume 和 /rewind 无法恢复 in-process 的 teammates。（5） 分屏显示需要 tmux 或 iTerm2（像 VS Code 自带的等部分终端不受支持）。简而言之，只在并行协调的收益大于其成本和精力时才使用它。

总结

Claude Code 的 subagents 和 Agent Teams 都是「在多个 AI 之间分工」，但它们的协调模型不同。Subagents 是内置的——主智能体把一个专注的任务委派给拥有全新上下文的助手，并只取回一份摘要（层级式、用完即弃、彼此不交流、最多嵌套 5 层）。Agent Teams 是实验性的、需主动开启，默认关闭（需要 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1）——多个独立会话通过共享任务列表和消息传递对等协作（持久、可分别操控、不可嵌套）。

如何选择：「只想要结果 / 不想污染上下文 → subagents」「工作者必须共享并协调的并行工作 → Agent Teams」「顺序进行 / 同一批文件 / 快速修复 → 单个会话」。一个常见的混淆：「5 层嵌套」是 subagents 的特性；Teams 是扁平的。另外请注意，v2.1.178 精简了团队启动——它并没有「默认启用」。Teams 成本高且实验性，所以请把它限定在协调能带来回报的场景。相关阅读：什么是多智能体系统、如何构建、AI 可观测性。

FAQ

Q. Subagents 和 Agent Teams 有何不同？
A. 它们的协调方式有着根本性的不同。Subagents 是层级式的——主智能体把一个专注的任务委派给拥有全新上下文的助手，并只取回一份摘要（助手之间彼此不交流；用完即弃）。Agent Teams 是点对点的——多个独立会话通过共享任务列表和一个 mailbox 协作，且你可以分别操控每一个（持久）。Subagents 是内置的；Agent Teams 是实验性的，需要一个标志。

Q. 我能立刻使用 Agent Teams 吗？
A. 不能——它们默认关闭。你必须在 env（或 settings.json 的 env）中设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。v2.1.178 只是精简了启动流程（它「移除了 TeamCreate 这一设置步骤，因此在设置了标志的情况下，每个会话都会隐式拥有一个团队」）——它并没有「默认启用团队」。标志仍然是必需的。

Q. 「最多嵌套 5 层」指的是哪一个？
A. Subagents。一个 subagent 可以派生出自己的 subagents，最多 5 层深（在第 5 层时无法再深入）。Agent Teams 无法嵌套——teammates 无法派生 teammates，且只有 lead 管理团队。不要把两者混为一谈。

Q. 我分不清该用哪一个。
A. 大多数情况下，单个会话或 subagents 就够了。如果你只想要结果，且不想让大量输出淹没你的主上下文，就用 subagents。如果在并行工作中工作者必须共享发现、交叉核对、自主协调（并行评审、对立假设调试、多模块开发），且你想分别操控，就用 Agent Teams。对于顺序进行的工作、频繁来回沟通、或触及同一批文件的情况，单个会话更合适。

Q. 使用 Agent Teams 时该注意什么？
A. Token 用量高（每个 teammate 都是独立实例；推荐 3-5 个）、每个会话一个团队且不可嵌套、teammates 不会在 worktree 中隔离所以在同一批文件上会冲突（需手动划分）、/resume 和 /rewind 的实验性限制，以及分屏需要 tmux/iTerm2。只在协调的收益大于其成本的并行工作中使用它。