Claude Code Agent Teams多Agent协作怎么配？从开启到避坑实战

摘要：Agent Teams是Claude Code里一个还挂着实验标签的能力（需要v2.1.32以上，靠环境变量CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1打开）。它和子代理最大的不同，是队友之间能直接通信、共享一份任务清单、自己认领活儿，而不是像子代理那样只能埋头干完向主会话汇报一句。它最适合并行评审、竞争假设调试、跨层开发这类"多视角同时推进才有价值"的活，代价是Token随队友数量近乎线性地涨上去。这篇把开启方式、四个核心组件、显示模式怎么选、三个真实场景，以及计划审批、指定模型、Hooks质量门禁这些容易被忽略的高级控制讲透，最后给一份上手避坑清单。

用Claude Code久了你会撞上一堵墙：明明手头三件事互不相干——后端写接口、前端做表单、有人补测试——可单个会话只能一件一件串着来，你在旁边干等。串行的本质问题不是慢，是它逼着一个上下文窗口同时装下三件事的全部细节，越往后越拥挤，越拥挤越容易出错。

Agent Teams想解决的就是这个。它让你在一个Claude Code会话里拉起一支"队伍"：一个Team Lead当队长，分活、协调、汇总；底下若干Teammate各自独立干，还能互相喊话。这篇不堆概念，按"它是什么→怎么开→怎么跑→怎么选→怎么用好"的顺序走一遍，顺带把官方文档里几处和坊间流传不一致的细节标出来，免得你照着过时的说法配了半天发现对不上。

Agent Teams和子代理到底差在哪？

很多人第一反应是："这不就是子代理（subagent）开了好几个吗？"差别恰恰在这。

子代理的模型是单向汇报：主会话派一个子代理去查资料或跑测试，子代理在自己的上下文窗口里闷头干完，把结论压缩成一段话回给主会话，仅此而已。子代理之间彼此不知道对方存在，更别说交流。这套机制的好处是省上下文——脏活累活在别的窗口干，主对话只收一份摘要；坏处是没法协作，五个子代理查同一个bug，会各查各的，谁也不知道别人排除了哪些可能。

Agent Teams换了一套模型：队友之间能直接通信。每个Teammate同样有独立上下文窗口，但它们共享一份任务清单，能自己认领没人做的活，能给指定队友发消息互相质疑、互相补位。你作为人，也能绕过队长直接找某个队友追问、纠偏，而不必所有指令都从队长那儿转一道。

官方的Agent Teams文档把这个取舍讲得很直白：选型的唯一判断标准，是你的这些"工人"需不需要彼此交流。下面这张表是两者的硬区别，记住它基本就不会用错：

一句话记忆法：要的是干净利落、办完就回的临时工，用子代理；要的是能商量、能互相挑刺、能自己分工的小队，用Agent Teams。这两个机制不是替代关系，更不是谁高级谁低级。它和Claude Code的另外几套扩展能力也各管一摊——想理清楚MCP、Skills、Hooks各自的边界，可以对照看Claude Code三大扩展机制怎么选那篇，省得把工具张冠李戴。

怎么开启Agent Teams？

这是个默认关着的实验功能，所以第一步是确认版本，第二步是手动打开。两步都别跳。

先看版本。Agent Teams要求Claude Code v2.1.32或更高，命令行敲一下确认：

claude --version

版本不够的话，跟着官方升级流程更到最新就行。这里要纠正一个流传挺广的说法：网上不少教程把Agent Teams描述成"某月某日随某个Opus版本一起发布的功能"，听着像是和某个模型版本绑定的。实际上官方文档只标了Claude Code的版本门槛（v2.1.32+），并没有把它和某个模型绑死。你用Opus也好、Sonnet也好，只要客户端版本够、功能开了，就能用。版本这种东西更新很快，照着官方的版本号核对，比记某个"发布日"靠谱。

再说打开。设一个环境变量CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS为1即可，可以写进shell环境，也可以写进settings.json的env段（推荐后者，跟着配置走，换台机器也不丢）：

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

开完重启会话，就可以用自然语言让Claude拉队伍了。注意"实验"这两个字不是摆设——官方明说它在会话恢复、任务协调、关闭行为三块都有已知限制，下文"上手避坑"会逐条讲。生产环境的关键任务现在还不建议无人值守地全交给它跑。

一支团队是怎么跑起来的？

开启之后，你不需要写什么配置文件去定义团队结构，直接用大白话告诉Claude你想要什么样的队伍、干什么活就行。比如：

我在设计一个帮开发者追踪代码库里 TODO 注释的 CLI 工具。
建一个 agent team 从不同角度探一探：一个队友看用户体验，
一个看技术架构，一个专门唱反调挑毛病。

Claude会据此建团队、生成队友、分派任务，干完还会尝试自己清理团队。这个例子之所以好用，是因为三个角色彼此独立，谁也不用等谁——这正是Agent Teams发挥价值的前提。

底层看，一支团队由四个组件构成，理解它们你才知道出问题时去哪儿排查：

这套东西的状态是落在本地磁盘的，知道位置有时候能救命。团队配置在~/.claude/teams/{团队名}/config.json，任务清单在~/.claude/tasks/{团队名}/。这里有个坑要提前打预防针：团队配置文件里存着会话ID、tmux面板ID这类运行时状态，是Claude Code自动生成并随时刷新的，千万别手动去改它、更别想着预先写一份，你写的内容下一次状态更新就被覆盖掉了。另外，项目目录里放一个类似.claude/teams/teams.json的文件是没用的，Claude不会把它当配置识别，只当普通文件。

任务清单有个让人安心的机制：任务之间可以设依赖，一个还有未完成前置依赖的任务是没法被认领的；而当某个队友干完了被别人依赖的任务，那些被卡住的下游任务会自动解锁，不需要你手动去捅。多个队友抢同一个任务时，靠文件锁来防止竞态，不会出现两个人同时认领同一件活的尴尬。

三种并行方案到底该怎么选？

聊到这儿绕不开一个更大的问题：Claude Code里能"并行"的玩法不止Agent Teams一种。还有子代理，还有Git worktree。三者解决的是不同层次的并行，选错了会很别扭。

分辨它们其实有个朴素的判断链。第一问：这些活需要彼此交流吗？需要，往Agent Teams走；不需要，继续。第二问：我只要个结果、不在乎过程吗？是，用子代理一派了之；如果是要长期维护几条互不干扰的功能分支、各跑各的会话，那就是Git worktree的主场了。worktree怎么用、和Agent Teams怎么配合，可以看Claude Code Worktree实战指南那篇，两套机制其实能叠着用：worktree隔离分支，团队在某个分支里并行干。

保哥的体会是，新手最容易犯的错，是看到"并行"两个字就无脑上Agent Teams。结果一个简单到单会话十分钟能搞定的活，开了三个队友，光协调和Token就把省下来的时间赔进去了。并行不是越多越好，它解决的是"多视角同时推进确实有价值"的问题，不是所有任务都配得上这个排场。

显示模式选in-process还是分屏？

队伍跑起来后，你得能看见队友在干嘛、能插话。Agent Teams提供两种显示模式，这里有个细节经常被传错，务必看清楚。

in-process模式：所有队友都跑在你的主终端里，按Shift+Down在队友之间循环切换，切到谁就能给谁发消息。它不挑终端，任何终端都能用，零额外配置。

分屏（split panes）模式：每个队友单独占一个窗格，你能同时看到所有人的输出，点进哪个窗格就直接和谁交互。但它需要tmux或iTerm2支持。

关键的纠正来了：默认模式不是in-process，而是"auto"。auto的逻辑是——如果你本来就在一个tmux会话里跑Claude，它用分屏；否则用in-process。还有个"tmux"选项，强制开分屏并自动判断用tmux还是iTerm2。想固定下来，在~/.claude/settings.json里设teammateMode：

{
  "teammateMode": "in-process"
}

只想给当前这一次会话强制in-process，命令行加个标志即可，不动全局配置：

claude --teammate-mode in-process

顺带说几个分屏的硬限制，免得你装了半天发现不支持：split panes 在VS Code内置终端、Windows Terminal、Ghostty里都不支持，这些环境只能走in-process。tmux本身在某些操作系统上也有已知限制，传统上macOS体验最好；iTerm2用户走tmux -CC是官方推荐的入口。in-process是那个"哪儿都能用"的稳妥选项，拿不准就用它。

常用快捷键归拢一下：Shift+Down循环切换队友（切到最后一个再按会绕回队长），Enter进入某队友的会话查看，Escape中断它当前这一轮，Ctrl+T切换任务清单显示。

实战：哪几类活真正值得开团队？

讲完机制，得落到"什么时候真该用"。官方点名的强场景有四类：研究与评审、新模块或新功能、竞争假设调试、跨层协调。下面挑三个最能体现价值的，结合保哥带客户站时的真实情形说一说。

场景一：并行代码评审

单个评审者有个改不掉的毛病——一次只盯一类问题，盯上了安全就顾不上性能，查完性能又忘了测试覆盖。把评审标准拆成几条互不重叠的独立赛道，让每个队友戴一副不同的"眼镜"同时看同一份代码，覆盖面一下子就上来了。一个典型指令是这样的：

建一个 agent team 评审 PR #142，开三个评审员：
一个专看安全隐患，一个查性能影响，一个验证测试覆盖。
让他们各自评审并汇报发现。

三个评审员看的是同一个PR，但各自套不同的过滤器，干完队长把三方发现综合成一份。保哥给一个做户外装备的DTC客户重构下单接口时就这么干过：安全队友揪出一处没做幂等的支付回调，性能队友发现一个N+1查询藏在订单列表里，测试队友补了一组边界用例。三件事要是串着来，光是反复切换关注点的损耗，比并行多花的Token贵多了。

场景二：竞争假设调试

这是Agent Teams最出彩的用法，因为它对症下药地治了一个人和单个AI都有的病——锚定效应。线索不明的时候，单个排查者往往找到一个看起来说得通的解释就停手了，剩下的可能性懒得再想。多个队友各执一个假设、还被明确要求互相拆台，活下来的那个理论才更可能是真凶。官方给的示范指令直接把"科学辩论"写进了prompt：

用户反馈 App 收到一条消息后就退出，没法保持连接。
开 5 个 agent 队友各查一个假设，让他们互相对话、
试着推翻对方的理论，像一场科学辩论。
把最后达成的共识更新到结论文档里。

这里的精髓是"辩论"这个结构。顺序排查会被锚定带跑偏，一旦先探了某个理论，后面的调查都会不自觉地往那个方向靠。而几个独立调查者主动互相证伪，能撑过这场围攻的解释，可信度高得多。保哥处理过一个WebSocket频繁断连的诡异问题，五个假设里——连接管理、token过期、服务端心跳、客户端重连、负载均衡的session亲和性——最后是"亲和性配置丢了"这个一开始没人看好的假设熬到了最后。要是单线程查，大概率卡在"重连逻辑"上出不来。

场景三：跨层并行开发

一个功能横跨前端、后端、测试三层，天然适合一人一层并行。后端队友负责接口、数据校验和落库，前端队友做表单、对接API、管表单状态，测试队友写单测和集成测试。原本串行要三四十分钟的活，并行下来十几分钟见雏形。但这个场景有个铁律：务必让每个队友负责不同的文件集。两个队友同时改同一个文件，结果就是互相覆盖，谁后写谁赢，前面的活白干。把工作切成"各管各的文件"，是并行实现类任务不翻车的前提。

这些高级控制，多数教程没讲全

基础场景之外，Agent Teams还有几个真正决定"能不能放心用"的控制项，恰恰是很多速成教程漏掉的。

给队友上"计划审批"

复杂或有风险的活，你可以要求队友先出方案、批准了才动手。队友会先在只读的计划模式里工作，把方案发给队长审批，没批之前一行代码都不改：

派一个架构师队友重构认证模块。
动手改任何东西之前，必须先通过计划审批。

队友规划完会发一个审批请求给队长，队长审了要么放行、要么带着反馈打回。被打回的队友留在计划模式里照反馈改了再交，直到通过才退出计划模式开始实现。队长是自主决定是否批准的，想影响它的判断，就在你的prompt里给标准，比如"只批准包含测试覆盖的方案""拒绝任何改动数据库schema的方案"。这一招对接管陌生代码库、或者改动面大的重构特别值，相当于在动手前加了一道闸。

给不同队友指定模型

队友默认不继承队长的/model选择。简单的活没必要都用顶配模型烧Token，你可以直接在prompt里指定：

建一个 4 个队友的团队并行重构这几个模块，每个队友用 Sonnet。

想改"prompt没指定时用哪个模型"这个默认值，去/config里设"Default teammate model"；选"Default（leader's model）"就让队友跟队长当前的模型走。这套分级用模型的思路，和单会话里"贵模型纠偏、便宜模型干活"的省钱逻辑是一脉相承的，Claude Code最佳实践那篇讲过怎么按任务难度选模型，团队里同样适用。

用子代理定义复用队友角色

这是个很多人不知道的隐藏福利：派队友时，你可以直接引用一个已定义的子代理类型（项目级、用户级、插件级、命令行定义的都行）。也就是说，你把"安全评审员""测试运行器"这种角色定义一次，既能当子代理派，也能当Agent Teams的队友复用：

用 security-reviewer 这个 agent 类型派一个队友去审计认证模块。

队友会遵循那个定义里的tools白名单和model，定义的正文会追加到队友的系统提示里（是追加不是替换）。有两个细节要记牢：一是团队协作工具（如发消息SendMessage、任务管理工具）始终对队友可用，哪怕tools限制了别的工具；二是子代理定义里的skills和mcpServers字段在当队友跑时不生效，队友的技能和MCP服务器是从你的项目和用户设置里加载的，跟普通会话一样。

用Hooks焊死质量门禁

想让规则自动执行、而不是靠你盯，就上Hooks。Agent Teams相关的有三个钩子，注意是三个，常见教程往往只列了前两个，把中间的TaskCreated漏了：

• TeammateIdle：队友即将空闲时触发。退出码2可以送一段反馈回去、让它继续干别停。
• TaskCreated：任务正被创建时触发。退出码2可以阻止这次创建并送反馈。
• TaskCompleted：任务正被标记完成时触发。退出码2可以阻止它被标记完成并送反馈。

退出码2这个约定是Hooks的通用语言——它表示"拦下来，这是我的意见"。比如你可以在TaskCompleted钩子里跑一遍测试，没过就用退出码2把"完成"挡回去，逼队友接着修。Hooks的事件类型、退出码语义这些底层规则，官方钩子文档讲得最全。

Token成本，到底值不值这个钱？

得把丑话说前头：Agent Teams比单会话明显更费Token。每个队友都有自己的上下文窗口，消耗随活跃队友数量大致线性增长。这里也纠正一个常见的精确化误区——你会看到"3-4倍"这种说法，但官方并没有给死一个倍数，只说随队友数线性涨。三个队友和六个队友的账，差着一倍呢，与其记一个虚的倍数，不如记住"队友越多越贵，而且是线性地贵"这个规律。

那什么时候这钱花得值？研究、评审、新功能开发这类天然能并行、又靠多视角提质量的活，多花的Token通常划算——把一两个钟头的串行工作压成一二十分钟，省下的人的时间远比Token贵。反过来，例行的、串行的、依赖一大堆的活，老老实实单会话更省。几条压成本的实操：

• 先用单会话评估这活到底值不值得并行，别一上来就拉队伍。
• 简单子任务指定用Sonnet这类更便宜的模型。
• 队友数量从3到5个起步，多数工作流这个区间最平衡——三个专注的队友常常比五个散乱的更出活。
• 每个队友配5到6个任务，既不闲着也不会上下文切换过频。15个独立任务，3个队友是个不错的起点。
• 干完的队友及时关掉，别让它空占着窗口烧钱。

上手避坑清单

实验功能，坑是真实存在的。把官方点名的已知限制和高频故障归到一处，照着这份单子心里就有数了：

• 会话恢复救不回in-process队友：/resume和/rewind不会恢复in-process队友。恢复会话后队长可能去找已经不存在的队友，碰上了就让队长重新拉一批新的。
• 任务状态会滞后：队友有时忘了把任务标成完成，卡住下游。看着卡住了，先确认活是不是真干完了，手动改状态或让队长去催。
• 关闭可能很慢：队友会先把当前这轮请求或工具调用跑完才关，急不得。
• 一次只能带一支队：一个队长同时只能管一个团队，建新队之前先把当前的清理掉。清理务必让队长来做（用一句"clean up the team"），队友自己跑清理可能因为团队上下文解析不对而留下一堆烂摊子。
• 不支持嵌套团队：队友不能再拉自己的队伍或队友，只有队长能管团队。
• 队长身份固定：建团队的那个会话终身是队长，没法把某个队友提拔成队长，也不能转移领导权。
• 权限在生成时定死：所有队友以队长的权限模式起步，队长要是开了--dangerously-skip-permissions，全体队友都跟着跳过确认。生成之后能单独改某个队友的模式，但没法在生成那一刻就给每人设不同模式。
• 队友不出现：in-process模式下它们可能已经在跑只是没显示，按Shift+Down循环看看；也确认下你给的活是不是复杂到值得开队——太简单Claude不会拉队伍。要分屏却没出来，which tmux查tmux装没装、在不在PATH里。
• 队长没干完就收工：队长有时会误判团队已经完事，提前收工。碰上了直接告诉它继续；也可以一开始就嘱咐它"等队友都干完再往下走"，免得它自己撸起袖子上手抢活。
• 残留tmux会话：团队结束后tmux会话没清干净，用tmux ls列出来，tmux kill-session -t <会话名>杀掉。

最后给个上手建议：新手别一头扎进并行写代码。先拿那些边界清晰、不用动代码的活练手——评审一个PR、调研一个库、排查一个bug。这类任务既能让你看到并行探索的价值，又避开了并行实现里"改同一个文件"那种最头疼的协调难题。等手感有了，再上跨层开发不迟。

常见问题解答

Agent Teams和子代理，到底该用哪个？

看一个问题就够：你的这些"工人"需不需要彼此交流。需要互相质疑、共享发现、自己分工的，用Agent Teams；只要派出去办完事回一份摘要、彼此不用打交道的，用子代理。子代理省Token，团队费Token但能协作，不是替代关系。

为什么我让Claude建团队，队友却没出现？

先按Shift+Down循环切换，in-process模式下队友可能已经在跑只是没显示。再确认你给的活够不够复杂——太简单Claude判断没必要就不拉队伍。如果明确要了分屏，用which tmux确认tmux装好且在PATH里，VS Code内置终端不支持分屏。

Agent Teams已经能用在生产环境的关键任务上了吗？

暂时不建议无人值守地全权交给它。它还挂着实验标签，会话恢复、任务状态同步、关闭行为三块都有已知问题。适合在你盯着的情况下做评审、调研、调试这类探索性工作，关键路径上的活留个人在旁边把关更稳妥。

队友会自动用我在队长里选的模型吗？

不会，队友默认不继承队长的/model。想统一就在prompt里直接指定（如"每个队友用Sonnet"），或去/config设"Default teammate model"，选"leader's model"才让队友跟队长走。简单活用便宜模型是控成本的关键。

会不会两个队友同时改一个文件把彼此覆盖了？

任务认领有文件锁防竞态，但代码文件的写冲突要靠你拆活避免——让每个队友负责不同的文件集。两个队友同时编辑同一文件就是互相覆盖、谁后写谁赢。这是并行实现类任务的头号铁律，拆任务时务必按文件边界切开。

开了团队Token大概会涨多少？

随活跃队友数量近乎线性增长，没有固定倍数——三个队友和六个队友差很多。研究、评审、新功能这类靠并行提质量的活通常划算，例行串行任务则单会话更省。控成本就少而精地用队友、简单子任务挂便宜模型、干完及时关闭。