网关协议(WebSocket)

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

传输

• WebSocket,带有 JSON 负载的文本帧。
• 第一帧必须是 connect 请求。

握手(连接)

网关 → 客户端(预连接挑战):

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

客户端 → 网关:

{
  "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": "…"
    }
  }
}

网关 → 客户端:

{
  "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 = 能力宿主(摄像头/screen/canvas/system.run)。

作用域(操作者)

常见作用域:

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

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

节点在连接时声明能力声明:

• caps:高级能力类别。
• commands:调用的命令白名单。
• permissions:细粒度开关(例如 screen.record, camera.capture)。

网关将这些视为声明并强制执行服务器端白名单。

在线状态

• system-presence 返回以设备身份为键的条目。
• 在线状态条目包括 deviceId、roles 和 scopes,因此 UI 可以为每个设备显示单行,即使它同时作为操作者和节点连接。

节点辅助方法

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

执行审批

• 当执行请求需要审批时,网关会广播 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 必须匹配,否则套接字将被关闭。
• 配对后,网关会签发一个设备令牌,其作用域限定于连接角色 + 作用域。它在 hello-ok.auth.deviceToken 中返回,客户端应持久化以用于将来的连接。
• 设备令牌可以通过 device.token.rotate 和 device.token.revoke 进行轮换/撤销(需要 operator.pairing 作用域)。

设备身份 + 配对

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

TLS + 固定

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

范围

此协议公开完整的网关 API(状态、频道、模型、聊天、代理、会话、节点、审批等)。确切的接口由 src/gateway/protocol/schema.ts 中的 TypeBox 模式定义。