多Agent通信协调的Gateway消息路由（详解实现方案与架构解析）

多 Agent 系统中，Agent 之间不直接通信，而是通过 Gateway 作为中央消息路由器进行转发和协调。OpenClaw 的 Gateway 承担消息分发、会话隔离、并发控制和幂等去重四项核心职责，是整个 Agent 协作体系的中枢。Agent A 需要调用 Agent B 时，向 Gateway 发送委托请求，Gateway 路由到目标 Agent，收集响应后返回给发起方。这种 Broker 模式让 Agent 可以独立增删、重启，互不影响通信层。

一、Agent 通信的三种基本方式

OpenClaw 中 Agent 间通信并不只有一种路径。根据消息流向和持久化需求，分为三种模式：

通信方式	工作原理	适用场景
Gateway API 调用	Agent A 向 Gateway 发 HTTP 请求，Gateway 路由到 Agent B 并返回响应	结构化任务委托，最可靠
共享记忆	多个 Agent 读取同一会话记忆存储，通过 QMD 交叉检索	异步数据传递，无需显式消息
渠道中继	Agent 监听共享渠道，检测标记给自己的消息并回复	人类可见的协作工作流

Gateway API 调用是最直接的通信方式。Agent A 向 Gateway 发送一条携带目标 Agent ID 的消息，Gateway 根据绑定规则路由到 Agent B，等待其处理完毕后将结果返回。整个过程基于 HTTP 文本传输，底层模型对通信双方面不可见——Claude 驱动的协调者可以调用 GPT 驱动的写作者，Ollama 本地模型也能接入同一团队（来源：docs.openclaw.ai 多 Agent 路由文档）。

1.1 跨 Agent 访问的配置

跨 Agent 通信需要显式开启。在 openclaw.json 中配置 tools.sessions.visibility 和 agentToAgent.allow：

{
  tools: {
    sessions: {
      visibility: "all"  // 允许跨 agent 访问会话
    },
    agentToAgent: {
      enabled: true,
      allow: ["main", "wukong", "bajie"]  // 必须包含发送方和接收方
    }
  }
}

allow 列表必须同时包含通信双方的 Agent ID，缺任何一方都会被拒绝。配置变更后需执行 openclaw gateway restart 才能生效（来源：botlearn.ai 社区实践帖）。

二、Gateway 在多 Agent 协调中的四项核心职责

Gateway 不只是转发消息，它承担了通信链路中四项关键职责：

职责	解决的问题	实现机制
消息路由	将请求精准分发到目标 Agent	绑定规则匹配，最具体优先
会话隔离	防止 Agent 之间状态串扰	按 agentId 独立会话空间
并发控制	防止子 Agent 瞬间打爆 LLM 速率限制	全局排队 enqueueGlobal
幂等去重	防止网络重试导致重复处理	idempotencyKey + dedupe Map

2.1 绑定路由规则

Gateway 的路由基于绑定（Bindings）配置，规则是确定性的，最具体的匹配优先。路由匹配的层级从高到低依次为：

精确对等体匹配（exact peer）
父级对等体（parent peer）
对等体通配符（peer wildcard）
服务器与角色（guild + roles）
服务器（guild）
团队（team）
账户（account）
渠道（channel）
默认 Agent（default agent）

同一层级内多个绑定匹配时，配置顺序靠前的优先。绑定设置多个匹配字段时，所有字段必须同时满足（AND 语义）。省略 accountId 的绑定只匹配默认账户，若需匹配所有账户需显式设置 accountId: "*"（来源：docs.openclaw.ai 多 Agent 路由文档）。

2.2 会话级排队与全局并发控制

Gateway 为每个 Agent 维护会话级队列，保证同一 Agent 的会话串行执行。当一个 Agent 运行耗时较长时，后续请求排队等待，不会并发干扰。

对于子 Agent 大量派生的场景，Gateway 通过 enqueueGlobal 进行全局并发控制。一次性派生数十个子 Agent 时，Gateway 按全局并发上限分批处理，防止瞬间高并发请求打爆 LLM API 的速率限制（来源：mianshiya.com 技术问答）。

// 每个 agent 设置独立 workspace 和会话
{
  agents: {
    entries: {
      alex: { default: true, workspace: "/.openclaw/workspace-alex" },
      mia:  { workspace: "/.openclaw/workspace-mia" }
    }
  },
  bindings: [
    { agentId: "alex", match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230001" } } },
    { agentId: "mia",  match: { channel: "whatsapp", peer: { kind: "direct", id: "+15551230002" } } }
  ]
}

2.3 循环检测

Agent 互相委托任务时容易陷入无限循环：A 委托给 B，B 又委托回 A。Gateway 内置了循环检测机制，每个对话跟踪委托深度（delegation depth），超过可配置的最大跳数限制（默认 5 跳）即终止链路。

除了框架层的硬性限制，还应在每个 Agent 的 SOUL.md 中写入防循环规则：

禁止将任务委托回发送方 Agent
收到委托任务后应自行完成，不再二次委托
只在任务明显超出自身专业领域时才发起委托

三、三种常见多 Agent 协作模式

实际部署中，多 Agent 系统通常采用以下三种模式之一，也可混合使用：

模式	工作方式	典型案例
监督者+工作者	一个协调者 Agent 接收任务，拆解后分派给专门 Agent	管理者路由编码问题给开发 Agent，路由研究问题给搜索 Agent
专家团队	每个 Agent 拥有独立领域，按主题路由请求	分设计费、技术支持、用户引导三个 Agent
流水线	前一个 Agent 的输出作为后一个的结构化输入	搜索 Agent 取数据，摘要 Agent 提炼，写作 Agent 产出

3.1 协调者模式的完整流程

以协调者模式为例，一次完整的多 Agent 协作流程如下：

协调者 Agent（Orion）收到用户请求：”写一篇关于 AI 自动化的 SEO 文章”
Orion 分析任务，拆解为子任务：关键词研究（委托 Radar）和内容撰写（委托 Echo）
Orion 通过 Gateway 向 Radar 发送委托消息，Gateway 路由并等待 Radar 返回关键词数据
Orion 将关键词数据附加到写作指令中，通过 Gateway 委托 Echo 撰写文章
Echo 完成写作，Gateway 将结果返回 Orion
Orion 汇总结果，向用户返回最终文章

# 创建多 Agent 团队
openclaw agents add orion  --workspace ./agents/orion  --non-interactive
openclaw agents add radar  --workspace ./agents/radar  --non-interactive
openclaw agents add echo   --workspace ./agents/echo   --non-interactive

# 启动 Gateway
openclaw gateway start

# 向协调者发送任务
openclaw agent --agent orion --message "写一篇关于AI自动化的SEO文章"

3.2 共享记忆的跨 Agent 检索

除了消息传递，OpenClaw 还支持通过共享记忆实现 Agent 间的数据传递。配置 extraCollections 可以让一个 Agent 检索另一个 Agent 的 QMD 会话记录：

{
  agents: {
    entries: {
      main: {
        memory: {
          search: {
            qmd: {
              extraCollections: [{ path: "notes" }]  // 解析到 workspace 内的 notes-main 集合
            }
          }
        }
      }
    }
  }
}

工作区内的路径保持 Agent 级隔离，每个 Agent 拥有独立的会话检索集。工作区外的路径可以跨 Agent 共享，但名称必须显式声明（来源：docs.openclaw.ai 多 Agent 路由文档）。

3.3 记忆库的 Agent 级隔离

默认情况下 Memory Wiki 使用全局库，所有 Agent 共享同一份知识。若要让支持类 Agent 的编译知识与营销类 Agent 分开，设置 vault.scope 为 agent：

{
  plugins: {
    entries: {
      "memory-wiki": {
        enabled: true,
        config: {
          vault: {
            scope: "agent",
            path: "/.openclaw/wiki"
          }
        }
      }
    }
  }
}

OpenClaw 会在配置路径后追加规范化的 Agent ID，生成类似 /.openclaw/wiki/support 和 /.openclaw/wiki/marketing 的独立目录（来源：docs.openclaw.ai 多 Agent 路由文档）。

四、落地时的三个易错点

角色边界模糊是最常见的问题。两个 Agent 职责重叠时，谁该接什么任务变得不确定，容易导致重复处理或互相推诿。每个 Agent 的 agents.md 应明确列出队友的角色和能力边界。

团队规模过大会增加协调开销。每增加一个 Agent 就多一份 LLM Token 消耗。实践中 2 至 3 个 Agent 的团队通常优于 10 个 Agent 的庞杂阵容，应先从小团队起步，发现明确的能力缺口再逐个扩展。

超时未处理会让整个会话卡死。子 Agent 挂掉不返回时，Gateway 会等待到超时才释放。为每个子 Agent 任务设置最大执行时间（如 300 秒），超时后 Gateway 主动向父 Agent 发送超时通知，父 Agent 据此决定重试或告知用户失败。

常见问题（FAQ）

Q1：Agent 之间能直接通信吗，为什么必须经过 Gateway？ 不能。Gateway 负责路由、鉴权和排队，直连会绕过安全边界。

Q2：不同模型提供商的 Agent 能否互相通信？ 能。Gateway 在文本层处理消息，底层模型对通信双方面不可见。

Q3：如何防止 Agent 互相委托陷入死循环？ Gateway 限制最大委托跳数（默认 5），同时在 SOUL.md 写入防循环规则。