Gateway 协议（WebSocket）

Gateway WS 协议是 OpenClaw 的统一控制平面 + Node 传输层。所有客户端（CLI、Web UI、macOS 应用、iOS/Android Node、无头 Node）都通过 WebSocket 连接，并在握手时声明自己的 role（角色）和 scope（权限范围）。

传输层

WebSocket，文本帧，JSON 格式的数据。
第一帧必须是 connect 请求。

握手（connect）

Gateway → 客户端（连接前挑战）：

{
  "type": "event",
  "event": "connect.challenge",
  "payload": { "nonce": "…", "ts": 1737264000000 }
}

客户端 → Gateway：

{
  "type": "req",
  "id": "…",
  "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"],
    "caps": [],
    "commands": [],
    "permissions": {},
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-cli/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

Gateway → 客户端：

{
  "type": "res",
  "id": "…",
  "ok": true,
  "payload": { "type": "hello-ok", "protocol": 3, "policy": { "tickIntervalMs": 15000 } }
}

当设备 Token 被签发时，hello-ok 还会包含：

{
  "auth": {
    "deviceToken": "…",
    "role": "operator",
    "scopes": ["operator.read", "operator.write"]
  }
}

Node 示例

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 3,
    "maxProtocol": 3,
    "client": {
      "id": "ios-node",
      "version": "1.2.3",
      "platform": "ios",
      "mode": "node"
    },
    "role": "node",
    "scopes": [],
    "caps": ["camera", "canvas", "screen", "location", "voice"],
    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],
    "permissions": { "camera.capture": true, "screen.record": false },
    "auth": { "token": "…" },
    "locale": "en-US",
    "userAgent": "openclaw-ios/1.2.3",
    "device": {
      "id": "device_fingerprint",
      "publicKey": "…",
      "signature": "…",
      "signedAt": 1737264000000,
      "nonce": "…"
    }
  }
}

帧格式

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

有副作用的方法需要幂等键（详见 schema）。

角色和权限范围

角色

operator = 控制平面客户端（CLI/UI/自动化）。
node = 能力宿主（摄像头/屏幕/画布/system.run）。

权限范围（operator）

常见的权限范围：

operator.read
operator.write
operator.admin
operator.approvals
operator.pairing

能力/命令/权限（node）

Node 在连接时声明能力声明：

caps：高级能力类别。
commands：可调用的命令白名单。
permissions：细粒度开关（例如 screen.record、camera.capture）。

Gateway 将这些视为声明，并在服务端强制执行白名单。

在线状态

system-presence 返回按设备身份键控的条目。
在线状态条目包含 deviceId、roles 和 scopes，这样 UI 可以为每个设备显示单行，即使它同时以 operator 和 node 身份连接。

Node 辅助方法

Node 可以调用 skills.bins 来获取当前的 Skill 可执行文件列表，用于自动允许检查。

执行审批

当执行请求需要审批时，Gateway 会广播 exec.approval.requested。
Operator 客户端通过调用 exec.approval.resolve 来解决（需要 operator.approvals 权限范围）。

版本管理

PROTOCOL_VERSION 定义在 src/gateway/protocol/schema.ts 中。
客户端发送 minProtocol + maxProtocol；服务器会拒绝不匹配的版本。
Schema 和模型从 TypeBox 定义生成：
- pnpm protocol:gen
- pnpm protocol:gen:swift
- pnpm protocol:check

认证

如果设置了 OPENCLAW_GATEWAY_TOKEN（或 --token），connect.params.auth.token 必须匹配，否则连接会被关闭。
Pairing 后，Gateway 会签发一个设备 Token，其权限范围限定为连接的角色和权限。它会在 hello-ok.auth.deviceToken 中返回，客户端应该保存它以便后续连接使用。
设备 Token 可以通过 device.token.rotate 和 device.token.revoke 进行轮换/撤销（需要 operator.pairing 权限范围）。

设备身份和配对

Node 应该包含一个稳定的设备身份（device.id），从密钥对指纹派生。
Gateway 为每个设备 + 角色签发 Token。
除非启用了本地自动审批，否则新设备 ID 需要配对审批。
本地连接包括回环地址和 Gateway 主机自己的 tailnet 地址（这样同主机的 tailnet 绑定仍然可以自动审批）。
所有 WS 客户端在 connect 时都必须包含 device 身份（operator + node）。控制 UI 仅在启用 gateway.controlUi.allowInsecureAuth 时可以省略它（或使用 gateway.controlUi.dangerouslyDisableDeviceAuth 进行紧急访问）。
非本地连接必须签名服务器提供的 connect.challenge nonce。

TLS 和证书固定

WS 连接支持 TLS。
客户端可以选择固定 Gateway 证书指纹（参见 gateway.tls 配置，以及 gateway.remote.tlsFingerprint 或 CLI 的 --tls-fingerprint）。

协议范围

这个协议暴露了完整的 Gateway API（状态、Channel、模型、聊天、Agent、Session、Node、审批等）。具体的接口由 src/gateway/protocol/schema.ts 中的 TypeBox schema 定义。