拆解 Claude Code 的多 Agent 编排：从 Coordinator、Task、Mailbox 到 Remote Worker

Explorer · 2026 年3 月 31 日 16:41

拆解 Claude Code 的多 Agent 编排：不是“多开几个 Agent”，而是把 Coordinator、Task、Mailbox、权限桥接和 Backend 组成一个操作系统

很多人研究多 Agent 系统时，容易把注意力放在“Prompt 怎么写”“一个 agent 怎么调用另一个 agent”这两个表层问题上。

但读完 Claude Code 这份源码之后，我最大的感受反而是：

真正把多 Agent 做成产品，不是多加几个 agent prompt，而是把 agent 之间的“组织结构、运行时、权限、通信、恢复、可见性”全部做成基础设施。

Claude Code 的多 Agent 设计，已经明显不是一个“让模型自己想办法协作”的玩具系统，而是一套比较完整的编排框架。它把多 Agent 问题拆成了五层：

Coordinator 层：负责拆任务、调度 worker、汇总结果
Agent Tool 层：把“创建 agent / 继续 agent / 停止 agent”抽象成标准工具
Task Runtime 层：把每个 agent 变成一个可跟踪、可恢复、可终止的任务
Swarm Collaboration 层：通过 team、mailbox、permission bridge 让多个 agent 真正协作
Backend 层：根据环境选择同进程、tmux / iTerm2、remote 等不同运行后端

这篇文章，我想重点讲清楚一件事：

Claude Code 是如何把“多 Agent”从提示词技巧，落成一个可运维、可恢复、可交互、可受控的工程系统。

一、Claude Code 的多 Agent，不是“Agent 调 Agent”，而是“Coordinator 调 Runtime”

从源码看，Claude Code 的多 Agent 入口不是某个神秘的 planner 模块，而是一个普通但很关键的工具：

src/tools/AgentTool/AgentTool.tsx

这个设计非常重要。它意味着：

agent 不是框架里的特殊对象，而是一个工具调用的结果
上层模型并不直接拥有 agent 生命周期，而是通过 tool API 启动子 agent
所有 agent 的启动、权限、返回值、状态更新，都被纳入统一的 tool runtime

这背后的思想很工程化：

多 Agent 不是让模型自由繁殖，而是让模型通过受控的 runtime 去申请计算单元。

这点和很多论文式多 Agent 框架不同。很多框架会把 agent 当成一个抽象节点，然后让 agent 之间互相发消息；而 Claude Code 更像在做一套“agent 操作系统”：

AgentTool 负责创建 worker
SendMessageTool 负责继续已有 worker
TaskStopTool 负责杀死 worker
TeamCreateTool 负责建立 swarm 团队上下文

也就是说，这里的多 Agent，本质上是：

Coordinator + 一组可被 runtime 管理的 worker task

而不是一群 prompt 自由对话。

二、Claude Code 的第一个关键设计：把“worker”做成 Task，而不是一次性调用

如果你只看论文，通常会觉得一个子 agent 就是“发一次 prompt，拿一次结果”。

但 Claude Code 没有这么做。

它把 agent 明确建模成了 Task：

src/Task.ts

这里的 TaskType 已经暴露出 Claude Code 对多 Agent 的完整心智模型：

local_agent
remote_agent
in_process_teammate
local_workflow
monitor_mcp
dream

这说明在 Claude Code 看来，agent 不是“消息”，而是“任务实体”。

这带来几个非常大的好处：

1. agent 有稳定身份

Task 有自己的 id、status、startTime、endTime、outputFile。

这意味着子 agent 不再只是对话历史里的一段内容，而是一个可被 UI、状态机、恢复逻辑识别的对象。

2. agent 可以异步运行

一旦 agent 被注册为 task，它就可以：

在后台继续跑
被前台切换出去
被恢复
被查看进度
被停止

这才是真正多 Agent 的前提。

很多所谓“多 Agent”系统，其实只是串行的 prompt tree。Claude Code 明显走得更远：它在做异步任务化的多 agent runtime。

3. agent 可以有不同后端

Task 把“逻辑身份”与“运行后端”解耦了。

同样一个 agent，在运行时可以是：

本地 background agent
同进程 teammate
远程 remote session

这使得 Claude Code 的多 Agent 编排不是绑死在某一种执行环境上的。

三、第二个关键设计：Coordinator 不是“更强的 agent”，而是一个专门的调度角色

很多系统说自己有 coordinator，但实际上只是给主 agent 多写几句“你负责规划”的 prompt。

Claude Code 不是。

它真的把 coordinator 模式单独做成了一个能力层：

src/coordinator/coordinatorMode.ts

这个文件最值得注意的地方，不是代码本身，而是它暴露出的产品哲学。

Coordinator prompt 里规定得非常明确：

你是 coordinator，不是直接执行者
你的职责是拆任务、发 worker、汇总结果、与用户沟通
worker 的结果以 <task-notification> 的形式回流
worker 是异步的，应该并行启动
research、implementation、verification 是不同阶段
verification 必须独立，不允许 rubber-stamp

也就是说，Claude Code 已经把多 Agent 从“谁来回答问题”变成了“谁负责哪一个生产阶段”：

Research：并行 worker 做信息搜集
Synthesis：coordinator 汇总并形成明确实现规格
Implementation：worker 落地改动
Verification：另一个 worker 做破坏式验证

这个分层很值得研究，因为它触及了一个核心问题：

多 Agent 的价值，不在于同时存在多个模型实例，而在于把“任务阶段”和“责任边界”分开。

Claude Code 的 coordinator 真正做的是：

控制并发度
控制写入冲突
控制反馈路径
控制何时汇总、何时继续已有 worker、何时停掉 worker

这已经接近一个小型“工程经理 + 调度器”的角色，而不是普通聊天机器人。

四、第三个关键设计：Agent Tool 只是入口，真正的执行是 runAgent + Task Runtime

如果继续往下追，会看到 AgentTool 并不直接等价于“agent 执行器”。

真正干活的是：

src/tools/AgentTool/runAgent.ts

这里面有几个很有启发的点。

1. 子 agent 不是从零开始，而是带着上下文生成

runAgent 会组装：

agent definition
prompt messages
tool pool
MCP clients
forked context
session transcript
system prompt

这说明 Claude Code 并不是简单给 worker 发一句“你去干这个”，而是会给 worker 配置完整运行环境。

换句话说，Claude Code 里的 worker 更像“一个带权限和工具箱的执行单元”，而不是一条子 prompt。

2. agent 可以有独立 MCP servers

runAgent.ts 里有 initializeAgentMcpServers()，说明 agent definition 可以声明额外的 MCP server。

这很关键，因为它意味着 Claude Code 的 agent specialization 不只是 prompt specialization，还包括：

工具可见性差异
外部能力差异
权限边界差异

这比单纯用不同 system prompt 的多 Agent 强很多。

3. agent 运行结果会被持久化

在这个执行链中，Claude Code 会记录 transcript、metadata、sidechain transcript。

这意味着它把 agent 当作可恢复、可回看、可追踪的执行过程。

如果一个多 Agent 系统没有持久化和恢复，你很难把它真正用在工程场景里，因为用户一旦断开、切换、误操作，整个协作就会断掉。

五、第四个关键设计：Claude Code 不是只有一种 worker，而是三种 worker 运行模型

这是 Claude Code 最值得研究的地方之一。

它并没有把“agent”绑定到一种执行方式，而是同时支持三类 worker：

Local background agent
In-process teammate
Remote agent

1. Local background agent

相关文件：

src/tasks/LocalAgentTask/LocalAgentTask.tsx

这类 agent 是标准后台任务。

它的特点是：

有进度跟踪
有 task notification 回流
有输出文件
可以在 UI 中被查看、恢复、终止
支持被 SendMessageTool 继续追加消息

这类 agent 更像“后台作业”。

适合：

长时间研究
异步代码修改
独立验证任务

2. In-process teammate

相关文件：

src/utils/swarm/spawnInProcess.ts
src/tasks/InProcessTeammateTask/InProcessTeammateTask.tsx
src/utils/swarm/inProcessRunner.ts

这类 worker 非常有意思。

它不是开一个新进程，也不是远程 session，而是在同一个 Node.js 进程里运行多个 teammate。

它能成立的核心，是 Claude Code 用了：

AsyncLocalStorage 风格的上下文隔离
TeammateContext
独立 AbortController

这让多个 teammate 虽然共处一个进程，但仍然拥有各自的：

identity
teamName
color
permission mode
message queue
transcript

这是一种很强的设计，因为它把“多 agent”从“多进程编排”扩展到了“同进程多执行上下文”。

这个思路很像：

一个进程里的 lightweight worker fibers，而不是一堆外部进程。

在工程上，这能带来更低的启动成本、更快的上下文共享，以及更容易的 UI 集成。

3. Remote agent

相关文件：

src/tasks/RemoteAgentTask/RemoteAgentTask.tsx
src/remote/RemoteSessionManager.ts

这类 worker 被放到远程 CCR 环境里执行。

这意味着 Claude Code 的多 Agent 并不是本地 CLI 自娱自乐，而是支持：

远程异步执行
session polling
session archival
remote log 和 remote progress 回收

这就把它从“终端工具”推到了“分布式 agent runtime”的方向。

我的判断是：

Claude Code 的多 Agent 设计，真正高级的地方，不是会开多少个 worker，而是它允许不同 worker 运行在不同隔离等级上。

从轻到重，大概是：

in-process teammate
local background agent
pane / tmux teammate
remote agent

这本质上是在做一个多层执行平面。

六、第五个关键设计：多 Agent 协作不是靠“共享记忆”，而是靠 Team + Mailbox + 状态文件

很多人研究多 Agent，第一反应是“它们怎么共享 memory”。

Claude Code 给出的答案非常务实：

先别急着做复杂共享记忆，先把组织结构和消息通道做稳定。

相关文件：

src/tools/TeamCreateTool/TeamCreateTool.ts
src/utils/swarm/teamHelpers.ts
src/utils/teammate.ts
src/tools/SendMessageTool/SendMessageTool.ts
src/utils/teammateMailbox.ts

Claude Code 的 swarm 协作基础，是一个 team 文件系统：

team 有 config.json
里面记录 lead、members、color、cwd、backendType、mode 等信息
每个 teammate 有 inbox 文件
SendMessageTool 会把消息写入对方 inbox

也就是说，Claude Code 没有把多 agent 协作建立在某种玄学“共享上下文池”上，而是用了非常工程化的对象：

team file：团队元数据
mailbox：异步消息队列
task state：运行时状态

这套设计有几个很大的优点。

1. 易恢复

只要 team file、task metadata、mailbox 还在，系统就能恢复协作状态。

2. 易调试

如果一个 teammate 没收到消息，你可以直接看 inbox 文件。

3. 易解释

相比“每个 agent 共享一个 vector memory，然后靠 embedding 检索”，邮箱模型更直观：

谁发给谁
何时发
是否已读
是否需要 leader 处理

对于真正的多 Agent 产品，这种可观察性比很多 fancy memory 方案更重要。

七、第六个关键设计：Claude Code 把“权限”也做成了多 Agent 一等公民

这是我最喜欢的部分之一。

多 Agent 系统如果一旦进入工程场景，就一定会遇到一个问题：

一个 worker 要执行 Bash / Edit / Write 时，谁来批准？

Claude Code 没有把这个问题藏起来，而是正面做成了基础设施：

src/utils/swarm/permissionSync.ts
src/utils/swarm/leaderPermissionBridge.ts
src/utils/swarm/inProcessRunner.ts

两种权限路径

路径 A：Leader UI Bridge

对于 in-process teammate，如果 leader 的 ToolUseConfirm UI 可用，那么 worker 的权限申请会直接桥接到 leader 的标准权限确认界面。

这意味着：

worker 不是自己弹权限框
用户看到的是统一的 leader UI
worker 仍然保留自己的 badge / identity

这是一种非常聪明的设计，因为它保证了：

多 worker 仍然有统一的人工控制入口
不会出现一堆独立终端同时向用户要权限

路径 B：Mailbox-based Permission Sync

如果 bridge 不可用，系统就退化到 mailbox 方案：

worker 生成 permission request
写到 leader mailbox 或 permission dir
leader 轮询并处理
决策再写回 worker mailbox
worker 继续执行

这里的启发非常强：

Claude Code 不是把“权限”看成 UI 层问题，而是看成分布式协调问题。

这就对了。因为一旦进入多 Agent、异步、后台、远程，权限不再是一个按钮，而是一个协议。

八、第七个关键设计：Backend Registry 让多 Agent 脱离具体终端环境

另一个被很多人忽略、但非常有产品价值的点，是 backend registry：

src/utils/swarm/backends/registry.ts

这个文件揭示了 Claude Code 的真实目标：

它不是想做“tmux 版多 Agent”，而是想做“后端可切换的多 Agent”。

当前 registry 会按环境检测并选择：

当前是否在 tmux 内
是否在 iTerm2
是否可用 it2 CLI
是否可用 tmux
是否需要 fallback 到 in-process

这个机制的意义在于：

协作模型和执行后端被分离了。

也就是说，用户想要的是“多 agent 协作”，而不是“必须开 tmux pane”。

如果没有这层抽象，整个产品会被单一终端环境锁死。

而 Claude Code 的做法更像：

上层看到的是 teammate / worker
中层看到的是 task / mailbox / permission
底层才决定到底跑在 tmux、iTerm、同进程还是 remote

这是很典型的系统分层成熟信号。

九、第八个关键设计：Claude Code 把“继续已有 worker”当成一等能力，而不是每次重新 spawn

很多多 Agent 系统有一个隐形浪费：

有一个 worker 已经加载了上下文
但上层不会继续用它，而是重新开一个新 worker

Claude Code 明显注意到了这个问题。

1. 减少重复上下文加载

已经读过大量文件、跑过命令、形成工作记忆的 worker，继续使用成本更低。

2. 保持责任连续性

同一个 worker 先研究、后修复、再补检查，责任链更清晰。

这说明 Claude Code 并不是把 worker 当成一次性 disposable prompt，而是更像“带状态的执行者”。

这是做多 Agent 时一个很重要的分水岭。

十、Claude Code 真正值得学习的地方：它把“多 Agent”拆成了四个彼此独立的设计问题

读完整体源码之后，我觉得 Claude Code 对多 Agent 的最大贡献，不是某一条 prompt，而是它把问题拆得很对。

问题 1：谁负责拆任务？

答案：Coordinator mode。

问题 2：worker 如何被创建和追踪？

答案：AgentTool + Task Runtime。

问题 3：worker 之间如何协作？

答案：Team + Mailbox + SendMessage + PermissionSync。

问题 4：worker 跑在哪？

答案：Backend Registry + Local / In-process / Remote 多后端。

这四个问题彼此解耦，所以 Claude Code 可以同时演化：

prompt 体系
agent specialization
UI 展示
runtime backend
remote session

而不会所有东西搅成一锅。

这其实就是系统设计成熟度。

十一、对多 Agent 研究者最有启发的几点

我觉得 Claude Code 至少给了我们五个很值得吸收的经验。

1. 多 Agent 的核心不是“更多 agent”，而是“更好的运行时”

如果没有 task、恢复、权限、消息、backend 抽象，多 agent 很快会退化成一堆 prompt 调用。

2. 不要把所有协调都压给 LLM

Claude Code 的很多关键协作能力，不是模型自己涌现出来的，而是系统提供的：

Task
Notification
Mailbox
Team file
Permission bridge

这说明：

好的多 Agent 系统，应该尽可能把“确定性协调”从 LLM 脑子里拿出来。

3. agent specialization 不只是 prompt specialization

Claude Code 的 specialized agent 还体现在：

allowed / disallowed tools
model inheritance
background capability
MCP capability
permission mode

这比“给 agent 换一段角色描述”高了一个层级。

4. 权限系统必须内生于多 Agent 设计

单 agent 时，权限是用户与模型之间的问题。

多 agent 时，权限是：

leader 与 worker 的关系问题
同步与异步的问题
人工确认如何映射到分布式执行的问题

Claude Code 在这点上做得很扎实。

5. 协作协议要比共享记忆更重要

很多研究都在追求 agent 共享 memory。

但从真实工程角度，Claude Code 告诉我们：

先把这些协议做好更重要：

谁是谁
谁负责什么
谁可以给谁发消息
谁能批准什么
结果如何回流
中断和恢复如何做

如果这些没做好，memory 再强也会变成混乱。

十二、Claude Code 多 Agent 设计的局限与思考

当然，这套设计也不是没有代价。

我看到的几个潜在限制是：

1. 编排仍然强依赖 prompt discipline

Coordinator prompt 写得再好，本质上还是靠模型遵守流程。

这意味着它并不是一个完全显式的 DAG 调度器，更多还是“runtime 增强型 agent orchestration”。

2. Team + Mailbox 仍然偏文件系统原语

这种方案的优点是简单、可调试、易恢复；但如果未来 worker 数量继续增加，可能会面临：

mailbox 扫描成本
文件锁竞争
状态一致性管理

3. 写冲突治理更多依赖 coordinator 常识

Claude Code 已经强调“写任务一个文件域一次只给一个 worker”，但这更多是调度层约束，还不是强一致事务控制。

不过我认为这不是缺点，而是一种现实主义取舍：

在今天的 agent 工程阶段，先通过任务分片和文件 ownership 控制冲突，通常比上来就做复杂事务调度更划算。

结语：Claude Code 的多 Agent，本质上是在做“Agent OS”

如果只看表面，你会说 Claude Code 做了：

spawn subagent
team collaboration
send message
remote worker

但如果再深入一点，我觉得它真正做的是：

把多 Agent 从“模型之间的提示词互调”，提升为“受控任务、可恢复状态、可桥接权限、可切换后端的操作系统式运行时”。

这件事非常重要。

因为它说明下一代多 Agent 系统的竞争，不会主要发生在“planner prompt 谁更华丽”，而会发生在这些基础设施层面：

调度
任务化
可观察性
可恢复性
权限协议
Backend abstraction

如果你也在研究多 Agent，我觉得 Claude Code 这份源码里最值得抄的，不是某个 prompt，而是这条路线：

把 agent 当作 runtime resource，而不是聊天角色。

这会极大改变你设计系统的方式。

参考源码路径

src/tools/AgentTool/AgentTool.tsx
src/tools/AgentTool/runAgent.ts
src/coordinator/coordinatorMode.ts
src/Task.ts
src/tasks/LocalAgentTask/LocalAgentTask.tsx
src/tasks/InProcessTeammateTask/InProcessTeammateTask.tsx
src/tasks/RemoteAgentTask/RemoteAgentTask.tsx
src/tools/TeamCreateTool/TeamCreateTool.ts
src/tools/SendMessageTool/SendMessageTool.ts
src/utils/teammateMailbox.ts
src/utils/swarm/permissionSync.ts
src/utils/swarm/inProcessRunner.ts
src/utils/swarm/backends/registry.ts

如果大家愿意，我下一篇可以继续拆：

Claude Code 的权限系统是怎么和多 Agent 融合的
Claude Code 的 verification agent 为什么值得单独研究
Claude Code 的 remote agent / cloud session 是怎么做异步恢复的

深求社区（DeepSeek.club）出品，国内领先的AI大模型及应用开源社区！