洪致知的个人网站

查看源代码

OpenClaw核心流程：一条消息如何跑完整个 Agent

洪致知2026-03-21

原文已做技术向整理，移除了推广信息、作者标识与无关内容，仅保留工程实现相关部分。

阅读导航

先看「十五、总结」了解全局结论
再看「一、整体架构」和「四、路由治理」建立主干认知
最后按需阅读「八~十四」深入到记忆、技能与多 Agent 协作细节

3 分钟结论

OpenClaw 的核心不是“会聊天”，而是 运行时治理能力。
关键工程价值来自：协议收束、幂等去重、会话车道、上下文压缩、错误回退。
多 Agent 的落地重点不在“多”，而在 边界与回流机制：谁拆任务、谁汇总、谁对最终结果负责。

OpenClaw 常被当作“会聊天、会调工具”的 Agent 应用来看待。
但从工程实现角度，它更接近一个 Agent Runtime + Gateway：把消息接入、会话治理、上下文管理、技能注入、工具调用、状态持久化、多 Agent 协作全部串成可运行、可扩展、可治理的链路。

为了更直观，我们用一个典型请求贯穿全文：

帮我整理今天的重要邮件，提炼待办，并生成一份给老板的简报。

一、整体架构：五层抽象

OpenClaw 的架构可以抽象为五层：

用户接口层：CLI / Web / App / WebSocket API
Gateway 核心层：连接管理、接入、配置热加载、健康检查
消息处理层：执行器、路由、会话、媒体、出站
扩展插件层：通道插件、技能系统、sub-agent
基础设施层：配置密钥、日志、任务、事件总线、记忆检索、安全沙箱

一条消息的执行主线是：

消息源 -> 协议适配 -> 路由分发 -> 会话构建 -> Agent 执行 -> 响应投递 -> 状态持久化

二、消息进门：先做协议适配

不同通道（钉钉、飞书、Telegram、Discord、WebSocket）消息结构天然异构。
OpenClaw 不让核心逻辑直接接触外部原始格式，而是先统一收敛成 MsgContext。

interface MsgContext {
  Body: string;
  BodyForAgent?: string;
  BodyForCommands?: string;
  RawBody?: string;
  SessionKey: string;
  Provider: string;
  Surface?: string;
  ChatType?: "direct" | "group";
  SenderId?: string;
  SenderName?: string;
  SenderUsername?: string;
  OriginatingChannel?: string;
  OriginatingTo?: string;
  AccountId?: string;
  MessageThreadId?: string;
  CommandAuthorized?: boolean;
  MessageSid?: string;
  GatewayClientScopes?: string[];
}

这样后续处理层只面向统一模型，不被通道细节污染。

三、统一入口：dispatchInboundMessage

所有入站最终都收束到统一入口，典型逻辑是：

export async function dispatchInboundMessage(params) {
  const finalized = finalizeInboundContext(params.ctx);
  return await withReplyDispatcher({
    dispatcher: params.dispatcher,
    run: () => dispatchReplyFromConfig({
      ctx: finalized,
      cfg: params.cfg,
      dispatcher: params.dispatcher,
      replyOptions: params.replyOptions,
      replyResolver: params.replyResolver,
    }),
  });
}

这里核心是两步：

先 finalizeInboundContext 做最终标准化
再进入统一回复分发主干

四、路由治理：去重、拦截、目标 Agent 选择

1) 幂等去重

生产环境中，Webhook 重试和网络抖动会导致重复投递。
OpenClaw 会构建幂等键，避免同一消息被重复执行。

export function buildInboundDedupeKey(ctx: MsgContext): string | null {
  const provider = normalizeProvider(
    ctx.OriginatingChannel ?? ctx.Provider ?? ctx.Surface
  );
  const messageId = ctx.MessageSid?.trim();
  if (!provider || !messageId) return null;

  const peerId = resolveInboundPeerId(ctx);
  if (!peerId) return null;

  const sessionKey = ctx.SessionKey?.trim() ?? "";
  const accountId = ctx.AccountId?.trim() ?? "";
  const threadId = ctx.MessageThreadId ? String(ctx.MessageThreadId) : "";

  return [provider, accountId, sessionKey, peerId, threadId, messageId]
    .filter(Boolean)
    .join("|");
}