Gateway 協定

Documentation Index

Fetch the complete documentation index at: https://docs2.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": 4,
    "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": 4,
    "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": 4,
    "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 Node 命令的請求：operator.pairing + operator.write
• 包含 system.run、system.run.prepare 或 system.which 的請求：operator.pairing + operator.admin

​

能力/命令/權限（Node）

• caps：高階能力類別，例如 camera、canvas、screen、location、voice 和 talk。
• commands：用於 invoke 的命令允許清單。
• permissions：細粒度切換（例如 screen.record、camera.capture）。

​

Presence

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

​

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.invoke.request：節點 invoke 要求廣播。
• device.pair.requested / device.pair.resolved：已配對裝置生命週期。
• voicewake.changed：喚醒詞觸發設定已變更。
• exec.approval.requested / exec.approval.resolved：exec 核准 生命週期。
• plugin.approval.requested / plugin.approval.resolved：plugin 核准 生命週期。

​

節點輔助方法

• 節點可以呼叫 skills.bins 來擷取目前的 skill 可執行檔清單， 供自動允許檢查使用。

​

任務分類帳 RPC

• tasks.list 需要 operator.read。
  • 參數：選用的 status（"queued"、"running"、"completed"、 "failed"、"cancelled" 或 "timed_out"）或這些狀態的陣列、 選用的 agentId、選用的 sessionKey、選用的 limit，範圍從 1 到 500，以及選用的字串 cursor。
  • 結果：{ "tasks": TaskSummary[], "nextCursor"?: string }。
• tasks.get 需要 operator.read。
  • 參數：{ "taskId": string }。
  • 結果：{ "task": TaskSummary }。
  • 缺少的任務 ID 會傳回 Gateway 的 not-found 錯誤形狀。
• tasks.cancel 需要 operator.write。
  • 參數：{ "taskId": string, "reason"?: string }。
  • 結果： { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }。
  • found 回報分類帳是否有相符任務。cancelled 回報執行階段是否接受或記錄了取消。

​

操作員輔助方法

• 操作員可以呼叫 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 和頻道工具。
• 操作員可以呼叫 tools.invoke（operator.write），透過與 /tools/invoke 相同的 gateway 政策路徑叫用一個可用工具。
  • name 為必填。args、sessionKey、agentId、confirm 和 idempotencyKey 為選用。
  • 如果同時存在 sessionKey 和 agentId，解析後的工作階段代理程式必須符合 agentId。
  • 回應是面向 SDK 的封套，包含 ok、toolName、選用的 output，以及具型別的 error 欄位。核准或政策拒絕會在酬載中傳回 ok:false，而不是 繞過 gateway 工具政策管線。
• 操作員可以呼叫 skills.status（operator.read）來擷取代理程式的可見 skill 清單。
  • agentId 為選用；省略即可讀取預設代理程式工作區。
  • 回應包含資格、缺少的需求、設定檢查，以及 經過清理且不暴露原始秘密值的安裝選項。
• 操作員可以呼叫 skills.search 和 skills.detail（operator.read）取得 ClawHub 探索中繼資料。
• 操作員可以呼叫 skills.upload.begin、skills.upload.chunk 和 skills.upload.commit（operator.admin），在安裝前暫存私人 skill 封存檔。 這是受信任用戶端的獨立管理員上傳路徑， 不是一般 ClawHub skill 安裝流程，且預設停用，除非 skills.install.allowUploadedArchives 已啟用。
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) 會建立繫結到該 slug 和 force 值的上傳。
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) 會在 精確的解碼位移附加位元組。
  • skills.upload.commit({ uploadId, sha256? }) 會驗證最終大小和 SHA-256。提交只會完成上傳；不會安裝 skill。
  • 上傳的 skill 封存檔是包含 SKILL.md 根目錄的 zip 封存檔。該 封存檔的內部目錄名稱絕不會選取安裝目標。
• 操作員可以在三種模式下呼叫 skills.install（operator.admin）：
  • ClawHub 模式：{ source: "clawhub", slug, version?, force? } 會將 skill 資料夾安裝到預設代理程式工作區的 skills/ 目錄。
  • 上傳模式：{ source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } 會將已提交的上傳安裝到預設代理程式工作區的 skills/<slug> 目錄。slug 和 force 值必須符合原始 skills.upload.begin 要求。除非 skills.install.allowUploadedArchives 已啟用，否則此模式會被拒絕。該設定不會 影響 ClawHub 安裝。
  • 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，回應會是允許的目錄，包括針對 provider/* 項目動態探索到的模型。否則回應會是完整的 Gateway 目錄。
• "configured"：適合選擇器大小的行為。如果已設定 agents.defaults.models，它仍然優先，包括針對 provider/* 項目的提供者範圍探索。沒有允許清單時，回應會使用明確的 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/工作階段內容。
• 如果呼叫端在 prepare 與最終已核准的 system.run 轉送之間變更 command、rawCommand、cwd、agentId 或 sessionKey，gateway 會拒絕該執行，而不是信任已變更的酬載。

​

代理程式傳遞備援

• agent 要求可以包含 deliver=true 以要求對外傳遞。
• bestEffortDeliver=false 會維持嚴格行為：無法解析或僅限內部的傳遞目標會傳回 INVALID_REQUEST。
• bestEffortDeliver=true 允許在無法解析外部可傳遞路由時，回退到僅工作階段執行（例如內部/webchat 工作階段或模稜兩可的多頻道設定）。
• 最終 agent 結果在要求傳遞時可能包含 result.deliveryStatus， 使用與 openclaw agent --json --deliver 文件中相同的 sent、suppressed、partial_failed 和 failed 狀態。

​

版本控管

• PROTOCOL_VERSION 位於 src/gateway/protocol/version.ts。
• 用戶端傳送 minProtocol + maxProtocol；伺服器會拒絕 未包含目前協定的範圍。原生用戶端使用 v3 下限，因此 加法式 v4 用戶端仍可連線到 v3 gateway。
• 結構描述 + 模型是從 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) 或非回送的 gateway.auth.mode: "trusted-proxy"，會從請求標頭而非 connect.params.auth.* 滿足連線驗證檢查。
• 私有入口 gateway.auth.mode: "none" 會完全略過共享祕密連線驗證； 不要將該模式暴露在公開/不受信任的入口上。
• 配對後，Gateway 會發出一個作用域限於連線角色 + scopes 的裝置權杖。 它會在 hello-ok.auth.deviceToken 中返回，且用戶端應保存它以供後續連線使用。
• 用戶端應在任何成功連線後保存主要的 hello-ok.auth.deviceToken。
• 使用該已儲存裝置權杖重新連線時，也應重用該權杖已儲存的已核准 scope 集合。 這會保留先前已授權的讀取/探測/狀態存取權，並避免重新連線被靜默縮減為較窄的隱含僅管理員 scope。
• 用戶端連線驗證組裝（src/gateway/client.ts 中的 selectConnectAuth）：
  • auth.password 是獨立的，設定時一律會轉送。
  • auth.token 會依優先順序填入：先是明確共享權杖， 接著是明確的 deviceToken，再來是已儲存的逐裝置權杖（以 deviceId + role 為鍵）。
  • auth.bootstrapToken 只會在上述皆未解析出 auth.token 時傳送。共享權杖或任何解析出的裝置權杖都會抑制它。
  • 在一次性的 AUTH_TOKEN_MISMATCH 重試中自動提升已儲存裝置權杖， 僅限於受信任端點：回送，或帶有固定 tlsFingerprint 的 wss://。 未固定的公開 wss:// 不符合資格。
• 其他 hello-ok.auth.deviceTokens 項目是啟動交接權杖。 只有在連線使用受信任傳輸上的啟動驗證時才保存它們，例如 wss:// 或回送/本機配對。
• 如果用戶端提供明確的 deviceToken 或明確的 scopes， 該呼叫端要求的 scope 集合仍具權威性；快取的 scopes 只會在用戶端重用已儲存的逐裝置權杖時使用。
• 裝置權杖可透過 device.token.rotate 和 device.token.revoke 輪替/撤銷（需要 operator.pairing scope）。
• device.token.rotate 會返回輪替中繼資料。它只會在同裝置呼叫且已使用該裝置權杖驗證時回傳替換 bearer 權杖， 讓僅權杖用戶端能在重新連線前保存替換權杖。共享/管理員輪替不會回傳 bearer 權杖。
• 權杖發行、輪替和撤銷皆受限於該裝置配對項目中記錄的已核准角色集合； 權杖變更無法擴大或指定配對核准從未授予的裝置角色。
• 對於已配對裝置權杖工作階段，除非呼叫端也有 operator.admin， 否則裝置管理限於自身 scope：非管理員呼叫端只能移除/撤銷/輪替其自己的裝置項目。
• device.token.rotate 和 device.token.revoke 也會檢查目標 operator 權杖 scope 集合是否符合呼叫端目前的工作階段 scopes。非管理員呼叫端無法輪替或撤銷比自己已持有更寬的 operator 權杖。
• 驗證失敗包含 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 動作指引。
• AUTH_SCOPE_MISMATCH 表示裝置權杖已被辨識，但未涵蓋要求的角色/scopes。 用戶端不應將此呈現為錯誤權杖；請提示 operator 重新配對，或核准較窄/較寬的 scope 合約。

​

裝置身分 + 配對

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

​

裝置驗證遷移診斷

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

​

TLS + 固定

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

​

Scope

​

相關

• 橋接協定
• Gateway 執行手冊