1. 为什么要在 macOS 上折腾 Claude Code Agent TeamsClaude Code Agent Teams 是 Claude Code CLI 里一个偏实验性质的多智能体协作能力简单说就是让一个 Lead 会话带着多个 Teammate 会话并行干活。每个 Teammate 有自己独立的上下文窗口互相之间还能通信最后把结果汇总回 Lead。它适合谁适合已经在用 Claude Code CLI 写代码、并且手头任务能拆成几块互不干扰的开发者比如一边查安全隐患、一边做性能分析、一边补测试覆盖率。但这里有个现实问题默认情况下 Agent Teams 跑在 In-process 模式所有队友都挤在主终端里你只能靠按键切换看不到谁在干什么。想真正“让一个团队为你工作”就得把每个队友拆到独立面板里这时候 tmux 和 iTerm2 就派上用场了。我试过在 macOS 上把 tmux 分屏和 Agent Teams 接起来整个过程不算复杂但有几个坑点比如鼠标点击切不了面板、环境变量没生效导致团队根本没创建。这篇就按可复制的步骤把 tmux 会话布局、iTerm2 分屏快捷键、启动命令和验证方法一次讲清楚你照着做就能在本地复现一个多 Agent 协作的编码场景。需要先说明一点Agent Teams 目前是研究预览阶段的功能默认禁用而且它比单会话消耗的 token 多得多。所以别拿它跑顺序任务或者同一个文件的反复编辑那种场景单会话更划算。它真正发光的地方是“多个独立方向并行推进”比如跨层协调——前端、后端、测试各由一个队友负责。2. 前置准备TaoToken 接入 Claude Code CLI 与 tmux 安装在搭 Agent Teams 之前得先保证 Claude Code CLI 能正常跑起来。我这边是通过 TaoToken 来接入的它的 API 地址是 https://taotoken.net/api 配合 Claude Code 的 Anthropic 兼容接口使用。如果你还没配好先做这一步否则后面团队创建会直接失败。先拿 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来。注意这个 Key 只在创建时完整显示一次丢了就得重建。然后配置 Claude Code 的接入信息。Claude Code 读取的是环境变量或者 settings.json。我习惯用 settings.json路径在~/.claude/settings.json。写入下面这段{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-opus-4-6, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 } }这里三件套要写全Base URL 是https://taotoken.net/apiKey 是你刚创建的Model ID 按你实际可用的填比如claude-opus-4-6。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS这个环境变量就是开启 Agent Teams 的开关默认是关的不设它团队功能根本不会出现。如果你不想改 settings.json也可以临时在终端里 exportexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的TaoToken密钥 export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS1 claude两种方式选一种就行settings.json 的好处是持久化重启终端不用重设。接下来装 tmux。macOS 上用 Homebrew 最省事brew install tmux装完验证一下版本tmux -V能打印出类似tmux 3.4就说明成功了。如果你机器上没有 Homebrew先去 brew.sh 装一个这里不展开。tmux 装好后还要改一下配置否则分屏面板鼠标点不动。编辑~/.tmux.confnano ~/.tmux.conf写入两行set -g mouse on set -g base-index 1mouse on让你能用鼠标点击切换面板base-index 1让窗口编号从 1 开始符合直觉。保存退出后执行tmux source-file ~/.tmux.conf这样配置立即生效不用重启。到这里前置就齐了TaoToken 接入通了tmux 装好且鼠标可用Agent Teams 开关打开。3. 可复制配置tmux 会话布局与 iTerm2 分屏设置Agent Teams 的 Split panes 模式有个特点分屏是 Claude Code 自己创建的不需要你手动tmux split-window。你要做的是给它一个 tmux 环境然后告诉它用 tmux 模式。所以配置的重点是“让 Claude Code 知道该用 tmux”以及“让 tmux 的面板可交互”。先强制指定分屏模式。有两种写法命令行参数claude --teammate-mode tmux或者在 settings.json 里加一行{ teammateMode: tmux, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-opus-4-6, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 } }teammateMode有三个可选值auto、in-process、tmux。auto是默认在 tmux 会话内就用分屏不在就用 in-process。我建议直接写死tmux避免它判断失误又退回单终端。如果你更想用 iTerm2 而不是 tmuxClaude Code 也支持。iTerm2 的分屏快捷键是CmdD垂直分屏、CmdShiftD水平分屏切换面板用CmdOption方向键。但要注意iTerm2 模式下 Claude Code 是通过 iTerm2 的 AppleScript 接口来创建面板的需要在 iTerm2 的 Preferences → General → Magic 里勾选 “Enable Python API”否则分屏可能不触发。相比之下 tmux 更稳定跨终端也通用所以我这篇以 tmux 为主iTerm2 作为备选。tmux 的会话布局其实不用你操心Claude Code 创建团队时会自动按队友数量切分。但你可以预设一个舒服的窗口大小。比如启动前先把终端窗口拉大或者用 tmux 的resize-pane手动调。我一般会在~/.tmux.conf里再加一条让新面板继承当前路径set-option -g default-command cd #{pane_current_path}; $SHELL这样每个队友面板的工作目录和主会话一致不会出现“队友在根目录找不到项目”的尴尬。还有一个细节tmux 里滚屏默认要按CtrlB再按[进入 copy mode。如果你想让鼠标滚轮直接滚set -g mouse on已经覆盖了这一点滚轮会直接进入 copy mode按q退出。配置写完后完整的 settings.json 长这样你可以直接复制{ teammateMode: tmux, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-opus-4-6, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 } }路径是~/.claude/settings.json别放错地方。放好后重启 Claude Code配置才会加载。4. 启动与验证创建 Agent Teams 并确认分屏生效配置就绪后进入 tmux 再启动 Claude Code。先开一个 tmux 会话tmux你会看到底部出现一条绿色状态栏说明已经在 tmux 里了。然后启动claude进入 Claude Code CLI 后用自然语言描述你要的团队。比如我想审查一个项目就输入创建一个 agent team 来审查项目代码包含三个审查者 - 一个专注于安全隐患 - 一个专注于性能分析 - 一个专注于验证测试覆盖率 各自审查完成后汇总输出审查报告回车后Claude Code 会开始创建团队。如果一切正常你会看到终端被自动切成多个面板每个面板对应一个队友Lead 在其中一个面板里协调。这时候用鼠标点击任意面板就能直接和那个队友交互输入指令。验证团队是否真的创建成功有两个办法。第一个是看界面输入框底部会列出所有 Agent包括 Team Lead用左右方向键可以切换按 Enter 进入某个 Agent 单独发指令。第二个是看本地文件。团队和任务会落盘到~/.claude/teams/{team-name}/config.json ~/.claude/tasks/{team-name}/config.json里有 members 数组记录每个队友的名称、agent ID 和类型。tasks目录里是共享任务列表和角色提示词。你可以开另一个终端cat一下确认cat ~/.claude/teams/code-review/config.json能看到三个 reviewer 的成员信息就说明团队真的建起来了。再验证一下分屏模式是不是 tmux。如果面板是 tmux 切的你在面板里按CtrlB再按w会弹出窗口列表如果是 in-process所有输出都在一个面板里滚动不会有多个 pane。这个区别很明显。等所有队友任务执行完结果会同步回 Lead 汇总然后 Claude Code 自动解散团队并清理任务配置和通信队列。你不需要手动tmux kill-session它自己会收尾。5. 常见报错排查401、local proxy failed 与分屏点击失效这一节是我踩过的坑按真实报错对照着查。401 Unauthorized。这个最常见基本是 Key 或 Base URL 的问题。先确认ANTHROPIC_BASE_URL是https://taotoken.net/api注意结尾没有多余的斜杠。再确认ANTHROPIC_AUTH_TOKEN是完整的sk-开头字符串没有换行或空格。如果你用的是 settings.json检查 JSON 格式有没有多逗号可以用python -m json.tool ~/.claude/settings.json验证一下。改完记得重启 Claude Code环境变量不会热加载。local proxy failed / connection refused。这个通常是网络层没通或者 Base URL 写成了别的地址。先curl https://taotoken.net/api看能不能通如果 curl 都失败那就是网络问题不是配置问题。如果 curl 通但 Claude Code 报 proxy failed检查是不是系统里设了别的代理环境变量比如HTTP_PROXY把它 unset 掉再试。reading choices 相关报错。这个一般出现在模型返回格式异常时多半是 Model ID 填错了。确认ANTHROPIC_MODEL是你账号下真实可用的模型名别自己编。填错模型名有时不会直接报 404而是返回一个空 choices然后解析时报 reading choices 失败。OAuth 相关报错。如果你之前用官方账号登录过 Claude Code本地可能残留 OAuth 凭证和 TaoToken 的 token 冲突。解决办法是清掉旧的凭证缓存通常在~/.claude/下把credentials.json之类删掉只保留 settings.json 里的 token 配置。分屏面板鼠标点不动。回到~/.tmux.conf确认set -g mouse on写了并且执行过tmux source-file ~/.tmux.conf。如果还不行检查 tmux 版本低于 2.1 的版本 mouse 支持不完整brew upgrade tmux升一下。另外如果你在 iTerm2 里套 tmuxiTerm2 自己的鼠标报告可能和 tmux 抢事件可以在 iTerm2 的 Preferences → Profiles → Terminal 里把 “Enable mouse reporting” 关掉试试。团队创建了但没有分屏。检查teammateMode是不是tmux以及启动 Claude Code 时是不是在 tmux 会话内。如果你在 tmux 外启动即使设了 tmux 模式它也可能退回 in-process。先tmux再claude顺序别反。队友之间不通信 / 任务卡住。看一下~/.claude/tasks/{team-name}/下的任务依赖关系。Agent Teams 会自动管理依赖一个任务完成后被阻塞的任务会解锁。如果卡住可能是某个队友的上下文爆了或者任务描述太模糊导致它一直在等。这时候用方向键切到那个队友按 Enter 进去补一句明确指令。6. 长期编码与 Agent 工作流把团队模式用对地方Agent Teams 不是万能药它的协调开销和 token 消耗都比单会话高。我两天跑了两个 Demo20 刀就没了所以用之前先想清楚场景。它最适合的是“多个独立方向并行”比如研究与评审——几个队友同时调查问题的不同方面然后互相质疑结论。新模块开发——前端、后端、测试各占一个队友互不干扰。竞争假设调试——并行测试不同理论谁先找到答案谁汇报。跨层协调——涉及多层变更时每层一个负责人。反过来顺序任务、同一文件的反复编辑、强依赖的工作流用单会话或者 Subagents 更高效。Subagents 和 Agent Teams 的区别在于Subagents 也是并行但队友之间不直接通信Agent Teams 的队友能互相发消息、共享任务列表。所以判断标准很简单——你的“工作人员”需不需要互相沟通需要就上 Agent Teams不需要Subagents 够了。如果你打算长期用这套工作流建议把 Coding Plan 用起来配合 tmux 常驻会话每天开工直接tmux attach回到昨天的团队环境。接入文档在 https://taotoken.net/doc 里面有完整的 Base URL、Key 和 Model ID 说明。想先验证模型对话是否正常可以去 https://taotoken.net/chat 试一句。Key 管理统一在 https://taotoken.net/api-keys 团队协作时给每个项目单独建 Key方便追踪消耗。最后一个小技巧tmux 会话可以命名启动时用tmux new -s agent-team下次tmux attach -t agent-team直接回到现场。配合set -g mouse on鼠标点面板、滚轮看日志整个多 Agent 协作的体验就顺了。