编排多个 Claude Code 会话组成的团队

协调多个 Claude Code 实例作为一个团队协同工作，具备共享任务、智能体间通信和集中管理能力。

智能体团队让你可以协调多个协同工作的 Claude Code 实例。其中一个会话充当团队负责人，负责协调工作、分配任务并汇总结果。团队成员各自独立工作，每个都拥有自己的上下文窗口，并可直接互相通信。

与只能在单个会话内运行、只能向主智能体报告的子智能体不同，你也可以直接与各个团队成员互动，而不必通过负责人。

何时使用智能体团队

智能体团队最适合那些并行探索能带来真正价值的任务。完整场景请参阅使用场景示例。最有说服力的使用场景包括：

• 调研与审查：多个团队成员可以同时调查一个问题的不同方面，然后分享并互相质疑对方的发现
• 新模块或新功能：每个团队成员可以各自负责一块独立的部分，互不干扰
• 用相互竞争的假设进行调试：团队成员并行验证不同的理论，更快地收敛到答案
• 跨层协调：涉及前端、后端和测试的变更，各由不同的团队成员负责

智能体团队会带来协调开销，且消耗的 Token 显著多于单个会话。当团队成员能够独立工作时，效果最好。对于顺序性任务、编辑同一文件的任务，或依赖关系繁多的工作，单个会话或子智能体更为有效。

与子智能体的比较

智能体团队和子智能体都能让你并行处理工作，但两者的运作方式不同。根据你的工作者是否需要互相通信来做选择：

当你需要快速、专注、能报告结果的工作者时，使用子智能体。当团队成员需要分享发现、互相质疑并自主协调时，使用智能体团队。

启用智能体团队

智能体团队默认关闭。要启用它，请将 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 环境变量设为 1，可以在 shell 环境中设置，也可以通过 settings.json 设置：

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

启动你的第一个智能体团队

启用智能体团队后，用自然语言描述任务和你想要的团队成员。Claude 会根据你的提示词生成他们并协调工作。

以下示例效果很好，因为这三个角色相互独立，可以在不等待对方的情况下探索问题：

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

之后，Claude 会填充一份共享任务列表，为每个视角生成一个团队成员，让他们去探索问题，并在完成后汇总各方发现。

负责人终端会在提示输入框下方的智能体面板中列出团队成员。在该面板中：

• 上下方向键：选择一个团队成员
• Enter：打开选中团队成员的记录，并直接给它发消息
• Escape：中断选中团队成员当前的轮次

从 v2.1.199 开始，只要有任何团队成员或子智能体仍在工作，一个闲置团队成员的行就会留在面板中，因此你可以选中它查看其记录或给它派发更多工作。一旦面板中的每个智能体都闲置下来，闲置行会在 30 秒后隐藏，并在该团队成员进入下一轮次时重新出现；隐藏期间该团队成员仍在运行，且可被寻址。在 v2.1.181 到 v2.1.198 之间，一个闲置行会在其自身轮次结束 30 秒后隐藏，即使其他团队成员仍在工作；在 v2.1.181 之前的版本上，闲置行不会被隐藏。

当同时有超过三个团队成员闲置时，前三个之外的行会折叠为一行，统计被折叠的团队成员数量，例如五个闲置时显示为 2 idle agents。选中它并按 Enter 可展开折叠的行，按 Esc 可再次折叠它们。正在工作的团队成员、失败的团队成员，以及你正在查看的团队成员，始终保留各自独立的行。

如果你想让每个团队成员都拥有自己独立的分屏面板，请参阅选择显示模式。

控制你的智能体团队

用自然语言告诉负责人你想要什么。它会根据你的指示处理团队协调、任务分配和委派工作。

选择显示模式

智能体团队支持两种显示模式：

• 进程内（In-process）：所有团队成员都在你的主终端内运行。在智能体面板中用上下方向键选择一个团队成员，按 Enter 查看它，直接输入即可给它发消息。适用于任何终端，无需额外设置。
• 分屏（Split panes）：每个团队成员各自拥有一个面板。你可以同时看到每个人的输出，点击某个面板即可直接与之交互。需要 tmux 或 iTerm2。

默认值是 "in-process"。在 v2.1.179 之前，默认值是 "auto"，因此之前会打开分屏的已升级会话，现在会停留在单个终端中，除非你显式设置模式。设为 "auto"，可以在你已经处于一个 tmux 会话中时，或你的终端是安装了 it2 CLI 的 iTerm2 时启用分屏，否则回退为进程内模式。"tmux" 设置会启用分屏模式，并根据你的终端自动检测使用 tmux 还是 iTerm2。

从 v2.1.186 开始，设为 "iterm2" 可显式使用 iTerm2 原生分屏。此模式需要 it2 CLI，如果缺少 it2，会显示一条带安装命令的错误。当你的终端是 iTerm2、且 tmux 可作为回退方案时，在 "auto" 或 "tmux" 下会出现提示，询问是否安装 it2 或切换到 tmux。

要覆盖默认值，在 ~/.claude/settings.json 中设置 teammateMode：

{
  "teammateMode": "auto"
}

要为单次会话设置模式，可作为标志传入：

claude --teammate-mode auto

分屏模式需要 tmux，或安装了 it2 CLI 的 iTerm2。手动安装方式：

• tmux：通过你系统的包管理器安装。关于各平台的具体说明，请参阅 tmux wiki。
• iTerm2：安装 it2 CLI，然后在 iTerm2 → Settings → General → Magic → Enable Python API 中启用 Python API。

指定团队成员和模型

Claude 会根据你的任务决定要生成多少团队成员，你也可以精确指定你想要的内容：

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

团队成员默认不会继承负责人的 /model 选择。要更改提示词未指定模型时使用的模型，可在 /config 中设置 Default teammate model。选择 Default (leader's model)，可让团队成员跟随负责人当前的模型。

团队成员会继承负责人的effort 级别。在分屏模式下，这一点从 v2.1.186 开始生效；更早的版本不会将负责人会话的 effort 传递给分屏中的团队成员。

要求团队成员先获得计划批准

对于复杂或高风险的任务，你可以要求团队成员先做计划再实施。该团队成员会以只读的计划模式工作，直到负责人批准其方案：

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

当一个团队成员完成计划后，会向负责人发送一份计划批准请求。负责人会审阅该计划，然后批准，或附带反馈拒绝它。如果被拒绝，该团队成员会留在计划模式中，根据反馈修改后重新提交。一旦获得批准，该团队成员会退出计划模式并开始实施。

负责人会自主做出批准决定。要影响负责人的判断，可以在提示词中给出评判标准，例如“只批准包含测试覆盖的计划”，或“拒绝修改数据库模式的计划”。

直接与团队成员交流

每个团队成员都是一个完整、独立的 Claude Code 会话。你可以直接给任何团队成员发消息，提供额外指示、追问，或调整其方案。

• 进程内模式：在智能体面板中用上下方向键选择一个团队成员，按 Enter 查看其会话，直接输入即可给它发消息。在选中某个团队成员时按 x 可停止它。按 Ctrl+T 可切换任务列表的显示。
• 分屏模式：点击某个团队成员的面板，即可直接与其会话交互。每个团队成员都拥有自己终端的完整视图。

当你正在查看某个进程内团队成员时，普通文本和技能会发给该团队成员，但内置命令仍在负责人的会话中运行。

一个团队成员的模型和快速模式在其生成时就已固定，因此 /model 和 /fast 只会更改负责人的设置。从 v2.1.199 开始，在查看某个团队成员时输入这两个命令中的任一个，会显示一条提示，说明该更改应用到的是负责人；更早的版本会悄悄将其应用到负责人，没有任何提示。/effort 仍会应用于所查看团队成员之后的轮次，因为团队成员会遵循负责人的effort 级别。

分配与认领任务

共享任务列表用于协调整个团队的工作。负责人创建任务，团队成员逐一处理它们。任务有三种状态：待处理、进行中和已完成。任务之间还可以存在依赖关系：一个存在未解决依赖的待处理任务，在这些依赖完成之前无法被认领。

负责人可以显式分配任务，团队成员也可以自行认领：

• 负责人分配：告诉负责人把哪个任务交给哪个团队成员
• 自行认领：完成一个任务后，团队成员会自行接手下一个未分配、且未被阻塞的任务

任务认领使用文件锁定机制，以防止多个团队成员同时尝试认领同一个任务时发生竞态条件。

关闭团队成员

要优雅地结束某个团队成员的会话，按名称指代它。例如，对于名为 researcher 的团队成员：

Ask the researcher teammate to shut down

负责人会发送一个关闭请求。该团队成员可以批准并优雅退出，也可以附带说明拒绝。

会话结束时，团队的共享目录会自动清理，因此不需要单独的清理步骤。关于哪些目录会被移除、哪些会为恢复的会话保留，请参阅架构。

用钩子强制执行质量门禁

使用钩子，可以在团队成员完成工作、或任务被创建或完成时强制执行规则：

• TeammateIdle：在某个团队成员即将闲置时运行。以退出码 2 退出可发送反馈并让该团队成员继续工作。
• TaskCreated：在某个任务被创建时运行。以退出码 2 退出可阻止创建并发送反馈。
• TaskCompleted：在某个任务被标记为完成时运行。以退出码 2 退出可阻止完成并发送反馈。

智能体团队的工作原理

本节介绍智能体团队背后的架构和运作机制。如果你想开始使用它们，请参阅上面的控制你的智能体团队。

Claude 如何启动智能体团队

当第一个团队成员被生成时，一个智能体团队就形成了，主会话充当负责人。有两种方式可以生成团队成员：

• 你请求团队成员：给 Claude 一个能从并行工作中获益的任务，并明确要求团队成员。Claude 会根据你的指示生成他们。
• Claude 提议团队成员：如果 Claude 判断你的任务能从并行工作中获益，它可能会建议生成团队成员。你需要在它继续之前确认。

无论哪种方式，你始终掌控全局。未经你的批准，Claude 不会生成团队成员。

架构

一个智能体团队由以下部分组成：

关于显示配置选项，请参阅选择显示模式。团队成员的消息会自动送达负责人。

系统会自动管理任务依赖关系。当一个团队成员完成了其他任务所依赖的某个任务时，被阻塞的任务会自动解除阻塞，无需人工干预。

团队和任务以本地方式存储，使用一个由会话派生的名称。该名称是 session- 后跟会话 ID 的前八个字符：

• 团队配置：~/.claude/teams/{team-name}/config.json
• 任务列表：~/.claude/tasks/{team-name}/

Claude Code 会在会话启动时自动生成这两者，并在团队成员加入、闲置或离开时更新它们。团队配置目录会在会话结束时被移除。任务列表目录会在本地持久保存，且从不上传，因此被恢复的会话仍会保留其任务。保留期限由你已经在为会话记录使用的同一个 cleanupPeriodDays 设置控制。

团队配置中保存的是运行时状态，例如会话 ID 和 tmux 面板 ID，因此请不要手动编辑它或预先编写它：你的更改会在下一次状态更新时被覆盖。

要定义可复用的团队成员角色，请改用子智能体定义。

团队配置包含一个 members 数组，其中记录了每个团队成员的名称、智能体 ID 和智能体类型。团队成员可以读取这个文件来发现其他团队成员。

团队配置没有项目级的对应物。项目目录中类似 .claude/teams/teams.json 的文件不会被识别为配置；Claude 会将其视为一个普通文件。

为团队成员使用子智能体定义

生成一个团队成员时，你可以引用来自任意子智能体范围（项目、用户、插件，或 CLI 定义）的子智能体类型。这让你可以只定义一次角色（例如 security-reviewer 或 test-runner），既可作为被委派的子智能体使用，也可作为智能体团队的团队成员使用。

要使用一个子智能体定义，在让 Claude 生成该团队成员时按名称提及它：

Spawn a teammate using the security-reviewer agent type to audit the auth module.

该团队成员会遵循该定义的 tools 允许列表和 model，该定义的正文会作为附加指令追加到该团队成员的系统提示词中，而不是替换它。像 SendMessage 之类的团队协调工具和任务管理工具，即使 tools 限制了其他工具，对团队成员始终可用。

权限

团队成员启动时使用负责人的权限设置。如果负责人以 --dangerously-skip-permissions 运行，所有团队成员也会如此。生成之后，你可以更改单个团队成员的模式，但无法在生成时为各个团队成员单独设置模式。

当一个智能体通过 SendMessage 向另一个发消息时，接收方会被告知该消息来自另一个 Claude 会话，而不是来自你。团队成员不能代表你批准权限提示或提供同意，一个被拒绝执行某操作的团队成员也不能把它转发给另一个团队成员来绕过该检查。在自动模式下，分类器会把来自另一个智能体转发的批准声明当作不可信的输入处理，而不是当作你本人的确认。团队成员的权限提示会浮现到负责人会话中，请在那里亲自批准它们。

上下文与通信

每个团队成员都拥有自己的上下文窗口。生成时，一个团队成员会加载与常规会话相同的项目上下文：CLAUDE.md、MCP 服务器和技能。它还会收到负责人给出的生成提示词。负责人的对话历史不会带过去。

团队成员之间如何共享信息：

• 自动消息送达：当团队成员发消息时，会自动送达给收件人。负责人不需要轮询获取更新。
• 闲置通知：当一个团队成员完成工作并停止时，会自动通知负责人。从 v2.1.198 开始，一个因 API 错误而结束轮次的团队成员，会通知负责人它失败了，并附上错误文本，而不是显示为正常完成。
• 共享任务列表：所有智能体都能看到任务状态并认领可用的工作。
• 团队成员消息：按名称给某个特定团队成员发消息。要触及所有人，需要对每个收件人各发一条消息。

负责人在生成每个团队成员时都会给其分配一个名称，任何团队成员都可以用该名称给其他任何团队成员发消息。要得到可以在之后的提示词中引用的、可预测的名称，请在你的生成指示中告诉负责人该如何称呼每个团队成员。

Token 用量

智能体团队消耗的 Token 显著多于单个会话。每个团队成员都拥有自己的上下文窗口，Token 用量会随活跃团队成员数量增长。对于调研、审查和新功能开发这类工作，额外的 Token 通常是值得的。对于日常任务，单个会话更具成本效益。关于用量指导，请参阅智能体团队的 Token 成本。

使用场景示例

以下示例展示了智能体团队如何处理那些并行探索能带来价值的任务。

运行一次并行代码审查

单个审查者往往会在某一时刻只专注于一类问题。把审查标准拆分为独立的领域，意味着安全性、性能和测试覆盖可以同时得到充分关注。以下提示词为每个团队成员分配了一个明确的视角，避免重叠：

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

每位审查者面对的是同一个 PR，但应用不同的过滤视角。他们完成后，负责人会汇总三方的发现。

用相互竞争的假设进行调查

当根本原因不明确时，单个智能体往往会找到一个看似合理的解释就停止继续调查。以下提示词通过让团队成员明确地相互对抗来对抗这种倾向：每个团队成员的任务不仅是调查自己的理论，还要挑战其他人的理论。

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

这种辩论式结构正是这里的关键机制。顺序式调查会受到锚定效应的影响：一旦某个理论被探索过，后续的调查就会偏向它。

有多个独立的调查者主动尝试推翻彼此的理论时，最终存活下来的那个理论，更有可能就是真正的根本原因。

最佳实践

为团队成员提供足够的上下文

团队成员会自动加载项目上下文，包括 CLAUDE.md、MCP 服务器和技能，但不会继承负责人的对话历史。详情请参阅上下文与通信。在生成提示词中包含任务特定的细节：

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

选择合适的团队规模

团队成员数量没有硬性上限，但存在实际的限制：

• Token 成本呈线性增长：每个团队成员都拥有自己的上下文窗口，独立消耗 Token。详情请参阅智能体团队的 Token 成本。
• 协调开销会增加：团队成员越多，意味着更多的通信、任务协调，以及潜在的冲突
• 收益递减：超过一定规模后，增加团队成员不会等比例加快工作速度

大多数工作流建议从 3 到 5 个团队成员开始。这在并行工作与可管理的协调开销之间取得了平衡。本指南中的示例使用 3 到 5 个团队成员，因为这个范围在不同类型的任务上都表现良好。

每个团队成员分配 5 到 6 个任务，能让大家保持高效，而不会过度切换上下文。如果你有 15 个独立任务，3 个团队成员是一个不错的起点。

只在工作确实能从团队成员同时工作中获益时才扩大规模。三个专注的团队成员往往比五个分散的团队成员表现更好。

合理拆分任务规模

• 太小：协调开销超过收益
• 太大：团队成员长时间工作而不进行检查点确认，增加了浪费精力的风险
• 恰到好处：能产出明确交付物的自包含单元，例如一个函数、一个测试文件或一次审查

等待团队成员完成

有时负责人会自己动手开始实施任务，而不是等待团队成员。如果你注意到这种情况：

Wait for your teammates to complete their tasks before proceeding

从调研和审查开始

如果你刚开始使用智能体团队，可以从边界清晰、不需要编写代码的任务开始：审查一个 PR、调研一个库，或调查一个 bug。这些任务能展示并行探索的价值，而不会带来并行实施所伴随的协调难题。

避免文件冲突

两个团队成员编辑同一个文件会导致相互覆盖。请拆分工作，让每个团队成员负责一组不同的文件。

监控并引导

关注团队成员的进展，纠正不奏效的方案，并及时汇总陆续到来的发现。让团队长时间无人看管地运行，会增加浪费精力的风险。

故障排查

团队成员没有出现

如果你让 Claude 生成团队成员后，他们没有出现：

• 在进程内模式下，团队成员会出现在提示输入框下方的智能体面板中。用上下方向键选择其中一个，按 Enter 查看它。
• 一个闲置后消失的团队成员行是被隐藏了，而不是被停止了。闲置行会在整个面板闲置 30 秒后隐藏，并在该团队成员进入下一轮次时重新出现。当超过三个团队成员闲置时，多出的那些行会折叠为一行 N idle agents，按 Enter 可展开。按名称给该团队成员发消息，即可让隐藏的行重新出现。
• 检查你给 Claude 的任务是否足够复杂，值得组建一个团队。Claude 会根据任务决定是否生成团队成员。
• 如果你明确要求了分屏，请确认 tmux 已安装并在你的 PATH 中可用：
  Copy

  which tmux
• 对于 iTerm2，请确认已安装 it2 CLI，并在 iTerm2 偏好设置中启用了 Python API。

权限提示过多

团队成员的权限请求会浮现到负责人那里，这可能造成干扰。在生成团队成员之前，先在权限设置中预先批准常见操作，以减少打断。

团队成员遇到错误就停止

团队成员在遇到错误后可能会停止，而不是自行恢复。在进程内模式下，在智能体面板中选中该团队成员并按 Enter，或在分屏模式下点击其面板，查看其输出，然后：

• 直接给它们提供额外指示
• 生成一个替补团队成员继续这项工作

从 v2.1.198 开始，来自负责人或另一个团队成员的消息，会唤醒一个正在等待重试失败 API 请求的进程内团队成员，使其立即重试，而不必等待完整的重试延迟。

负责人在工作完成前就关闭团队

负责人可能在所有任务实际完成之前就判断团队已经完成。如果发生这种情况，告诉它继续下去。如果它开始自己动手做工作而不是委派，你也可以告诉负责人在继续之前先等待团队成员完成。

遗留的 tmux 会话

如果一个 tmux 会话在 Claude Code 会话结束后仍然存在，可能是没有被完全清理。列出会话并结束由该团队创建的那一个：

tmux ls
tmux kill-session -t <session-name>

限制

智能体团队是实验性功能。需要注意的当前限制：

• 进程内团队成员不支持会话恢复：/resume 和 /rewind 不会恢复进程内团队成员。恢复会话后，负责人可能会尝试给已不存在的团队成员发消息。如果发生这种情况，告诉负责人生成新的团队成员。
• 任务状态可能滞后：团队成员有时无法将任务标记为已完成，这会阻塞依赖它的任务。如果某个任务看起来卡住了，检查该工作是否实际已经完成，手动更新任务状态，或告诉负责人去催促该团队成员。
• 关闭可能较慢：团队成员会先完成当前的请求或工具调用再关闭，这可能需要一些时间。
• 每个会话只能有一个团队：一个会话恰好拥有一个团队，且限定于该会话。你无法创建额外的命名团队，也无法在多个会话之间共享一个团队。
• 不支持嵌套团队：团队成员不能生成自己的团队成员。只有负责人才能管理该团队。
• 进程内团队成员不能生成后台子智能体：一个进程内团队成员自己的子智能体会在前台运行。无论是通过 run_in_background，还是通过设置了 background: true 的子智能体定义来请求一个后台子智能体，都会返回错误，因为团队成员的后台工作无法比负责人的进程活得更久。从主对话启动的子智能体则遵循后台默认设置。
• 负责人是固定的：主会话在其整个生命周期内都是负责人。你无法将某个团队成员提升为负责人，也无法转移负责人身份。
• 权限在生成时设定：所有团队成员启动时都使用负责人的权限模式。生成之后你可以更改单个团队成员的模式，但无法在生成时为各个团队成员单独设置模式。
• 分屏需要 tmux 或 iTerm2：默认的进程内模式适用于任何终端。分屏模式在 VS Code 的集成终端、Windows Terminal 或 Ghostty 中不受支持。

后续步骤

探索用于并行工作和委派的相关方式：

• 轻量级委派：子智能体在你的会话内生成辅助智能体用于调研或验证，更适合不需要智能体间协调的任务
• 手动并行会话：Git worktree 让你可以自己运行多个 Claude Code 会话，而无需自动化的团队协调
• 比较各种方式：请参阅子智能体与智能体团队的对比，了解详细的逐项比较