深入理解 OpenClaw 技术架构与实现原理（上篇）

开篇：为什么需要 OpenClaw？

在开始深入技术细节之前，我们先回答一个根本问题：OpenClaw 到底是什么？

简单说，OpenClaw 是一个AI 智能体运行时平台——它让你能够拥有一个真正"活着"的数字助手，而不是每次对话都从零开始的聊天机器人。这个助手有记忆、有个性、能主动做事，并且可以通过你日常使用的通讯工具（微信、Telegram、Discord 等）随时联系。

但它的野心不止于此。OpenClaw 想要解决的是AI 智能体落地的最后一公里问题：如何让大模型从"会聊天"变成"能办事"，从"玩具"变成"工具"。

上篇我们将深入 OpenClaw 的核心架构，理解它是如何组织起来的。

一、整体架构概览

1.1 三层架构模型

OpenClaw 的架构可以概括为三层：

┌─────────────────────────────────────────┐│          交互层（Channels）              ││  WhatsApp / Telegram / Discord / 微信... │└─────────────────┬───────────────────────┘                  │ WebSocket┌─────────────────▼───────────────────────┐│          网关层（Gateway）               ││  消息路由 / 会话管理 / 工具编排 / 安全   │└─────────────────┬───────────────────────┘                  │ 嵌入式 Agent 运行时┌─────────────────▼───────────────────────┐│          智能层（Agent）                 ││  大模型 / 技能系统 / 记忆系统 / 工具调用 │└─────────────────────────────────────────┘

关键设计原则：

1. 单一网关：每台主机只运行一个 Gateway，统一管理所有通讯渠道
2. WebSocket 为中心：所有连接（客户端、节点、智能体）都通过 WebSocket 与网关通信
3. 会话隔离：每个对话有独立的会话上下文，支持精细的路由策略
4. 工具沙箱：支持 Docker 沙箱执行，平衡能力与安全

1.2 核心组件

Gateway（网关）

Gateway 是 OpenClaw 的中枢神经，负责：

• 维护与各大通讯平台（WhatsApp、Telegram 等）的连接
• 处理所有 WebSocket 客户端的连接和认证
• 路由消息到正确的 Agent 实例
• 管理会话状态和持久化
• 提供 Canvas（可视化界面）和 A2UI 服务

技术细节：

• 默认监听端口：18789
• 支持本地绑定（127.0.0.1）或远程访问（Tailscale/SSH 隧道）
• 使用 JSON Schema 验证所有入站消息
• 支持设备级配对和令牌轮换

Agent（智能体）

每个 Agent 是一个独立的智能体实例，拥有：

• 独立的工作空间（workspace）
• 独立的会话存储（sessions）
• 独立的认证配置（auth-profiles）
• 独立的技能和工具配置

多 Agent 路由： OpenClaw 支持在一台网关上运行多个隔离的 Agent，通过 bindings 配置将不同渠道/用户的消息路由到不同的 Agent：

{  agents: {    list: [      { id: "work", workspace: "~/.openclaw/workspace-work" },      { id: "personal", workspace: "~/.openclaw/workspace-personal" }    ]  },  bindings: [    { agentId: "work", match: { channel: "telegram", accountId: "work" } },    { agentId: "personal", match: { channel: "whatsapp" } }  ]}

这意味着你可以有工作助手和个人助手两个完全隔离的智能体，它们有不同的个性、记忆和权限。

Nodes（节点）

Nodes 是 OpenClaw 的能力扩展，运行在你的手机、电脑或其他设备上，提供：

• 摄像头控制（camera.snap, camera.clip）
• 屏幕录制（screen.record）
• 位置获取（location.get）
• Canvas 渲染（canvas.navigate）
• 系统命令执行（system.run）

节点通过 WebSocket 连接到网关，声明自己的能力和权限，网关根据配对策略决定是否授权。

二、通信协议详解

2.1 WebSocket 握手流程

OpenClaw 的 WebSocket 协议是其核心控制平面，所有客户端（CLI、Web UI、iOS/Android 节点）都通过此协议与网关通信。

握手流程：

1. 客户端发起 WebSocket 连接2. 网关返回 connect.challenge 事件（包含 nonce 和时间戳）3. 客户端用设备密钥对 challenge 签名，发送 connect 请求4. 网关验证签名，返回 hello-ok 响应（包含协议版本和设备令牌）5. 连接建立，开始正常通信

connect 请求示例：

{"type":"req","id":"req_123","method":"connect","params":{"minProtocol":3,"maxProtocol":3,"client":{"id":"cli","version":"1.2.3","platform":"macos","mode":"operator"},"role":"operator","scopes":["operator.read","operator.write"],"device":{"id":"device_fingerprint","publicKey":"...","signature":"...","signedAt":1737264000000,"nonce":"..."}}}

关键安全机制：

1. 设备指纹：每个设备有唯一 ID，首次连接需要配对审批
2. 挑战 - 响应签名：防止重放攻击
3. 设备令牌：配对后颁发，后续连接使用
4. 本地信任：本地回环或同一主机的 Tailscale 地址可自动审批

2.2 消息帧格式

协议使用简单的 JSON 帧：

• 请求：{type:"req", id, method, params}
• 响应：{type:"res", id, ok, payload|error}
• 事件：{type:"event", event, payload, seq?}

幂等性保证： 对于有副作用的方法（如 send、agent），客户端需要提供幂等键，网关维护短时去重缓存，支持安全重试。

三、会话管理系统

3.1 会话键设计

OpenClaw 的会话管理是其最精妙的设计之一。会话键（sessionKey）决定了对话上下文的隔离粒度。

会话键格式：

agent:<agentId>:<scope>

DM 会话作用域（通过 session.dmScope 配置）：

安全建议： 如果你的 Agent 可能被多人私信，强烈建议设置 dmScope: "per-channel-peer"，否则不同用户的对话上下文会混在一起，导致隐私泄露。

3.2 会话生命周期

重置策略：

1. 每日重置：默认每天凌晨 4 点（网关主机本地时间）创建新会话
2. 空闲重置：可配置空闲超时（如 120 分钟无活动则重置）
3. 手动重置：发送 /new 或 /reset 命令
4. 隔离任务：Cron 任务始终创建新会话

维护机制： OpenClaw 自动维护会话存储，防止无限增长：

{  session: {    maintenance: {      mode: "enforce",      pruneAfter: "30d",        // 删除 30 天前的会话      maxEntries: 500,          // 最多保留 500 个会话      rotateBytes: "10mb",      // 存储文件超过 10MB 时轮换      maxDiskBytes: "1gb"       // 会话目录总大小限制    }  }}

3.3 会话转录存储

会话记录以 JSONL 格式存储在：

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

每条记录包含：

• 角色（user/assistant/tool）
• 内容（文本、工具调用、工具结果）
• 时间戳
• Token 使用统计

优势：

• 追加写入，性能高
• 易于解析和流式处理
• 支持部分读取（不需要加载整个文件）

四、Agent 运行时

4.1 嵌入式 pi-mono

OpenClaw 的 Agent 运行时基于 pi-mono（一个轻量级 Agent 框架），但做了深度定制：

关键差异：

• 不使用 Pi/Tau 的会话文件夹
• 会话管理完全由 OpenClaw 控制
• 工具发现和编排由网关负责
• 支持多 Agent 隔离运行

4.2 Agent 循环（Agent Loop）

一个完整的 Agent 循环包含以下步骤：

1. 接收消息（通过网关 WebSocket）2. 解析会话键，加载会话上下文3. 组装系统提示（包含技能、记忆、工具定义）4. 调用大模型（流式输出）5. 执行工具调用（读/写/执行/浏览器等）6. 流式回复到通讯渠道7. 持久化会话记录

流式处理： OpenClaw 支持两种流式：

1. 块流式（Block Streaming）：将助手输出分块发送，每块是一条完整的消息
2. 预览流式（Preview Streaming）：在 Telegram/Discord/Slack 中更新预览消息

配置示例：

{  agents: {    defaults: {      blockStreamingDefault: "on",      blockStreamingBreak: "text_end",  // 或 "message_end"      blockStreamingChunk: {        minChars: 800,        maxChars: 1200      }    }  }}

4.3 工具系统

核心工具（始终可用）：

• read / write / edit：文件操作
• exec：执行 shell 命令（可沙箱化）
• web_search / web_fetch：网络搜索
• browser：浏览器自动化
• message：发送消息
• sessions_*：会话管理

技能系统： 技能是从 ClawHub 或本地加载的可复用模块，每个技能包含：

• SKILL.md：技能说明和使用指南
• 脚本/二进制文件
• 配置文件

技能加载优先级：

1. 工作空间技能（<workspace>/skills）
2. 本地技能（~/.openclaw/skills）
3. 捆绑技能（OpenClaw 自带）

工具策略： 可以为不同 Agent 配置不同的工具允许/拒绝列表：

{  agents: {    list: [      {        id: "family",        tools: {          allow: ["read", "exec"],          deny: ["write", "edit", "browser"]        }      }    ]  }}

五、记忆系统

5.1 记忆文件布局

OpenClaw 的记忆是纯 Markdown 文件，存储在 Agent 工作空间：

~/.openclaw/workspace/├── MEMORY.md              # 长期记忆（精选）├── memory/│   ├── 2026-03-20.md      # 每日记忆（原始日志）│   ├── 2026-03-19.md│   └── projects.md        # 专题记忆├── AGENTS.md              # 操作指令├── SOUL.md                # 人格设定└── USER.md                # 用户信息

设计哲学：

• 文件即真相：记忆只存在于磁盘上，模型只"记得"写入文件的内容
• 双层结构：每日记忆是原始日志，MEMORY.md 是精选摘要
• 手动维护：重要内容需要显式写入，不会自动记忆

5.2 记忆工具

OpenClaw 提供两个记忆工具供 Agent 使用：

1. memory_search：语义搜索记忆片段

• 使用向量嵌入（支持 OpenAI/Gemini/本地模型）
• 返回相关片段（含文件路径和行号）
• 支持混合搜索（BM25 + 向量）

2. memory_get：读取特定记忆文件

• 按路径读取
• 支持指定起始行和行数

5.3 向量搜索配置

嵌入提供商（自动选择或手动配置）：

{  agents: {    defaults: {      memorySearch: {        provider: "openai",  // 或 "gemini", "local", "ollama"        model: "text-embedding-3-small",        remote: {          apiKey: "YOUR_API_KEY"        }      }    }  }}

本地嵌入（无需 API 密钥）： 使用 node-llama-cpp 加载 GGUF 模型，自动下载到缓存目录。

混合搜索（实验性）： 结合向量相似度和 BM25 关键词匹配，提高召回率：

{  memorySearch: {    query: {      hybrid: {        enabled: true,        vectorWeight: 0.7,        textWeight: 0.3,        mmr: {          enabled: true,  // 最大边界相关性，减少重复          lambda: 0.7        },        temporalDecay: {          enabled: true,  // 时间衰减，新记忆权重更高          halfLifeDays: 30        }      }    }  }}

5.4 自动记忆刷新

当会话接近自动压缩时，OpenClaw 会触发静默记忆刷新：

• 提醒模型将重要信息写入记忆文件
• 默认回复 NO_REPLY，用户看不到此过程
• 防止压缩后丢失重要上下文

配置：

{  agents: {    defaults: {      compaction: {        memoryFlush: {          enabled: true,          softThresholdTokens: 4000        }      }    }  }}

小结

上篇我们深入了 OpenClaw 的核心架构：

1. 三层架构：交互层 → 网关层 → 智能层
2. WebSocket 协议：安全的挑战 - 响应握手，设备级认证
3. 会话管理：灵活的会话键设计，支持细粒度隔离
4. Agent 运行时：基于 pi-mono 的嵌入式循环，支持流式输出
5. 记忆系统：Markdown 文件 + 向量搜索，双层记忆结构

下篇我们将继续探讨：

• 工具执行与安全沙箱
• 多 Agent 协作与路由
• 插件系统与扩展机制
• 生产环境部署与运维

敬请期待！

参考资料：

• OpenClaw 官方文档：https://docs.openclaw.ai^[1]
• GitHub 仓库：https://github.com/openclaw/openclaw^[2]
• 社区 Discord：https://discord.com/invite/clawd^[3]

引用链接