OpenClaw 架构- 控制平面、会话和事件循环

为什么它感觉“有生命”……而实际上只是输入 + 状态 + 循环

大多数 AI 代理演示都显得充满魔力。OpenClaw 看起来是自主的。但在其底层，这并非魔法——而是一个纪律严明的 事件驱动系统 。

OpenClaw 是一个自托管的开源个人 AI 助手，它比典型的聊天应用更贴近你的操作系统。它不像在浏览器标签页中聊天那样工作，而是连接到你已经使用的消息渠道（WhatsApp、Telegram、Slack、Discord、iMessage、WebChat 等），并可以通过工具执行实际操作。

很多人将 OpenClaw 描述为“自主的”或“始终在线”。解释它的最佳方式是：

OpenClaw 变得主动并不是因为它“醒来并开始思考”。它之所以感觉主动，是因为除了你的消息外，它还有更多种类的输入源，并且在一个一致的循环中处理这些输入。

这就是其优雅的架构秘密。

01

OpenClaw 是什么（以及不是什么）

它是：

• 网关 (Gateway) ： 一个网关（控制平面），从多个地方接收事件并将它们路由

• 代理运行时 (Agent Runtime) ： 一个代理运行时，它执行“回合”，调用 LLM，使用工具，写入状态并回复 。

OpenClaw 自己的文档将 Gateway WebSocket 协议描述为所有客户端连接的单一控制平面（CLI、Web UI、macOS 应用、iOS/Android 节点等）

它不是：

• 一个有意识的系统。

• 一个在后台持续推理的大脑。

如果它看起来像是“凌晨 3 点有灵感”，那通常是因为一个计时器、日程安排、webhook 或 hook 在凌晨 3 点创建了一个事件，然后代理执行了一个常规的轮次。

02

以网关为中心的星型结构

OpenClaw 本质上是一个事件驱动、会话隔离、单写入者的状态机，围绕一个集中的控制平面构建

核心思想：网关是交通管制器和事实来源。代理运行时是执行“思考+行动”的工人。

中央路由器（和真相来源）

OpenClaw 运行一个网关守护进程，保持运行状态，维持连接，并协调整个系统。文档明确说明：

所有会话状态都由网关拥有。

UI 客户端应查询网关，而不是直接读取本地会话文件。

3.1. 会话：隔离是刻意为之（且可配置）

当你从不同地方（DM 与群聊、Telegram 与 Slack 等）与 OpenClaw 交互时，你不想出现意外的上下文泄露。OpenClaw 将此建模为会话密钥。

会话模型很灵活，但默认概念是：

• 每个代理有一个主要的类 DM 会话（通常称为）。

main

• 群组/频道/线程拥有独立的会话。

• 可选的“安全 DM 模式 (Secure DM Mode)”，按发送者/频道/账户隔离 DM，以避免在不同人之间泄露上下文。

如果你不仅为自己运行 OpenClaw，那么安全 DM 模式就很重要——因为默认的 DM 范围可以在未配置的情况下跨 DM 共享相同的会话上下文以保持连续性。

3.2. 会话状态实际存储在哪里

OpenClaw 将会话转录存储在磁盘上的 JSONL 文件中，并维护一个映射会话键与会话 ID 及元数据的存储文件。文档显示的路径如下：

存储：

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

转录：

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

这有两个重要原因：

• 持久性 ：会话在重启后依然存在。

• 安全性 ：这些文件可能包含敏感内容。

3.3. 队列：OpenClaw 如何防止“同时两个想法”的冲突

如果有多个输入几乎同时到达（Slack 私信 + 心跳 + Webhook），你绝对不希望并发运行导致相同的会话文件或工具状态被覆盖。

OpenClaw 通过 车道感知 FIFO 队列 (Lane-aware FIFO Queue) 解决此问题：

• 它保证每个会话在同一时间只有一个活动运行。

• 它仍然允许在不同会话之间进行并行处理（直到配置的限制）。

以下是该队列工作的简化版本：

OpenClaw 还支持不同的队列行为（“模式”），例如：

• Collect (默认) ：将多条消息合并为一个后续回合。

• Followup ：总是等待当前运行结束。

• Steer ：在当前运行的工具边界处注入新消息。

因此，“顺序状态机”的感觉在每个会话层面是真实的——但根据配置，系统仍然可以并发运行其他会话。

3.4. 协议：所有内容都使用相同的类型化 WebSocket 语言

OpenClaw 之所以能支持多种界面（CLI、Web UI、桌面应用、移动节点），一个重要原因是它将网关视为一个真正的控制平面。

三种帧类型：req / res / event

OpenClaw 定义了一个简单的 WebSocket 消息模型：

• 请求 (Request) :

{ type: "req", id, method, params }

• 响应 (Response) :

{ type: "res", id, ok, payload | error }

• 事件 (Event) :

{ type: "event", event, payload, ... }

第一个帧必须是请求

connect

TypeBox：模式驱动验证和代码生成

OpenClaw 使用 TypeBox 模式作为其协议的真理来源。这使得：

• 运行时验证（拒绝错误的帧）。

• JSON Schema 导出。

• 客户端的模型/代码生成。

这是最简单的“你好世界”连接流程

文档中也提到了协议版本控制和连接时的认证，包括如果你设置了网关令牌时的基于令牌的认证。

03

代理运行时循环：从“聊天”转变为“工作”

一旦网关决定哪个代理和哪个会话应该处理输入，代理运行时就会执行标准循环：

1. 加载上下文（会话历史 + 工作区上下文）。
2. 调用模型。
3. 执行工具调用（浏览器、文件系统、Shell、节点、插件）。
4. 持久化更新。
5. 回复（或故意保持沉默）。

一个紧凑的循环图：

4.1 “记忆”不是学习——而是文件

这是最重要的思维转变之一：

OpenClaw 不会通过改变模型权重来“学习”。它通过在磁盘上读写状态并在回合期间重新注入上下文来维持连续性。

OpenClaw 的“代理工作区 (Agent Workspace)”文档将工作区描述为代理的家，你应该将其视为内存。

另外值得注意的是：工作区是默认的工作目录，而不是严格的沙箱——相对路径在工作区内解析，但如果启用沙箱功能，绝对路径可以访问其他地方。

04

创造“自主性”幻觉的五种输入类型

大多数聊天机器人只有在您输入时才会唤醒。OpenClaw 可以基于多种触发类型唤醒，这也是它感觉“有活力”的原因

一些非常具体的细节：

• 心跳 (Heartbeats) ：默认为 30 分钟（某些认证模式除外），推荐的模式是：如果没有需要注意的事项，回复。

HEARTBEAT_OK

• Webhooks ：可以配置为立即触发回合或等到下一个心跳，并且可以启用/禁用传递。

• Hooks ：这是一个事件驱动的自动化系统，可以从多个目录（工作区、托管、捆绑包）中发现。

“凌晨三点的电话”示例：这只是流水线

让我们消除这个经典恐怖时刻的神秘感：

“为什么我的助理在我睡觉的时候决定做点什么？”

不需要涌现。只需：

1. 时间创建了一个事件。
2. 网关将其排队。
3. 代理运行了一个回合。
4. 工具执行了操作。

05

安全性：强大的代理天生就是“辛辣”的

OpenClaw 自身的安全文档基本上表达了大家都在想的事情：运行具有 shell/文件访问权限的代理是有风险的，不存在完美的安全配置，你的目标是要明确谁可以与之通信，它可以在哪里行动，以及它可以接触什么

7.1 为什么攻击面很大

OpenClaw 可以：

• 从多个渠道接收不受信任的文本。

• 读取文件、浏览网页、运行工具。

• 安装/执行“技能”或扩展。

这种组合使得经典的代理风险变得非常真实：

• 提示词注入 （直接或通过网页/文档/电子邮件间接）。

• 技能供应链风险 （一个“有用”的技能实际上是恶意软件）。

• 凭证泄露 （令牌、API 密钥、Cookie）。

• 命令误发 （一个试图提供帮助但使用破坏性 Shell 命令的模型）。

Cisco 的 AI 威胁与安全研究团队强调了“技能”的风险，并引用了一项研究，即分析的 31,000 个代理技能中有 26% 至少包含一个漏洞，并为此发布了一个开源扫描工具。

7.2 你应该实际使用的内置缓解措施

实用的加固清单：

• 配对 + DM 策略 ：配对码在一小时后过期，挂起的请求有限制，所以未知用户不能只是给你发私信并获得完全访问权限。

• 非本地访问的网关令牌 ：如果你将网关暴露在 localhost 之外，必须要求令牌，以便连接必须在握手时进行身份验证。

• 多人 DM 时的安全 DM 模式 ：按发送者/频道隔离，以避免上下文泄露。

• 沙箱化/最小权限 ：请记住：工作区默认不是沙箱。如果你让代理运行代码或触摸敏感路径，请启用沙箱。

• 审计你的设置 ：文档建议运行来发现危险设置和暴露。

• 将社区技能视为不可信代码 ：扫描、审查、固定版本，并避免“每日随机技能”的行为。

7.3 部署建议（简单且现实）

如果你想获得好处而不必经历噩梦：

1. 在专用机器或 VM 上运行 OpenClaw（这样“代理被攻破”并不意味着“你的整个笔记本电脑被攻破”）。
2. 为电子邮件、Slack、GitHub 等使用单独的帐户/限定令牌。
3. 先从“只读”工作流开始（摘要、草稿），然后再让它执行操作。

06

快速查看代码/文档的地图

如果你想深入了解，以下是与架构最相关的入口点：

• 网关协议和握手 （模式、版本控制、认证）

• TypeBox 帧模型 （req/res/event + connect-first 规则）

• 会话管理 （dmScope、安全 DM 模式、文件位置）

• 命令队列 （车道感知 FIFO、每会话保证、模式）

• 心跳 （默认间隔、HEARTBEAT_OK 行为/模式）

• Hooks + Webhooks （内部与外部事件触发器）

• 插件 （OpenClaw 如何通过命令/工具/RPC 扩展）

07

最终结论：OpenClaw 的“自主性”是一种工程模式

如果你把所有东西都提炼出来，OpenClaw 的架构基本上由四部分组成：

1. 时间 （心跳 + Cron）
2. 事件 （消息 + Hooks + Webhooks）
3. 状态 （会话 + 磁盘上的工作区内存）
4. 循环 （代理回合：读取 → 决策 → 行动 → 写入）

原文地址： https://theagentstack.substack.com/p/openclaw-architecture-part-1-control