网关协议（WebSocket）

网关 WS 协议是 OpenClaw 的统一控制面和节点传输层。所有客户端（CLI、Web UI、macOS 应用、iOS/Android 节点、无界面节点）都通过 WebSocket 连接，并在握手时声明自己的角色和作用域。

传输

  • WebSocket，文本帧，JSON 载荷。
  • 第一帧必须是 connect 请求。

握手（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 } }
}

当签发设备 token 时，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?}

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

角色与作用域

角色

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

作用域（operator）

常见作用域：

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

方法级作用域只是第一道门。某些通过 chat.send 触达的斜杠命令会在此基础上施加更严格的命令级检查。例如，持久化的 /config set 和 /config unset 写操作需要 operator.admin 作用域。

能力/命令/权限（node）

节点在连接时声明能力：

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

网关将这些视为声明，并在服务端执行白名单校验。

在线状态

  • system-presence 返回按设备身份索引的条目。
  • 在线条目包含 deviceId、roles 和 scopes，UI 可以在同一设备同时作为 operator 和 node 连接时仍然只显示一行。

节点辅助方法

  • 节点可调用 skills.bins 获取当前 skill 可执行文件列表，用于自动允许检查。

操作员辅助方法

  • 操作员可调用 tools.catalog（需 operator.read）获取某个 agent 的运行时工具目录。响应包含分组工具和来源元数据：
    • source：core 或 plugin
    • pluginId：当 source="plugin" 时的插件所有者
    • optional：该插件工具是否可选

执行审批

  • 当执行请求需要审批时，网关广播 exec.approval.requested。
  • 操作员客户端通过调用 exec.approval.resolve 处理（需 operator.approvals 作用域）。
  • 当 host=node 时，exec.approval.request 必须包含 systemRunPlan（规范化的 argv/cwd/rawCommand/会话元数据）。缺少 systemRunPlan 的请求会被拒绝。

版本管理

  • 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 必须匹配，否则连接被关闭。
  • 配对后，网关签发一个设备 token，与连接角色和作用域绑定。它在 hello-ok.auth.deviceToken 中返回，客户端应持久化保存用于后续连接。
  • 设备 token 可通过 device.token.rotate 和 device.token.revoke 轮换/撤销（需 operator.pairing 作用域）。
  • 认证失败包含 error.details.code 和恢复提示：
    • error.details.canRetryWithDeviceToken（布尔值）
    • error.details.recommendedNextStep（retry_with_device_token、update_auth_configuration、update_auth_credentials、wait_then_retry、review_auth_configuration）
  • AUTH_TOKEN_MISMATCH 的客户端行为：
    • 可信客户端可以尝试一次有限重试，使用缓存的设备 token。
    • 重试仍失败时，客户端应停止自动重连循环，引导操作员介入。

设备身份与配对

  • 节点应包含稳定的设备身份（device.id），由密钥对指纹派生。
  • 网关按设备+角色签发 token。
  • 新设备 ID 需要配对审批，除非启用了本地自动批准。
  • 本地连接包括回环地址和网关主机自身的 tailnet 地址（所以同主机 tailnet 绑定也能自动批准）。
  • 所有 WS 客户端在 connect 时必须包含 device 身份（operator 和 node 都是）。控制 UI 仅在以下模式下可以省略：
    • gateway.controlUi.allowInsecureAuth=true，用于本地不安全 HTTP 兼容。
    • gateway.controlUi.dangerouslyDisableDeviceAuth=true（紧急开关，严重降低安全性）。
  • 所有连接必须对服务端提供的 connect.challenge nonce 进行签名。

设备认证迁移诊断

对于仍使用旧版签名行为的客户端，connect 现在在 error.details.code 中返回 DEVICE_AUTH_* 详细码，并带有稳定的 error.details.reason。

常见的迁移失败场景：

消息details.codedetails.reason含义
device nonce requiredDEVICE_AUTH_NONCE_REQUIREDdevice-nonce-missing客户端未发送 device.nonce（或发了空值）。
device nonce mismatchDEVICE_AUTH_NONCE_MISMATCHdevice-nonce-mismatch客户端签名使用了过时/错误的 nonce。
device signature invalidDEVICE_AUTH_SIGNATURE_INVALIDdevice-signature签名载荷与 v2 载荷不匹配。
device signature expiredDEVICE_AUTH_SIGNATURE_EXPIREDdevice-signature-stale签名时间戳超出允许偏差范围。
device identity mismatchDEVICE_AUTH_DEVICE_ID_MISMATCHdevice-id-mismatchdevice.id 与公钥指纹不匹配。
device public key invalidDEVICE_AUTH_PUBLIC_KEY_INVALIDdevice-public-key公钥格式/规范化失败。

迁移目标：

  • 始终等待 connect.challenge。
  • 签名包含服务端 nonce 的 v2 载荷。
  • 在 connect.params.device.nonce 中发送同一个 challenge nonce。
  • 推荐使用 v3 签名载荷，它在 device/client/role/scopes/token/nonce 字段之外还绑定了 platform 和 deviceFamily。
  • 旧版 v2 签名仍然兼容，但已配对设备的元数据固定仍控制重连时的命令策略。

TLS 与证书固定

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

覆盖范围

本协议暴露完整的网关 API（状态、通道、模型、聊天、agent、会话、节点、审批等）。具体接口由 src/gateway/protocol/schema.ts 中的 TypeBox schema 定义。

arrow_back
上一页
Sandbox Vs Tool Policy Vs Elevated
下一页
Bridge Protocol
arrow_forward