启用 Agent Teams 必须设置的环境变量（解析未启用时的具体行为）

启用 Claude Code Agent Teams 的关键变量是 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS，把它设为 1 才能让多 Agent 协作进入激活态；只要这个变量未设置或值不为 1，会话启动阶段就不会生成任何团队目录，也不会出现团队负责人与队友两类角色，Claude 会把任务当成普通单会话执行。下面从变量位置、未启用时的具体表现、典型使用形态与易错点四块展开。

一、必须设置的环境变量

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 唯一作用是给运行时”打开”多 Agent 协作的开关，它属于 Claude Code 的实验性能力（agent teams 默认处于关闭态），因此必须显式声明。配置方式有两种，二选一即可：

配置方式	写法	适用场景
Shell 环境变量	`export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`	当前终端会话临时启用
项目级 settings.json	`{"env": {"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"}}` 写入 `~/.claude/settings.json`	长期启用、跨会话复用

变量值必须是字符串 "1"，非 1 之外的真值（如 true、yes、on）不被识别，仍会按未启用处理。需要 Claude Code 2.1.32 及以上版本才能生效，老版本不会读取这一变量。

二、变量未设置时系统的具体表现

未设置或值非 1 时，运行时的行为变化是可观察的，而不是”仅在提示词层屏蔽”。官方说明明确指出三条具体表现：

不会建立任何团队结构：会话启动时不会写入团队目录、不创建任务列表文件，也不分配 team_name；
不会生成队友：Claude 既不会主动 spawn 队友，也不会提议组建团队，所有子任务仍走主会话或 subagent 通道；
不会切换为多 Agent 协作语义：即使你在提示词里写”请组织一个三人团队”，Claude 也会以单 Agent 视角做计划或转用 subagent，而不会构建共享任务列表与队友间直接消息通道。

可以把这条变量看作”多 Agent 协作的总闸”：闸门关闭时，整个 Agent Teams 的运行时机制（任务认领、队友间直接消息、共享任务列表、worktree 隔离）都不存在；闸门打开时，Claude 才会按多 Agent 协议分配工作。

三、启用后的典型工作流

启用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 后，团队启动与任务流转可按以下顺序操作：

在终端导出变量并启动 Claude Code：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 && claude；
用自然语言描述目标与角色拆分，例如”我要做一个 CLI 工具追踪 TODO 注释，请拉一支三人团队，分别负责 UX、技术架构、对失败模式挑战”；
团队负责人自动创建任务列表并分配 / 认领任务，队友在各自 context window 内独立执行；
通过 Shift+Down 在 in-process 模式下轮询各队友消息，或在 tmux / iTerm2 下用 split-pane 模式同时观察多个队友；
任务结束后向负责人发送”清理团队”指令，会话退出时团队目录自动回收。

变量打开还会带来一个连锁变化：Claude 命名生成的 subagent 会自动以”队友”身份启动，使得即使你没明确要求组建团队，也可能在会话中看到多 Agent 形态出现。

四、变量启用前后的行为对比

下面用一张表把关键差异点对齐，方便排查”为什么我看不到队友”或”为什么任务没有分配给队友”。

维度	变量未设置或值非 `1`	变量设为 `1`
团队目录	不会创建	启动时自动生成
队友 spawn	不发生	按自然语言指令生成
通信方式	仅 subagent 向主会话回报	队友间可直接发消息
任务列表	不存在共享列表	自动维护共享任务列表与认领锁
协调成本	与单会话持平	显著上升，token 消耗成倍增加
关闭 / 清理	无需处理	退出会话时自动清理

五、常见易错点与建议

最容易踩的坑是”以为设置了就能用”——版本低于 2.1.32、变量值写成 true、把变量写进普通 package.json 而非 settings.json，都会让运行时走未启用分支。建议先在终端用 claude --version 确认版本，再通过 echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 确认值，最后用一段简短任务验证团队目录是否被创建。还要注意：Agent Teams 是实验性能力，会话恢复、任务协调、关闭行为都存在已知限制，生产环境应预留回退到单会话的方案。在排错时还可以打开 Claude Code 的日志，观察是否出现 “agent teams enabled” 或 “team directory created” 这类提示，缺失提示即说明变量未生效。同时建议把变量配置统一收口到 ~/.claude/settings.json 的 env 字段，避免在多个 shell 窗口里各自导出造成行为不一致。团队规模上也建议从两到三个队友开始，等流程跑稳再考虑扩展，多人协作的协调成本会随角色数量非线性增长。

下面这段配置示例同时覆盖 shell 导出与 settings.json 两种写法，可直接复制到本地验证：

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "in-process"
}

# 临时启用：仅在当前 shell 窗口生效
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude --teammate-mode in-process

配置完成后用 claude --version 检查版本号不低于 2.1.32，再用一段简短任务验证团队目录是否被创建。配置生效后，Claude 命名生成的 subagent 会自动以”队友”身份启动，使得即使你没显式要求组建团队，也可能在会话中观察到多 Agent 形态出现。

常见问题（FAQ）

Q1：把 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 设为 1 后，还需要额外配置什么吗？

不需要额外环境变量；如需 split-pane 展示，准备好 tmux 或 iTerm2 即可。

Q2：变量未设置时，写”请组建团队”会被忽略吗？

会被忽略；Claude 会回退到单会话或 subagent 模式，不会生成团队目录与队友。

Q3：变量已设置但没有出现队友，可能是什么原因？

通常是版本低于 2.1.32、变量值非字符串 1，或 settings.json 写错位置，逐项排查即可。