OpenClaw 如何用 WebSocket 管理多端控制平面

核验范围： 本文以 2026 年 7 月查阅的官方文档为准，Gateway protocol 当时为第 3 版。协议字段、命名空间与能力分级会随版本变化；本文区分 OpenClaw 的现有实现和一般的架构设计经验。

OpenClaw 的 Gateway 是多端交互的协调层。CLI、WebChat、手机节点和消息通道不各自维护一套会话状态，而是连接到 Gateway，由它处理连接、路由、会话与事件分发。理解这一层，才能解释同一个任务为什么可以在不同入口继续查看、暂停或接管。

初学者阅读地图

先记住的对象 它解决的问题
Gateway 统一连接、会话与事件的协调入口
控制平面 决定谁连接、状态在哪里、事件发给谁
数据平面 实际运行模型、工具和多媒体传输
Node 连接到 Gateway 并声明自身能力的设备或执行端

阅读时先看第一、二节建立控制平面与 WebSocket 的概念，再看协议、Node 和两个流程图，最后再看统一入口带来的安全边界。

一、先把概念摆正：控制平面是什么

分布式系统里有个经典划分：控制平面 / 数据平面。放到 AI 交互里同样关键。

  • 控制平面（Control Plane） 负责「指挥与协调」：会话与状态管理（谁在发言、哪个任务在跑、跑到第几步）、路由与调度（这条消息发给哪个节点、工具调用落到哪台设备）、权限与策略（哪些端能读写、谁能触发浏览器自动化）、事件分发（流式输出、执行进度、typing 状态、通知）。
  • 数据平面（Data Plane） 负责「干活」：模型推理与流式生成、工具执行（文件、命令、浏览器）、多媒体传输（截图、录音、图片）。

把两者分开有个直接好处：Gateway 只做调度与一致性，不承担计算与执行。 它是一个真正的「中枢神经系统」，而不是又一个塞满业务逻辑的巨无霸服务。这个「职责只做一件事」的克制，和第一篇讲 lane 队列时那个「约束做进结构」的思路是一脉相承的。

二、OpenClaw 为什么选择 WebSocket

WebSocket 不是控制平面的唯一实现方式，但它适合 OpenClaw 这类需要多端协作、流式输出、任务进度和异步事件的场景。相比把实时同步拆成轮询和额外推送通道，长连接能把双向事件放在同一条连接里处理。

WebSocket 恰好匹配控制平面需要的三件事：

  1. 全双工。 AI 交互不是一问一答，更像协作：模型在持续吐 token、工具在持续汇报进度、用户随时插话、节点随时上报状态。全双工让「事件」成为一等公民。
  2. 低延迟 + 长连接。 流式输出、实时同步、typing indicator、任务状态更新，都需要持续连接和快速推送。
  3. 跨平台一致。 CLI、浏览器、移动端、桌面端几乎都能稳定地做 WebSocket 客户端，不用为每个平台重造通信栈。

OpenClaw 的做法就是让所有节点统一连到一个 Gateway，本地模式下是 ws://127.0.0.1:18789。从这一步起，系统形态就变了：不是「每个端直连各自后端」，而是「所有端接入同一个控制平面」。

三、Gateway 作为「唯一事实源」

拓扑上，它不是网状互连，而是典型的 Hub & Spoke（星形）：

关键不在「都能连上」，而在 Gateway 成了唯一事实源：会话状态在它这里收敛，任务进度在它这里编排，事件在它这里广播或定向分发。客户端因此越做越薄，只负责输入与渲染，不各自维护复杂状态机。

由此得到一个很工程化的收益——扩展新入口 ≠ 重写 Agent 逻辑。新接一个 Telegram bot，本质是多了一个「节点」，而不是多了一套「系统」。

从职责上，Gateway 可以拆成三块：

  • 连接中枢（Connection Manager）：客户端注册与认证、心跳检测、断线重连、会话生命周期管理。做过移动端的人都懂：网络切换、后台挂起、代理变化，会让连接状态充满「脏边界」，没有一个统一的连接层，状态漂移是必然的。
  • 消息路由（Message Router）：不只是转发，而是聪明分发——请求分发与响应回传、单播 / 多播 / 广播、优先级队列（中断、取消要比普通消息优先）。
  • 状态协调器（State Coordinator）：真正决定「多端是否一致」的部分——全局状态同步、事件驱动传播、冲突解决（两端同时操作怎么办）。它不执行工具，但它知道谁在执行、执行到哪、结果该广播给谁。

四、协议层：JSON-RPC 2.0 + 命名空间

多端统一，协议必须足够规整。OpenClaw 用的是 JSON-RPC 2.0。一次调用大致长这样：

1
2
3
4
5
{
  "jsonrpc": "2.0",
  "method": "chat.sendMessage",
  "params": { "peer": "tg:12345", "text": "Hello" }
}

能力按命名空间分组，大致是 chat.*（消息、会话、typing）、agent.*（编排、任务启停、工具触发）、node.*（节点注册、能力上报、心跳）、browser.*（自动化控制、DOM / 截图回传）、system.* / debug.*（系统能力与诊断）。这类协议的价值在于它不是「拼凑的事件名」，而是一套可演进的 API 面：加新端、新能力，靠扩展 method 就能自然生长。

这里补几个原文没有、但对判断成熟度很重要的官方现状（截至 2026 年 7 月）：

  • Gateway 协议当前是第 3 版（PROTOCOL_VERSION = 3），全部通信是 WebSocket 文本帧 + JSON。
  • 三种帧（客户端发起的 RPC、服务端响应、服务端主动广播）统一在一个叫 GatewayFrame 的判别联合（discriminated union）类型下。
  • 连接的第一帧必须是 connect 请求，握手时服务端会下发一个带 nonce 的 connect.challenge 事件，客户端必须签名这个 nonce 才能建立连接。预连接帧上限 64 KiB。

也就是说，原文把它描述成一套「规整、可演进的协议」并不夸张——官方实现确实带版本号、带握手挑战、帧类型有明确的类型定义。

五、节点接入：设备不是「客户端」，而是「Node」

OpenClaw 一个重要抽象是：每个设备 / 入口都是一个节点（Node）。节点接入时不只是连接，还要声明能力（capabilities）。

比如 iOS 节点声明 ["camera", "location", "notification"]，CLI 节点声明 ["exec", "file_read"]。Gateway 据此维护一张「能力感知路由表」：当 Agent 需要「定位」或「拍照」，它不会盲目广播给所有端，而是路由到具备对应能力的节点。这比「写死某个平台负责某件事」更灵活，也更贴合多设备协作的现实。

配对这块，官方实现比原文更严谨，值得单独说清楚（这也是安全的第一道关）：

  • 所有 WS 客户端（操作者和节点）连接时都要带一个设备身份。
  • 新设备 ID 需要配对审批；通过后 Gateway 发一个 device token，之后再连就用这个 token。
  • 节点连接要带 role: "node"，并在 connect 里附上 caps / commands / permissions。
  • 能力（更准确地说是「探针能证明的权限级别」）分五级：read-only、write-capable、admin-capable、pairing-pending、connect-only。

换句话说，一个设备能做什么，不是它自己说了算，而是在配对和能力协商时就被 Gateway 框定了。

六、多端一致性：多端只是「不同的显示器」

前面都是结构，用两个流程看它跑起来是什么样。

案例一：CLI 发起任务，多端同步。

最关键的一句：状态不在客户端拼凑，而在 Gateway 统一生产与分发。 多端只是「不同的显示器」看同一份状态。

案例二：WebChat 下发浏览器自动化。 用户在 WebChat 说「帮我登录并截图订单页」，Gateway 判断需要 browser.* 能力，调度 Browser Node，Playwright 执行时持续上报步骤和截图，Gateway 再把截图 / 进度推给所有相关端——手机端也能看到同一张截图、同一个进度条，必要时还能发「停止」。

这里藏着一个第一篇没提、但很能体现控制平面价值的点：人类操作和 Agent 操作可以共存于同一 Session。 用户在网页上手动点了一下、Agent 接着接管；或者 Agent 正在跑流程、用户从手机端发来「暂停」。这些协作都需要一个统一的状态协调器，否则你很快会陷入「到底谁在控制」的混乱。控制平面把「任务执行」变成了一个可观测、可中断、可协作的流程，而不是某个端里黑盒跑完再回一句「好了」。

七、统一的代价：一个入口，也是一个靶心

原文的收尾很激昂：下一代 AI 系统拼的不是模型，是「中枢神经系统」；模型能力正在趋同，真正拉开差距的是架构抽象。这个判断我认同。把 Session 当一等公民、把控制平面从各端抽出来，用一个 WebSocket Gateway 统一所有交互——CLI、WebChat、移动端、浏览器自动化、消息通道，从此不是「多个产品」，而是同一个系统伸出的不同触角。

但作为系列的第三篇，我想给这个「统一」补上它的另一面，也正好接回第一篇。

统一入口的力量，来自它是唯一事实源；而它的代价，恰恰也来自「唯一」——它同时成了整个系统的唯一靶心。 这不是抽象的担忧。第一篇引用的那篇 arXiv 安全分析里，470 条 advisory 按接口统计，排第一的就是 Gateway WebSocket 接口，121 条，占 25.7%，其中 7 条 Critical、47 条 High。第一篇讲的那条完整未授权 RCE 链，第一步就是打 Gateway 的 gatewayUrl（SSRF），偷 token，再通过 node.invoke 改写策略。

这两件事是同一枚硬币：你把所有交互收敛到一个点，这个点就既是控制力的来源，也是风险的汇聚。 所以第五节讲的那套配对握手、device token、能力五分级，不是可选的装饰，而是这个架构能不能安全成立的地基。控制平面越强，它的鉴权和治理就越不能是「行为引导」，必须是结构性的强制——这正是本系列反复撞见的同一条线。

所以三篇连起来看，OpenClaw 给的启示是完整的一体两面：把能力统一到控制平面，是把复杂度做进了结构，这是它最聪明的地方；而正因为一切都汇于此，这个中枢的鉴权、可观测、可治理，就必须做到同样的结构强度——这也是它最脆弱、最不容出错的地方。 统一带来整体性，整体性要求可治理，可治理不能靠自觉。

我的理解与核验

我在整理这一篇时，把“Gateway 负责什么”和“Node 实际执行什么”分开看。前者解决连接、状态与路由，后者提供具体能力；把两层混在一起，最容易误以为 Gateway 自己执行所有动作。阅读或部署时，我会优先检查握手、配对、设备 token 与能力声明，再讨论多端体验。

文中协议版本、端口和能力名称都是版本相关信息，适合用来理解结构，不应直接替代当前版本的配置检查。

小结

这一篇把前两篇的背景板 Gateway 翻过来看了一遍：控制平面 / 数据平面的分工、WebSocket 的选型理由、Gateway 的三块职责、JSON-RPC 协议与命名空间、Node 的能力声明与配对、以及多端共享同一 Session 的一致性。核心就一句话——把控制平面从各端抽出来，让入口只是「不同的显示器」。

如果你在自己做多端 AI 产品，这套抽象值得抄：先分清控制与数据，再让一个中枢收敛状态，别让每个入口各自维护状态机。但抄的时候记得连它的代价一起抄——唯一事实源必然是唯一靶心，中枢的鉴权和治理要和它的控制力一样强。

下一篇《OpenClaw 系统提示词深度解析：上下文拼装与 Token 成本》会从架构转向成本，解释每轮请求为什么会包含远多于用户消息的上下文。

参考资料