Claude Code 的 agent teams 跑不起来：成员、视图与任务分派的前置条件

2026-08-18

有一类现场特别容易误判：你写了「派三个 teammate 分头查这个 bug」，Claude 也确实起了几个 agent，可你后面想按名字单独给其中一个发指令、想看那个共享任务列表，全都对不上号；或者你的编排脚本在等一个 subagent 的返回结果，一直等不回来。

这些现象在 Claude Code 官方文档里都有明确的前提条件，麻烦在于条件散在好几处：开关在一处、会话形态要求在另一处、显示模式和平台限制又在第三处。典型现象大致是这几种——要求开团队但起来的是 subagent、teammate 起来了可行不见了、分屏一直没出来、等 subagent 结果的流程卡住、/resume 之后 lead 说联系不上 teammate。它们的判定动作不一样，别混着排。

判定一：开关到底有没有生效

文档在页首的警告框里写得很直白：agent teams 是 experimental，默认关闭，需要把 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 设为 1（在 settings.json 或环境变量里）。没有这个变量时，会话启动不建立任何 team、不写任何 team 目录，Claude 也不会 spawn 或提议 teammate。

所以最干脆的判定动作不是回忆自己配没配，而是去看磁盘上有没有生成目录。文档写明团队与任务按一个从 session 派生的名字存放，这个名字是 session- 加上 session ID 的前八个字符：

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

这两个都由 Claude Code 在会话启动时自动生成，并随 teammate 加入、转为 idle、离开而更新。目录压根没出现，就是开关没生效，别再往下查了。

处置就是文档给的这段配置：

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

这里有个会咬人的优先级细节，文档在故障排查一节写明了：在用户 settings.json 里把这个变量设为 0，会覆盖 shell 里的 export；但项目设置、本地设置和 --settings 载荷都在用户设置之后生效，其中任何一处把它设成 1 都会赢；managed settings 在所有来源之后生效，组织在那里开了的话只能找管理员改。所以「我明明关了怎么还在起 teammate」和「我明明开了怎么没有」，都得顺着这条链查一遍，而不是只看自己那一层。文档还写明改完不必新开会话：保存时 Claude Code 会把设置文件里的 env 值重新应用到运行中的会话，并且每次 spawn subagent 时都会重读这个变量。

Windows 侧：这两页给出的写法只有 settings.json 的 env 块，文档没有给 Windows 侧的 shell 导出写法。所以直接用 env 块这条路，是这两页里唯一有依据的写法（至于不同 Windows shell 之间环境变量导出语义的差异，属于通用运维经验，不是官方文档写明的内容）。另外，文档里的 ~/.claude/settings.json 这个路径写法在 Windows 上具体展开到哪里，这两页没有说明。

判定二：这是不是一个交互式会话

第二个前置条件很容易被忽略：spawn teammate 需要交互式会话。文档写明，在带 -p 的 non-interactive mode 下（包括 Agent SDK 会话），即使 agent teams 已启用，Claude 也不会 spawn teammate，被 Claude 命名的 subagent 就按普通 subagent 跑。

如果你的场景是 CI、headless 或 SDK 编排，那么「团队没组起来」不是配置问题，是文档写明的边界。

判定三：面板里有行，不等于 team 成了

这是最坑的一条，而且文档自己点破了：Claude 有时会改用 subagent 而不是建团队，subagent 与 teammate 出现在同一个 agent panel 里，所以光看面板确认不了团队是否形成。文档给的建议是：如果起的是 subagent，就再问一次并明确要求 agent team。

要拿到确凿证据，去读 team config。文档写明它包含一个 members 数组，每个成员有名字与 agent ID；lead 的条目 agent type 恒为 team-lead；teammate 的条目带的是 lead spawn 它时指定的 agent type（内置类型或某个 subagent 定义），没指定则不存在这个字段。teammate 之间可以读这个文件来发现其他成员。

两条配套红线也在文档里：这个 config 存的是 session ID、tmux pane ID 这类运行时状态，不要手改也不要预先写好，改动会在下一次状态更新时被覆盖；另外不存在项目级等价物，项目目录里放一个 .claude/teams/teams.json 不会被当成配置。

分派机制：任务是怎么落到具体成员头上的

确认团队成立之后，才轮到看分派。文档描述的共享任务列表有三种状态：pending、in progress、completed。任务之间可以有依赖，一个还有未解决依赖的 pending 任务不能被 claim，要等依赖完成；而依赖完成后的解锁是自动的，不需要你介入。

落到具体成员上有两条路径，文档并列写着：lead 显式指派（你告诉 lead 把哪个任务给谁），或者 teammate 自取（做完一个之后自己挑下一个未指派、未阻塞的任务）。多个 teammate 同时抢同一个任务的竞态，文档说是用文件锁处理的。

要注意，共享任务列表不是所有 agent 都有：文档写明没有 Task 工具的 agent 改用消息互相协调，看不到也认领不了共享任务。

想在分派环节加约束，文档指了三个 hook 事件，语义都是「退出码 2 阻断并回传反馈」：

Hook	触发时机	退出码 2 的效果
`TeammateIdle`	teammate 即将转入 idle	回传反馈并让它继续干活
`TaskCreated`	任务正在被创建	阻止创建并回传反馈
`TaskCompleted`	任务正在被标记完成	阻止标记完成并回传反馈

另一个和分派直接相关的机制是复用 subagent 定义：文档写明 spawn teammate 时可以引用任意 subagent 作用域（project、user、plugin、CLI 定义）里的类型，于是同一个角色定义既能当被委派的 subagent 用，也能当 teammate 用。生效范围要看清楚——teammate 遵循该定义的 tools allowlist 与 model，定义正文是追加到 teammate 的 system prompt 而不是替换它；对 in-process teammate，Claude Code 会往那份 allowlist 里加上 SendMessage，在拥有 Task 工具的会话里还会再加 TaskCreate、TaskGet、TaskList、TaskUpdate。

文档在这里专门加了一条注记，值得单独记住：subagent 定义里的 skills 与 mcpServers 两个 frontmatter 字段，在该定义作为 teammate 运行时不生效；teammate 的 skills 与 MCP 服务器是从你的项目与用户设置里加载的，跟普通会话一样。

权限侧同样是「spawn 时定死」：teammate 以 lead 的权限设置起步，lead 跑在 --dangerously-skip-permissions 下则所有 teammate 也是；spawn 之后可以改单个 teammate 的模式，但不能在 spawn 时按 teammate 分别设定。teammate 的权限提示冒泡到 lead 会话，需要你在那里批。文档把 plan approval 列为设计上的例外：lead 会自行批准 teammate 的计划，不再单独问你。

至于 agent 之间的消息，文档写明 Claude Code 会告诉接收方这条消息来自另一个 Claude 会话而不是来自你；teammate 不能替你批准权限提示或提供同意，被拒绝了某个动作的 teammate 也不能转手让别的 teammate 去做以绕过检查。auto mode 下另有分类器的两道检查：把「另一个 agent 转述的批准」当作不可信输入，以及在投递前审查每条消息（含 shutdown 请求、计划批准回复这类结构化协议消息），被拦下的消息不会到达接收方。这些是文档写明的机制，能不能满足你的安全要求，请结合自身环境评估。

显示模式与 Windows：分屏出不来多半不是你配错了

文档列了两种显示模式：in-process（全部 teammate 跑在主终端里）和 split panes（每个 teammate 一个窗格，需要 tmux 或 iTerm2）。默认值是 "in-process"；v2.1.179 之前默认是 "auto"，所以升级之后，原本会开分屏的会话现在会留在一个终端里，除非你显式设置。

设置项是 ~/.claude/settings.json 里的 teammateMode：

{
  "teammateMode": "auto"
}

单次会话则用 flag：

claude --teammate-mode auto

文档明说 --teammate-mode 这个 flag 是 experimental，并且不会出现在 claude --help 里——你在 --help 输出里搜不到它是正常的，别据此认为版本不对。

Windows 侧的结论比较硬：文档在 Limitations 一节写明，split-pane 模式不支持 VS Code 的集成终端、Windows Terminal 和 Ghostty，默认的 in-process 模式在任何终端都能用。也就是说，Windows 读者遇到「分屏怎么都出不来」，先别查配置，这是文档写明的不支持范围。文档给的排查命令 which tmux 是 shell 侧的写法，Windows 上的等价查法这两页没有说明。

（以上命令与配置片段均按官方文档中的参数语义组合，未经实测，以官方文档与 --help 的实际输出为准。）

处置之后怎么验证

按文档能核到的几条验证点：~/.claude/teams/ 下出现了 session- 开头的目录；config.json 的 members 数组里，lead 条目的 agent type 是 team-lead，teammate 条目带着你期望的类型；~/.claude/tasks/{team-name}/ 下有任务且状态在流转。文档还提醒，团队的共享目录在会话结束时自动清理，没有单独的清理步骤——team config 目录会被删除，任务列表目录保留在本地、从不上传，所以恢复的会话还能拿到自己的任务，保留期受你已有的 cleanupPeriodDays 管辖。

想在后续 prompt 里稳定引用某个成员，就在 spawn 指令里直接告诉 lead 该叫什么名字：文档写明 lead 在 spawn 时给每个 teammate 分配名字，任何 teammate 都能按名字给别人发消息。

什么情况说明不是这个原因

下面这些现象在文档里都有各自的解释，跟开关和配置无关：

teammate 的行不见了 ≠ 它停了。 文档说 idle 行是被隐藏了不是被停掉，隐藏期间 teammate 仍在运行且可寻址，按名字给它发条消息就能把行唤回来；idle 的 teammate 多到一定数量时，多出来的行会折叠成一行 N idle agents。不同版本的隐藏时机还不一样（v2.1.199、v2.1.181 至 v2.1.198、以及 v2.1.181 之前各有各的行为），排查前先确认自己在哪个区间。
等 subagent 结果的流程卡住，是「命名」造成的。 文档写明：启用 agent teams 期间，Claude 在 lead 会话里自己命名的 subagent 会以 teammate 身份启动，而 Claude 本来就会给普通 subagent 起名字以便后续给它发消息——于是你从没框定为团队协作的委派也可能变成团队。两者回报方式不同：subagent 完成时 Claude 收到结果，teammate 只会发一条 idle 通知说它停了、不带输出。等结果的编排流程因此可能停住。想改回去，把变量设为 0。
/resume 之后 lead 找不到 teammate，文档在 Limitations 里明说：/resume 与 /rewind 不恢复 in-process teammate，lead 可能会去联系已经不存在的成员，此时让它重新 spawn 就是了。
任务卡住不一定是依赖有问题。 文档承认任务状态会滞后：teammate 有时没把任务标成完成，从而阻塞依赖它的任务。
有些边界本来就没得配：一个会话恰好一支团队，不能建额外的具名团队也不能跨会话共享；不能嵌套团队，teammate 不能再 spawn 自己的 teammate；lead 是主会话且终生固定，不能把 teammate 提升为 lead。
在 claude agents 里找不到 teammate 是设计如此。 agent view 那一页写明，一个会话 spawn 的 subagent 与 teammate 不会作为单独的行列出。顺便一提，agent view 自身处于 research preview 阶段，文档写明界面与快捷键可能随功能演进而变化。
消息发不出去会明确报错。 文档写明每个 agent 的 mailbox 是 ~/.claude/teams/{team-name}/inboxes/{agent-name}.json，只有写入接收方 mailbox 文件成功才算发送成功；写入失败（比如磁盘满或 mailbox 目录不可写）时发送方收到错误，什么都不会发出。v2.1.207 之前，一条格式不对的 mailbox 条目会每秒重复报错并阻塞该 mailbox 的投递，得手工删文件。

最后提一句取舍：文档自述 agent teams 会带来协调开销、消耗的 token 明显多于单会话，适合各自能独立推进的工作；顺序任务、改同一个文件、依赖很多的活儿，用单会话或 subagent 更合适。这是文档自己写的判断，不是我们的评价。

本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。