夜雨聆风一句话摘要：OpenClaw 通过基于 Session 的消息传递系统实现多 Agent 协作——如果说传统的单 Agent 是独自搬砖的工人，OpenClaw 的多 Agent 就是一个自带对讲机和施工图的包工队。
1. 概述
1.1 什么是 OpenClaw 多 Agent 通信？
凌晨两点，你的 AI Agent 正在帮你分析一份 300 页的技术报告。你满怀期待地等着结果，结果它卡在第 47 页——因为它需要同时搜索互联网、查询内部知识库、还要跑一段代码验证数据。一个 Agent 做三件事，就像一个人同时切菜、炒菜、洗碗——理论上可行，实际上盘子摔了一地。
OpenClaw 的多 Agent 通信机制就是为了解决这个问题而生的。它允许一个 Agent（主 Agent）将任务拆分并派发给多个子 Agent 并行执行，每个子 Agent 在独立的 Session 中运行，完成后自动将结果汇报回来。整个过程是推送式（push-based）的——子 Agent 做完了自己来报告，主 Agent 不需要反复追问"做完了没？"。
你可以把它想象成一个项目经理（主 Agent）和几个工程师（子 Agent）的协作模式：经理把任务分配下去，每个工程师独立干活，干完了在群里发个汇报消息，经理汇总后给客户交付。高效、有序、互不干扰。
💡 人话翻译：一个 Agent 把活分给几个子 Agent 同时干，干完自动汇报，老板不用催。
1.2 解决了什么问题？
在多 Agent 通信出现之前，世界是这样的：
• 单 Agent 串行执行复杂任务，10 分钟能搞定的事要等 30 分钟 • 长任务占满 Agent 的上下文窗口，后面的回答质量直线下降 • Agent 遇到需要不同"技能"的子任务时，只能笨拙地在同一个上下文中切换角色
然后，OpenClaw 的 带着它的 Session 隔离 + 自动汇报机制出现了——
它让主 Agent 可以在 1 秒内派出多个子 Agent 并行工作，每个子 Agent 拥有独立的上下文、独立的工具权限、甚至可以使用不同的 AI 模型。任务完成后，结果自动推送回主 Agent，无需轮询。
1.3 核心优势
| 并行执行 | ||
| Session 隔离 | ||
| 推送式汇报 | ||
| 嵌套编排 |
2. 核心概念
🗺️ 进入正题之前，先装备好这些概念——否则后面的内容会像没有字幕的外语电影。
2.1 Session（会话）
定义：Session 是 OpenClaw 中 Agent 运行的基本单元，每个 Session 有唯一的 Session Key，包含独立的聊天历史、路由状态和工具权限。
直觉：你可以把 Session 想象成一个独立的聊天窗口——每个窗口有自己的对话记录和权限设置。
示例：主 Agent 运行在 agent:main:main Session 中，当它 spawn 一个子 Agent 时，会创建一个新的 Session agent:main:subagent:<uuid>。
2.2 Announce（结果汇报）
定义：Announce 是子 Agent 完成任务后，将执行结果推送回父 Agent 的机制。它是推送式（push-based）的，父 Agent 不需要主动轮询。
直觉：类似于工作完成后自动发送的邮件通知——你不需要每隔 5 分钟刷一次收件箱。
示例：子 Agent 完成数据分析后，Announce 步骤会将分析结果、运行时长、Token 消耗等信息打包成一条消息，注入到父 Agent 的 Session 中。
2.3 Lane（执行队列）
定义：Lane 是 OpenClaw 用于控制并发的队列机制。子 Agent 运行在专用的 subagent Lane 中，默认并发上限为 8。
直觉：Lane 就像高速公路的车道——subagent 车道最多同时跑 8 辆车，防止一个 Agent 把整个系统堵死。
示例：当主 Agent 同时 spawn 了 10 个子 Agent，前 8 个立即开始执行，后 2 个在队列中排队等待。
2.4 术语表
3. 架构设计
🏗️ 本节拆开引擎盖，看看 OpenClaw 多 Agent 通信内部长什么样。
3.0 技术栈一览
3.1 整体架构
OpenClaw 的多 Agent 通信架构遵循中心化路由 + 去中心化执行的设计哲学：所有消息通过 Gateway 路由，但每个 Agent 在自己的 Session 中独立执行。
图 1：OpenClaw 多 Agent 通信整体架构——从用户请求到多 Agent 并行执行再到结果汇报
图中关键路径解读：
1. 用户请求路径 → 用户消息经 Gateway 路由到主 Agent 2. 任务派发路径 → 主 Agent 通过 sessions_spawn创建子 Agent Session3. 结果回传路径 → 子 Agent 完成后通过 Announce 机制自动推送结果 4. 并发控制 → 所有子 Agent 运行通过 Lane Queue 控制并发
🔍 架构设计的精妙之处：Announce 机制采用了"先尝试直接投递→失败则入队列"的两阶段分发策略（
subagent-announce-dispatch.ts），在保证可靠性的同时最小化延迟。
4. 三种通信机制详解
⚙️ OpenClaw 提供了三种 Agent 间通信方式，各有适用场景。选错了方式就像用锤子拧螺丝——能拧，但效率堪忧。
4.1 机制一：sessions_spawn — 派生子 Agent（主要方式）
sessions_spawn 是最核心的工作指派方式。主 Agent 调用它创建一个全新的、独立的子 Agent Session 来执行特定任务。
图 2：sessions_spawn 工作流程——从任务派发到结果自动推送
核心参数说明：
task | "分析 Q3 销售数据并生成报告" | ||
agentId | "coding" | ||
runtime | subagent | "subagent""acp" | |
mode | "run""session"（持久化） | ||
model | "anthropic/claude-sonnet-4-6" | ||
thinking | "high" | ||
runTimeoutSeconds | 900 | ||
thread | true | ||
cleanup | "delete""keep" |
操作示例 — 派生单个子 Agent：
主 Agent 调用 sessions_spawn 工具：
{ "task": "搜索最近一周关于 RAG 技术的论文，整理出 Top 5 并写出摘要", "model": "anthropic/claude-sonnet-4-6", "runTimeoutSeconds": 300}返回结果（立即返回，非阻塞）：
{ "status": "accepted", "childSessionKey": "agent:main:subagent:a1b2c3d4-e5f6-7890", "runId": "run-uuid-12345", "note": "Auto-announce is push-based. Wait for completion events."}操作示例 — 并行派生多个子 Agent：
主 Agent 可以连续调用 sessions_spawn 并行派发多个任务：
# 第一个子 Agent：搜索论文sessions_spawn(task="搜索 RAG 最新论文 Top 5", model="claude-sonnet")# 第二个子 Agent：分析代码库sessions_spawn(task="分析 src/ 目录下的 RAG 实现代码", agentId="coding")# 第三个子 Agent：使用 Codex 执行代码测试sessions_spawn(task="运行 RAG 管道的单元测试", runtime="acp", agentId="codex")⚠️ 关键原则：spawn 之后不要轮询！Announce 是推送式的。主 Agent 应该等待完成事件以 user message 的形式自动到达，而不是调用
sessions_list或exec sleep反复查询。
4.2 机制二：sessions_send — 向已有 Session 发消息（A2A 通信）
与 sessions_spawn 创建新 Session 不同，sessions_send 是向一个已经存在的 Session 发送消息，实现 Agent 之间的对话式通信。
图 3：sessions_send A2A 通信流程——包含多轮 Ping-Pong 对话
操作示例 — 通过 Session Key 发消息：
{ "sessionKey": "agent:coding:main", "message": "请帮我 review 最近提交的 PR #42 中的代码变更"}操作示例 — 通过 Label 发消息：
{ "label": "support inbox", "agentId": "support", "message": "用户反馈登录接口 500 错误，请排查"}⚠️ 前提条件：
sessions_send的 Agent-to-Agent 功能默认关闭！需要在配置中显式开启：
{ tools: { agentToAgent: { enabled: true, // 必须显式开启 allow: ["main", "coding", "support"] // 白名单 } }}sessions_spawn vs sessions_send 对比：
4.3 机制三：嵌套编排模式（Orchestrator Pattern）
OpenClaw 支持子 Agent 再派生子 Agent，形成主 Agent → 编排器 → 工人的树形编排结构。
图 4：嵌套编排模式——主 Agent → 编排器 → 叶子工人的三级结构
深度级别与权限对照：
agent:<id>:main | |||
agent:<id>:subagent:<uuid> | maxSpawnDepth >= 2 | ||
agent:<id>:subagent:<uuid>:subagent:<uuid> |
启用嵌套编排的配置：
{ agents: { defaults: { subagents: { maxSpawnDepth: 2, // 允许子 Agent 再派生（默认 1，不允许嵌套） maxChildrenPerAgent: 5, // 每个 Agent Session 最多 5 个活跃子 Agent maxConcurrent: 8, // 全局并发上限 runTimeoutSeconds: 900 // 默认超时 15 分钟 } } }}Announce 链路（结果逐级上报）：
1. Depth-2 工人完成 → Announce 给 Depth-1 编排器 2. Depth-1 编排器收集所有工人结果，综合处理后 → Announce 给 Depth-0 主 Agent 3. 主 Agent 收到综合结果 → 回复用户
💡 每层只能看到直接子级的 Announce。Depth-2 工人的结果不会直接到达主 Agent，而是由编排器综合后转发。
5. 关键指标与配置
📊 了解限制才能用好系统。
5.1 系统限制
maxSpawnDepth: 1-5 | |||
maxChildrenPerAgent: 1-20 | |||
maxConcurrent | |||
runTimeoutSeconds | |||
session.agentToAgent.maxPingPongTurns | |||
archiveAfterMinutes |
5.2 安全控制配置
{ tools: { // Agent 间直接消息（sessions_send）的访问控制 agentToAgent: { enabled: false, // 默认关闭！ allow: ["main", "coding", "support"] // 白名单 }, // Session 工具的可见性范围 sessions: { // "self": 只能看到自己的 Session // "tree": 当前 Session + 子 Session（默认） // "agent": 当前 Agent 的所有 Session // "all": 所有 Session（跨 Agent 仍需 agentToAgent 授权） visibility: "tree" } }}6. 实践指南
🛠️ 理论看完了，现在撸起袖子搬砖。
6.1 适用场景
• 场景 A — 并行研究：需要同时搜索多个信息源、对比多篇文档时，spawn 多个子 Agent 各负责一个方向 • 场景 B — 代码审查流水线：主 Agent 接收 PR，spawn 子 Agent 分别负责代码风格检查、安全扫描、测试覆盖率分析 • 场景 C — 跨工具链协作：需要同时使用 OpenClaw 原生 Agent 和外部 Codex/Claude Code 时，混合使用 runtime: "subagent"和runtime: "acp"
6.2 最佳实践
1. - 明确任务描述
• ✅ 推荐做法： sessions_spawn(task="分析 src/agents/ 目录下所有 .ts 文件，找出未被测试覆盖的公共函数，输出函数名+文件路径列表")• ❌ 反面教材： sessions_spawn(task="看看代码")• 💡 原因：子 Agent 的上下文完全独立于主 Agent，模糊的任务描述会导致子 Agent 完全不知道该做什么
2. - 为子 Agent 选择合适的模型
• ✅ 推荐做法：简单搜索任务用便宜快速的模型（ model: "claude-haiku"），复杂推理用高级模型• ❌ 反面教材：所有子 Agent 都用最贵的模型 • 💡 原因：每个子 Agent 有独立的 Token 消耗。10 个子 Agent 用 Opus 模型，成本是 Haiku 的 60 倍
3. - 设置合理超时
• ✅ 推荐做法： runTimeoutSeconds: 300（5 分钟）用于常规任务• ❌ 反面教材：不设超时（默认 0 = 无限制） • 💡 原因：子 Agent 可能陷入死循环或等待不存在的资源。超时是安全阀
6.3 常见陷阱
sessions_list | |||
sessions_sendforbidden | agentToAgent.enabled | ||
maxChildrenPerAgent 限制 | |||
7. 操作示例
💻 以下是 OpenClaw 多 Agent 通信的完整操作示例。
7.1 示例一：并行派发三个研究任务
场景：主 Agent 需要同时研究三个技术方向并汇总报告。
主 Agent 的操作步骤：
步骤 1: 调用 sessions_spawn 派发第一个任务────────────────────────────────────Tool: sessions_spawn{ "task": "搜索 2024 年关于 RAG 技术的最新论文，整理 Top 5 并写出 100 字摘要", "label": "rag-research", "model": "anthropic/claude-sonnet-4-6", "runTimeoutSeconds": 300}→ 返回: { "status": "accepted", "childSessionKey": "agent:main:subagent:aaa-111" }步骤 2: 调用 sessions_spawn 派发第二个任务────────────────────────────────────Tool: sessions_spawn{ "task": "分析 LangChain 和 LlamaIndex 的 RAG 实现方案差异，输出对比表格", "label": "framework-compare", "model": "anthropic/claude-sonnet-4-6", "runTimeoutSeconds": 300}→ 返回: { "status": "accepted", "childSessionKey": "agent:main:subagent:bbb-222" }步骤 3: 调用 sessions_spawn 派发第三个任务────────────────────────────────────Tool: sessions_spawn{ "task": "在 /workspace/rag-demo 目录中运行性能基准测试脚本并收集结果", "label": "benchmark", "runtime": "acp", "agentId": "codex", "runTimeoutSeconds": 600}→ 返回: { "status": "accepted", "childSessionKey": "agent:main:acp:ccc-333" }步骤 4: 等待（不轮询！）────────────────────────────────────三个子 Agent 并行执行。主 Agent 无需做任何事情。完成事件会以 user message 的形式自动注入。步骤 5: 收到完成事件后汇总────────────────────────────────────[子 Agent aaa-111 完成] → RAG 论文 Top 5 列表[子 Agent bbb-222 完成] → 框架对比表格[子 Agent ccc-333 完成] → 性能测试数据主 Agent 综合三份结果，生成最终报告回复用户。7.2 示例二：使用 Slash 命令管理子 Agent
在聊天中直接操作子 Agent：
# 查看当前 Session 的所有子 Agent 运行/subagents list# 查看特定子 Agent 的详细信息/subagents info #1# 查看子 Agent 的运行日志（最近 20 条，包含工具调用）/subagents log #1 20 tools# 手动 spawn 一个子 Agent/subagents spawn coding "重构 auth 模块的错误处理" --model claude-sonnet --thinking high# 终止一个运行中的子 Agent/subagents kill #2# 终止所有子 Agent/subagents kill all# 给运行中的子 Agent 发送补充指令/subagents send #1 "优先关注安全相关的代码"# 给运行中的子 Agent 发送 steer 指令（修改方向但不替换上下文）/subagents steer #1 "缩小范围，只看 src/auth/ 目录"7.3 示例三：配置多 Agent 环境
完整的 配置示例：
{ // 定义多个 Agent agents: { defaults: { subagents: { maxSpawnDepth: 2, // 允许嵌套编排 maxChildrenPerAgent: 5, // 每个 Agent 最多 5 个子 Agent maxConcurrent: 8, // 全局并发上限 runTimeoutSeconds: 600, // 默认 10 分钟超时 model: "anthropic/claude-sonnet-4-6", // 子 Agent 默认模型 archiveAfterMinutes: 30 // 30 分钟后自动归档 } }, list: [ { id: "main", default: true, workspace: "~/.openclaw/workspace", model: "anthropic/claude-opus-4-6" // 主 Agent 用高级模型 }, { id: "coding", workspace: "~/.openclaw/workspace-coding", model: "anthropic/claude-sonnet-4-6", // coding Agent 允许被其他 Agent spawn subagents: { allowAgents: ["main"] // 只有 main 可以 spawn coding } }, { id: "research", workspace: "~/.openclaw/workspace-research", model: "anthropic/claude-haiku" // 研究 Agent 用便宜模型 } ] }, // Agent 间直接通信 tools: { agentToAgent: { enabled: true, allow: ["main", "coding", "research"] }, sessions: { visibility: "agent" // 同一 Agent 的所有 Session 可见 } }, // ACP 配置（外部工具链） acp: { enabled: true, backend: "acpx", defaultAgent: "codex", allowedAgents: ["codex", "claude"], maxConcurrentSessions: 4 }}8. 哲学反思与展望
🔭 技术解决问题，但真正有趣的问题往往在技术之外。
8.1 多 Agent 通信背后的思想
OpenClaw 的多 Agent 通信机制本质上做了一件很深刻的事：它把中心化的决策与去中心化的执行统一在了一个优雅的框架中。主 Agent 负责理解意图和分解任务（中心化决策），而子 Agent 在各自独立的 Session 中自主完成工作（去中心化执行），最后通过 Announce 机制将信息重新聚合。
这让人想起组织管理学中的一个经典命题：最高效的团队不是没有管理者的团队，而是管理者只负责分配任务和整合结果、不干预具体执行的团队。 OpenClaw 的 Session 隔离 + push-based Announce 正是这一理念的技术体现。
8.2 未解之题
• 信息损耗问题：当子 Agent 的详细分析经过 Announce 压缩后传递给主 Agent，不可避免地会丢失部分信息。如何在"精简汇报"和"信息完整性"之间找到最优平衡？ • 级联失败：在嵌套编排模式中，如果中间层编排器超时或出错，其下游所有工人的成果可能全部丢失。如何设计更健壮的故障恢复机制？
8.3 未来展望
从当前的技术趋势来看，多 Agent 通信正在从"工具式协作"向"自组织协作"演进。OpenClaw 目前的模式是由主 Agent 显式决定 spawn 哪些子 Agent，但未来可能出现 Agent 自发地根据任务复杂度决定是否需要协作、以及与谁协作的能力。
另一个值得关注的方向是跨网关的 Agent 通信。当前 OpenClaw 的多 Agent 通信限于单个 Gateway 进程内，但随着 ACP（Agent Client Protocol）的成熟，跨进程、跨机器的 Agent 协作正在变为可能。
💭 结语：当我们教会 Agent 如何协作，也许真正在回答的问题不是"AI 能做什么"，而是"分工与协作的本质是什么"——毕竟，这个问题人类自己也还没完全想清楚。
9. 参考资料
源码
• OpenClaw sessions-spawn-tool.ts: src/agents/tools/sessions-spawn-tool.ts - [1]
• 📌 核心：sessions_spawn 工具的完整实现，包含参数验证和 ACP/Subagent 分流逻辑
• OpenClaw sessions-send-tool.ts: src/agents/tools/sessions-send-tool.ts - [2]
• 📌 核心：sessions_send 工具实现，包含 A2A 访问控制
• OpenClaw subagent-announce-dispatch.ts: src/agents/subagent-announce-dispatch.ts - [3]
• 📌 核心：Announce 两阶段分发策略实现
• OpenClaw subagent-spawn.ts: src/agents/subagent-spawn.ts - [4]
• 📌 核心：子 Agent 派生的底层逻辑，包含深度检查、模型选择、工作空间继承
官方文档
• Multi-Agent Routing - [5]
• 📌 适合：了解多 Agent 路由和 Binding 机制的完整配置
• Sub-Agents - [6]
• 📌 适合：sessions_spawn 工具的完整参数说明和嵌套编排配置
• ACP Agents - [7]
• 📌 适合：使用外部工具链（Codex/Claude Code）的详细指南
• Agent Send - [8]
• 📌 适合：从 CLI 触发 Agent 运行的操作指南
引用链接
[1] src/agents/tools/sessions-spawn-tool.ts: ../../openclaw/src/agents/tools/sessions-spawn-tool.ts[2] src/agents/tools/sessions-send-tool.ts: ../../openclaw/src/agents/tools/sessions-send-tool.ts[3] src/agents/subagent-announce-dispatch.ts: ../../openclaw/src/agents/subagent-announce-dispatch.ts[4] src/agents/subagent-spawn.ts: ../../openclaw/src/agents/subagent-spawn.ts[5] Multi-Agent Routing: ../../openclaw/docs/concepts/multi-agent.md[6] Sub-Agents: ../../openclaw/docs/tools/subagents.md[7] ACP Agents: ../../openclaw/docs/tools/acp-agents.md[8] Agent Send: ../../openclaw/docs/tools/agent-send.md
