AI 2026年3月22日 3 分钟阅读

Claude Code Agent Teams 完全指南：多代理协作的终极形态

tinyash 0 条评论

文章信息

发布时间 2026年3月22日
作者 tinyash
阅读时长 3 分钟阅读

摘要：Agent Teams 是 Claude Code 的实验性功能，允许协调多个 Claude Code 实例作为一个团队协同工作。与只能在主代理和子代理间单向通信的 Subagents 不同，Agent Teams 中的成员可以直接互相通信、共享任务列表、自主协调工作。本文将详细介绍 Agent Teams 的启用、配置、使用场景和最佳实践。

一、Agent Teams 是什么？

1.1 核心概念

Agent Teams（代理团队） 是 Claude Code v2.1.32+ 引入的实验性功能，让你能够：

协调多个 Claude Code 实例作为一个团队协同工作，共享任务、互相通信、集中管理。

团队结构：

Team Lead（团队主管） – 主 Claude Code 会话，负责创建团队、生成成员、协调工作
Teammates（团队成员） – 独立的 Claude Code 实例，各自在独立的上下文中工作
Shared Task List（共享任务列表） – 团队成员可以认领和完成任务
Mailbox（邮箱系统） – 代理间的消息传递系统

1.2 与 Subagents 的区别

Subagents（子代理） 和 Agent Teams（代理团队） 都支持并行工作，但工作方式完全不同：

特性	Subagents	Agent Teams
上下文	独立上下文窗口；结果返回给调用者	独立上下文窗口；完全独立
通信	仅向主代理报告结果	团队成员直接互相通信
协调	主代理管理所有工作	共享任务列表，自主协调
最佳场景	只需要结果的任务	需要讨论和协作的复杂工作
Token 成本	较低：结果汇总回主上下文	较高：每个成员是独立的 Claude 实例

关键区别：

Subagents：子代理只能向主代理报告，彼此之间不能通信
Agent Teams：团队成员可以直接互相发消息、挑战彼此的观点、自主认领任务

图示对比：

Subagents 架构：
    主代理
   ↙  ↓  ↘
子代理 子代理 子代理
   ↓  ↓  ↓
  报告回主代理（彼此不通信）

Agent Teams 架构：
    团队主管
   ↕  ↕  ↕
成员 A ↔ 成员 B ↔ 成员 C
（共享任务列表，直接互相通信）

1.3 适用场景

Agent Teams 最有效的场景：

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

不适合的场景：

❌ 顺序任务 – 需要等待前一步完成的任務
❌ 同文件编辑 – 多个成员编辑同一文件会导致冲突
❌ 高依赖工作 – 任务间依赖过多会增加协调开销
❌ 常规任务 – 单个会话更经济高效

二、启用 Agent Teams

2.1 前提条件

Claude Code 版本：v2.1.32 或更高
实验性功能：默认禁用，需要手动启用

检查版本：

claude --version

2.2 启用方法

方法 1：通过 settings.json（推荐）

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

方法 2：通过环境变量

# Linux/macOS
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Windows PowerShell
$env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS="1"

# Windows CMD
set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

方法 3：启动时指定

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

三、创建第一个 Agent Team

3.1 基础示例

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

我正在设计一个帮助开发者追踪代码库中 TODO 注释的 CLI 工具。
创建一个代理团队从不同角度探索这个问题：
一个成员负责 UX，一个负责技术架构，一个扮演反对者角色。

Claude 会：

创建团队和共享任务列表
生成三个成员（UX、架构、反对者）
协调成员独立探索问题
综合发现并尝试在完成后清理团队

3.2 查看团队成员

团队主管的终端会显示：

Agent Team: todo-explorer
├─ Lead (you) - Coordinating work
├─ teammate-ux - Exploring user experience requirements
├─ teammate-arch - Designing technical architecture
└─ teammate-critic - Challenging assumptions and findings

切换查看成员：

Shift+Down – 循环切换查看成员
切换到最后一个成员后，再次 Shift+Down 回到主管

四、控制 Agent Teams

4.1 选择显示模式

Agent Teams 支持两种显示模式：

模式 1：进程内（In-process）

特点：

所有成员在主终端内运行
使用 Shift+Down 循环切换成员
适用于任何终端，无需额外配置

适用场景：

简单终端环境
不需要同时查看所有成员输出
资源受限环境

模式 2：分屏（Split panes）

特点：

每个成员有独立的窗格
可以同时看到所有成员的输出
点击窗格直接与成员交互
需要 tmux 或 iTerm2

配置方法：

// ~/.claude/settings.json
{
  "teammateMode": "tmux"
}

强制单会话使用分屏：

claude --teammate-mode tmux

强制进程内模式：

claude --teammate-mode in-process

自动模式（默认）：

{
  "teammateMode": "auto"
}

如果已在 tmux 会话中，使用分屏
否则使用进程内模式

安装 tmux

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Fedora/RHEL
sudo dnf install tmux

# Arch Linux
sudo pacman -S tmux

安装 iTerm2 it2 CLI（macOS）

# 安装 it2 CLI
brew install it2

# 启用 Python API
# iTerm2 → 设置 → General → Magic → Enable Python API

注意：tmux 在某些操作系统上有已知限制，在 macOS 上效果最好。

4.2 指定成员数量和模型

让 Claude 自动决定：

创建一个团队来重构这些模块。

明确指定成员数量：

创建 4 个成员的团队来并行重构这些模块。

指定模型：

创建 3 个成员的团队，每个成员使用 Sonnet 模型。

4.3 要求计划审批

对于复杂或高风险任务，可以要求成员在实施前先制定计划：

生成一个架构师成员来重构认证模块。
在做出任何更改之前需要计划审批。

工作流程：

成员进入只读计划模式
制定计划并提交给主管审批
主管审查计划：
- 批准 → 成员退出计划模式，开始实施
- 拒绝 → 提供反馈，成员修改后重新提交

影响审批标准：

只批准包含测试覆盖的计划
拒绝修改数据库架构的计划

4.4 直接与成员通信

每个成员都是完整的独立 Claude Code 会话，可以直接交互。

进程内模式

Shift+Down    → 切换到下一个成员
输入消息      → 发送指令
Enter         → 查看成员会话
Escape        → 中断成员当前回合
Ctrl+T        → 切换任务列表

分屏模式

点击成员窗格  → 直接交互
每个成员有独立的终端视图

使用场景：

提供额外指令
询问后续问题
重定向方法

4.5 分配和认领任务

共享任务列表协调团队工作。

任务状态：

Pending（待处理） – 等待认领
In Progress（进行中） – 已被认领
Completed（已完成） – 已完成

任务依赖：

有待解决依赖的待处理任务不能被认领
依赖完成后，阻塞的任务自动解锁

分配方式

主管分配：

把任务 3 分配给架构师成员

自主认领：

成员完成任务后，自动认领下一个未分配、未阻塞的任务
使用文件锁防止多个成员同时认领同一任务

4.6 关闭成员

优雅关闭成员：

让研究员成员关闭

流程：

主管发送关闭请求
成员可以批准（优雅退出）或拒绝（带解释）

4.7 清理团队

完成后清理：

清理团队

注意：

⚠️ 始终使用主管清理 – 成员不应运行清理
主管清理时会检查是否有活跃成员
如果有成员仍在运行，清理会失败

五、使用 Hooks 执行质量检查

使用 Hooks 在成员完成工作或任务完成时执行规则。

5.1 TeammateIdle Hook

触发时机：成员即将进入空闲状态

用途：

检查成员工作质量
提供反馈让成员继续工作

示例：

// ~/.claude/hooks.json
{
  "TeammateIdle": [
    {
      "type": "command",
      "command": "echo '检查工作是否完成'"
    }
  ]
}

退出码：

0 – 允许进入空闲
2 – 发送反馈，让成员继续工作

5.2 TaskCompleted Hook

触发时机：任务即将标记为完成

用途：

验证任务完成质量
防止过早标记完成

示例：

{
  "TaskCompleted": [
    {
      "type": "command",
      "command": "python3 verify_task.py"
    }
  ]
}

退出码：

0 – 允许完成任务
2 – 阻止完成，发送反馈

六、工作原理

6.1 团队启动方式

方式 1：用户请求团队

给 Claude 一个受益于并行工作的任务
明确要求创建代理团队
Claude 根据指令创建团队

方式 2：Claude 提议团队

Claude 判断任务受益于并行工作
建议创建团队
用户确认后继续

两种情况下用户都保持控制权 – Claude 不会在未经批准的情况下创建团队。

6.2 架构组件

组件	角色
团队主管	主 Claude Code 会话，创建团队、生成成员、协调工作
团队成员	独立的 Claude Code 实例，各自执行分配的任务
任务列表	共享的工作项列表，成员认领和完成
邮箱	代理间通信的消息系统

存储位置：

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

团队配置示例：

{
  "name": "todo-explorer",
  "members": [
    {
      "name": "teammate-ux",
      "agentId": "agent-123",
      "agentType": "teammate"
    },
    {
      "name": "teammate-arch",
      "agentId": "agent-456",
      "agentType": "teammate"
    },
    {
      "name": "teammate-critic",
      "agentId": "agent-789",
      "agentType": "teammate"
    }
  ]
}

6.3 权限

成员权限：

成员继承主管的权限设置
如果主管使用 --dangerously-skip-permissions，所有成员也跳过权限
生成后可以更改个别成员模式
⚠️ 不能在生成时设置每个成员的独立权限

6.4 上下文和通信

成员上下文：

每个成员有独立的上下文窗口
启动时加载与常规会话相同的项目上下文：
- CLAUDE.md
- MCP 服务器
- Skills
接收来自主管的生成提示
不继承主管的对话历史

信息共享方式：

方式	说明
自动消息传递	成员发送的消息自动传递给接收者，主管无需轮询
空闲通知	成员完成并停止时自动通知主管
共享任务列表	所有代理可以看到任务状态并认领可用工作

消息类型：

message – 发送给特定成员
broadcast – 同时发送给所有成员（谨慎使用，成本随团队规模增长）

6.5 Token 使用

Agent Teams 使用明显更多的 Token：

每个成员有独立的上下文窗口
Token 使用量与活跃成员数量成比例增长
对于研究、审查和新功能开发，额外 Token 通常是值得的
对于常规任务，单个会话更经济

详见：Agent Team Token 成本

七、实战示例

7.1 示例 1：并行代码审查

场景：审查 PR #142，需要全面检查安全性、性能和测试覆盖率

提示：

创建一个代理团队来审查 PR #142。生成三个审查员：
- 一个专注于安全影响
- 一个检查性能影响
- 一个验证测试覆盖率

让他们各自审查并报告发现。

为什么有效：

三个角色独立，可以同时探索
每个审查员应用不同的过滤条件
主管在完成后综合所有发现

优势：

单个审查员倾向于一次关注一类问题
分成独立领域意味着安全性、性能、测试覆盖率同时得到彻底审查

7.2 示例 2：竞争假设调查

场景：用户报告应用在一条消息后退出，而不是保持连接

提示：

用户报告应用在一条消息后退出而不是保持连接。
生成 5 个代理成员调查不同的假设。
让他们互相交流，试图反驳彼此的理论，像科学辩论一样。
将出现的共识更新到发现文档中。

为什么有效：

顺序调查容易受锚定效应影响：一旦探索了一个理论，后续调查会偏向它
多个独立调查员积极试图反驳彼此，存活下来的理论更可能是真正的根本原因
辩论结构是关键机制

工作流程：

成员 A：假设是网络连接超时
成员 B：假设是认证令牌过期
成员 C：假设是服务器端会话管理问题
成员 D：假设是客户端状态管理 bug
成员 E：反对者，挑战所有理论

成员互相质疑、提供反例、要求证据，最终收敛到最可能的原因。

7.3 示例 3：跨层功能开发

场景：开发新的用户个人资料功能，涉及前端、后端、数据库、测试

提示：

创建一个代理团队来开发用户个人资料功能。
生成 4 个成员：
- 前端成员：负责 UI 组件和样式
- 后端成员：负责 API 端点和业务逻辑
- 数据库成员：负责 Schema 更改和迁移
- 测试成员：负责编写集成测试

每个成员负责自己的一层，完成后互相审查接口。

任务分解：

任务 1：数据库 Schema 设计（数据库成员）
任务 2：API 端点实现（后端成员）
任务 3：UI 组件开发（前端成员）
任务 4：集成测试编写（测试成员）
任务 5：接口审查和联调（所有成员）

7.4 示例 4：Bug 根因分析

场景：生产环境出现间歇性性能下降

提示：

生产环境出现间歇性性能下降，每周 2-3 次，每次持续 5-10 分钟。
创建一个代理团队调查根因。
生成 5 个成员，每个调查一个可能的原因：
- 成员 1：数据库查询性能
- 成员 2：缓存失效模式
- 成员 3：第三方 API 依赖
- 成员 4：服务器资源使用
- 成员 5：网络延迟和 CDN

让他们共享日志访问权限，互相挑战彼此的结论。

八、最佳实践

8.1 提供足够的上下文

问题：成员不继承主管的对话历史

解决方案：在生成提示中包含任务特定细节

示例：

生成一个安全审查成员，提示如下：
"审查 src/auth/ 的认证模块是否存在安全漏洞。
专注于令牌处理、会话管理和输入验证。
应用使用存储在 httpOnly cookie 中的 JWT 令牌。
报告任何问题并附带严重程度评级。"

8.2 选择合适的团队规模

考虑因素：

因素	说明
Token 成本线性增长	每个成员有独立上下文，独立消耗 Token
协调开销增加	更多成员意味着更多通信、任务协调和潜在冲突
收益递减	超过某一点后，额外成员不会成比例加快工作

8.3 合理分配任务大小

任务大小指南：

大小	问题	建议
太小	协调开销超过收益	合并相关小任务
太大	成员长时间工作无检查，增加浪费风险	拆分为更小的可交付单元
刚好	自包含单元，产生清晰的可交付成果	函数、测试文件、审查报告

提示主管拆分任务：

把工作拆分成更小的任务，每个成员 5-6 个任务

8.4 等待成员完成

问题：主管有时开始自己实施任务而不是等待成员

解决方案：

等待你的成员完成任务后再继续

8.5 从研究和审查开始

新手建议：

从有明确边界、不需要写代码的任务开始
审查 PR、研究库、调查 bug
这些任务展示并行探索的价值，没有并行实施的协调挑战

8.6 避免文件冲突

问题：两个成员编辑同一文件导致覆盖

解决方案：

拆分工作，让每个成员负责不同的文件集
使用任务依赖确保顺序修改

示例：

成员 A 负责 src/frontend/ 的所有文件
成员 B 负责 src/backend/ 的所有文件
成员 C 负责 tests/ 的所有文件

8.7 监控和引导

主动管理：

检查成员进度
重定向不起作用的方法
综合收到的发现
不要让团队长时间无人看管

检查方法：

Shift+Down → 查看每个成员的状态
Ctrl+T → 查看任务列表

九、故障排查

9.1 成员未出现

症状：请求创建团队后成员未出现

排查步骤：

进程内模式下成员可能已在运行但不可见 按 Shift+Down 循环查看活跃成员
检查任务是否足够复杂 Claude 根据任务决定是否生成成员给更复杂的任务或明确要求创建团队
检查 tmux 是否安装（分屏模式） which tmux # 如果未找到，安装 tmux
检查 iTerm2 配置
- 确认 it2 CLI 已安装
- 在 iTerm2 偏好设置中启用 Python API

9.2 过多权限提示

问题：成员权限请求冒泡到主管，造成摩擦

解决方案：

在生成成员前预批准常见操作
修改权限设置

{
  "permissions": {
    "read": "autoApprove",
    "write": "autoApprove"
  }
}

9.3 成员因错误停止

问题：成员遇到错误后停止而不是恢复

解决方案：

查看成员输出 进程内模式：Shift+Down 切换查看分屏模式：点击成员窗格
提供额外指令 忽略这个错误，继续工作
生成替代成员 生成一个新成员继续未完成的工作

9.4 主管在工作完成前关闭

问题：主管在所有任务完成前决定团队结束

解决方案：

继续，等待成员完成他们的任务

预防：

在继续之前等待成员完成他们的任务

9.5 孤立的 tmux 会话

问题：团队结束后 tmux 会话仍然存在

解决方案：

# 列出会话
tmux ls

# 删除团队创建的会话
tmux kill-session -t <session-name>

十、已知限制

Agent Teams 是实验性功能，当前限制：

限制	说明	解决方法
进程内成员无法恢复会话	`/resume` 和 `/rewind` 不恢复进程内成员	告诉主管生成新成员
任务状态可能滞后	成员有时未能标记任务为完成，阻塞依赖任务	检查工作是否完成，手动更新或让主管提醒成员
关闭可能缓慢	成员在完成当前请求或工具调用后才关闭	耐心等待
每会话一个团队	主管一次只能管理一个团队	清理当前团队后再开始新团队
无嵌套团队	成员不能生成自己的团队或成员	只有主管可以管理团队
主管固定	创建团队的会话是终身主管	不能提升成员为主管或转移领导权
权限在生成时设置	所有成员继承主管的权限模式	生成后可以更改个别成员模式
分屏需要 tmux 或 iTerm2	分屏模式不支持 VS Code 集成终端、Windows Terminal、Ghostty	使用进程内模式

CLAUDE.md 正常工作：

✅ 成员从工作目录读取 CLAUDE.md 文件
✅ 使用 CLAUDE.md 提供项目特定指导

十一、成本考虑

11.1 Token 成本计算

单会话：

Token 成本 = 输入 Token × 输入价格 + 输出 Token × 输出价格

Agent Teams：

Token 成本 = Σ(每个成员的输入 Token × 输入价格 + 每个成员的输出 Token × 输出价格)

示例（3 个成员，每个使用 Sonnet）：

单会话：100K 输入 + 50K 输出 = $0.60
3 成员团队：3 × (100K 输入 + 50K 输出) = $1.80

11.2 成本效益分析

值得使用 Agent Teams 的场景：

✅ 时间敏感任务（更快完成 = 节省人力成本）
✅ 复杂问题（多视角 = 更好的解决方案）
✅ 高质量要求（并行审查 = 更少遗漏）

不值得的场景：

❌ 简单任务（协调开销超过收益）
❌ 预算受限（Token 成本过高）
❌ 顺序依赖（无法并行）

11.3 降低成本技巧

使用更便宜的模型 使用 Haiku 模型创建 3 个成员的团队
限制团队规模 创建 2 个成员的团队（而不是 5 个）
及时清理 完成后立即清理团队
使用进程内模式
- 分屏模式需要额外的 tmux/iTerm2 资源

十二、与 OpenClaw 的对比

12.1 多代理能力对比

特性	Claude Code Agent Teams	OpenClaw Subagents
代理间通信	✅ 直接互相通信	❌ 仅向主代理报告
共享任务列表	✅ 自主认领任务	❌ 主代理分配
显示模式	✅ 进程内/分屏	✅ 后台运行
计划审批	✅ 支持	✅ 支持
Hooks	✅ TeammateIdle/TaskCompleted	✅ 自定义 Hooks
云同步	❌ 本地存储	✅ 支持
跨平台	❌ 仅 CLI	✅ 多平台（Discord、Telegram 等）

12.2 选择指南

使用 Claude Code Agent Teams：

需要代理间直接通信
在终端环境中工作
需要分屏查看多个代理

使用 OpenClaw：

需要跨平台支持
需要与消息应用集成
需要云同步和持久化

十三、总结

Agent Teams 核心价值：

✅ 直接通信 – 成员可以互相交流、挑战彼此观点
✅ 自主协调 – 共享任务列表，自主认领工作
✅ 并行探索 – 多个视角同时调查问题
✅ 灵活显示 – 进程内或分屏模式
✅ 计划审批 – 高风险任务需要主管批准
✅ Hooks 集成 – 强制执行质量检查

适用场景：

🔍 研究和审查（并行调查）
🏗️ 新功能开发（独立模块）
🐛 多假设调试（竞争理论）
🌉 跨层协调（前端/后端/测试）

不适用场景：

❌ 顺序任务
❌ 同文件编辑
❌ 高依赖工作
❌ 常规简单任务

下一步行动：

启用 Agent Teams：设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
创建第一个团队：从研究和审查任务开始
尝试不同显示模式：进程内 vs 分屏
实践最佳实践：合理团队规模、任务分配、监控引导

参考资料：

本文基于 Claude Code v2.1.32+ 编写，Agent Teams 是实验性功能，行为可能随版本更新而变化。

AI AI 工具

一、Agent Teams 是什么？

1.1 核心概念

1.2 与 Subagents 的区别

1.3 适用场景

二、启用 Agent Teams

2.1 前提条件

2.2 启用方法

三、创建第一个 Agent Team

3.1 基础示例

3.2 查看团队成员

四、控制 Agent Teams

4.1 选择显示模式

模式 1：进程内（In-process）

模式 2：分屏（Split panes）

安装 tmux

安装 iTerm2 it2 CLI（macOS）

4.2 指定成员数量和模型

4.3 要求计划审批

4.4 直接与成员通信

进程内模式

分屏模式

4.5 分配和认领任务

分配方式

4.6 关闭成员

4.7 清理团队

五、使用 Hooks 执行质量检查

5.1 TeammateIdle Hook

5.2 TaskCompleted Hook

六、工作原理

6.1 团队启动方式

6.2 架构组件

6.3 权限

6.4 上下文和通信

6.5 Token 使用

七、实战示例

7.1 示例 1：并行代码审查

7.2 示例 2：竞争假设调查

7.3 示例 3：跨层功能开发

7.4 示例 4：Bug 根因分析

八、最佳实践

8.1 提供足够的上下文

8.2 选择合适的团队规模

8.3 合理分配任务大小

8.4 等待成员完成

8.5 从研究和审查开始

8.6 避免文件冲突

8.7 监控和引导

九、故障排查

9.1 成员未出现

9.2 过多权限提示

9.3 成员因错误停止

9.4 主管在工作完成前关闭

9.5 孤立的 tmux 会话

十、已知限制

十一、成本考虑

11.1 Token 成本计算

11.2 成本效益分析

11.3 降低成本技巧

十二、与 OpenClaw 的对比

12.1 多代理能力对比

12.2 选择指南

十三、总结

发表评论 取消回复

发表评论取消回复