OpenClaw 架构详解-夜雨聆风

OpenClaw 架构详解

1. OpenClaw 是什么2. Gateway 核心架构3. WebSocket 协议详解4. 连接生命周期5. Agent Runtime6. Agent Loop 全链路7. 记忆系统8. 多 Agent 路由9. 安全与配对机制10. 架构全景总结

01 SECTION

OpenClaw 是什么

如果你用过 WhatsApp、Telegram 或 Slack，大概能想象出一个 AI 助手接管这些渠道的样子——它收到你的消息，调用工具，给你回复，记住上次你说过什么。OpenClaw 就是这样一个开源的”个人 AI 中枢”，把多个即时通讯渠道统一接入一个本地运行的 AI Agent，并提供完整的工具调用、记忆管理和多 Agent 路由能力。

OpenClaw 的设计哲学是本地优先（local-first）：所有数据、会话记录和凭证默认存储在你自己的机器上，不经过任何第三方服务器。这使它特别适合对隐私敏感的个人或小团队使用。

一句话定义：OpenClaw 是一个以 WebSocket Gateway 为核心的本地 AI 中间件，它把多渠道 IM 接入、Agent 推理循环、记忆管理和多 Agent 路由整合在同一个守护进程中。

在展开技术细节之前，先明确几个贯穿全文的核心概念：

⚡Gateway

守护进程，所有消息渠道的单一控制平面，对外暴露 WebSocket API。

🧠Agent Runtime

内嵌的推理引擎，每个 Gateway 拥有一个，负责会话、工具调用和 LLM 交互。

📡Node

macOS/iOS/Android 等设备端，通过 WebSocket 向 Gateway 提供硬件能力（摄像头、屏幕录制等）。

🔗Channel

具体的消息渠道实现，如 WhatsApp（Baileys）、Telegram（grammY）、Slack、Discord 等。

02 SECTION

Gateway 核心架构

Gateway 是 OpenClaw 的大脑和枢纽。架构上有一条绝对的不变量：每台主机只运行一个 Gateway 实例，它是唯一持有 WhatsApp Baileys 会话的进程，也是所有客户端连接的集中点。

图 1 · Gateway 整体拓扑

从图中可以看出，Gateway 扮演着”星形拓扑中心”的角色：左边接入各类消息渠道，右边通过 WebSocket 服务控制平面客户端（macOS 应用、CLI、Web 管理界面）和 Node 设备，底部内嵌 Agent Runtime 负责实际推理。

三类连接方的区别

OpenClaw 明确区分了三类接入方，它们共享同一个 WebSocket 服务端口，但身份和能力截然不同：

Clients（控制平面）：macOS 客户端、CLI、Web Admin 等。发送 health、status、send、agent 等请求，订阅 tick、presence、shutdown 等事件。每个客户端维持一条 WebSocket 长连接。

Nodes（设备平面）：连接时必须声明 role: node，并携带设备标识和能力列表（caps/commands）。可以暴露 canvas.*、camera.*、screen.record、location.get 等硬件指令，让 Agent 能够感知和操控物理设备。

Canvas / WebChat：Gateway HTTP 服务器在同一端口下挂载静态 UI：/__openclaw__/canvas/ 用于 Agent 可编辑的 HTML/CSS/JS 画布，/__openclaw__/a2ui/ 为 A2UI 宿主。WebChat 通过相同的 WebSocket API 获取聊天历史和发送消息。

03 SECTION

WebSocket 协议详解

OpenClaw 的 Gateway 协议是一套精心设计的 JSON over WebSocket 协议，所有帧都是文本帧，结构清晰且强类型。理解这个协议是理解整个系统通信机制的关键。

帧类型

帧类型	方向	结构	说明
req	Client → Gateway	`{type:"req", id, method, params}`	请求帧，需要携带幂等键以支持安全重试
res	Gateway → Client	`{type:"res", id, ok, payload\|error}`	响应帧，与请求 id 一一对应
event	Gateway → Client	`{type:"event", event, payload, seq?, stateVersion?}`	服务端推送，包含序列号用于检测消息丢失
connect	Client → Gateway	连接后第一帧，必须含 challenge 签名	握手帧，非 connect 的第一帧会被硬断开

认证方式

OpenClaw 支持三种认证模式，灵活适配不同的部署场景：

共享密钥模式（默认）：在 connect.params.auth.token 或 connect.params.auth.password 中传入预配置的密钥。适合本地和私有网络环境。

Tailscale / 受信代理模式：启用 gateway.auth.allowTailscale: true 后，认证信息从请求 Header 中读取，无需在 connect 帧中携带密钥。适合通过 Tailscale VPN 或反向代理访问的场景。

无认证模式（none）：完全关闭共享密钥验证，仅应用于完全私有的内网或容器内部连接，绝不应暴露在公网。

幂等性设计

对于有副作用的方法（send、agent），OpenClaw 要求客户端携带幂等键（idempotency key）。Gateway 维护一个短期去重缓存，确保网络波动导致的重试不会触发重复的消息发送或 Agent 调用。这在移动端网络环境下尤为重要。

{  "type": "req",  "id": "req_7f3a",  "method": "send",  "params": {    "to": "+8613800000000@s.whatsapp.net",    "text": "Hello from OpenClaw",    "idempotencyKey": "idem_abc123"  // 幂等键，防止重复发送  }}

协议类型定义由 TypeBox schema 生成，并从中生成 JSON Schema，再进一步生成 Swift 模型，实现了从单一真相源（TypeBox）到多端类型约束的自动化链条。

04 SECTION

连接生命周期

每一条 WebSocket 连接从建立到断开，都遵循严格的状态机。理解这个生命周期有助于排查连接问题和设计自动重连逻辑。

1建立连接 + 发送 connect 帧

客户端在 WebSocket 握手后立即发送 connect 帧，包含设备标识、角色声明（client 或 node）、以及对 challenge nonce 的签名（v3 格式同时绑定 platform 和 deviceFamily）。任何非 connect 的首帧将触发硬断开。

2设备配对验证

Gateway 检查设备 ID 是否已配对。新设备进入待审批状态，需要人工确认（本地回环连接可自动批准）。配对成功后 Gateway 颁发设备 token，后续重连使用 token 而非手动审批。

3hello-ok + 快照推送

Gateway 返回 res(ok)，payload 为 hello-ok，包含当前支持的 methods 和 events 发现元数据。随即推送 event:presence 和 event:tick 快照，让客户端同步当前状态。

4正常通信阶段

客户端发送请求（req），Gateway 同步返回响应（res）并异步推送事件（event）。Agent 调用返回 { runId, status: "accepted" } 后，后续通过 event:agent 流式推送进度，最终以 res:agent final 结束。

5事件间隙处理

Gateway 的事件不会重放。客户端若发现 seq 跳跃，应主动请求状态刷新（如重新拉取 presence 快照）。这是一种有意识的权衡：简化服务端实现，代价是客户端需要处理间隙。

远程访问方案

OpenClaw 推荐通过 Tailscale 或 VPN 实现安全的远程访问。也可以使用 SSH 端口转发：

# 将远程主机的 18789 端口映射到本地ssh -N -L 18789:127.0.0.1:18789 user@your-host# 同一套握手 + 认证 token 在隧道上同样有效# 远程场景可启用 TLS + 可选证书固定（certificate pinning）

05 SECTION

Agent Runtime

每个 Gateway 内嵌一个 Agent Runtime——基于 Pi Agent Core 构建的推理引擎。它拥有自己的工作区（workspace）、引导文件集（bootstrap files）和会话存储。

工作区与引导文件

Agent 的工作区是其唯一的工作目录，所有工具调用的相对路径都解析到这里。工作区内有一套约定的引导文件，在每次会话首轮时被注入系统提示词的”项目上下文”区域：

AGENTS.md

操作指令与”记忆”。Agent 的核心行为规范，告知它如何处理各类请求、使用哪些工具、遵守哪些约束。

SOUL.md

人格、边界与语气。定义 Agent 的性格特征、回复风格和不应越界的行为红线。

USER.md

用户画像与偏好。存储关于用户的背景信息，让 Agent 能够提供更个性化的响应。

TOOLS.md / IDENTITY.md / BOOTSTRAP.md

工具使用约定、Agent 名称/表情符号/氛围、以及仅在全新工作区首次运行时执行的引导仪式（完成后自动删除）。

大文件处理：若引导文件超出 bootstrap 预算，OpenClaw 会将文件保留在磁盘但截断注入到上下文的副本，并添加截断标记。可通过 /context detail 或 openclaw doctor 查看原始大小与实际注入大小的差异。

技能（Skills）加载顺序

OpenClaw 从多个位置加载技能（Skills），优先级从高到低依次为：

1. <workspace>/skills           # 工作区内的技能（最高优先级）2. <workspace>/.agents/skills    # 项目级 Agent 技能3. ~/.agents/skills             # 个人级 Agent 技能4. ~/.openclaw/skills           # 托管/本地技能5. bundled skills               # 安装包内置技能6. skills.load.extraDirs        # 配置文件中指定的额外目录

模型引用格式

模型引用统一采用 provider/model 格式，以第一个 / 分割。对于 OpenRouter 这类模型 ID 本身含斜杠的场景，需要显式带上 provider 前缀：openrouter/moonshotai/kimi-k2。省略 provider 时，OpenClaw 先查别名，再匹配唯一已配置 provider，最后回退到默认 provider 的首个模型。

06 SECTION

Agent Loop 全链路

Agent Loop 是 OpenClaw 最核心的执行路径：从消息接收到最终回复，所有推理、工具调用和状态持久化都发生在这条链路上。每个会话的 Loop 是串行的（per-session 序列化），保证会话历史的一致性。

完整执行流程

1agent RPC 入口验证与调度

agent RPC 收到请求后立即验证参数、解析 sessionKey/sessionId、持久化会话元数据，并同步返回 { runId, acceptedAt }。实际推理异步进行，客户端通过 agent.wait 或事件流跟踪进度。

2agentCommand 模型解析与 Skills 快照

解析模型配置（含 thinking/verbose/trace 默认值），加载当前 Skills 快照，调用 runEmbeddedPiAgent 进入核心推理引擎。若嵌入式 Loop 未发出生命周期结束事件，agentCommand 会补发兜底事件。

3runEmbeddedPiAgent 核心推理

通过 per-session + global 队列序列化并发运行。解析模型和 auth profile，构建 Pi 会话，订阅 Pi 事件并将 assistant/tool delta 流式推送给客户端，同时强制执行超时限制（默认 48 小时，可配置）。

4subscribeEmbeddedPiSession 事件桥接

将 Pi Agent Core 的原始事件映射到 OpenClaw 的标准 agent stream：工具事件 → stream: "tool"，助手 delta → stream: "assistant"，生命周期 → stream: "lifecycle"（phase: start | end | error）。

5回复整形与抑制

最终 payload 由 assistant 文本（含可选推理内容）、内联工具摘要、错误文本拼接而成。精确 token NO_REPLY/no_reply 会被过滤；消息工具发送的重复内容会被去重；若无可渲染内容且工具报错，会自动生成兜底错误回复。

队列模式（消息并发控制）

当 Agent 正在推理时，新消息到来该如何处理？OpenClaw 提供三种队列模式：

模式	行为	适用场景
steer	消息注入当前运行，在当前 turn 的工具调用执行完后、下一次 LLM 调用前投递	需要实时修正 Agent 方向的场景
followup	持有消息直到当前 turn 结束，再以新 turn 开始处理	普通对话，保持 turn 完整性
collect	批量收集当前 turn 期间的所有消息，一次性开启新 turn 处理	高频消息场景，减少 LLM 调用次数

Plugin Hook 系统

OpenClaw 提供了丰富的 Hook 插入点，允许开发者在 Agent Loop 的关键节点注入自定义逻辑：

before_model_resolve

在模型解析前运行，可覆盖 provider/model 选择

before_prompt_build

会话加载后，注入动态上下文或修改系统提示词

before_agent_reply

LLM 调用前，可直接返回合成回复或静默 turn

before_tool_call / after_tool_call

拦截工具参数或结果，支持阻断（block: true 终止链）

before_compaction / after_compaction

观察或标注压缩循环，可触发 retry

message_received / message_sending

入站/出站消息钩子，cancel: true 可终止发送链

session_start / session_end

会话生命周期边界

agent_end

推理完成后，检查最终消息列表和元数据

Block Streaming 分块推送

Block streaming 控制 Assistant 回复是否在生成过程中分块推送，默认关闭（off）。启用后：

分块边界由 blockStreamingBreak 控制（text_end 或 message_end，默认 text_end）；软分块大小由 blockStreamingChunk 控制（默认 800-1200 字符，优先段落 → 换行 → 句子）；blockStreamingCoalesce 基于空闲时间合并碎片 chunk，减少单行刷屏。非 Telegram 渠道需要显式设置 *.blockStreaming: true 才能启用。

07 SECTION

记忆系统

OpenClaw 的记忆系统遵循一个简洁但深刻的设计原则：Agent 只记住写到磁盘的东西，没有隐藏状态。所有记忆以普通 Markdown 文件的形式存储在工作区，用户和开发者可以直接查看、编辑甚至版本控制。

三层记忆结构

📋MEMORY.md

长期记忆层。存储持久事实、偏好和决策摘要。每次 DM 会话开始时自动注入，大小超出预算时截断注入（原文件完整保留）。

📅memory/YYYY-MM-DD.md

日志层。运行中的上下文和观察记录。今日和昨日的日记自动加载，历史日记通过 memory_search 工具按需检索。

💭DREAMS.md

梦境日记（可选）。后台巩固 pass 的输出，供人工审查。Dreaming 系统从短期信号中筛选高质量候选，晋升到长期记忆。

记忆后端选择

OpenClaw 支持多种记忆存储后端，适应从个人使用到高级研究的不同需求：

后端	特点	适合场景
Builtin (SQLite)	零额外依赖，支持关键词搜索 + 向量相似度 + 混合搜索	大多数用户的默认选择
QMD	本地优先 sidecar，支持重排序、查询扩展、工作区外目录索引	高级本地部署，需要更强检索能力
Honcho	AI 原生跨会话记忆，用户建模 + 语义搜索 + 多 Agent 感知	需要跨 Agent 共享用户画像的场景
LanceDB	本地 LanceDB 向量库，支持 Ollama 本地嵌入	完全本地、离线运行的场景

Dreaming：异步记忆巩固

Dreaming 是一个可选的后台记忆巩固机制——类似人类睡眠中的记忆整合过程。它定期从短期 dreaming store（memory/.dreams/）中收集信号，对候选记忆进行评分（考量召回频率、查询多样性等维度），只有通过评分门槛的条目才会晋升到 MEMORY.md。

Grounded Backfill：可以使用 openclaw memory rem-backfill 对历史日记文件进行回溯分析，将结果暂存到短期 dreaming store（而非直接写入 MEMORY.md），保留人工审查的机会。

记忆搜索

当配置了嵌入 API（OpenAI、Gemini、Voyage、Mistral 均自动检测），memory_search 工具启用混合搜索模式：结合向量相似度（语义匹配）与关键词匹配（精确术语、ID、代码符号），两者互补——语义搜索擅长模糊匹配，关键词搜索确保精确实体不被遗漏。

08 SECTION

多 Agent 路由

OpenClaw 支持在同一个 Gateway 进程中运行多个完全隔离的 Agent，每个 Agent 拥有独立的工作区、auth profiles 和会话存储。这个能力让一台服务器可以同时服务多人，或让同一用户在不同场景下使用不同人格的 AI。

Agent 是什么

一个 agentId 代表一个完整隔离的”大脑”：

独立 工作区（AGENTS.md / SOUL.md / USER.md / 本地笔记）
独立 状态目录（~/.openclaw/agents/<agentId>/agent，含 auth profiles 和模型注册表）
独立 会话存储（~/.openclaw/agents/<agentId>/sessions）
独立 OAuth 账号（不跨 Agent 共享刷新 token）

消息路由规则（最具体优先）

Bindings 是消息路由的配置，采用最具体优先（most-specific wins）的确定性匹配策略：

1peer match

精确匹配 DM/群组/频道 ID，优先级最高

2parentPeer

线程继承匹配

3guildId + roles

Discord 服务器 + 角色路由

4guildId

Discord 服务器级匹配

5teamId

Slack 工作区级匹配

6accountId

渠道账号级回退（如 WhatsApp 手机号）

7channel + *

accountId: "*" 渠道全局回退

8default agent

回退到 agents.list[].default，否则列表第一个，最终默认为 main

多字段 binding 采用 AND 语义：同时设置 peer + guildId 时，两者都必须匹配才生效。同优先级内多个匹配时，配置文件中靠前的优先。

{  agents: {    list: [      {        id: "daily",            // 日常快速 Agent        workspace: "~/.openclaw/workspace-daily",        model: "anthropic/claude-sonnet-4-6"      },      {        id: "deep",             // 深度工作 Agent        workspace: "~/.openclaw/workspace-deep",        model: "anthropic/claude-opus-4-6"      }    ]  },  bindings: [    // Peer 精确匹配优先级最高    { agentId: "deep",  match: { channel: "whatsapp", peer: { kind: "direct", id: "+8613800001234" } } },    // 渠道级全局回退    { agentId: "daily", match: { channel: "whatsapp" } },    { agentId: "deep",  match: { channel: "telegram" } }  ]}

跨 Agent QMD 记忆共享

默认情况下每个 Agent 的记忆完全隔离。如需跨 Agent 检索记忆（例如让 work Agent 也能搜索 family Agent 的会话记录），可以在配置中添加 extraCollections：

重要安全说明：不要跨 Agent 共享 agentDir（这会导致 auth/session 碰撞）。Auth profiles 是 per-agent 的，OAuth 刷新 token 不会自动克隆到其他 Agent 的存储中。如需独立 OAuth 账号，请从对应 Agent 重新登录。

09 SECTION

安全与配对机制

OpenClaw 的安全模型围绕设备身份（device identity）构建，而非简单的 token 校验。每条 WebSocket 连接（无论是 Client 还是 Node）都必须携带设备标识并完成配对流程。

配对流程

1首次连接 → 待审批

新设备 ID 触发配对审批流程。本地回环连接（loopback）可自动批准，以保证同机 UX 流畅。非本地连接（包括同机 Tailnet 绑定）仍需显式批准。

2Challenge 签名验证

所有连接必须对 connect.challenge nonce 进行签名。v3 签名 payload 还需绑定 platform 和 deviceFamily——Gateway 会在重连时固定这些元数据，元数据变更需要重新配对。

3颁发设备 Token

配对成功后，Gateway 颁发设备 token，后续重连使用 token 而非重复审批。

4Auth 层叠加

gateway.auth.* 配置对所有连接生效（本地和远程均不例外），与设备配对机制叠加，形成双重验证。

关键安全不变量

每台主机精确一个 Gateway 控制一个 Baileys（WhatsApp）会话。握手是强制的，任何非 JSON 或非 connect 的首帧都会触发硬断开。事件不重放，客户端需主动处理间隙。

10 SECTION

架构全景总结

经过前九节的逐层拆解，我们可以用一张层次图来俯瞰整个 OpenClaw 的架构：

图 2 · OpenClaw 完整架构层次图

架构核心设计原则

• 单一 Gateway 原则：每台主机一个进程，一个 Baileys 会话，一个 WebSocket 服务端口（18789）。避免了多实例的状态同步问题。

• 协议强类型：TypeBox → JSON Schema → Swift 的自动化代码生成链，确保客户端和服务端的协议一致性，而非通过文档约定。

• 本地优先：所有数据（会话 JSONL、记忆 Markdown、auth profiles）默认存储在 ~/.openclaw，用户完全掌控自己的数据。

• 可观测的记忆：记忆以普通文件形式存在，没有黑盒数据库。Agent 记住的一切都是人类可读可编辑的 Markdown。

• 渐进式复杂度：从单 Agent 的零配置到多 Agent 的精细路由，系统在简单场景下极简，在复杂场景下功能完整。

• 钩子驱动的可扩展性：Hook 系统覆盖从模型选择到消息发送的完整链路，无需修改核心代码即可定制任意行为。

OpenClaw 的架构设计展现了一种务实的工程哲学：用 WebSocket 这个简单的协议承载所有通信，用文件系统作为记忆的基础设施，用明确的序列化保证会话一致性。这让它在复杂度可控的前提下，实现了从个人 AI 助手到多渠道多 Agent 中台的完整覆盖。