​

Gateway 協議（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 } }
}

{
  "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 = 能力主機（攝影機/螢幕/畫布/system.run）。

​

範圍（operator）

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

​

能力/指令/權限（node）

• caps：高級能力類別。
• commands：用於 invoke 的指令允許清單。
• permissions：細粒度切換（例如 screen.record、camera.capture）。

​

存在

• system-presence 回傳由設備身分索引的項目。
• 存在項目包括 deviceId、roles 和 scopes，讓 UI 可顯示每個設備一行，即使它同時連接為 operator 和 node。

​

節點協助方法

• 節點可呼叫 skills.bins 以取得目前技能可執行檔清單進行自動允許檢查。

​

Operator 協助方法

• Operator 可呼叫 tools.catalog（operator.read）以取得代理的執行時工具目錄。回應包括已分組工具和出處中繼資料：
  • source：core 或 plugin
  • pluginId：當 source="plugin" 時的外掛所有者
  • optional：外掛工具是否可選

​

執行批准

• 當執行請求需要批准時，Gateway 廣播 exec.approval.requested。
• Operator 客戶端透過呼叫 exec.approval.resolve 解析（需要 operator.approvals 範圍）。
• 對於 host=node，exec.approval.request 必須包括 systemRunPlan（正規 argv/cwd/rawCommand/會話中繼資料）。遺失 systemRunPlan 的請求被拒絕。

​

版本控制

• 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 必須符合或 socket 關閉。
• 配對後，Gateway 發出針對連接角色 + 範圍的 設備權杖。它在 hello-ok.auth.deviceToken 中回傳，應由客戶端持久化以供未來連接。
• 設備權杖可透過 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：
  • 受信任客戶端可嘗試一次有界重試與快取逐設備權杖。
  • 如果該重試失敗，客戶端應停止自動重新連接迴圈並表面 operator 動作指導。

​

設備身分 + 配對

• 節點應包括穩定設備身分（device.id）衍生自金鑰對指紋。
• Gateway 發出各設備 + 角色的權杖。
• 新設備 ID 需要配對批准，除非啟用本地自動批准。
• 本地 連接包括環回和 Gateway 主機自身的 tailnet 地址（所以相同主機 tailnet 繫結仍可自動批准）。
• 所有 WS 客戶端必須在 connect 期間包括 device 身分（operator + node）。 Control UI 只能在這些模式中省略它：
  • gateway.controlUi.allowInsecureAuth=true 用於 localhost 唯一不安全 HTTP 相容性。
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true（破裂玻璃，嚴重安全降級）。
• 所有連接必須簽署伺服器提供的 connect.challenge nonce。

​

設備驗證遷移診斷

• 一律等待 connect.challenge。
• 簽署包括伺服器 nonce 的 v2 負載。
• 在 connect.params.device.nonce 中發送相同 nonce。
• 偏好簽署負載是 v3，它除了設備/客戶端/角色/範圍/權杖/nonce 欄位外還繫結 platform 和 deviceFamily。
• 遺留 v2 簽署保持相容接受，但配對設備中繼資料釘選仍控制重新連接時的指令政策。

​

TLS + 釘選

• TLS 對 WS 連接支援。
• 客戶端可選用釘選 Gateway 憑證指紋（見 gateway.tls 設定加上 gateway.remote.tlsFingerprint 或 CLI --tls-fingerprint）。

​

範圍