1. 为什么单窗口的 Claude Code 会卡住你如果你已经用 Claude Code 写过一段时间代码大概率遇到过这种场景让它重构一个模块它先读文件、再改代码、然后跑测试中间任何一步卡住整个会话就停在那里等你回话。你没法同时让它去查另一个 bug也没法让两个思路并行验证。这就是单实例串行模式的天然瓶颈——它像一个极其勤奋但只能一件件干活的初级程序员。Claude Code 的 AgentTeams 特性正是冲着这个瓶颈来的。它允许你在同一个项目里拉起多个 Claude Code 实例每个实例有独立的上下文窗口彼此之间可以发消息、共享任务列表、互相挑战判断。你可以把它理解成从「一个人干活」升级成「一个小组干活」Team Lead 负责拆任务和协调Teammates 各自认领子任务并行推进。这篇文章聚焦三件事AgentTeams 的调度原理到底怎么运转、tmux 会话隔离怎么让多个 Subagent 同屏可见、Hooks 事件钩子怎么在队友偷懒或任务糊弄时把它拽回来。我会给出可以直接复制的settings.json和 tmux 配置骨架并演示一次多 Subagent 并行任务的完整验证动作。适合已经在用 Claude Code、想从单窗口串行升级到多智能体协作的开发者。需要说明的是AgentTeams 目前是实验特性需要 Claude Code 2.1.33 以上版本并且 Token 消耗速度是单体模式的数倍建议先用小任务试水。2. 前置准备版本、实验开关与 TaoToken 接入在动手搭骨架之前先把运行环境铺好。这一步不做后面 tmux 分屏和 Hooks 都会报错。2.1 版本检查与实验标识先确认 Claude Code 版本低于 2.1.33 的话 AgentTeams 相关字段会被忽略claude update claude --version然后在~/.claude/settings.json里打开实验开关。这个文件如果不存在就新建注意 JSON 不能有注释{ env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1 } }2.2 用 TaoToken 统一模型接入多 Subagent 并行意味着请求量成倍增长如果每个实例各自配置模型端点管理起来会很乱。我习惯用 TaoToken 做统一接入层它的 API 地址是https://taotoken.net/api兼容主流模型调用格式把 Key 配一次所有 Claude Code 实例共享同一套凭证。先到控制台创建 API Key# 打开 API Keys 管理页创建密钥 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys拿到 Key 之后写进环境变量或 settings.json 的 env 段。我倾向放在 shell 配置里避免明文进版本库export TAOTOKEN_API_KEYsk-你的密钥 export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEY这样 Team Lead 和所有 Teammate 实例都会走同一个端点。如果你对某个队友想换模型可以在团队配置里单独指定 model 字段后面会讲。2.3 安装 tmux分屏模式依赖 tmuxmacOS 用 brewLinux 用包管理器brew install tmux tmux -V版本号能打印出来就说明装好了。iTerm2 用户额外在偏好设置里开启 tmux 集成能获得更好的窗格交互。3. 可复制配置settings.json 与 tmux 骨架这一节是全文的核心操作区配置直接抄改路径即可。3.1 settings.json 完整骨架把下面这段合并进~/.claude/settings.json。teammateMode设为tmux表示强制走分屏模式hooks段是质量闸门后面单独拆解{ env: { CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: 1, ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥 }, teammateMode: tmux, hooks: { TeammateIdle: [ { matcher: *, hooks: [ { type: command, command: bash ~/.claude/hooks/check-idle.sh } ] } ], TaskCompleted: [ { matcher: *, hooks: [ { type: command, command: bash ~/.claude/hooks/check-task.sh } ] } ] } }注意teammateMode有两个可选值in-process是进程内模式所有队友挤在一个终端里用 Shift上/下切换tmux是分屏模式每个 Member 独占一个窗格。想同时看到多个队友的输出必须选tmux。3.2 tmux 会话启动脚本不要直接在裸终端里跑claude那样断开 SSH 会话就没了。用命名会话包起来# 创建名为 claude 的会话并直接运行 claude tmux new -s claude claude # 分离会话后台继续跑 # 快捷键CtrlB 然后按 D # 重新连接 tmux attach -t claude # 查看所有会话 tmux ls # 结束会话 tmux kill-session -t claude我建议把启动命令写成一个脚本start-team.sh省得每次敲#!/usr/bin/env bash set -e SESSIONclaude-team if tmux has-session -t $SESSION 2/dev/null; then echo 会话已存在直接连接 tmux attach -t $SESSION else tmux new -s $SESSION claude fi给执行权限chmod x start-team.sh以后一条命令进团队环境。3.3 团队与任务目录结构AgentTeams 的状态都落在文件系统里理解目录结构才能排查问题路径作用~/.claude/teams/{team-name}/config.json记录每个 teammate 的 model 和角色 prompt~/.claude/teams/{team-name}/inboxes/Team Lead 分配给各队员的任务含 taskId 和 subject~/.claude/tasks/{team-name}/共享任务列表所有队员可见任务有三种状态pending、in progress、completed。任务可以设依赖前置没完成的任务无法被认领。多个队友同时抢一个任务时靠文件锁防止竞争条件——这也是为什么任务拆得越细锁冲突越少并行效率越高。3.4 Hooks 质量闸门脚本Hooks 是 AgentTeams 里最容易被忽略但最有价值的部分。两个关键事件TeammateIdle在队友准备进入空闲状态时触发。如果返回exit 2并输出反馈队友会继续工作而不是闲着。TaskCompleted在任务即将完成时触发返回exit 2可以阻止任务完成把修改意见退回给队友。先建目录mkdir -p ~/.claude/hookscheck-idle.sh示例检查队友是否真的无事可做#!/usr/bin/env bash # 读取 hook 传入的 JSONstdin INPUT$(cat) TEAMMATE$(echo $INPUT | jq -r .teammate_name // unknown) # 简单策略如果共享任务列表里还有 pending 任务就不许空闲 PENDING$(ls ~/.claude/tasks/*/ 2/dev/null | wc -l) if [ $PENDING -gt 0 ]; then echo 还有 $PENDING 个待处理任务请继续认领 exit 2 fi exit 0check-task.sh示例任务完成前做最低限度校验#!/usr/bin/env bash INPUT$(cat) TASK_ID$(echo $INPUT | jq -r .task_id // unknown) # 检查是否有未提交的改动示意 if ! git diff --quiet 2/dev/null; then echo 任务 $TASK_ID 存在未提交改动请先确认 exit 2 fi exit 0这两个脚本是骨架实际策略按你的项目改。核心逻辑就是返回 0 放行返回 2 拦截并给反馈。4. 验证请求一次多 Subagent 并行任务配置铺好后跑一次真实任务验证协作流程。我选一个跨层功能开发场景因为它天然适合拆分。4.1 用自然语言拉起团队在 tmux 会话里的 Claude Code 主窗口输入我需要为这个项目添加一个通知系统。请组建一个团队并行开发 - 队友 1后端 API创建、列表、标记已读 - 队友 2数据库表结构和迁移脚本 - 队友 3前端 React 组件通知铃铛、下拉菜单、列表 - 队友 4端到端集成测试 每个队友只修改自己负责的文件通过共享任务列表协调。 需要依赖他人结果时明确标记任务依赖。关键点是明确告诉 Lead「并行处理」和「文件边界」。如果你只说「加个通知系统」Lead 可能自己闷头写或者拆出模糊任务导致队友互相踩文件。4.2 观察分屏与任务流转如果 tmux 分屏生效你会看到主窗格是 Team Lead其余窗格陆续被 Teammate 占据。每个队友的输出实时可见有的在读文件有的在写迁移脚本有的在跑测试。此时可以另开一个终端观察任务状态# 查看共享任务列表 ls -la ~/.claude/tasks/*/ # 查看某个队员的收件箱 cat ~/.claude/teams/*/inboxes/*.json | jq .你会看到任务从pending变成in progress完成后变completed被依赖的任务在前置完成后自动解锁。这个过程不需要人工干预是 AgentTeams 调度机制在起作用。4.3 委托模式与计划批准如果发现 Team Lead 自己开始写代码而不是调度按ShiftTab切到委托模式delegate mode on。这个模式下 Lead 只负责拉起队友、发消息、管任务列表不再改代码跑命令。对于高风险任务可以让队友先进入 plan mode 提交规划。队友此时只能读文件、调查信息不能改代码。Lead 可以批准、或者拒绝并反馈队友根据反馈改计划重新提交。这个机制在重构类任务里特别有用能避免队友一上来就大改。4.4 指定队友模型与权限预批不同队友可以配不同模型。比如测试队友用轻量模型架构队友用强模型。直接在自然语言里说「队友 3 使用 xxx 模型」配置会固化到config.json的 model 字段。权限方面队友每次要权限都问 Lead 会很烦。提前用/permissions批准常用操作比如项目目录文件读写、常用测试命令。如果你完全信任团队也可以claude --dangerously-skip-permissions但这个开关要谨慎只在隔离环境用。4.5 清理团队任务完成后让 Lead 清理团队资源。注意必须通过 Lead 执行因为 Lead 会先检查是否还有活跃队友有的话清理会失败。所以先关闭所有队友再让 Lead 清理。5. 本篇常见错排查配置和运行过程中下面几个坑我踩过列出来帮你省时间。分屏没生效所有队友挤在一个终端。检查teammateMode是否设为tmux以及 Claude Code 是否真的运行在 tmux 会话里。如果是在裸终端直接跑claude它会回退到 in-process 模式。用tmux new -s claude claude启动。队友一直空闲任务不推进。大概率是任务拆得太模糊。Lead 的拆解质量决定成败如果队友经常卡住或很闲手动介入帮 Lead 把任务拆细。检查~/.claude/tasks/里的任务描述如果 subject 只有一句话没有明确文件边界队友不知道从哪下手。Hooks 返回 exit 2 但队友没反应。确认 hook 脚本有执行权限且settings.json里的 matcher 写对了。另外 hook 是通过 stdin 传 JSON 的脚本里要用cat读取别指望环境变量。调试时可以在脚本里加echo $INPUT /tmp/hook.log看实际传入内容。Token 消耗过快。AgentTeams 跑 3~5 个并行实例消耗是单体数倍。简单 Bug 修复用 Subagents 就够别上团队。任务复杂、需要讨论和协作时才用 AgentTeams。另外 broadcast 广播消息成本随团队规模增长谨慎使用。队友之间改同一个文件冲突。这是任务拆解的锅。每个队友应该只修改自己负责的文件跨文件依赖用任务依赖标记而不是让两个人同时改一个文件。共享任务列表的文件锁只能防任务重复认领防不了文件级冲突。清理团队失败。说明还有活跃队友。先关闭所有队友再让 Lead 执行清理。6. 从骨架到生产下一步怎么走把上面的骨架跑通之后你会发现 AgentTeams 真正的门槛不在配置而在任务拆解和 CLAUDE.md 的质量。每个 Member 都是独立实例加载相同的CLAUDE.md、MCP、Skills这份文件是所有 Agent 共享的「员工手册」定义了代码目录架构、规范、架构决策和测试标准。CLAUDE.md 写得越清楚队友跑偏的概率越低。如果你还在单窗口串行阶段建议先用 Subagents 熟悉独立上下文的概念再升级到 AgentTeams。Subagents 像工人完成后向包工头报告AgentTeams 像团队队员之间可以互相讨论、挑战。需要快速明确产出时用前者任务复杂需要协作时用后者。模型接入这块多实例并行时统一走 TaoToken 的 API 端点能省不少管理成本Key 在控制台创建一次即可https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi_keys接入文档里有完整的端点说明和参数对照配置遇到问题可以查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc想先验证模型对话是否通可以直接在网页端试一轮https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat如果你打算长期跑编码 Agent、频繁拉起团队Coding Plan 的额度模型比按次调用更适合这种高频场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan最后给一个实操建议第一次跑团队时先用一个真实但边界清晰的小功能试水比如给现有 API 加一个字段。观察 Lead 怎么拆任务、队友怎么认领、Hooks 有没有拦住偷懒。跑通一次之后再上跨层功能开发和对抗式调试这类复杂场景。骨架搭对了后面就是调任务粒度的活。