OpenClaw 多 Agent 通信机制:一个 Agent 如何指挥一支 AI 包工队

一句话摘要：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 核心优势

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. 1. 用户请求路径 → 用户消息经 Gateway 路由到主 Agent
2. 2. 任务派发路径 → 主 Agent 通过 sessions_spawn 创建子 Agent Session
3. 3. 结果回传路径 → 子 Agent 完成后通过 Announce 机制自动推送结果
4. 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 工作流程——从任务派发到结果自动推送

核心参数说明：

操作示例 — 派生单个子 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 → 编排器 → 叶子工人的三级结构

深度级别与权限对照：

启用嵌套编排的配置：

{  agents: {    defaults: {      subagents: {        maxSpawnDepth: 2,          // 允许子 Agent 再派生（默认 1，不允许嵌套）        maxChildrenPerAgent: 5,    // 每个 Agent Session 最多 5 个活跃子 Agent        maxConcurrent: 8,          // 全局并发上限        runTimeoutSeconds: 900     // 默认超时 15 分钟      }    }  }}

Announce 链路（结果逐级上报）：

1. 1. Depth-2 工人完成 → Announce 给 Depth-1 编排器
2. 2. Depth-1 编排器收集所有工人结果，综合处理后 → Announce 给 Depth-0 主 Agent
3. 3. 主 Agent 收到综合结果 → 回复用户

💡 每层只能看到直接子级的 Announce。Depth-2 工人的结果不会直接到达主 Agent，而是由编排器综合后转发。

5. 关键指标与配置

📊 了解限制才能用好系统。

5.1 系统限制

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 最佳实践

2. 1. 
3. 明确任务描述
   • • ✅ 推荐做法：sessions_spawn(task="分析 src/agents/ 目录下所有 .ts 文件，找出未被测试覆盖的公共函数，输出函数名+文件路径列表")
   • • ❌ 反面教材：sessions_spawn(task="看看代码")
   • • 💡 原因：子 Agent 的上下文完全独立于主 Agent，模糊的任务描述会导致子 Agent 完全不知道该做什么
5. 2. 
6. 为子 Agent 选择合适的模型
   • • ✅ 推荐做法：简单搜索任务用便宜快速的模型（model: "claude-haiku"），复杂推理用高级模型
   • • ❌ 反面教材：所有子 Agent 都用最贵的模型
   • • 💡 原因：每个子 Agent 有独立的 Token 消耗。10 个子 Agent 用 Opus 模型，成本是 Haiku 的 60 倍
8. 3. 
9. 设置合理超时
   • • ✅ 推荐做法：runTimeoutSeconds: 300（5 分钟）用于常规任务
   • • ❌ 反面教材：不设超时（默认 0 = 无限制）
   • • 💡 原因：子 Agent 可能陷入死循环或等待不存在的资源。超时是安全阀

6.3 常见陷阱

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