閘道協定

​

傳輸與框架

• WebSocket、文字框架、JSON 承載。
• 第一個框架必須是 connect 請求。
• 預連線框架上限為 64 KiB（MAX_PREAUTH_PAYLOAD_BYTES）。握手後， 請遵循 hello-ok.policy.maxPayload 與 hello-ok.policy.maxBufferedBytes。啟用診斷時，過大的傳入框架與緩慢的 傳出緩衝區會在閘道關閉或丟棄框架前發出 payload.large 事件。 這些事件會攜帶 surface、位元組大小、限制與安全的原因代碼， 絕不包含訊息正文、附件內容、原始框架位元組、權杖、Cookie 或秘密。

• 請求：{type:"req", id, method, params}
• 回應：{type:"res", id, ok, payload|error}
• 事件：{type:"event", event, payload, seq?, stateVersion?}

​

握手

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

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "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": {
    "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"]
      }
    ]
  }
}

​

節點 connect 範例

{
  "type": "req",
  "id": "…",
  "method": "connect",
  "params": {
    "minProtocol": 4,
    "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": "…"
    }
  }
}

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

​

角色與範圍

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

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

​

Presence

• system-presence 會傳回以裝置身分為鍵的項目，包含 deviceId、roles 與 scopes，因此即使裝置同時以操作者與節點身分連線， UI 也能為每個裝置顯示一列。
• node.list 包含選用的 lastSeenAtMs 與 lastSeenReason。已連線節點會以 connect 原因回報目前連線時間；已配對節點也可以透過受信任的節點事件， 回報持久的背景 presence。

​

節點背景存活事件

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

​

廣播事件範圍控管

• Chat、agent 與工具結果框架（串流的 agent 事件、工具結果事件）至少需要 operator.read。沒有此範圍的工作階段會完全略過這些框架。
• 外掛定義的 plugin.* 廣播預設受 operator.write 或 operator.admin 控管；明確項目例如 plugin.approval.requested / plugin.approval.resolved 則改用 operator.approvals。
• 狀態/傳輸事件（heartbeat、presence、tick、connect/disconnect 生命週期）保持不受限制，讓每個已驗證工作階段都能觀察傳輸健康狀態。
• 未知的廣播事件家族預設受範圍控管（fail-closed）， 除非已註冊的 handler 明確放寬限制。

​

RPC 方法家族

​

常見事件系列

• chat：UI 聊天更新，例如 chat.inject 和其他僅限逐字稿的聊天事件。在通訊協定 v4 中，差異酬載會帶有 deltaText；message 仍然是累積的助理快照。非前綴替換會設定 replace=true，並使用 deltaText 作為替換文字。
• session.message、session.operation、session.tool：已訂閱工作階段的逐字稿、進行中的工作階段操作，以及事件串流更新。
• sessions.changed：工作階段索引或中繼資料已變更。
• presence：系統存在狀態快照更新。
• tick：週期性保活／存活事件。
• health：閘道健康狀態快照更新。
• heartbeat：心跳偵測事件串流更新。
• cron：排程執行／工作變更事件。
• shutdown：閘道關閉通知。
• node.pair.requested / node.pair.resolved：節點配對生命週期。
• node.invoke.request：節點叫用請求廣播。
• device.pair.requested / device.pair.resolved：已配對裝置生命週期。
• voicewake.changed：喚醒詞觸發設定已變更。
• exec.approval.requested / exec.approval.resolved：執行核准生命週期。
• plugin.approval.requested / plugin.approval.resolved：外掛核准生命週期。

​

節點輔助方法

​

稽核帳本 RPC

• 參數：選用的精確 agentId、sessionKey 或 runId；選用的 kind（"agent_run" 或 "tool_action"）；選用的 status（"started"、"succeeded"、"failed"、"cancelled"、"timed_out"、"blocked" 或 "unknown"）；選用的包含端點 after / before Unix 毫秒界線；選用的 limit，範圍從 1 到 500；以及來自前一頁的選用字串 cursor。
• 結果：{ "events": AuditEvent[], "nextCursor"?: string }。

​

工作帳本 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 會傳回閘道找不到項目的錯誤形狀。
• 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 為選用，且只會影響原生命名以及原生外掛命令可用性。
  • includeArgs=false 會從回應中省略序列化的引數中繼資料。
• tools.catalog（operator.read）會擷取代理的執行階段工具目錄。回應包含分組工具和來源中繼資料：
  • source：core 或 plugin
  • pluginId：當 source="plugin" 時的外掛擁有者
  • optional：外掛工具是否為選用
• tools.effective（operator.read）會擷取工作階段的執行階段有效工具清單。
  • sessionKey 為必要。
  • 閘道會從伺服器端工作階段推導可信的執行階段內容，而不是接受呼叫端提供的驗證或傳遞內容。
  • 回應是工作階段範圍、由伺服器推導的作用中清單投影，包含核心、外掛、通道，以及已探索的 MCP 伺服器工具。
  • tools.effective 對 MCP 是唯讀的：它可以透過最終工具政策投影已暖機工作階段的 MCP 目錄，但不會建立 MCP 執行階段、連接傳輸，或發出 tools/list。如果不存在相符的已暖機目錄，回應可能包含通知，例如 mcp-not-yet-connected、mcp-not-yet-listed 或 mcp-stale-catalog。
  • 有效工具項目會使用 source="core"、source="plugin"、source="channel" 或 source="mcp"。
• tools.invoke（operator.write）會透過與 /tools/invoke 相同的閘道政策路徑叫用一個可用工具。
  • name 為必要。args、sessionKey、agentId、confirm 和 idempotencyKey 為選用。
  • 如果同時存在 sessionKey 和 agentId，解析出的工作階段代理必須符合 agentId。
  • 僅限擁有者的核心包裝器，例如 cron、gateway 和 nodes，需要擁有者／管理員身分（operator.admin），即使 tools.invoke 本身是 operator.write。
  • 回應是面向 SDK 的封套，包含 ok、toolName、選用的 output，以及具型別的 error 欄位。核准或政策拒絕會在酬載中傳回 ok:false，而不是繞過閘道工具政策管線。
• skills.status（operator.read）會擷取代理的可見技能清單。
  • agentId 為選用；省略它可讀取預設代理工作區。
  • 回應包含資格、缺少的需求、設定檢查，以及經過清理的安裝選項，而不會暴露原始密鑰值。
• skills.search 和 skills.detail（operator.read）會傳回 ClawHub 探索中繼資料。
• skills.upload.begin、skills.upload.chunk 和 skills.upload.commit（operator.admin）會在安裝前暫存私人技能封存檔。這是供可信用戶端使用的獨立管理員上傳路徑，不是一般 ClawHub 技能安裝流程，且預設停用，除非啟用 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.md 根目錄的 zip 封存檔。封存檔的內部目錄名稱永遠不會選擇安裝目標。
• skills.install（operator.admin）有三種模式：
  • ClawHub 模式：{ source: "clawhub", slug, version?, force? } 會將技能資料夾安裝到預設代理工作區的 skills/ 目錄。
  • 上傳模式：{ source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } 會將已提交的上傳安裝到預設代理工作區的 skills/<slug> 目錄。slug 和 force 值必須符合原始 skills.upload.begin 請求。除非啟用 skills.install.allowUploadedArchives，否則會被拒絕；該設定不會影響 ClawHub 安裝。
  • 閘道安裝器模式：{ name, installId, timeoutMs? } 會在閘道主機上執行宣告的 metadata.openclaw.install 動作。較舊的用戶端仍可能傳送 dangerouslyForceUnsafeInstall；此欄位已棄用，僅為通訊協定相容性而接受，且會被忽略。請使用 security.installPolicy 進行操作者擁有的安裝決策。
• skills.update（operator.admin）有兩種模式：
  • ClawHub 模式會更新一個追蹤的 slug，或預設代理工作區中的所有追蹤 ClawHub 安裝。
  • 設定模式會修補 skills.entries.<skillKey> 值，例如 enabled、apiKey 和 env。

​

models.list 檢視

• 省略或 "default"：如果已設定 agents.defaults.models，回應會是允許的目錄，包含為 provider/* 項目動態探索的模型。否則回應會是完整閘道目錄。
• "configured"：適合挑選器大小的行為。如果已設定 agents.defaults.models，它仍然優先，包含 provider/* 項目的提供者範圍探索。沒有允許清單時，回應會使用明確的 models.providers.<provider>.models 項目，只有在沒有任何已設定模型資料列時才退回完整目錄。
• "all"：完整閘道目錄，繞過 agents.defaults.models。用於診斷／探索 UI，而不是一般模型挑選器。

​

執行核准

• 當執行請求需要核准時，閘道會廣播 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，閘道會拒絕該執行，而不是信任變更後的酬載。

​

代理傳遞後援

• agent 請求可以包含 deliver=true 以請求對外傳遞。
• bestEffortDeliver=false（預設）會維持嚴格行為：無法解析或僅限內部的傳遞目標會傳回 INVALID_REQUEST。
• bestEffortDeliver=true 允許在無法解析外部可傳遞路由時退回僅工作階段執行（例如內部／網頁聊天工作階段或模糊的多通道設定）。
• 最終 agent 結果在請求傳遞時可能包含 result.deliveryStatus，使用與 openclaw agent --json --deliver 所記錄相同的 sent、suppressed、partial_failed 和 failed 狀態。

​

版本控管

• PROTOCOL_VERSION、MIN_CLIENT_PROTOCOL_VERSION、 MIN_NODE_PROTOCOL_VERSION 和 MIN_PROBE_PROTOCOL_VERSION 位於 packages/gateway-protocol/src/version.ts。
• 用戶端會傳送 minProtocol + maxProtocol。操作者與 UI 用戶端必須 在該範圍中包含目前協定；目前的用戶端與伺服器執行 protocol v4。
• 同時具備 role: "node" 與 client.mode: "node" 的已驗證用戶端 可以使用 N-1 節點協定（目前為 v3）。輕量重新啟動探測會使用 相同的 N-1 視窗。裝置驗證、配對、範圍、命令政策與執行核准 不會因這個相容性視窗而改變。外掛擁有的節點 功能與命令會保留不提供，直到該節點升級到目前 協定，因為其託管介面不屬於 N-1 合約。
• Schema 與模型由 TypeBox 定義產生：
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

​

用戶端常數

​

驗證

• 共享密鑰閘道驗證會使用 connect.params.auth.token 或 connect.params.auth.password，取決於設定的 gateway.auth.mode（"none" | "token" | "password" | "trusted-proxy"）。
• 帶有身分的模式，例如 Tailscale Serve（gateway.auth.allowTailscale: true） 或非 loopback 的 gateway.auth.mode: "trusted-proxy"，會從請求標頭 滿足連線驗證檢查，而不是使用 connect.params.auth.*。
• 私有入口的 gateway.auth.mode: "none" 會完全略過共享密鑰連線驗證； 請勿在公開/不受信任的入口公開該模式。
• 配對後，閘道會發出限定於連線 角色 + 範圍的裝置權杖，並在 hello-ok.auth.deviceToken 中傳回。用戶端應 在任何成功連線後保存它。
• 使用該已儲存的裝置權杖重新連線時，也應重用針對該權杖所儲存的 已核准範圍集。這會保留已授予的讀取/探測/狀態存取權， 並避免重新連線悄悄縮減為較窄的隱含僅管理員範圍。
• 用戶端連線驗證組裝（packages/gateway-client/src/client.ts 中的 selectConnectAuth）：
  • auth.password 是正交的，設定時一律轉送。
  • auth.token 依優先順序填入：明確共享權杖優先， 接著是明確的 deviceToken，再來是已儲存的逐裝置權杖（以 deviceId + role 為鍵）。
  • auth.bootstrapToken 只會在上述項目都未解析出 auth.token 時傳送。共享權杖或任何已解析的裝置權杖會抑制它。
  • 在一次性的 AUTH_TOKEN_MISMATCH 重試中自動提升已儲存裝置權杖，僅限受信任端點：loopback， 或具有釘選 tlsFingerprint 的 wss://。未釘選的公開 wss:// 不符合資格。
• 內建設定碼 bootstrap 會傳回主要節點 hello-ok.auth.deviceToken，以及在 hello-ok.auth.deviceTokens 中供受信任行動交接使用的有界操作者權杖。該操作者權杖 包含 operator.talk.secrets 以讀取原生 Talk 設定，但 排除配對變更範圍與 operator.admin。
• 當非基準設定碼 bootstrap 等待核准時， PAIRING_REQUIRED 詳細資料會包含 recommendedNextStep: "wait_then_retry"、 retryable: true 和 pauseReconnect: false。請使用 相同的 bootstrap 權杖持續重新連線，直到請求獲准或權杖變成 無效。
• 只有在連線於受信任傳輸（例如 wss:// 或 loopback/local 配對）上使用 bootstrap 驗證時，才保存 hello-ok.auth.deviceTokens。
• 如果用戶端提供明確的 deviceToken 或明確的 scopes，該 呼叫者要求的範圍集仍具權威性；快取的範圍只會在 用戶端重用已儲存的逐裝置權杖時才重用。
• 裝置權杖可透過 device.token.rotate 和 device.token.revoke 輪替/撤銷（需要 operator.pairing）。輪替或撤銷 節點或其他非操作者角色也需要 operator.admin。
• device.token.rotate 會傳回輪替中繼資料。它只會針對已使用該 裝置權杖驗證的同裝置呼叫回傳替換的 bearer 權杖，因此僅權杖用戶端可在 重新連線前保存其替換權杖。共享/管理員輪替不會回傳 bearer 權杖。
• 權杖發行、輪替與撤銷會限制在該裝置配對項目中記錄的已核准角色 集合內；權杖變更不能擴展或指定配對核准從未授予的裝置角色。
• 對於已配對裝置權杖工作階段，除非呼叫者也有 operator.admin， 否則裝置管理為自我範圍限定：非管理員呼叫者只能管理其自身裝置項目的 操作者權杖。節點與其他非操作者權杖 管理僅限管理員，即使是呼叫者自己的裝置也一樣。
• device.token.rotate 和 device.token.revoke 也會檢查目標 操作者權杖範圍集是否符合呼叫者目前的工作階段範圍。 非管理員呼叫者不能輪替或撤銷比自己已持有範圍更廣的操作者權杖。
• 驗證失敗會包含 error.details.code 以及復原提示：
  • error.details.canRetryWithDeviceToken（boolean）
  • error.details.recommendedNextStep：下列之一：retry_with_device_token、 update_auth_configuration、update_auth_credentials、 wait_then_retry、review_auth_configuration (packages/gateway-protocol/src/connect-error-details.ts)。
• AUTH_TOKEN_MISMATCH 的用戶端行為：
  • 受信任用戶端可以嘗試使用快取的逐裝置 權杖進行一次有界重試。
  • 如果該重試失敗，請停止自動重新連線迴圈，並顯示操作者 操作指引。
• AUTH_SCOPE_MISMATCH 表示裝置權杖已被辨識，但未 涵蓋要求的角色/範圍。不要將此呈現為錯誤權杖；請提示 操作者重新配對，或核准較窄/較廣的範圍合約。

​

裝置身分與配對

• 節點應包含從 金鑰組指紋衍生的穩定裝置身分（device.id）。
• 閘道會依每個裝置 + 角色發行權杖。
• 除非啟用本機 自動核准，否則新的裝置 ID 需要配對核准。
• 配對自動核准以直接 local loopback 連線為核心。
• OpenClaw 也有一條狹窄的後端/容器本機自我連線路徑，用於 受信任的共享密鑰輔助流程。
• 同主機 tailnet 或 LAN 連線仍會被視為遠端配對， 並需要核准。
• WS 用戶端通常會在 connect 期間包含 device 身分（操作者 + 節點）。唯一不含裝置的操作者例外是明確信任路徑：
  • gateway.controlUi.allowInsecureAuth=true，用於僅 localhost 的不安全 HTTP 相容性。
  • 成功的 gateway.auth.mode: "trusted-proxy" 操作者 Control UI 驗證。
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true（break-glass，嚴重 安全性降級）。
  • 保留內部 輔助路徑上的 direct-loopback gateway-client 後端 RPC。
• 省略裝置身分會造成範圍後果。當不含裝置的 操作者連線透過明確信任路徑獲准時，OpenClaw 仍會將自我宣告的範圍清空為空集合，除非該路徑有 具名的範圍保留例外。範圍控管的方法接著會因 missing scope 而失敗。
• gateway.controlUi.dangerouslyDisableDeviceAuth=true 是 Control UI break-glass 範圍保留路徑。它不會授予任意 自訂後端或 CLI 形態 WebSocket 用戶端範圍。
• 保留的 direct-loopback gateway-client 後端輔助路徑只會為 內部本機控制平面 RPC 保留範圍；自訂後端 ID 不會收到此例外。
• 所有連線都必須簽署伺服器提供的 connect.challenge nonce。

​

裝置驗證遷移診斷

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

​

TLS 與釘選

• WS 連線支援 TLS（gateway.tls 設定）。
• 用戶端可選擇透過 gateway.remote.tlsFingerprint 或命令列介面 --tls-fingerprint 釘選閘道憑證指紋。

​

範圍

​

相關

• 橋接協定
• 閘道執行手冊