OpenClaw WebSocket 网关协议

OpenClaw 中的 WebSocket 是其核心通信机制，主要体现在 Gateway（网关）组件上。OpenClaw 是一个开源的个人 AI 助手框架，支持本地运行的 AI Agent，通过 WebSocket 实现多客户端的实时、双向通信。

1. Gateway WebSocket 的作用

单一控制平面（Single Control Plane）
：所有客户端（CLI、Web UI、macOS App、iOS/Android 节点、headless 节点等）都通过 WebSocket 连接到 Gateway，实现控制、事件分发和节点通信。
默认端口
：通常是 18789（ws://127.0.0.1:18789），默认绑定到 localhost（回环地址）以提升安全性。
传输方式
：

使用 文本帧 + JSON 负载。
连接建立后，第一个帧必须是 connect 请求（握手），声明角色（role）和作用域（scope）。
协议基于 JSON-RPC 风格：消息类型包括 "req"（请求）、"res"（响应）、"event"（事件）。

2. 连接流程（Gateway Protocol）

客户端发起 WebSocket 连接。
服务端可能返回 connect.challenge（含 nonce）。
客户端发送 connect 请求，包含认证信息（token、device ID、public key 等）、minProtocol、version、mode、scopes 等参数。
握手成功后，建立长连接，支持实时双向通信（如 Agent 流式响应、工具调用、事件推送）。

示例 connect 请求大致结构（简化）：

JSON

{
  "type": "req",
  "id": "connect-xxx",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "auth": { ... },
    "device": { "id": "...", ... },
    "scopes": ["operator.admin", ...],
    "role": "..."
  }
}

所有后续通信都在这个持久连接上进行，支持服务器主动推送，适合 AI Agent 的流式推理和多端同步。

3. 为什么使用 WebSocket？

相比 HTTP 轮询：支持服务器主动推送、低延迟、持久连接，完美匹配 Agent 的实时交互（流式输出、工具调用、多客户端同步）。
统一所有通信：CLI、WebChat、移动节点、插件等都走同一个 Gateway WS，无需额外端口。

4. 安全与已知问题

OpenClaw 的 WebSocket 曾曝出多个安全问题（尤其是早期版本），常见包括：

Origin 验证不足
：浏览器允许跨域 WS 连接到 localhost，恶意网站可能通过 JS 打开 ws://127.0.0.1:18789 并尝试劫持（ClawJacked 等漏洞）。
认证/授权绕过
：共享 token 或密码认证时，客户端声明的 scopes 可能未被严格服务器端绑定，导致权限提升（scope elevation）。
握手前日志投毒
、无认证升级、reconnect 导致会话中断等。
修复建议
：及时更新到最新版本（2026.3.x 系列已修复多处），避免将 Gateway 暴露到公网，启用 TLS + certificate pinning，严格配置 Origin 检查和 scope 绑定。

官方文档推荐仅限本地访问，并结合设备配对、token 轮换等机制加强安全。

5. 开发/使用相关

CLI 操作
：openclaw gateway 子命令可查询、管理 Gateway（如 discover、status），所有查询都走 WebSocket RPC。
Web UI
：WebChat 直接使用 Gateway WS，无独立端口。
插件/扩展
：支持通过 WS 接入自定义 channel（如 openclaw-websocket 插件）。
源码位置
：GitHub openclaw/openclaw 中，核心在 src/gateway/server/（ws-connection.ts 等）。

更多细节可参考官方文档：

https://docs.openclaw.ai/gateway/protocol （Gateway Protocol）
https://docs.openclaw.ai/gateway （Gateway 整体）

如果你是想实现自定义客户端连接、调试协议、修复 reconnect 问题，还是关注具体的安全补丁/配置，告诉我更多细节，我可以进一步说明！