Gateway 协议

Gateway 协议 (WebSocket)

Gateway WS 协议是 OpenClaw 的 单一控制平面 + 节点传输。所有客户端 (CLI, Web UI, macOS 应用, iOS/Android 节点, 无头节点) 都通过 WebSocket 连接并在握手时声明其角色 + 范围。

传输

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 } }
}

当颁发设备令牌时，hello-ok 还包括：

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

节点示例

{
  "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?}

有副作用的方法需要 幂等键 (见架构)。

角色 + 范围

角色

operator = 控制平面客户端 (CLI/UI/自动化)。
node = 能力主机 (相机/屏幕/canvas/system.run)。

范围 (操作员)

常见范围：

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

能力/命令/权限 (节点)

节点在连接时声明能力主张：

caps: 高级能力类别。
commands: 调用的命令允许列表。
permissions: 细粒度切换 (例如 screen.record, camera.capture)。

Gateway 将这些视为主张并强制执行服务器端允许列表。

在场 (Presence)

system-presence 返回以设备身份为键的条目。
在场条目包括 deviceId, roles, 和 scopes，以便 UI 可以在设备同时作为 操作员 和节点连接时显示单行。

节点辅助方法

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

执行批准

当执行请求需要批准时，Gateway 广播 exec.approval.requested。
操作员客户端通过调用 exec.approval.resolve 解决 (需要 operator.approvals 范围)。

版本控制

PROTOCOL_VERSION 位于 src/gateway/protocol/schema.ts。
客户端发送 minProtocol + maxProtocol；服务器拒绝不匹配。
架构 + 模型从 TypeBox 定义生成：
- pnpm protocol:gen
- pnpm protocol:gen:swift
- pnpm protocol:check

认证

如果设置了 OPENCLAW_GATEWAY_TOKEN (或 --token)，connect.params.auth.token 必须匹配，否则套接字关闭。
配对后，Gateway 颁发作用于连接角色 + 范围的 设备令牌。它在 hello-ok.auth.deviceToken 中返回，并且应该由客户端持久化以供将来连接使用。
设备令牌可以通过 device.token.rotate 和 device.token.revoke 轮换/撤销 (需要 operator.pairing 范围)。

设备身份 + 配对

节点应包含从密钥对指纹派生的稳定设备身份 (device.id)。
Gateway 每个设备 + 角色颁发令牌。
除非启用了本地自动批准，否则新设备 ID 需要配对批准。
本地连接包括回环和 Gateway 主机自己的 tailnet 地址 (因此同一主机 tailnet 绑定仍然可以自动批准)。
所有 WS 客户端必须在 connect 期间包含 device 身份 (操作员 + 节点)。控制 UI 仅在启用 gateway.controlUi.allowInsecureAuth (或 gateway.controlUi.dangerouslyDisableDeviceAuth 用于紧急使用) 时可以省略它。
非本地连接必须签署服务器提供的 connect.challenge 随机数。

TLS + Pinning

WS 连接支持 TLS。
客户端可以选择固定 Gateway 证书指纹 (见 gateway.tls 配置加上 gateway.remote.tlsFingerprint 或 CLI --tls-fingerprint)。

范围

此协议暴露了 完整的 Gateway API (状态、频道、模型、聊天、代理、会话、节点、批准等)。确切的表面由 src/gateway/protocol/schema.ts 中的 TypeBox 架构定义。