2026年Claude Code 分屏配置

大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。

在 iTerm2 里开启 Claude Code Agent Teams，却仍然只看到一个终端窗口，通常不是团队没创建，而是队友仍在 in-process 模式。这个模式下，所有 teammate 都在主终端里，通过 Shift+Down 轮流切换；只有进入 split panes 模式，才会为每个 teammate 单独开 pane。

官方文档里有一个容易混淆的点：agent-teams 页面把 auto 描述成“已在 tmux 会话里才用 split panes”，settings 页面又把 auto 描述成“在 tmux 或 iTerm2 中选择分割窗格”。如果目标是在 iTerm2 里稳定分屏，最稳妥的做法不是赌 auto，而是显式开启实验开关，再把 teammateMode 设成 tmux。

Agent Teams 相关配置分散在两个地方：

实验开关 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 可以放在 shell 环境变量里，也可以写进 /.claude/settings.json 的 env。
显示模式 teammateMode 写在 /.claude.json。

teammateMode 不是 settings.json 字段。Claude Code 的 settings 文档明确写到，这类全局配置项保存在 /.claude.json，写进 settings.json 会触发 schema 校验错误。

Agent Teams 默认关闭。官方支持两种开启方式：

在 shell 环境里导出 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1。
或者写进用户级 /.claude/settings.json。

如果希望配置能长期生效，直接写文件更省事：

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

然后确认 Claude Code 版本不低于 v2.1.32：

claude –version

如果版本太旧，先升级，再重新打开 Claude Code 会话。

split-pane 模式需要二选一：

tmux
iTerm2 + it2 CLI

如果走 iTerm2 路线，官方给出的最小前置条件有三项。

先安装 it2：

go install github.com/tmc/it2/cmd/it2@latest

再在 iTerm2 里打开：

Settings → General → Magic → Enable Python API

修改后重启 iTerm2，再验证连接：

it2 auth check

这一步没过，Claude Code 通常就没法在 iTerm2 里自动创建 pane。

想稳定看到每个 teammate 单独占一个 pane，直接在 /.claude.json 里设置：

{  "teammateMode": "tmux" }

这里最容易误解的是值名。"tmux" 在 Agent Teams 文档里的含义不是“必须手动进入 tmux 会话”，而是“启用 split panes 模式”，然后 Claude Code 再根据当前终端判断用 tmux 还是 iTerm2。

常见值有三个：

auto：官方两页文档写法不完全一致；保守理解是“自动选择”，但在 iTerm2 里是否一定分屏，文档没有给出完全一致的描述。
in-process：所有 teammate 留在主终端里。
tmux：显式启用 split panes；在 iTerm2 下也会尝试走 iTerm2 分屏。

如果只想对单次会话禁用分屏，可以临时覆盖：

claude –teammate-mode in-process

如果目标就是在 iTerm2 里稳定分屏，最小配置如下。

/.claude/settings.json：

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

/.claude.json：

{  "teammateMode": "tmux" }

再配合两项 iTerm2 前置条件：

已安装 it2 CLI。
已开启 Enable Python API 并重启 iTerm2。

这一套配置的重点不是 auto，而是显式把 split-pane 模式打开。

如果已经在 iTerm2 里，但仍然没有分屏，优先检查下面几项：

先按 Shift+Down。文档明确提到，队友可能已经在 in-process 模式里运行，只是当前没有显示成 pane。
确认当前终端真的是 iTerm2。split-pane 模式不支持 VS Code 内置终端、Windows Terminal 和 Ghostty。
检查任务是否真的适合 agent team。任务太顺序化、太小，Claude 可能根本不会生成多个 teammate。
确认 it2 auth check 能通过。
确认 iTerm2 的 Enable Python API 已开启，而且修改后已经重启过 iTerm2。
确认 teammateMode 写在 /.claude.json，不是 settings.json。
确认 Claude Code 版本至少是 v2.1.32。

如果更想走 tmux 路线，Agent Teams 文档仍然建议在 iTerm2 里使用 tmux -CC 作为进入 tmux 的入口点。

Claude Code Agent Teams
Claude Code Settings
it2 documentation

2026年Claude Code 分屏配置 ​

相关推荐

2026年Claude Code 分屏配置