Claude Code 多实例团队协作：Agent Teams 配置与排错指南 #

Agent Teams 让多个 Claude Code 实例以团队形式协同工作，队员各有独立上下文且可直接相互通信，适合并行研究、跨模块开发等需要深度讨论的场景。启用后在 settings.json 中设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1，然后使用自然语言创建团队；通过 Shift+Down 切换队员，支持 in-process 和 split-panes 两种显示模式。队员不出现时先按 Shift+Down 查看，或在已有 tmux 会话中自动启用分屏。

实验性功能，默认关闭。 在 settings.json 中设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 后启用。

Agent Teams 让多个 Claude Code 实例协同工作：一个会话作为团队领导，协调分配任务、汇总结果；队员独立运行，各有自己的上下文窗口，并可以直接相互通信。

需要 Claude Code v2.1.32 或更高版本，用 claude --version 确认。

Agent Teams 适合哪些场景 #

并行探索能带来真正价值的场景最有效。典型使用场景：

• 研究与审查：多个队员同时研究问题的不同方面，分享并挑战彼此发现
• 新模块或功能：队员各自负责独立部分，互不干扰
• 调试竞争假设：队员并行测试不同理论，更快收敛到答案
• 跨层协调：变更涉及前端、后端和测试，每个队员负责不同层

Agent Teams 会引入协调开销，Token 消耗显著高于单个会话。队员最好能独立操作。顺序任务、同文件编辑或依赖关系多的工作，单个会话或子代理更合适。

和子代理的区别 #

子代理只能向主代理汇报结果，队员无法相互通信。Agent Teams 中队员共享任务列表，可以互相认领任务并直接通信。

子代理用于需要快速、专注执行者的场景。Agent Teams 用于队员需要共享发现、互相挑战、自主协调的场景。

Agent Teams 启用步骤 #

Agent Teams 默认关闭。在 settings.json 中添加：

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

或者设置环境变量：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

怎么创建你的第一个 Agent 团队 #

启用后，用自然语言告诉 Claude 创建一个团队：

我正在设计一个帮助开发者跟踪代码库 TODO 注释的 CLI 工具。
创建一个 Agent 团队从不同角度探索这个问题：
一个负责用户体验，一个负责技术架构，一个扮演唱反调的角色。

Claude 会创建团队，领导终端会列出所有队员和工作内容。使用 Shift+Down 在队员间循环切换，直接输入文字发消息。切换到最后一名队员后，Shift+Down 会回到领导。

要使用分屏显示，见 选择显示模式。

怎么控制你的 Agent 团队 #

用自然语言告诉领导你需要的操作，它负责协调、分配和委托。

选择显示模式 #

Agent Teams 支持两种显示模式：

• in-process（进程内模式）：所有队员在主终端内运行。使用 Shift+Down 循环切换队员并直接发消息。任何终端都可用，无需额外配置。
• split-panes（分屏模式）：每个队员有独立窗格，可以看到所有输出，点击窗格直接交互。需要 tmux 或 iTerm2。

tmux 在某些操作系统上有已知限制，传统上在 macOS 上表现最好。在 iTerm2 中使用 tmux -CC 是推荐的 tmux 入口。

默认值为 "auto"，如果你已经在 tmux 会话内运行则使用分屏，否则使用 in-process。"tmux" 设置启用分屏模式并根据终端自动检测使用 tmux 还是 iTerm2。要覆盖，在 ~/.claude/settings.json 中设置：

{
  "teammateMode": "in-process"
}

要强制某个会话使用 in-process 模式，传递命令行参数：

claude --teammate-mode in-process

分屏模式需要 tmux 或 iTerm2 的 it2 CLI。安装方法：

• tmux：通过系统包管理器安装，参见 tmux wiki
• iTerm2：安装 it2 CLI，然后在 iTerm2 → Settings → General → Magic → Enable Python API 中启用 Python API

指定队员和模型 #

Claude 根据任务决定队员数量，你也可以精确指定：

创建一个 4 人团队并行重构这些模块，每个队员使用 Sonnet。

队员默认不继承领导的 /model 选择。要更改未指定模型时使用的模型，在 /config 中设置 Default teammate model。选择 Default (leader’s model) 让队员跟随领导当前模型。

要求计划审批 #

对于复杂或高风险任务，要求队员在实施前先制定计划。队员以只读计划模式工作，直到领导批准：

生成一个架构师队员来重构认证模块。
要求在做任何修改前先审批计划。

队员完成计划后向领导发送审批请求。领导审查并通过或拒绝。拒绝时队员留在计划模式，根据反馈修订后重新提交。批准后队员退出计划模式并开始实施。

领导自主决策。要引导判断，在提示词中给出标准，例如“只批准包含测试覆盖的计划”或“拒绝修改数据库 Schema 的计划”。

直接与队员通信 #

每个队员都是完整的独立 Claude Code 会话。你可以直接给队员发消息，给出额外指令、追问或调整方向。

• in-process 模式：Shift+Down 切换到队员，输入文字发消息。按 Enter 查看队员会话，按 Escape 中断当前轮次。按 Ctrl+T 切换任务列表。
• split-pane 模式：点击队员窗格直接交互，每个队员有自己的完整终端视图。

分配和认领任务 #

共享任务列表协调团队工作。领导创建任务，队员逐一处理。任务状态有三种：待处理、进行中、已完成。任务可以有依赖关系：依赖未解决的任务不能被认领。

领导可以显式分配任务，队员也可以自行认领：

• 领导分配：告诉领导把任务给哪个队员
• 自行认领：完成任务后，队员自动认领下一个未指派、未被阻塞的任务

任务认领使用文件锁定，防止多个队员同时尝试认领相同任务。

关闭队员 #

优雅地结束队员会话：

让研究员队员关闭

领导发送关闭请求，队员可以批准（平稳退出）或拒绝（带解释）。

清理团队 #

结束所有工作后让领导清理：

清理团队

这移除共享团队资源。运行时领导会检查活跃队员，如果仍有队员在运行则失败，所以先关闭所有队员。

始终用领导清理。 队员不应执行清理，因为团队上下文可能解析不正确，导致资源处于不一致状态。

用 Hooks 强制质量门控 #

使用 hooks 在队员完成工作或任务创建/完成时强制执行规则：

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

Agent Teams 的工作原理 #

启动方式 #

Agent Teams 有两种启动方式：

• 你主动请求：明确定义需要并行工作的任务并请求创建团队，Claude 按指令创建。
• Claude 主动建议：如果 Claude 判断任务适合并行，可能会建议创建团队。你确认后才会继续。

两种情况下你都在掌控中，Claude 不会未经批准创建团队。

架构 #

一个 Agent Team 包含以下组件：

团队配置和任务存储在本地：

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

Claude Code 自动生成这些文件，队员加入、闲置或离开时实时更新。团队配置包含运行时状态（如会话 ID 和 tmux 窗格 ID），不要手工编辑或预先授权，否则下次状态更新会覆盖。

团队配置中的 members 数组包含每个队员的姓名、代理 ID 和代理类型。队员可以读取该文件发现其他团队成员。

项目目录下没有等效配置。.claude/teams/teams.json 不会被识别为配置，Claude 将其视为普通文件。

用子代理定义作为队员 #

生成队员时可以引用 子代理 定义，从项目、用户、插件或 CLI 定义范围中选择。这样可以定义一次角色（如 security-reviewer 或 test-runner），同时用于子代理委托和 Agent Team 队员：

生成一个使用 security-reviewer 代理类型的队员来审计 auth 模块。

队员遵守该定义的 tools 白名单和 model，定义的正文作为附加指令追加到队员系统提示中。即使 tools 限制了其他工具，团队协调工具（如 SendMessage 和任务管理工具）始终可用。

子代理定义中的 skills 和 mcpServers 字段在作为队员运行时不会生效。队员从项目和用户设置中加载技能和 MCP 服务器，与常规会话一致。

权限 #

队员从领导的权限设置开始。如果领导以 --dangerously-skip-permissions 运行，所有队员也一样。生成后可以更改个别队员的权限模式，但生成时不能逐个设置。

上下文和通信 #

每个队员都有自己的上下文窗口。生成时，队员加载与常规会话相同的项目上下文：CLAUDE.md、MCP 服务器和技能。它还会收到领导的生成提示。领导的对话历史不会传递。

队员之间通过以下方式共享信息：

• 消息自动送达：队员发送消息时自动送达接收方，领导无需轮询
• 闲置通知：队员完成工作并停止时自动通知领导
• 共享任务列表：所有代理可以看到任务状态并认领可用任务
• 队员间消息：按姓名发送消息给特定队员。要广播给所有队员，逐个发送。

领导在生成时会为每个队员分配名称，任何队员都可以按名称给其他队员发消息。要获得可在后续提示中引用的可预测名称，在生成指令中告诉领导每个队员的名称。

Token 消耗 #

Agent Teams 消耗的 Token 显著多于单个会话。每个队员有独立上下文窗口，Token 消耗随活跃队员数量线性增长。研究、审查和新功能开发场景通常值得额外 Token。常规任务建议用单个会话，更经济。见 Agent Team Token 成本。

使用案例 #

并行代码审查 #

单个审查者倾向于聚焦一类问题。将审查标准拆分为独立领域，安全性、性能和测试覆盖率同时获得全面关注。提示词给每个审查者独特的视角，避免重叠：

创建一个 Agent 团队审查 PR #142。生成三个审查者：
- 一个专注于安全影响
- 一个检查性能影响
- 一个验证测试覆盖率
让他们各自审查并汇报发现。

每个审查者基于相同的 PR 但应用不同的过滤器。全部完成后领导汇总发现。

用竞争假设调试 #

当根本原因不明确时，单个代理倾向于找到一个合理解释后停止。提示词让队员彼此对抗，每个队员不仅要研究自己假设，还要挑战其他队员：

用户报告应用发送一条消息后就退出，而不是保持连接。
生成 5 个 Agent 队员研究不同假设。让他们互相讨论，
尝试反驳彼此的理论，像科学辩论一样。
把出现的共识更新到 findings 文档中。

辩论结构是关键机制。顺序调查容易受锚定效应影响：一旦一个理论被探索，后续调查就会偏向它。多个独立调查者主动试图互相反驳，生存下来的理论更有可能是真正的原因。

最佳实践 #

给队员足够的上下文 #

队员自动加载项目上下文（CLAUDE.md、MCP 服务器和技能），但不继承领导的对话历史。在生成提示词中包含任务特定细节：

生成一个安全审查队员，提示词为："审查 src/auth/ 中的认证模块
是否有安全漏洞，专注于 Token 处理、会话管理和输入验证。
应用使用存储在 httpOnly Cookie 中的 JWT Token。
报告任何问题并附上严重性评级。"

选择适当的团队规模 #

没有硬性限制，但实际约束：

• Token 成本线性增长：每个队员独立消耗 Token
• 协调开销增加：更多队员意味着更多通信和任务协调
• 收益递减：超过一定数量后额外队员不会成比例加速

大多数工作流从 3-5 个队员开始，每个队员 5-6 个任务保持高效率。例如 15 个独立任务时 3 个队员是好的起点。只有在工作确实需要同时处理时才扩大规模。3 个专注的队员往往优于 5 个分散的队员。

让任务大小合适 #

• 太小：协调开销超过收益
• 太大：队员长时间工作无检查，增加返工风险
• 恰好：自包含单元，产生明确交付物（一个函数、一个测试文件、一次审查）

领导会自动将工作拆分成任务分配给队员。如果觉得任务不够多，让领导继续拆分。每个队员 5-6 个任务保持高效，也让领导在队员卡住时可以重新分配。

等待队员完成 #

有时领导会自己开始实施而不是等待队员。如果发现这种情况：

在继续之前等你的队员完成任务

从研究和审查开始 #

Agent Teams 新手建议从边界清晰、不需要写代码的任务开始：审查 PR、研究库、调查 bug。这些任务展现了并行探索的价值，无需面对并行实施的协调挑战。

避免文件冲突 #

两个队员编辑同一个文件会导致覆盖。确保工作拆分后每个队员负责不同的文件集合。

监控和引导 #

定期检查队员进度，纠正无效方向，汇总发现。让团队长时间无人监督会增加返工风险。

队员不出现怎么解决 #

队员没有显示时：

• in-process 模式下队员可能已运行但不显示。按 Shift+Down 循环切换活跃队员。
• 检查任务是否足够复杂。Claude 根据任务决定是否生成队员。
• 如果请求分屏模式，确认 tmux 已安装并在 PATH 中：

  which tmux

• iTerm2 需安装 it2 CLI 并在偏好设置中启用 Python API。

权限提示太多怎么解决 #

队员的权限请求会冒泡到领导，可能造成干扰。在生成队员前，在 权限设置 中预批准常用操作，减少中断。

队员遇到错误后停止怎么解决 #

队员可能遇到错误后停止而不是恢复。in-process 模式用 Shift+Down 切换到该队员查看输出，分屏模式点击该队员窗格。然后：

• 直接给更多指令
• 生成替代队员继续工作

领导在工作完成前关闭怎么解决 #

领导可能认为工作已完成，但实际任务未全部完成。告诉领导继续，或在提示词中说明让领导等待队员完成任务后再继续。

残留 tmux 会话怎么清理 #

清理后如果有残留 tmux 会话：

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

当前限制 #

• 无法恢复 in-process 队员：/resume 和 /rewind 不能恢复 in-process 队员。恢复后领导可能向不存在的队员发消息，需重新生成。
• 任务状态可能滞后：队员有时无法标记任务为完成，阻塞依赖任务。可手动更新状态或让领导催促队员。
• 关闭可能较慢：队员完成当前请求或工具调用后才关闭，耗时不定。
• 每会话只有一个团队：领导只能管理一个团队，创建新团队前需清理当前团队。
• 不支持嵌套团队：队员不能生成自己的团队或队员，只有领导可以管理团队。
• 领导固定不变：创建团队的会话终身是领导，不能将队员提升为领导或转让领导权。
• 生成时确定权限：所有队员以领导权限模式启动。生成后可以更改个别队员模式，但生成时不能逐个设置。
• 分屏模式需要 tmux 或 iTerm2：默认 in-process 模式在任何终端可用。分屏不支持 VS Code 集成终端、Windows Terminal 或 Ghostty。

CLAUDE.md 正常工作：队员从工作目录读取 CLAUDE.md。用此文件提供项目级指导。

下一步 #

• 子代理：更轻量的委托方式，适用于不需要代理间协调的任务
• Git Worktrees：手动并行会话，无需自动团队协调
• 功能对比：子代理与 Agent Teams 详细对比

常见问题 #

Claude Code Agent Teams 怎么启用和创建团队？ #

在 settings.json 的 env 中添加 "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"，或用 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 设置环境变量。需要 v2.1.32 以上。启用后用自然语言告诉 Claude 创建团队，例如“创建一个 3 人团队研究这个问题”。

Agent Teams 和子代理有什么区别？ #

子代理只向主代理汇报结果，队员不能互相通信，适合简单任务。Agent Teams 的队员可以直接相互通信、共享任务列表、自主协调，适合需要讨论的复杂协作，但 Token 消耗更高。子代理总结结果到主上下文，Agent Teams 每个队员是完全独立的 Claude 实例。

Agent Teams 队员不出现或者权限提示太多怎么办？ #

队员不显示时先按 Shift+Down 循环切换活跃队员，确认任务是否足够复杂。权限提示多可在生成队员前在权限设置中预批准常用操作。分屏模式下队员不出现需确认 tmux 或 iTerm2 配置正确。