OpenClaw 底层架构：1 个 Gateway 如何管理 30+ 消息平台

运维有术

发布于 2026-04-01 19:54:46

1930

🚩 2026 年「术哥无界」系列实战文档 X 篇原创计划第 58 篇，OpenClaw 最佳实战「2026」系列第 28 篇大家好，欢迎来到 术哥无界 | ShugeX ｜运维有术。我是术哥，一名专注于 AI 编程、AI 智能体、Agent Skills、MCP、云原生、AIOps、Milvus 向量数据库的技术实践者与开源布道者！ Talk is cheap, let's explore。无界探索，有术而行。

OpenClaw 是 2026 年最火爆的现象级 AI 开源项目。这个 2025 年 11 月才发布的开源项目，GitHub Star 数已经突破 31 万：超过了 React、Vue 等明星项目多年的积累。

NVIDIA CEO 黄仁勋的评价更直接：「OpenClaw 是个人 AI 的操作系统」。

但大多数介绍文章只停留在「它能做什么」的层面。如果你和我一样，更关心「它是怎么做到的」，这篇文章会带你深入 OpenClaw 的底层架构：看看 pi-mono 运行时、Gateway 控制平面、Context Engine 和 Session Management 是怎么协同工作的。

1. 整体架构：一个 Gateway 统管全局

先看一张简化版的架构图：

消息平台 (WhatsApp/Telegram/Slack/Discord/...)
                    │
                    ▼
          ┌─────────────────┐
          │    Gateway      │
          │  (控制平面)      │
          │ 127.0.0.1:18789 │
          └────────┬────────┘
                   │
    ┌──────────────┼──────────────┐
    │              │              │
    ▼              ▼              ▼
macOS App      CLI/WebUI      iOS/Android
 (Client)       (Client)       (Node)

OpenClaw 的核心设计思想是：一个长生命周期的 Gateway 进程，统一管理所有消息渠道。

这种设计有几个直接的好处：

第一，避免重复连接。 如果你同时用 WhatsApp 和 Telegram 跟 Agent 聊天，不需要分别启动两个进程。Gateway 内部维护了两套连接，但对外只暴露一个 WebSocket 接口。

第二，状态一致性。 所有会话状态都由 Gateway 持有。无论你从手机还是电脑发起对话，看到的都是同一个上下文。

第三，简化部署。 只需要在服务器上跑一个 Gateway，客户端（macOS app、WebChat、CLI）通过 WebSocket 连接即可。

官方文档里有一句话很关键：

One Gateway per host; it is the only place that opens a WhatsApp session.

这意味着 Gateway 是「单一事实来源」。所有 UI 客户端必须向 Gateway 查询会话列表和消息数量，而不是自己解析本地的 JSONL 文件。

2. Agent Runtime：pi-mono 的嵌入式运行时

Gateway 负责消息路由，但真正「思考」的是 Agent Runtime。OpenClaw 使用的是 pi-mono，一个嵌入式 Agent Runtime。

2.1 pi-mono 是什么？

根据官方文档的描述：

OpenClaw runs a single embedded agent runtime derived from pi-mono.

注意这里用的是「derived from」（派生自），不是「based on」。这意味着 OpenClaw 重用了 pi-mono 代码库的部分组件（比如 models/tools），但会话管理、发现机制和工具绑定是 OpenClaw 自有的。

具体来说：

OpenClaw 不使用 pi-coding agent runtime
OpenClaw 不读取~/.pi/agent 或 <workspace>/.pi 配置
会话存储路径是 OpenClaw 自己定义的：~/.openclaw/agents/<agentId>/sessions/

2.2 Agent Loop 的执行流程

Agent Loop 是一个完整的「思考-行动」周期。官方文档定义了 6 个阶段：

intake → context assembly → model inference → tool execution → streaming replies → persistence

Intake（消息摄入）

Gateway 接收到用户消息，验证参数，解析会话 ID，立即返回 { runId, acceptedAt }。这一步是异步的——用户不需要等 Agent 思考完就能收到确认。

Context Assembly（上下文组装）

这是最复杂的一步。Context Engine 会：

从 JSONL 文件加载历史消息
注入 6 个上下文文件（AGENTS.md、SOUL.md、TOOLS.md 等）
加载 Skills 快照
根据模型上下文窗口大小截断或压缩历史

Model Inference（模型推理）

调用 LLM API（Claude、GPT 或本地模型），传入组装好的上下文。

Tool Execution（工具执行）

如果模型决定调用工具（比如浏览网页、读取文件），这一步会执行工具并将结果返回给模型。

Streaming Replies（流式回复）

模型的输出会实时流式返回给客户端，而不是等全部生成完才发送。

Persistence（持久化）

完整的对话轮次被写入 JSONL 文件。

2.3 队列与并发控制

Agent Loop 是按会话序列化执行的。这意味着：

同一个会话中，后发的消息会排队等待前一条处理完
不同会话可以并行执行

官方文档用了「per-session lane」（会话车道）的比喻：

Runs are serialized per session key (session lane) and optionally through a global lane.

这种设计防止了「工具竞态」——如果同一个会话中同时执行两个修改文件的工具，可能会产生冲突。

2.4 Hook 系统：在哪里可以拦截？

OpenClaw 提供了两套 Hook 系统，让你可以在特定时机注入自定义逻辑：

内部 Hooks（Gateway Hooks）

agent:bootstrap：在构建引导文件时运行，可以添加/删除引导上下文
命令 Hooks：/new、/reset、/stop 等命令的触发点

插件 Hooks（Plugin Hooks）

更细粒度的生命周期钩子：

Hook	触发时机
before_model_resolve	模型解析前，可以覆盖 provider/model
before_prompt_build	提示词构建前，可以注入上下文
before_tool_call / after_tool_call	工具调用前后
session_start / session_end	会话生命周期边界

这套 Hook 系统让 OpenClaw 具备了很强的可扩展性——你可以通过插件实现自定义的上下文管理、工具拦截、安全审计等功能。

3. Context Engine：上下文的四个生命周期

Context Engine 是 OpenClaw 中负责「管理模型能看到什么」的组件。它有四个生命周期点：

3.1 Ingest（摄入）

每条新消息被添加到会话时触发。Context Engine 可以在这里存储或索引消息。

3.2 Assemble（组装）

每次模型运行前触发。Context Engine 返回一组有序的消息（以及可选的 systemPromptAddition），这些消息会被放入模型的上下文窗口。

3.3 Compact（压缩）

当上下文窗口满了，或者用户执行 /compact 命令时触发。Context Engine 负责压缩历史——通常是把旧消息总结成摘要。

3.4 After Turn（轮次后）

一次完整的对话轮次结束后触发。Context Engine 可以在这里持久化状态、触发后台压缩、更新索引。

3.5 默认引擎 vs 插件引擎

OpenClaw 默认使用 legacy 引擎：

Ingest：无操作（Session Manager 直接处理消息持久化）
Assemble：透传（使用运行时的 sanitize → validate → limit 管道）
Compact：委托给内置的摘要压缩
After Turn：无操作

你也可以通过插件注册自定义的 Context Engine。比如一个基于向量检索的引擎，可以在 Assemble 阶段用 RAG 方式召回相关历史，而不是简单地截断。

配置方式：

{
  plugins: {
    slots: {
      contextEngine: "my-custom-engine",
    },
    entries: {
      "my-custom-engine": {
        enabled: true,
      },
    },
  },
}

4. Session Management：会话隔离与持久化

4.1 会话存储结构

OpenClaw 的会话数据存储在两个地方：

会话列表（sessions.json）

~/.openclaw/agents/<agentId>/sessions/sessions.json

这是一个 sessionKey -> { sessionId, updatedAt, ... } 的映射表。

会话记录（JSONL 文件）

~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

每行是一个完整的对话轮次，包含用户消息、模型回复、工具调用等。

4.2 会话键（Session Key）的映射规则

Session Key 决定了哪些消息会被归到同一个会话中。映射规则取决于聊天类型：

直接消息（Direct Message）

由 session.dmScope 配置控制：

main（默认）：所有直接消息共享主会话，跨设备/跨渠道连续
per-peer：按发送者 ID 隔离
per-channel-peer：按渠道 + 发送者隔离（推荐用于多人共享收件箱）
per-account-channel-peer：按账户 + 渠道 + 发送者隔离

官方有一个重要的安全警告：

If your agent can receive DMs from multiple people, you should strongly consider enabling secure DM mode. Without it, all users share the same conversation context, which can leak private information between users.

群组消息

格式为 agent:<agentId>:<channel>:group:<id>，每个群组有独立的会话。

4.3 会话维护（Maintenance）

OpenClaw 会自动清理过期会话，默认配置：

{
  session: {
    maintenance: {
      mode: "warn",        // "warn" 只报告，"enforce" 执行清理
      pruneAfter: "30d",   // 超过 30 天的会话会被清理
      maxEntries: 500,     // 最多保留 500 个会话
      rotateBytes: "10mb", // sessions.json 超过 10MB 时轮转
    },
  },
}

维护操作的执行顺序：

清理超过 pruneAfter 天数的旧会话
限制会话数量不超过 maxEntries
归档不再引用的 JSONL 文件
轮转过大的 sessions.json

4.4 注入文件：6 个上下文增强点

OpenClaw 会在构建系统提示词时自动注入工作区中的 6 个文件：

文件	作用
AGENTS.md	操作指令 + 「记忆」
SOUL.md	人设、边界、语调
TOOLS.md	用户维护的工具说明
BOOTSTRAP.md	一次性首次运行仪式（完成后删除）
IDENTITY.md	智能体名称/风格/表情符号
USER.md	用户配置 + 首选地址

这些文件让你可以高度定制 Agent 的行为，而不需要修改代码。

5. 与 LangChain/CrewAI/AutoGen 的本质差异

OpenClaw 的官方文档有一句很直接的声明：

Unlike LangChain, CrewAI, AutoGen, and Semantic Kernel, OpenClaw prioritizes modularity.

但「modularity」（模块化）这个词太空洞了。更本质的差异是定位不同：

维度	OpenClaw	LangChain/CrewAI/AutoGen
核心定位	个人 AI 助手	LLM 应用开发框架
目标用户	终端用户	开发者
运行方式	本地长期运行	按需调用
渠道支持	30+ 平台开箱即用	需自行集成
Gateway	统一控制平面	无
状态管理	内置持久化	需自行实现