引言

2026年2月，Anthropic 发布了一个令人震撼的案例：他们使用 Opus 4.6 和 Agent Teams 功能，仅用 $20,000 的 API 成本，就构建了一个能够编译 Linux 内核的 C 编译器。这个 10 万行代码的编译器是由 16 个 Claude 实例在近 2000 个会话中协同完成的，几乎不需要人工干预。

这个案例充分展示了 Agent Teams 的强大能力。本教程将手把手教你如何使用 Claude Code 的 Agent Teams 功能，包括所有配置细节和我在实践中遇到的各种坑。

什么是 Agent Teams？

Agent Teams 是 Claude Code 的一个实验性功能，它允许多个 Claude 实例作为一个团队协同工作。与传统的单个 AI 助手不同，Agent Teams 具有以下特点：

核心特性

1. 并行工作能力

   • 多个 Claude 实例同时处理不同任务
   • 每个成员拥有独立的上下文窗口
   • 适合需要并行探索的复杂任务

2. 团队协作机制

   • 团队领导（Lead）负责协调工作
   • 团队成员（Teammates）独立执行任务
   • 成员之间可以直接通信和讨论
   • 共享任务列表进行协调

3. 自主任务管理

   • 领导分配任务或成员自主认领
   • 支持任务依赖关系
   • 自动同步任务状态

与 Subagents 的区别

特性	Agent Teams	Subagents
上下文	每个成员独立上下文	在主会话内运行
通信方式	成员间直接通信	只能向主代理报告
协调机制	共享任务列表，自我协调	主代理管理所有工作
适用场景	需要讨论和协作的复杂工作	专注任务，只需结果
Token 成本	较高（每个成员独立实例）	较低（结果汇总到主上下文）

📌 何时使用哪种方式？

官方指导原则：

💡 使用 Subagents：当您需要快速、专注且能及时汇报工作的员工时
👥 使用 Agent Teams：当团队成员需要分享发现、互相挑战并自主协作时

⚠️ 何时不应该使用 Agent Teams

重要提示：代理团队会增加协调开销，并且比单个会话消耗更多的令牌。

以下场景更适合使用单个会话或 Subagents：

1. 顺序任务

   • 任务之间有严格的先后依赖关系
   • 后续任务需要前一个任务的结果
   • 例如：必须先设计数据库模式，再实现 API，最后写测试

2. 同一文件的编辑

   • 多个成员修改同一个文件会导致冲突
   • 合并变更需要额外的协调成本
   • 例如：修改同一个配置文件、更新同一个函数

3. 涉及多个依赖项的工作

   • 工作之间紧密耦合，难以独立进行
   • 需要频繁的信息同步
   • 例如：重构核心模块，影响整个代码库

4. 简单直接的任务

   • 任务范围小，单个 Agent 就能快速完成
   • 创建团队的开销大于收益
   • 例如：修改一个 bug、添加一个简单功能

最佳实践原则：

💡 当团队成员能够独立操作时，Agent Teams 的效果最佳。如果发现成员之间需要频繁沟通协调，或者工作内容高度重叠，那么单个会话可能更合适。

环境准备

前置要求

1. Claude Code

2. 操作系统

   • macOS
   • Linux
   • Windows（通过 WSL）

启用 Agent Teams 功能

Agent Teams 是实验性功能，默认关闭。需要手动启用：

方法 1：通过 settings.json 配置

编辑 ~/.cursor/settings.json 文件（如果使用 Cursor 编辑器）或相应的配置文件：

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

方法 2：通过环境变量

在你的 shell 配置文件（如 ~/.zshrc 或 ~/.bashrc）中添加：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

然后重新加载配置：

source ~/.zshrc  # 或 source ~/.bashrc

配置多屏显示（重点）

Agent Teams 支持两种显示模式：

In-process 模式：所有成员在同一个终端内运行

claude --teammate-mode in-process

创建好的团队如下：

这种模式下，你如果想看每个成员的会话的话，可以使用 shift+上下箭头 来选择

Split-pane分屏模式： 每个成员在独立的窗口面板中

Split-pane 模式需要额外配置，但体验更好。

可以看到这创建团队之后的分屏模式，左边是主Agent，相当于是Team-lead 。右边都是创建的成员，每个都是全新的会话。正在等待着Lead给他们分配任务。

也可以跟每个成员单独交互

配置 Claude Code 使用 tmux

编辑 ~/.cursor/settings.json（或相应配置文件）：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "tmux"
}

teammateMode 的可选值：

• "auto"（默认）：在 tmux 会话中自动使用 split-pane
• "in-process"：强制使用单终端模式
• "tmux"：强制使用 tmux split-pane 模式

当然，启动的时候也可以指定具体模式，优先级高于配置

claude --teammate-mode in-process
claude --teammate-mode auto
claude --teammate-mode tmux

分屏模式需要使用带有命令行界面的tmux或 iTerm2 。

安装 tmux

macOS:

brew install tmux

Ubuntu/Debian:

sudo apt-get install tmux

CentOS/RHEL:

sudo yum install tmux

配置 tmux

创建或编辑 ~/.tmux.conf 文件：

# 启用鼠标支持（重要！）
set -g mouse on

# 设置更友好的快捷键前缀（可选）
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# 优化窗口分割快捷键（可选）
bind | split-window -h
bind - split-window -v

# 使窗口索引从 1 开始（可选）
set -g base-index 1
setw -g pane-base-index 1

修改了配置记得要

重新加载配置：

tmux source-file ~/.tmux.conf

📌 关于 set -g mouse on 的重要说明

这个配置是解决 macOS 快捷键冲突的关键！

问题背景：

• tmux 默认使用键盘快捷键来切换面板，例如 Ctrl+B 然后按方向键
• 在 macOS 上，许多系统快捷键会与 tmux 的快捷键冲突
• 特别是 Ctrl+方向键 被 macOS 用于切换桌面空间（Mission Control）
• 这导致你无法使用键盘在 Agent Teams 的多个面板之间切换

set -g mouse on 的作用：

1. ✅ 启用鼠标点击切换面板：直接点击任意面板即可激活
2. ✅ 鼠标滚动浏览历史：在面板中滚动鼠标查看历史输出
3. ✅ 鼠标拖动调整面板大小：拖动面板边界即可调整
4. ✅ 鼠标选择和复制文本：直接选中文本进行复制

为什么必须设置：

❌ 没有鼠标模式：无法切换面板 → Agent Teams 无法使用
✅ 启用鼠标模式：点击即可切换 → 完美工作

macOS 快捷键冲突示例：

tmux 快捷键	macOS 系统功能	结果
Ctrl+B ←	Mission Control 切换桌面	❌ tmux 无法响应
Ctrl+B ↑	应用程序窗口（App Exposé）	❌ tmux 无法响应
鼠标点击	无冲突	✅ 完美工作

两种解决方案：

方案 1（推荐）：启用鼠标模式

# 在 ~/.tmux.conf 中添加
set -g mouse on

# 立即生效（在 tmux 内执行）
tmux set -g mouse on

方案 2：修改 tmux 前缀键

# 将前缀从 Ctrl+B 改为 Ctrl+A（不与 macOS 冲突）
set -g prefix C-a
unbind C-b
bind C-a send-prefix

💡 最佳实践：两种方案同时使用！既有鼠标的便利性，又有键盘的快捷性。

重新加载配置：

tmux source-file ~/.tmux.conf

iTerm2 用户的额外配置（macOS推荐）

如果你是MacOS并且使用 iTerm2终端，那我觉得体验上可能比单纯的tmux要好一点

那么还需要做以下操作才行

1. 安装 it2 CLI：

   pip install iterm2
   

2. 在 iTerm2 中启用 Python API：

   • 打开 iTerm2 → Settings（设置）
   • 选择 General（通用）→ Magic（魔法）
   • 勾选 “Enable Python API”

   
   配置好了之后，重启Iterm2，然后启动tmux

注意啊，这里还是要安装tmux的

brew install tmux

然后在Iterm2 启动tmux

tmux -CC

最终的展示界面

之所以我觉得在Iterm2里面使用tmux很舒服是因为我们可以手动去调整每个会话的大小
因为如果一次创建了好多个成员的话，原生tmux展示的自动排版堆叠很丑，Iterm2上我可以手动拖拽调整很舒服

比如上面的那个界面我手动调整成下面这样的布局，就能够看到更多的信息

组建你的第一个Agent Teams

都配置完成之后，那如何触发AgentTeams呢？ 只需要主动跟Claude code说，创建AgentTeams就行

如下：

创建一个3人团队的AgentTeams.前端开发，后端开发，产品经理兼职UI设计，然后一个测试，先创建好团队，我再给你说需求。

这样他就会给每个成员创建好单独的会话，并且有一个主会话来协调各个成员工作

需要团队Lead批准计划

对于复杂或高风险的任务，您可以要求团队成员在实施前进行计划。在负责人批准其方案之前，团队成员以只读模式编写计划：

在进行任何更改之前，必须使用Plan 模式，需要获得方案的批准。 Require plan approval before they make any changes.

当团队成员完成计划后，会向项目负责人发送计划审批请求。项目负责人审核计划后，会批准或拒绝并提供反馈意见。

如果计划被拒绝，团队成员会继续留在plan模式，根据反馈意见进行修改，然后重新提交。一旦计划获得批准，团队成员就会退出plan模式并开始实施。

项目负责人自主做出审批决定。为了影响项目负责人的判断，请在提示中给出一些标准，例如“只批准包含测试覆盖率的计划”或“拒绝修改数据库架构的计划”。

可以理解为：所有的成员在正在开始任务之前都需要把方案给到团队老板，获得老板批准才能执行

什么是委托模式

如果我们不希望team-lead 自己下场去完成任务改代码，那么我们可以使用委托模式。
这个让team-lead完全专注于统筹安排，例如分解工作、分配任务和综合结果，而无需直接接触代码时，这非常有用。

要启用此功能，请先创建一个团队，然后按 Shift+Tab 切换到委派模式。

清理团队

Clean up the team

这将移除共享的团队资源。当主管运行清理程序时，它会检查是否有活跃的团队成员正在运行，如果有，则会运行失败，因此需要先关闭这些成员。

Agent Teams 结构

组件	角色
Team-Lead 团队负责人	Claude Code 的主要会话用于创建团队、生成队友并协调工作。
Teammates 成员	多个独立的 Claude Code 实例，各自负责分配的任务。
Task list 任务清单	团队成员认领和完成的工作项共享列表
Mailbox 邮箱	用于代理之间通信的消息传递系统

团队和任务存储在本地：

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

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

如果Team-lead开启了--dangerously-skip-permissions, 那么成员也会开启该权限

使用案例

并行运行Code Review

单个评审员往往一次只关注一种类型的问题。将评审标准拆分成独立的领域，意味着安全性、性能和测试覆盖率都能同时得到充分的关注。这样，每个团队成员就被分配了一个不同的视角，避免了重叠

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

让他们分别进行审查并报告审查结果。

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

当根本原因不明时，单个调查员往往会找到一个看似合理的解释就停止调查。为了避免这种情况，提示系统明确地将团队成员置于对立位置：每个人的任务不仅是验证自己的理论，还要质疑其他人的理论。

用户反映应用会在发送一条消息后退出，而不是保持连接。
生成 5 名特工队友来调查不同的假设。让他们互相交流，
尝试反驳对方的理论，就像一场科学辩论。
将最终达成的共识更新到调查结果文档中。

辩论结构是关键机制。循序渐进的调查研究容易受到锚定效应的影响：一旦某个理论被探讨过，后续的调查研究就会倾向于该理论。
由于多位独立调查人员都在积极尝试反驳对方的观点，最终被采纳的理论更有可能是真正的根本原因。
​

实战：遇到的坑和解决方案

坑 1：tmux 无法切换面板

问题描述：
启动 Agent Teams 后，创建了多个 tmux 面板，但是使用 Ctrl+B + 方向键无法切换面板。

原因分析：
macOS 的系统快捷键可能与 tmux 的默认快捷键冲突。

解决方案：

方法 1：启用鼠标模式（推荐）

# 在 tmux 会话中执行
tmux set -g mouse on

或者在 ~/.tmux.conf 中永久设置：

set -g mouse on

启用后，你可以：

• 直接用鼠标点击不同的面板进行切换
• 使用鼠标滚轮滚动终端输出
• 拖动面板边界调整大小

方法 2：修改 tmux 快捷键前缀

如果你更喜欢键盘操作，可以修改 tmux 的前缀键，避免与系统快捷键冲突：

# 在 ~/.tmux.conf 中设置
set -g prefix C-a
unbind C-b
bind C-a send-prefix

然后使用 Ctrl+A + 方向键切换面板。

坑 2：iTerm2 剪贴板访问权限配置

问题描述：
在 iTerm2 中启动 tmux 并运行 Claude Code 后，会弹出一个权限选择对话框，询问是否允许终端应用访问剪贴板。

如果选择错误或需要修改设置，会影响 Agent Teams 的正常使用。

解决方案：

1. 配置剪贴板访问权限：
   • 打开 iTerm2 → Settings（设置）
   • 选择 General（通用）→ Selection（选择）标签
   • 找到 “Access:” 部分
   • 勾选 ✅ “Applications in terminal may access clipboard”
   • 在下拉菜单中选择 “Ask Each Time” 或 “Always”（推荐 Always 以减少干扰）

注意： 如果不勾选或选择错误，Agent Teams 的成员之间可能无法正常通信和共享信息。

2. 授予 iTerm2 完全磁盘访问权限：

   • 打开 System Settings（系统设置）
   • 进入 Privacy & Security（隐私与安全）→ Full Disk Access（完全磁盘访问）
   • 添加 iTerm2 到允许列表

3. 确保 Python API 已启用：
   参见前面的 “iTerm2 用户的额外配置” 部分

注意清理tmux

如果团队会议结束后 tmux 会话仍然存在，则可能尚未完全清理。请列出会话并终止团队会议创建的会话：

tmux ls
tmux kill-session -t

高级技巧

1. 使用 Plan 审批模式

对于复杂或有风险的任务，可以要求成员先制定计划：

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

成员会先在只读的 Plan 模式下工作，制定好方案后提交给 Lead 审批。Lead 可以批准或拒绝并提供反馈。

2. 设置质量门控

使用 hooks 来强制执行规则：

# 在项目根目录创建 .claude/hooks/
mkdir -p .claude/hooks

# 创建 TeammateIdle hook
cat > .claude/hooks/TeammateIdle << 'EOF'
#!/bin/bash
# 成员完成工作前运行测试
npm test
if [ $? -ne 0 ]; then
  echo "ERROR: Tests failed. Fix issues before going idle."
  exit 2  # 发送反馈并保持工作状态
fi
EOF

chmod +x .claude/hooks/TeammateIdle

3. 优化任务大小

任务大小指导原则：

• ✅ 合适：实现一个函数、一个测试文件、一次代码评审
• ❌ 太小：修改一行代码、修复一个拼写错误
• ❌ 太大：重构整个模块、实现完整功能

让 Lead 拆分大任务：

Break the authentication refactor into 6-8 smaller tasks, 
one per function or component

4. 避免文件冲突

最佳实践：

1. 按文件/模块分工：每个成员负责不同的文件集
2. 使用 Git 分支：每个成员在独立分支工作
3. 设置文件锁：由 Lead 协调哪个成员可以编辑哪些文件

示例：

Assign src/auth/jwt.ts to Security Reviewer (exclusive)
Assign src/auth/oauth.ts to OAuth Specialist (exclusive)
No other teammates should modify these files

5. 成本优化

Agent Teams 的 Token 成本较高，因为每个成员都是独立实例。

降低成本的策略：

1. 使用更小的模型：对于简单任务使用 Haiku

   Create a team with 3 Haiku teammates for code review
   

2. 控制成员数量：不要创建过多成员

   • 2-4 个成员：最佳
   • 5-8 个成员：可以接受
   • 8+ 个成员：可能过度

3. 及时关闭闲置成员：完成任务后立即关闭

   Shut down the test engineer teammate, their work is complete
   

4. 使用 Subagents 替代简单任务：不需要成员间通信时用 Subagents

6. 日志和调试

查看团队日志：

# 团队配置
cat ~/.claude/teams/{team-name}/config.json

# 任务列表
ls -la ~/.claude/tasks/{team-name}/

# Claude Code 日志
tail -f ~/.claude/logs/latest.log

调试技巧：

1. 检查成员状态：

   List all teammates and their current tasks
   

2. 手动更新任务状态：

   Mark task "implement-jwt-validation" as completed
   

3. 重启卡住的成员：

   Shut down the backend developer teammate
   Spawn a new backend developer to continue the API work
   

实战案例：构建一个完整功能

让我们通过一个实际案例来演示 Agent Teams 的完整流程。

任务：构建一个分析 agent-teams的交互过程的可视化分析平台

启动团队

# 启动 tmux
tmux -CC

# 启动 Claude Code
claude --dangerously-skip-permissions

创建团队

在 Claude Code 中：

创建一个3人团队的AgentTeams.前端开发，后端开发，产品经理兼职UI设计，然后一个测试
具体需求是帮我创建一个专门用于分析Claude code Agent Teams 工作方式，沟通，协同
 的一个分析平台。用户只要启动这个平台，就能自动分析每个会话，里面是否使用了AgentTeams功能，以及看到每个团队工作的形式，主要还是要清晰的追踪到每个会话直接的交互链路，可以按照时间线展示，或者用各种可视化图谱展示。这样能够清晰的知道Agent teams 是如何完成任务的，你可以先试用 /brainstorming  skill来先确定任务，请一次性多问问题，不要一个问题问一次。

监控进度

团队创建后，你会看到：

1. 5 个 tmux 面板：每个成员一个面板
2. 共享任务列表：显示所有子任务
3. Lead 协调：在主面板中显示整体进度

Lead分析需求并把它拆解成了多个任务
然后指派成员来完成。如下图所示，它先指派了一个

• 需求分析和数据模型设计的任务给 ：@product-manager

而且其他的任务是被任务1阻塞的，意思是需要任务1完成才行

项管完成任务之后，team-lead 手动任务完成的状态，然后就让前端和后端同学同事进行开发了

测试终于能干活了

清理

# 关闭所有成员
Shut down all teammates

# 清理团队资源
Clean up the team

# 退出
exit

展示创建好的平台

最佳实践总结

✅ 应该做的

1. 明确任务边界：给每个成员清晰、独立的任务
2. 充分上下文：在 spawn 命令中提供足够的背景信息
3. 定期检查：监控成员进度，及时调整方向
4. 使用鼠标模式：启用 tmux 鼠标支持，提升操作体验
5. 适当任务大小：每个任务应该是独立、可完成的单元
6. 记录决策：让成员维护设计文档和决策日志
7. 启用日志：保留详细日志用于调试
8. 分阶段验证：不要等到最后才验证成果

❌ 不应该做的

1. 过多成员：不要创建超过必要的成员数量
2. 文件冲突：避免多个成员编辑同一文件
3. 任务太小：不要为琐碎任务创建团队
4. 缺乏监督：不要让团队无人监管太久
5. 忽略错误：成员出错时要及时介入
6. 混合模式：不要在同一项目中混用 in-process 和 split-pane
7. 忘记清理：完成后一定要关闭成员和清理资源
8. 直接部署：团队产出要经过人工审查再部署

故障排除

问题：tmux 会话残留

症状：
关闭团队后，tmux 会话仍然存在

解决：

# 列出所有 tmux 会话
tmux ls

# 杀死特定会话
tmux kill-session -t session-name

# 杀死所有会话
tmux kill-server

问题：成员不响应

症状：
向成员发送消息后没有反应

排查：

# 检查成员是否还在运行
List all active teammates

# 查看成员最后的输出
Show me the last 50 lines from the JWT Specialist

解决：

# 重启成员
Shut down the unresponsive teammate
Spawn a new JWT Specialist to continue the work

问题：任务卡住

症状：
任务标记为 in-progress 但实际已完成

解决：

# 手动更新任务状态
Mark task "implement-jwt-validation" as completed

# 或让 Lead 检查
Check if all in-progress tasks are actually being worked on

问题：权限提示过多

症状：
不断弹出权限确认提示

解决：

1. 使用 --dangerously-skip-permissions 标志
2. 或在配置中预先批准常见操作

配置文件示例

完整的 settings.json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "tmux",
  "permissions": {
    "read": "always_allow",
    "write": "prompt",
    "execute": "prompt"
  }
}

参考资源

参考资料

• Claude Code Agent Teams 文档
• Building a C compiler with a team of parallel Claudes
• Claude Code GitHub Discussions
• tmux 官方 Wiki
• Subagents 文档
• Git Worktrees 与并行会话
• Claude Code Hooks

总结

Agent Teams 是一个强大但复杂的功能。通过本教程，你应该已经掌握了：

1. ✅ Agent Teams 的核心概念和适用场景
2. ✅ 完整的环境配置流程（特别是 tmux）
3. ✅ 常见问题的解决方案
4. ✅ 从创建到关闭的完整工作流
5. ✅ 高级技巧和最佳实践

记住，Agent Teams 不是所有任务的最佳选择。对于简单任务，单个 Claude 会话或 Subagents 可能更合适。但对于需要并行探索、协作讨论的复杂项目，Agent Teams 能够显著提升效率。