Gateway 通訊協定

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

傳輸

• WebSocket，文字訊框搭配 JSON 承載。
• 第一個訊框必須是 connect 請求。
• 連線前訊框上限為 64 KiB。握手成功後，用戶端應遵循 hello-ok.policy.maxPayload 和 hello-ok.policy.maxBufferedBytes 限制。啟用診斷時，過大的入站訊框與緩慢的出站緩衝區會在 gateway 關閉或捨棄受影響訊框前發出 payload.large 事件。這些事件會保留大小、限制、介面與安全原因代碼。不會保留訊息本文、附件內容、原始訊框本文、權杖、Cookie 或祕密值。

​

握手（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,
    "server": { "version": "…", "connId": "…" },
    "features": { "methods": ["…"], "events": ["…"] },
    "snapshot": { "…": "…" },
    "auth": {
      "role": "operator",
      "scopes": ["operator.read", "operator.write"]
    },
    "policy": {
      "maxPayload": 26214400,
      "maxBufferedBytes": 52428800,
      "tickIntervalMs": 15000
    }
  }
}

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

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

{
  "auth": {
    "deviceToken": "…",
    "role": "node",
    "scopes": [],
    "deviceTokens": [
      {
        "deviceToken": "…",
        "role": "operator",
        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "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?}

​

角色 + 範圍

​

角色

• operator = 控制平面用戶端（CLI/UI/自動化）。
• node = 能力主機（camera/screen/canvas/system.run）。

​

範圍（操作員）

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

• 不含指令的請求：operator.pairing
• 帶有非 exec 節點指令的請求：operator.pairing + operator.write
• 包含 system.run、system.run.prepare 或 system.which 的請求：operator.pairing + operator.admin

​

能力/指令/權限（節點）

• caps：高階能力類別。
• commands：供呼叫使用的指令允許清單。
• permissions：細粒度開關（例如 screen.record、camera.capture）。

​

在線狀態

• system-presence 會傳回以裝置身分為鍵的項目。
• 在線狀態項目包含 deviceId、roles 和 scopes，因此即使同一裝置同時以操作員和節點身分連線，介面也能為每個裝置顯示單一列。
• node.list 包含選用的 lastSeenAtMs 和 lastSeenReason 欄位。已連線節點會將目前連線時間回報為 lastSeenAtMs，原因為 connect；配對節點也可以在受信任的節點事件更新其配對中繼資料時，回報持久背景在線狀態。

​

Node 背景存活事件

{
  "event": "node.presence.alive",
  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"
}

{
  "ok": true,
  "event": "node.presence.alive",
  "handled": true,
  "reason": "persisted"
}

​

廣播事件範圍控管

• 聊天、代理與工具結果訊框（包括串流的 agent 事件與工具呼叫結果）至少需要 operator.read。沒有 operator.read 的工作階段會完全略過這些訊框。
• Plugin 定義的 plugin.* 廣播會依照該 Plugin 的註冊方式，受 operator.write 或 operator.admin 控管。
• 狀態與傳輸事件（heartbeat、presence、tick、連線/斷線生命週期等）維持不受限制，讓每個已驗證工作階段都能觀察傳輸健康狀態。
• 未知廣播事件族預設會受範圍控管（預設封閉），除非已註冊處理器明確放寬限制。

​

常見 RPC 方法族

​

常見事件系列

• chat：UI 聊天更新，例如 chat.inject 與其他僅逐字稿的聊天 事件。
• session.message 與 session.tool：已訂閱工作階段的逐字稿／事件串流更新。
• sessions.changed：工作階段索引或中繼資料已變更。
• presence：系統存在狀態快照更新。
• tick：週期性 keepalive／存活事件。
• health：Gateway 健全狀態快照更新。
• heartbeat：Heartbeat 事件串流更新。
• cron：Cron 執行／工作變更事件。
• shutdown：Gateway 關閉通知。
• node.pair.requested / node.pair.resolved：Node 配對生命週期。
• node.invoke.request：Node 叫用請求廣播。
• device.pair.requested / device.pair.resolved：配對裝置生命週期。
• voicewake.changed：喚醒詞觸發器設定已變更。
• exec.approval.requested / exec.approval.resolved：exec 核准 生命週期。
• plugin.approval.requested / plugin.approval.resolved：Plugin 核准 生命週期。

​

Node 輔助方法

• Node 可呼叫 skills.bins 來擷取目前的技能可執行檔清單，以進行自動允許檢查。

​

操作者輔助方法

• 操作者可以呼叫 commands.list（operator.read）來擷取代理程式的執行階段 命令清單。
  • agentId 為選填；省略即可讀取預設代理程式工作區。
  • scope 控制主要 name 目標所屬的介面：
    • text 會傳回不含開頭 / 的主要文字命令權杖
    • native 與預設的 both 路徑會在可用時傳回感知提供者的原生命令名稱
  • textAliases 帶有精確的斜線別名，例如 /model 和 /m。
  • nativeName 會在存在時帶有感知提供者的原生命令名稱。
  • provider 為選填，且只會影響原生命名以及原生 Plugin 命令可用性。
  • includeArgs=false 會從回應中省略序列化的引數中繼資料。
• 操作者可以呼叫 tools.catalog（operator.read）來擷取代理程式的執行階段工具目錄。回應包含分組工具與來源中繼資料：
  • source：core 或 plugin
  • pluginId：當 source="plugin" 時的 Plugin 擁有者
  • optional：Plugin 工具是否為選用
• 操作者可以呼叫 tools.effective（operator.read）來擷取工作階段中執行階段實際生效的工具清單。
  • sessionKey 為必填。
  • Gateway 會從伺服器端的工作階段推導受信任的執行階段脈絡，而不是接受 呼叫端提供的驗證或傳遞脈絡。
  • 回應以工作階段為範圍，並反映目前作用中的對話現在可以使用的內容， 包含核心、Plugin 與頻道工具。
• 操作者可以呼叫 skills.status（operator.read）來擷取代理程式可見的 Skills 清單。
  • agentId 為選填；省略即可讀取預設代理程式工作區。
  • 回應包含資格、缺少的需求、設定檢查，以及 已清理的安裝選項，且不會暴露原始秘密值。
• 操作者可以呼叫 skills.search 和 skills.detail（operator.read）取得 ClawHub 探索中繼資料。
• 操作者可以用兩種模式呼叫 skills.install（operator.admin）：
  • ClawHub 模式：{ source: "clawhub", slug, version?, force? } 會將 Skills 資料夾安裝到預設代理程式工作區的 skills/ 目錄。
  • Gateway 安裝程式模式：{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? } 會在 Gateway 主機上執行宣告的 metadata.openclaw.install 動作。
• 操作者可以用兩種模式呼叫 skills.update（operator.admin）：
  • ClawHub 模式會更新一個受追蹤的 slug，或更新預設代理程式工作區中所有受追蹤的 ClawHub 安裝項目。
  • 設定模式會修補 skills.entries.<skillKey> 值，例如 enabled、 apiKey 和 env。

​

models.list 檢視

• 省略或 "default"：目前的執行階段行為。如果已設定 agents.defaults.models，回應會是允許的目錄；否則回應會是完整的 Gateway 目錄。
• "configured"：適合選擇器大小的行為。如果已設定 agents.defaults.models，它仍會優先。否則回應會使用明確的 models.providers.*.models 項目，只有在沒有已設定的模型列時才會退回完整目錄。
• "all"：完整 Gateway 目錄，略過 agents.defaults.models。將此用於診斷與探索 UI，而非一般模型選擇器。

​

Exec 核准

• 當 exec 請求需要核准時，Gateway 會廣播 exec.approval.requested。
• 操作者用戶端透過呼叫 exec.approval.resolve 來解析（需要 operator.approvals 範圍）。
• 對於 host=node，exec.approval.request 必須包含 systemRunPlan（標準 argv/cwd/rawCommand/工作階段中繼資料）。缺少 systemRunPlan 的請求會被拒絕。
• 核准後，轉送的 node.invoke system.run 呼叫會重用該標準 systemRunPlan 作為具權威性的命令/cwd/工作階段脈絡。
• 如果呼叫端在準備和最終核准的 system.run 轉送之間變更 command、rawCommand、cwd、agentId 或 sessionKey，Gateway 會拒絕該執行，而不是信任已變更的承載。

​

代理程式傳遞後援

• agent 請求可以包含 deliver=true 以要求輸出傳遞。
• bestEffortDeliver=false 會維持嚴格行為：無法解析或僅供內部使用的傳遞目標會傳回 INVALID_REQUEST。
• bestEffortDeliver=true 允許在無法解析任何外部可傳遞路由時，後援為僅限工作階段的執行（例如內部/webchat 工作階段或不明確的多頻道設定）。

​

版本控管

• PROTOCOL_VERSION 位於 src/gateway/protocol/schema/protocol-schemas.ts。
• 用戶端傳送 minProtocol + maxProtocol；伺服器會拒絕不相符的版本。
• 結構描述與模型會從 TypeBox 定義產生：
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

用戶端常數

​

驗證

• 共用秘密 Gateway 驗證會使用 connect.params.auth.token 或 connect.params.auth.password，取決於已設定的驗證模式。
• 帶有身分的模式，例如 Tailscale Serve （gateway.auth.allowTailscale: true）或非 local loopback gateway.auth.mode: "trusted-proxy"，會從請求標頭而非 connect.params.auth.* 滿足連線驗證檢查。
• 私有入口 gateway.auth.mode: "none" 會完全略過共用秘密連線驗證； 請勿在公開/不受信任的入口暴露該模式。
• 配對後，Gateway 會發出一個範圍限定為連線角色 + 範圍的裝置權杖。 它會在 hello-ok.auth.deviceToken 中傳回，且用戶端應將其持久保存以供未來連線使用。
• 用戶端應在任何成功連線後持久保存主要的 hello-ok.auth.deviceToken。
• 使用該已儲存裝置權杖重新連線時，也應重用該權杖已儲存的 已核准範圍集合。這會保留先前已授權的讀取/探測/狀態存取權， 並避免在不明顯的情況下將重新連線縮減為較窄的隱含僅管理員範圍。
• 用戶端連線驗證組裝（src/gateway/client.ts 中的 selectConnectAuth）：
  • auth.password 是正交的，設定時一律會被轉送。
  • auth.token 依優先順序填入：明確的共用權杖優先， 接著是明確的 deviceToken，再來是已儲存的每裝置權杖（以 deviceId + role 為鍵）。
  • 只有在上述都未解析出 auth.token 時，才會傳送 auth.bootstrapToken。 共用權杖或任何已解析的裝置權杖都會抑制它。
  • 在一次性的 AUTH_TOKEN_MISMATCH 重試上，自動提升已儲存裝置權杖僅限於受信任端點： loopback，或具有釘選 tlsFingerprint 的 wss://。沒有釘選的公開 wss:// 不符合資格。
• 額外的 hello-ok.auth.deviceTokens 項目是啟動程序交接權杖。 只有在連線於受信任傳輸（例如 wss:// 或 loopback/local 配對）上使用啟動驗證時，才持久保存它們。
• 如果用戶端提供明確的 deviceToken 或明確的 scopes，該呼叫端要求的範圍集合仍具有權威性；只有在用戶端重用已儲存的每裝置權杖時，才會重用快取的範圍。
• 裝置權杖可透過 device.token.rotate 和 device.token.revoke 輪替/撤銷（需要 operator.pairing 範圍）。
• device.token.rotate 會傳回輪替中繼資料。它只會對已使用該裝置權杖完成驗證的同一裝置呼叫回傳替換的持有者權杖，因此僅權杖用戶端可在重新連線前持久保存替換項。共用/管理員輪替不會回傳持有者權杖。
• 權杖發行、輪替與撤銷仍會被限制在該裝置配對項目中記錄的已核准角色集合內；權杖變更不能擴大或瞄準配對核准從未授予的裝置角色。
• 對於已配對裝置權杖工作階段，除非呼叫端也擁有 operator.admin，否則裝置管理僅限自身範圍：非管理員呼叫端只能移除/撤銷/輪替自己的裝置項目。
• device.token.rotate 和 device.token.revoke 也會檢查目標操作者 權杖範圍集合是否符合呼叫端目前的工作階段範圍。非管理員呼叫端 不能輪替或撤銷比自己已持有範圍更廣的操作者權杖。
• 驗證失敗包含 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 的用戶端行為：
  • 受信任用戶端可以使用快取的每裝置權杖嘗試一次有界重試。
  • 如果該重試失敗，用戶端應停止自動重新連線迴圈，並顯示操作者動作指引。

​

裝置身分 + 配對

• 節點應包含穩定的裝置身分識別 (device.id)，並由 金鑰組指紋衍生而來。
• Gateway 會依裝置 + 角色核發權杖。
• 新裝置 ID 必須獲得配對核准，除非已啟用本機自動核准。
• 配對自動核准以直接 local loopback 連線為核心。
• OpenClaw 也有狹窄的後端/容器本機自我連線路徑，用於 受信任的共享密鑰輔助流程。
• 同主機 tailnet 或 LAN 連線在配對時仍會被視為遠端，並且 需要核准。
• WS 用戶端通常會在 connect 期間包含 device 身分識別（操作者 + 節點）。唯一不含裝置的操作者例外是明確的信任路徑：
  • gateway.controlUi.allowInsecureAuth=true 用於僅限 localhost 的不安全 HTTP 相容性。
  • 成功的 gateway.auth.mode: "trusted-proxy" 操作者控制 UI 驗證。
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true（緊急處置，嚴重降低安全性）。
  • 以共享 Gateway 權杖/密碼驗證的直接 loopback gateway-client 後端 RPC。
• 所有連線都必須簽署伺服器提供的 connect.challenge nonce。

​

裝置驗證遷移診斷

• 一律等待 connect.challenge。
• 簽署包含伺服器 nonce 的 v2 酬載。
• 在 connect.params.device.nonce 中傳送相同的 nonce。
• 偏好的簽章酬載是 v3，除了裝置/用戶端/角色/範圍/權杖/nonce 欄位外， 也會綁定 platform 和 deviceFamily。
• 舊版 v2 簽章仍會因相容性而被接受，但已配對裝置的 中繼資料釘選仍會控制重新連線時的命令政策。

​

TLS + 釘選

• WS 連線支援 TLS。
• 用戶端可選擇釘選 Gateway 憑證指紋（請參閱 gateway.tls 設定，加上 gateway.remote.tlsFingerprint 或 CLI --tls-fingerprint）。

​

範圍

​

相關

• 橋接協定
• Gateway 運行手冊