OpenClaw 很容易被写成“能在 Telegram、Slack 或 WhatsApp 里聊天的 AI 助手”。但只看聊天体验，会错过源码中最重要的工程选择：它把渠道、设备、会话、工具、权限和记忆都放进一个长期运行的 Gateway 控制面。

本文以 openclaw/openclaw 的 2026.9.6 release 和 2026-09-24 主线为参照。近期版本持续加强了插件信任、命令解析、浏览器 origin、凭证处理、消息恢复和关闭流程，因此本文不再把它描述成“带记忆的助手”，而是把它当作一套本地优先 Agent 平台来读。

01 先看全局：OpenClaw 的中心是 Gateway

OpenClaw overall architecture

OpenClaw 可以拆成四个平面：

控制面：Gateway、鉴权、路由、配置、生命周期、事件广播
执行面：Agent Runtime、Model、Tool、Subagent、Sandbox
接入面：Channel、Node、Plugin、Browser、Media
数据面：Session、Transcript、Context、Memory、Compaction

一次请求的大致路径是：

消息渠道 / CLI / Webhook
  -> Gateway handshake + auth
  -> channel route -> session key
  -> workspace/bootstrap + skills
  -> context engine + memory recall
  -> model stream
  -> tool policy -> tool / node / plugin
  -> transcript + delivery + durable state

这个模型解释了两个表面矛盾：为什么 OpenClaw 比普通 Agent 更重，以及为什么它适合长期运行。重，是因为它负责连接和治理；适合长期运行，是因为它没有把“本轮回答”当成全部状态。

02 Gateway：把所有入口变成同一套协议

Gateway control plane

Gateway 不是简单的 HTTP router，而是系统宿主，负责：

  • 监听 WebSocket、HTTP、CLI 和内部调用；
  • 完成首帧握手、origin 校验、认证和能力协商；
  • 将 channel、node、agent、session 等方法映射到显式 method table；
  • 广播事件，并在连接断开时回收订阅和后台任务；
  • 统一处理配置、插件生命周期和消息投递。

显式方法表的价值在于可审计。动态把对象上的每个函数暴露出去很方便，却很难回答“哪些方法是公共协议、谁有权限调用、返回值是否可序列化”。OpenClaw 近期对 origin、payload size、超时、关闭排空和 malformed input 的修复，本质上都在强化这一层。

Gateway 还承担身份归一化。来自不同渠道的用户消息，必须被映射成稳定的 channel、account、peer、thread 和 session key，否则同一个人会得到多个记忆空间，或者不同用户意外共享上下文。

03 Agent Runtime：复杂度在“接着谁说话”

CLI startup flow

Agent Runtime 的关键工作不是调用模型，而是把运行条件准备齐：

  1. 解析 session key，找到历史 transcript 和 workspace。
  2. 加载 bootstrap 文件、项目规则和 skills snapshot。
  3. 选择 provider、model、thinking level 和 context engine。
  4. 根据 channel、sandbox 和 policy 装配有效工具集。
  5. 运行 attempt，发送中间事件，处理工具结果和 delivery。
  6. 在结束、失败、取消或 compaction 时收口状态。

因此一次对话不是函数调用，而是一项可恢复的 attempt。重试不能简单复制最后一条 prompt，因为工具可能已经产生副作用；必须区分“模型请求失败”“工具执行失败”“消息投递失败”和“状态写入失败”。

04 工具系统：有效工具集是动态算出来的

Tool assembly pipeline

OpenClaw 的工具来源通常包括核心工具、channel 工具、node 工具、插件工具、MCP 工具和 sandbox 工具。模型拿到的不是全部工具，而是：

有效工具集 =
  capability registry
  ∩ channel / node availability
  ∩ sandbox capabilities
  ∩ user / agent / group policy
  ∩ tool profile

这种动态装配可以让同一个 Agent 在 Telegram 群聊、个人终端和远程 Node 中拥有不同边界。它也带来一个测试要求：必须测试“工具过滤后剩下什么”，而不只测试工具本身是否能运行。

message 之类的平台工具体现了 OpenClaw 的平台化思路。模型提出的是“向某个目标发送某种动作”，具体如何映射到 Slack thread、Telegram reply 或设备通知，由 channel runtime 决定。业务 Agent 不应该知道每个平台的 API 细节。

05 Plugin、Channel、Node：三种扩展的分工

Multi-agent routing

扩展解决的问题生命周期
Plugin增加 provider、tool、hook、memory 或 UI 能力被 Gateway 发现、验证、加载、卸载
Channel接入消息平台并完成收发与线程语义连接、接收、路由、发送、重连
Node接入摄像头、屏幕、文件、设备动作等能力配对、授权、调用、断线恢复

Plugin 不是普通配置。它可能加载代码、访问网络、读取凭证或注册工具，所以当前 OpenClaw 强调外部插件安装前查看能力、来源、版本和精确 artifact。安全的插件系统必须把“发现”和“启用”分开，拒绝更新时也不应破坏旧版本。

Node 的危险性更高，因为它把模型行为连接到真实设备。Node 需要独立身份、配对和 capability policy，不能因为消息渠道已经认证，就默认获得设备控制权。

06 记忆闭环：文件只是载体，检索和晋升才是机制

OpenClaw memory loop

OpenClaw 的记忆可以按生命周期理解：

会话事件
  -> memory flush / observation
  -> 索引与 embedding
  -> hybrid recall
  -> 注入当前 context
  -> recall tracking
  -> 高价值内容 promotion / dreaming
  -> 长期文件或结构化记录

这里要分清三个词：Memory 是跨会话可复用的信息；Context 是当前一次模型调用可见的内容；Compaction 是为了继续运行而对当前会话做的历史投影。把 compaction 当成 memory，会导致所有临时日志都被错误地长期保存。

显式记忆文件的优点是可读、可编辑、可备份。检索层则解决规模问题：先用关键词、时间、路径和 embedding 召回候选，再按来源、相关性、作用域和新鲜度排序。Active Memory 把“主动回想”前置到回答之前，Dreaming 或 promotion 则把重复出现且被证明有用的信号升级为长期知识。

这不是模型自己学会了新参数，而是上下文数据系统变得更会保存和取用信息。它的效果取决于写入门控、冲突处理、用户隔离和检索质量。

07 Compaction 与可靠性：长期运行的真正门槛

长会话最容易丢的不是文字，而是状态：未完成的子任务、文件变更、已经尝试过的方案、等待中的投递和用户授权。可靠的 compaction 应先做 memory flush，再生成结构化摘要，并保留可追溯的原始事件。

OpenClaw 近期 release notes 中反复出现的 message/session integrity、stream recovery、bounded reads 和 shutdown draining，说明真正的生产问题并不在“能不能调用模型”，而在并发失败时是否会静默丢消息。

可以把一次执行看成两个提交：

事实提交：模型事件、工具结果、状态变化先写入 durable transcript
副作用提交：发送消息、改文件、调用设备由 policy + executor 执行

两者不能完全原子化，所以需要幂等键、重试边界、outbox 或 delivery status，避免“已经发出但数据库说没发”造成重复动作。

08 安全模型：可信 Gateway，不可信执行

OpenClaw 的安全边界可以归纳为四层：

  1. Gateway 认证和 origin 校验，防止任意客户端调用控制协议。
  2. Plugin/Channel/Node 的身份和 capability，防止接入能力越权。
  3. Tool policy 和 sandbox，限制模型可见的文件、命令、网络和设备。
  4. Memory scope 和日志脱敏，防止长期状态跨用户泄露。

“本地运行”不等于安全。Gateway 进程一旦能读凭证、执行 shell 或加载第三方插件，就已经是高权限程序。生产部署应使用最小权限、独立工作区、可回滚配置和可审计插件清单。

09 适用场景与边界

OpenClaw 适合需要多渠道接入、设备协同、长期会话和本地控制的个人或团队。它不适合只想在 CI 里跑一次函数调用的场景，也不适合未经隔离就接收不可信用户输入的多租户服务。

源码阅读建议从 Gateway server 和 method table 开始，再读 agent command、tool policy、plugin runtime、channel contract，最后读 memory-core 与 active-memory。这样能先理解控制面，再理解数据面。

10 最后的判断

OpenClaw 的核心贡献不是给 Agent 加了一个记忆文件，而是把 Agent 置于一个可连接、可治理、可恢复的控制面中。它把“聊天”升级成“持续运行的工作系统”，代价是协议、权限、插件供应链和状态一致性都必须认真设计。

如果只想复制它的功能，容易得到一堆渠道适配器；如果复制它的架构，应该先复制 Gateway、session identity、动态工具集和 durable event 这四条主线。

参考资料