Claude Code Agent Teams：从单兵作战到团队协作的完整指南

本节核心问题：Claude Code Agent Teams 是什么，它如何改变了我们与代码交互的方式？
「答案：」 这是一个原生的多代理编排系统，将传统的单一线性任务处理转变为由主代理协调、多个子代理并行工作的“团队协作”模式，无需任何插件或自定义技能即可实现复杂的协同开发。

在软件开发领域，效率的提升往往来自于协作模式的变革。OpenClaw 社区最早探索了通过自定义技能编排多个 Claude Code 会话的可能性，他们实现了代理之间的任务协调、上下文共享和并行运行。这一创新显然引起了 Anthropic 的注意，因为他们刚刚将这一功能原生集成到了 Claude Code 中，并将其正式命名为“Agent Teams”。

这就好比从雇佣一个单打独斗的自由职业者，变成了雇佣了一位自带全套施工队伍的项目经理。以前，你给 Claude Code 一个任务，它会按部就班地完成第一步，再进行第二步，就像一个只能串行工作的员工。而现在，启用 Agent Teams 后，一个主代理会接管你的需求，将其拆解，并启动多个队友同时工作。它们之间不仅向主代理汇报，还能直接相互交流，共享发现。

Coding Collaboration
图片来源：Unsplash

这是一个仍在研究预览阶段的功能，大多数人尚未知晓。本文将深入探讨如何安装、配置以及正确使用这一强大的新工具，帮助你从单线程的思维模式切换到多线程的团队协作模式。

从单兵作战到团队协作：核心概念解析

本节核心问题：Agent Teams 与传统的单代理模式在工作机制上有何根本不同？
「答案：」 传统模式下代理按顺序独立完成任务；Agent Teams 模式下引入了“主代理”与“队友”的角色分工，支持任务的并行处理与上下文隔离。

在过去，Claude Code 就像一名尽职尽责的单人开发者。你下达指令，它开始执行第一行代码，完成后移动到第二行。这种线性的、串行的工作方式虽然稳定，但在面对复杂项目时，时间的消耗是线性的累积。

Agent Teams 彻底打破了这一限制。当你描述一个目标时，不再是一个代理独自苦干，而是一个主代理先审视任务，将其拆解为多个独立的模块，然后为每个模块启动一个独立的队友。

「场景举例：」
假设你正在开发一个新的支付网关功能。

  • 「传统模式：」 一个代理先写 API 接口，写完后再写数据库模型，最后写单元测试。
  • 「Agent Teams 模式：」 主代理分配任务——队友 A 负责 API 接口，队友 B 负责数据库模型，队友 C 负责编写单元测试。三个人同时在各自的上下文窗口中工作，互不干扰，最终由主代理整合成果。

这种模式下，每个队友都拥有独立的上下文窗口和工作空间。它们不仅仅是向主代理汇报，还能直接通过消息交换意见。例如，负责 API 的队友发现数据库字段设计有问题，可以直接通知负责数据库的队友，而不需要通过主代理层层转达。主代理则始终处于全局视角，管理着共享的任务列表，并在队友完成工作后进行最终的整合。

深度对比：子代理与 Agent Teams 的本质区别

本节核心问题：既然已经有了子代理功能，为什么还需要 Agent Teams？
「答案：」 子代理是廉价、单向的助手，专注于单一任务；Agent Teams 是昂贵、双向交互的专业团队，专注于需要复杂协作的工程。

如果你是 Claude Code 的老用户，可能已经使用过“子代理”。它们通常在会话内部启动，完成一个特定任务（如读取文件或搜索文档），然后返回结果。这种方式简单有效，且相对节省 Token。

但 Agent Teams 是完全不同的“物种”。我们可以通过以下表格清晰地看到它们的差异：

特性 子代理 Agent Teams
「独立性与上下文」 在主会话内运行，上下文依赖主会话 每个队友都是完全独立的 Claude Code 会话，拥有独立上下文窗口
「交互模式」 单向汇报：子代理 -> 主代理 多向交互：队友 <-> 队友，队友 <-> 主代理
「协作能力」 无，仅执行被分配的孤立任务 强，通过共享任务列表和直接消息进行自我协调
「成本」 较低 较高（因为同时运行多个会话）
「适用场景」 快速查询、简单工具调用 复杂问题解决、并行开发、代码审查

什么时候用哪个？

选择的关键在于：「你的工作者之间是否需要沟通？」

  • 「使用子代理：」 如果你只是需要一个快速的结果，比如“帮我查一下这个函数的用法”，不需要额外的协调。这就像派助手去拿一杯咖啡，拿回来就行。
  • 「使用 Agent Teams：」 如果工作能从协作中受益。这就像把一组专家放在一个房间里，让他们共同解决一个难题。虽然成本更高，但对于复杂、多部分的工作，单个代理花费的时间可能远超团队协作的总和。

❝

💡 「专家反思：成本与价值的权衡」
从工程经济学的角度看，Agent Teams 引入了一个新的成本维度：通信开销与并行收益。在 AI 编程中，我们习惯了线性思考（Token 消耗与时间成正比）。但 Agent Teams 告诉我们，通过支付额外的“并行计算费用”（同时运行多个实例），我们可以换取时间上的指数级压缩。这不仅仅是技术的升级，更是 AI 辅助开发思维的范式转移。

❞

战略决策：何时启用 Agent Teams 才最具性价比？

本节核心问题：在什么场景下使用 Agent Teams 是明智的，什么时候又是浪费资源？
「答案：」 当任务可以被拆解且并行探索能显著增值（如竞对假设调试、跨层开发）时使用；对于强依赖顺序的任务或简单任务，应避免使用。

Agent Teams 并不是一个“适用于所有场景”的万能功能。由于它增加了协调开销，并且消耗 Token 的速度显著快于单会话，你需要有策略地决定何时启动它。

最佳适用场景

  1. 「研究与审查：」
    当需要从多个角度调查问题时。例如，多个队友同时调查代码库的不同部分（安全性、性能、可读性），然后对比笔记。这种并行探索能大幅减少盲区。

  2. 「功能构建：」
    当每个队友可以拥有一个独立的模块或文件时。例如，队友 A 负责前端组件，队友 B 负责后端逻辑，队友 C 负责数据层。每个人都拥有自己的一块领地，互不踩脚。

  3. 「调试——最精彩的场景：」
    这是 Agent Teams 最具威力的地方。传统调试中，一个代理可能沿着一条错误的理论路径越走越远，浪费大量时间。有了 Agent Teams，你可以启动多个队友，让他们并行测试「竞争性的假设」。

    • 场景： 程序崩溃。
    • 队友 A： 验证“内存泄漏”假设。
    • 队友 B： 验证“并发竞态”假设。
    • 结果： 谁先找到答案谁就赢，其他的队友可以立即停止工作。

应该避免的场景

  1. 「顺序依赖任务：」
    如果第二步必须依赖第一步完成后的结果，那么并行化没有任何意义，只会增加上下文同步的复杂性。

  2. 「同文件编辑：」
    让两个队友同时编辑同一个文件是灾难性的。这会导致版本冲突和覆盖问题。确保任务拆解时，每个队友拥有独立的文件集合。

  3. 「简单任务：」
    如果协调任务的成本比让一个代理快速处理还要高，那就不要用团队。

Teamwork Strategy
图片来源：Unsplash

安装与配置：30 秒启用实验性功能

本节核心问题：如何在自己的环境中开启 Agent Teams 功能？
「答案：」 通过在 settings.json 中添加特定配置或设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 即可启用。

由于 Agent Teams 目前处于实验阶段，默认是禁用的。在使用之前，你必须手动开启它。这里有两种方法，你可以根据个人习惯选择。

方法一：修改 settings.json 文件（推荐）

这是最干净的方法，配置会持久化保存。你需要找到你的 Claude Code 配置文件 settings.json，然后添加以下内容：

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

确保 JSON 格式正确，特别是逗号和括号的位置。保存文件后，重启 Claude Code 即可。

方法二：设置 Shell 环境变量

如果你不想修改配置文件，或者只是想在当前会话中临时测试，可以直接在 Shell 中设置环境变量：

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

这种方法在当前终端会话关闭后失效。

验证配置

完成上述任一步骤后，Claude Code 就会识别 Agent Teams 相关的命令了。此时，你就可以开始尝试创建你的第一个团队。需要注意的是，作为一个实验性功能，官方文档可能会更新，但目前上述配置是开启它的标准方式。

❝

💡 「专家反思：实验性功能的魅力与风险」
作为早期采用者，使用实验性功能总是伴随着“粗糙边缘”的风险。这就像在软件发布 Alpha 版本时就投入生产，虽然可能会有 Bug，但你获得的是先行者的优势和效率红利。通过 settings.json 这种底层方式控制功能开关，体现了 Anthropic 给予高级用户的控制权，同时也提醒我们：这是一个正在快速演进的工具。

❞

启动你的第一个 Agent Team

本节核心问题：如何通过提示词正确启动并分配任务给 Agent Team？
「答案：」 使用自然语言描述需求，明确指定队友的独立角色（如 UX、架构等），避免任务重叠，即可让主代理生成团队并开始工作。

你不需要学习任何特殊的编程语法来启动团队。只需要用清晰的自然语言告诉 Claude 你想要什么，并指示它创建一个团队。

提示词工程：明确角色是关键

一个成功的启动提示词，核心在于给主代理提供足够清晰、独立的角色定义。如果任务太模糊，主代理不得不花费大量 Token 去自行拆解结构，这通常会导致结果不够聚焦。

「最佳实践示例：」

假设你要设计一个帮助开发者跟踪代码库中 TODO 注释的 CLI 工具。

❝

“我正在设计一个 CLI 工具，用于帮助开发者跟踪代码库中的 TODO 注释。请创建一个代理团队，从不同角度进行探索：一名队友专注于用户体验（UX），一名队友专注于技术架构，另一名队友担任‘魔鬼倡导者’（Devil’s Advocate）来挑刺。”

❞

在这个例子中，你明确了三个独立的维度：UX、架构和批判性审查。这比仅仅说“帮我设计一个工具”要有效得多。

指定队友数量与模型

你还可以进一步控制团队的规模和使用的模型：

❝

“创建一个由 4 名队友组成的团队，并行重构这些模块。每个队友使用 Sonnet 模型。”

❞

显示模式选择

一旦团队开始运行，你有两种显示模式可选：

  1. 「进程内模式（默认）：」
    所有队友都在主终端内运行。你可以使用 Shift + Up 或 Shift + Down 键在不同的队友输出之间循环切换。这种模式兼容性最好。

  2. 「分屏模式：」
    这种模式下，每个队友都有自己的面板，你可以同时看到所有人的输出。但这需要终端支持 tmux 或 iTerm2。注意：VS Code 的集成终端、Windows Terminal 或 Ghostty 目前不支持分屏模式，只能使用默认的进程内模式。

运行时控制：如何指挥你的团队

本节核心问题：在团队运行过程中，如何进行干预、沟通和任务管理？
「答案：」 可以直接与任意队友对话，使用 Delegate Mode 限制主代理仅做协调，并通过任务列表管理工作流。

当你的团队开始运转后，作为“管理者”，你需要掌握几个关键的控制操作，以确保项目按预期推进。

1. 直接与队友沟通

你不需要通过主代理传话。在进程内模式下，按下 Shift + Up 或 Shift + Down 选中某个队友，直接开始输入即可。在分屏模式下，直接点击对应的面板，就像操作正常的 Claude Code 会话一样。这对于纠偏或追问非常有用。

2. 使用 Delegate Mode（委托模式）

这是一个解决常见痛点的重要功能。有时候，主代理会决定“既然任务这么急，不如我自己动手做”，而不是等待队友完成。这违背了使用团队的初衷。

「Delegate Mode」 的作用是将主代理锁定为“纯协调者”状态。开启后，主代理只能生成队友、分配任务、发送消息和管理任务列表，不能亲自下场写代码。

  • 「操作方法：」 当团队运行后，按下 Shift + Tab 即可切换此模式。

3. 任务分配与认领

在 Agent Teams 中，任务管理是灵活的：

  • 「主分配：」 主代理指定谁做什么。
  • 「自认领：」 当队友完成当前任务后，它们会自动查看共享的任务列表，并认领下一个未分配的任务。

如果你需要更精细的控制，可以直接告诉主代理将特定任务分配给特定的队友。

4. 关闭与清理

资源管理很重要。当队友完成工作后，你可以要求主代理将其关闭。

  1. 主代理发送关闭请求。
  2. 队友确认。
  3. 队友优雅退出。

当整个团队的所有任务都完成后，告诉主代理进行“清理”，它会移除所有共享的团队资源。「切记：」 在运行清理之前，请确保所有队友都已经关闭。

最佳实践：避免 Token 浪费的实战技巧

本节核心问题：如何在使用 Agent Teams 时最大化效率并最小化成本？
「答案：」 提供详细的生成提示词，合理切分任务大小，确保文件隔离，并从非代码类的审查任务开始练习。

Agent Teams 因为并行运行多个会话，Token 消耗速度极快。以下技巧能帮你省钱并减少挫败感。

1. 提供详细的生成提示词

队友虽然会自动从你的项目目录和 MCP 服务器加载上下文，但它们「不会继承主代理的对话历史」。
这意味着，如果队友需要了解特定的背景信息才能做好工作，你必须把这些信息包含在主代理生成队友时的提示词里。前期越具体，后期的来回扯皮就越少。

2. 合理控制任务粒度

  • 「太细碎：」 如果任务太小（比如“改一个变量名”），协调任务的开销会比任务本身还大，得不偿失。
  • 「太宏大：」 如果任务太大，队友会工作很久而没有检查点，增加了走错方向浪费资源的概率。
  • 「最佳甜区：」 自包含的任务单元，能够产出明确的交付物，比如“写完这个函数”、“生成这个测试文件”或“完成这个模块的代码审查”。

3. 严格的文件隔离

永远不要让两个队友编辑同一个文件。这会导致覆盖冲突，这是一个你绝对不想处理的头疼问题。拆分工作时，确保每个队友拥有自己的一组文件。

4. 学习曲线：从审查开始

如果你是新手，不要一开始就尝试让团队并行构建复杂代码。建议从「研究和审查」任务开始。

  • 让队友从不同角度审查一个 Pull Request（PR）。
  • 让队友用竞争性理论调查一个 Bug。

这些任务能让你直观感受到并行工作的价值，而无需承担同时编写代码带来的协调复杂性。

5. 定期检查

不要让团队在无人看管的情况下运行太久。定期查看进度，特别是防止某个队友在一个低效的路径上越陷越深。

❝

💡 「专家反思：上下文隔离的隐形优势」
很多人认为队友不继承主代理历史是一个缺陷，但我认为这是架构设计的精妙之处。如果每个队友都继承完整的历史，上下文窗口会瞬间爆炸，成本也会失控。这种“上下文隔离”迫使我们作为用户必须更清晰地表达意图，实际上是在训练我们写出更好的 Prompt。这也让每个队友保持“轻量”和“专注”，正如在一个高效的人类团队中，并不是每个人都需要知道会议前五分钟所有的闲聊内容，只需要知道分配给自己的任务背景。

❞

当前局限性：不要因为这些而责怪工具

本节核心问题：目前的 Agent Teams 还有哪些已知的未完善之处？
「答案：」 进程内队友不支持会话恢复、任务状态可能滞后、单会话单团队限制以及分屏模式对终端有特定要求。

作为一个研究预览功能，Agent Teams 有一些粗糙的边缘。提前了解这些可以避免你在遇到问题时误以为是自己的操作失误。

  1. 「会话恢复不支持：」
    如果你使用 /resume 或 /rewind 命令，你的队友不会回来。主代理可能会尝试向它们发送消息，但它们已经不存在了。如果发生这种情况，只需告诉主代理重新生成队友。

  2. 「任务状态延迟：」
    有时候队友完成了工作，但忘记将任务标记为“已完成”。这会阻塞所有依赖该任务的其他任务。如果看起来卡住了，检查工作是否真的完成了，然后手动更新状态，或者告诉主代理提醒一下队友。

  3. 「架构限制：」

    • 每个会话只能运行一个团队。
    • 队友不能生成自己的团队（不能套娃）。
    • 创建团队的会话在其整个生命周期内始终是主代理，不能中途提拔队友或转移领导权。

  4. 「平台兼容性：」
    分屏模式仅支持 tmux 或 iTerm2。VS Code 集成终端、Windows Terminal 或 Ghostty 暂不支持。不过，默认的进程内模式在所有平台上都能正常工作。

了解这些限制后，你就可以更从容地规划工作流，把它们当作当前版本的边界条件，而不是不可逾越的障碍。

结论与展望

本节核心问题：Agent Teams 的未来发展方向是什么，现在值得投入时间学习吗？
「答案：」 这是一个处于快速迭代中的基线功能，随着协调和关闭行为的完善，它将成为 Claude Code 的标准配置，现在建立肌肉记忆将带来先发优势。

Agent Teams 目前处于研究预览阶段，这意味着 Anthropic 正在积极开发它。今天的版本只是一个基线，远非天花板。随着他们解决会话恢复、任务协调和关闭行为中的粗糙边缘，这一功能将逐渐成为人们使用 Claude Code 的标准方式。

那些现在就开始安装、使用并建立肌肉记忆的人，将在该功能移出预览并成为默认配置时，拥有显著的效率优势。正如从单人编程到结对编程的跨越，从单代理到多代理团队的演进，或许正是 AI 辅助开发的下一个里程碑。

实用摘要 / 操作清单

为了方便你快速上手，以下是基于本文内容的操作要点总结：

启用前准备

  • [ ] 打开 settings.json 或设置环境变量 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 为 “1”。
  • [ ] 确保你使用的是支持的终端（如需分屏功能则需 tmux 或 iTerm2）。

团队启动

  • [ ] 使用自然语言明确指定队友的独立角色（如 UX、架构、测试）。
  • [ ] 可指定模型（如 Sonnet）和队友数量。
  • [ ] 避免任务定义模糊，确保主代理能直接分配。

运行中管理

  • [ ] 使用 Shift + Up/Down 在进程内模式中切换队友。
  • [ ] 按 Shift + Tab 开启/关闭 Delegate Mode，强制主代理只做协调。
  • [ ] 直接选中队友进行对话，不必通过主代理传话。
  • [ ] 确保不同队友编辑不同的文件，防止冲突。

最佳实践

  • [ ] 在生成队友的提示词中包含详细背景，因为它们不继承主代理历史。
  • [ ] 从代码审查或调查类任务开始练习，再过渡到并行开发。
  • [ ] 定期检查任务状态，防止队友卡在未标记完成的状态。
  • [ ] 任务结束后，手动指示关闭队友并清理资源。

一页速览（One-page Summary）

概念 关键点
「定义」 原生多代理系统，主代理协调，队友并行工作，独立上下文。
「对比子代理」 子代理=单向助手（便宜）；Agent Teams=协作专家（贵，功能强）。
「启用方法」 设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"。
「启动指令」 明确角色分工（例：“A做UX，B做架构，C做测试”）。
「显示模式」 In-process（通用，切换窗口）；Split-pane（需 tmux/iTerm2）。
「快捷键」 Shift+Up/Down（切换队友），Shift+Tab（切换 Delegate Mode）。
「最佳场景」 调试（竞争假设）、跨层开发、多维代码审查。
「避坑指南」 避免同文件编辑；避免强依赖顺序的任务；注意 Token 消耗。
「当前限制」 不支持会话恢复、状态可能滞后、单会话单团队。

常见问答（FAQ）

  1. 「Agent Teams 和普通的子代理有什么本质区别？」
    Agent Teams 中的每个队友都是独立的会话，拥有自己的上下文，并且队友之间可以直接双向沟通和协作；而子代理只是在主会话中执行简单单向任务，无法相互交流。

  2. 「如何在 Claude Code 中开启 Agent Teams 功能？」
    你需要在 settings.json 文件中添加 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1" 配置，或者在 Shell 中设置该环境变量。

  3. 「使用 Agent Teams 会消耗更多的 Token 吗？」
    是的，因为它是同时运行多个独立的 Claude Code 会话，所以 Token 的消耗速度会比单个会话快得多，建议用于复杂任务。

  4. 「我想让多个队友同时写代码，应该注意什么？」
    最重要的是确保每个队友负责编辑不同的文件。如果两个队友同时修改同一个文件，会导致代码覆盖和冲突。

  5. 「如果队友完成任务后没有更新状态怎么办？」
    这是当前预览版的一个已知限制。你可以手动检查工作是否完成，然后告诉主代理更新状态，或者提醒队友确认。

  6. 「VS Code 的集成终端可以使用分屏模式查看队友吗？」
    不可以。目前分屏模式仅支持 tmux 或 iTerm2。在 VS Code 中只能使用默认的进程内模式，通过快捷键切换队友视图。

  7. 「主代理有时候会自己去写代码而不分配给队友，怎么解决？」
    你可以按下 Shift + Tab 开启“委托模式”，这样主代理就被锁定为只能进行协调，无法亲自执行代码任务。