閘道協定

OpenClaw 的閘道 WS 通訊協定是唯一的控制平面與節點傳輸機制。操作端與節點用戶端（命令列介面、網頁 UI、macOS 應用程式、iOS/Android 節點、無介面節點）透過 WebSocket 連線，並在交握時宣告角色與範圍。

傳輸與訊框

• 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 }}

用戶端以 connect 回覆：

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

閘道以 hello-ok 回應：

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

server、features、snapshot、policy 與 auth 均為 HelloOkSchema（packages/gateway-protocol/src/schema/frames.ts）的必要項目。即使未核發裝置權杖，auth 也會回報協商後的角色／範圍（格式如上）。pluginSurfaceUrls 為選用項目，會將外掛介面名稱（例如 canvas）對應至限定範圍的託管 URL；該 URL 可能會過期，因此節點會使用 { "surface": "canvas" } 呼叫 node.pluginSurface.refresh，以取得新的項目。 已棄用的 canvasHostUrl / canvasCapability / node.canvas.capability.refresh 路徑不受支援；請使用外掛介面。

閘道仍在完成啟動附屬程序時，connect 可能會傳回可重試的 UNAVAILABLE 錯誤，其中包含 details.reason: "startup-sidecars" 與 retryAfterMs。請在連線時間預算內重試，不要將其視為終止性的交握失敗。

核發裝置權杖時，hello-ok.auth 會加入該權杖：

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

內建 QR／設定代碼啟動程序是行動裝置的交接路徑。成功的基準設定代碼連線會傳回一個主要節點權杖，以及一個受限的操作端權杖：

{  "auth": {    "deviceToken": "…",    "role": "node",    "scopes": [],    "deviceTokens": [      {        "deviceToken": "…",        "role": "operator",        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]      }    ]  }}

此操作端交接刻意受到限制：足以啟動行動裝置操作端迴圈與原生設定，包括用於讀取 Talk 設定的 operator.talk.secrets，但不包含配對變更範圍，也不包含 operator.admin。若需要更廣泛的 配對／管理員存取權，必須使用另一個經核准的配對或權杖流程。只有當啟動驗證透過受信任的 傳輸（wss:// 或迴路／本機配對）執行時，才持久保存 hello-ok.auth.deviceTokens。

受信任的同程序後端用戶端（client.id: "gateway-client"、 client.mode: "backend"）在直接迴路連線上使用共用閘道權杖／密碼進行驗證時，可以省略 device。此路徑僅供內部控制平面 RPC 使用（例如子代理工作階段更新），並可避免 過時的命令列介面／裝置配對基準阻擋本機後端工作。遠端、瀏覽器來源、節點，以及明確使用裝置權杖／裝置身分的用戶端，仍需通過一般配對與範圍升級檢查。

工作節點角色與封閉式通訊協定

雲端工作節點透過閘道擁有、固定主機金鑰的 SSH 通道，使用專用的迴路輸入端點。該端點只接受工作節點身分，絕不分派一般驗證、節點事件、操作端 RPC 或外掛方法。嚴格的 connect 會驗證靜態雜湊、短效且綁定至環境、套件組合雜湊、擁有者世代、RPC 集合版本、到期時間及一個可為 null 之工作階段的認證資訊；它也會分別檢查目前版本與功能集。成功時會傳回最小化的 worker-hello-ok；功能協商獨立於一般通訊協定版本。訊框維持在 64 KiB 以下，但經協商的 worker.inference.start 訊框可達 25 MiB。封閉式允許清單包含 worker.heartbeat、 worker.transcript.commit、worker.live-event、worker.inference.start 與 worker.inference.cancel。

逐字稿提交使用擁有者世代隔離、閘道擁有的工作階段繫結、基礎葉節點比較並交換，以及可持久保存的序列重播；閘道會透過一般工作階段寫入器產生逐字稿項目與父項目 ID。每次 RPC 都會重新檢查擁有權與到期時間。

用戶端功能

操作端用戶端可以在 connect.params.caps 中宣告選用功能：

• tool-events：接受結構化工具生命週期事件。
• inline-widgets：可以呈現託管的行內小工具結果。

用戶端功能描述的是已連線的用戶端，而非授權。代理工具可以宣告必要功能；除非原始用戶端的 caps 中包含所有必要項目，否則閘道會省略這些工具。源自頻道的執行不具有閘道用戶端功能，因此即使工具原則明確允許，仍無法使用受功能限制的工具。

節點連線範例

{  "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：用於叫用的命令允許清單。
• permissions：細粒度切換項目（例如 screen.record、camera.capture）。

閘道將這些項目視為聲明，並強制執行伺服器端允許清單。

角色與範圍

如需完整的操作端範圍模型、核准時檢查與共用密鑰語意，請參閱操作端範圍。

角色：

• operator：控制平面用戶端（命令列介面／UI／自動化）。
• node：功能主機（攝影機／螢幕／畫布／system.run）。
• worker：在專用封閉式工作節點通訊協定上運作的雲端執行主機。

操作端範圍（src/gateway/operator-scopes.ts），完整的封閉集合：

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

搭配 includeSecrets: true 的 talk.config 需要 operator.talk.secrets（或 operator.admin）。包含密鑰時，請從 talk.resolved.config.apiKey 讀取使用中的 Talk 供應商 認證資訊；talk.providers.<id>.apiKey 會維持來源格式，且可能是 SecretRef 物件或經遮蔽的字串。

由外掛註冊的閘道 RPC 方法可以要求其自身的操作端範圍，但以下保留的核心前綴一律解析為 operator.admin（src/shared/gateway-method-policy.ts）：config.*、exec.approvals.*、 wizard.*、update.*。

方法範圍只是第一道關卡。部分透過 chat.send 觸及的斜線命令會套用更嚴格的命令層級檢查：即使閘道用戶端已持有較低的操作端範圍，持久性的 /config set 與 /config unset 寫入仍需要 operator.admin。

除了基本方法範圍（operator.pairing）外，node.pair.approve 還會依據待處理請求所宣告的 commands（src/infra/node-pairing-authz.ts），額外進行核准時範圍檢查：

功能／命令／權限（節點）

節點會在連線時宣告功能聲明：

• caps：例如 camera、canvas、screen、 location、voice 與 talk 等高階功能類別。
• commands：用於叫用的命令允許清單。
• permissions：細粒度切換項目（例如 screen.record、camera.capture）。

閘道將這些項目視為聲明，並強制執行伺服器端允許清單。 已連線的節點可在成功連線或重新連線後，透過 node.pluginTools.update 發布選用且代理可見的外掛或 MCP 工具描述元。無介面節點主機會重新啟動，以套用宣告式 MCP 清單變更。此更新方法是唯一的發布路徑；connect 參數不接受外掛工具描述元。每個描述元都必須使用供應商安全的工具 name，並指定節點目前命令允許清單中的 command。閘道信任來自已配對節點的描述元中繼資料，會篩除核准命令介面以外的描述元，在節點中斷連線時移除描述元，並拒絕操作端嘗試修改其他節點的目錄。設定 gateway.nodes.pluginTools.enabled: false 即可忽略節點發布的描述元。

已連線的節點主機會透過 node.skills.update 發布其完整的技能替換目錄。此節點角色方法是唯一的節點技能發布 路徑；connect 參數不接受技能。每個描述項目都包含 安全的名稱、說明，以及有界的 SKILL.md 內容。閘道會使用一般的技能載入器解析該 內容，在節點連線期間將其納入代理程式技能快照， 並在中斷連線時移除。設定 gateway.nodes.skills.enabled: false 可忽略節點發布的技能。

在線狀態

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

原生 macOS 節點也可傳送經過驗證的 node.presence.activity 事件， 其中包含有界的輸入閒置時間。閘道會依據自身時鐘推導活動時間戳記， 透過 node.list 和 node.describe 公開最近仍在線的 Mac，並向具有讀取範圍的用戶端廣播 node.presence 更新。 如需瞭解選取、隱私權、模型 上下文及通知路由行為，請參閱作用中電腦在線狀態。

節點背景存活事件

節點會使用 event: "node.presence.alive" 呼叫 node.event，以記錄 已配對的節點曾在背景喚醒期間存活，但不會將其標示為已連線：

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

trigger 是封閉列舉：background、silent_push、bg_app_refresh、 significant_location、manual、connect。未知值會正規化為 background（src/shared/node-presence.ts）。此事件僅會為 經過驗證的節點裝置工作階段持久儲存；無裝置或未配對的工作階段會傳回 handled: false。

成功的閘道會傳回結構化結果：

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

較舊的閘道可能只會針對 node.event 傳回 { "ok": true }；應將其視為 已確認的 RPC，而非持久在線狀態的儲存結果。

廣播事件範圍

伺服器推送的廣播事件會受範圍控管，因此僅限配對範圍或僅限節點的 工作階段不會被動接收工作階段內容 （src/gateway/server-broadcast.ts）：

• 聊天、代理程式及工具結果框架（串流的 agent 事件、工具結果 事件）至少需要 operator.read。不具此範圍的工作階段會完全略過這些 框架。
• 外掛定義的 plugin.* 廣播預設會限制為 operator.write 或 operator.admin；plugin.approval.requested / plugin.approval.resolved 等明確項目則改用 operator.approvals。
• 狀態／傳輸事件（heartbeat、presence、tick、連線／中斷連線 生命週期）不受限制，因此每個經過驗證的工作階段都能觀察 傳輸健康狀態。
• 未知的廣播事件系列預設會受範圍控管（失敗時關閉）， 除非已註冊的處理常式明確放寬限制。

每個用戶端連線都會維護各自的用戶端序號，因此即使不同用戶端看到 經過不同範圍篩選的事件串流子集，廣播在該通訊端上仍會維持 單調遞增的順序。

RPC 方法系列

hello-ok.features.methods 是由 src/gateway/server-methods-list.ts 加上已載入的外掛／頻道方法 匯出所建立的保守探索清單，而不是每個方法的自動產生傾印；即使某些方法（例如 push.test、web.login.start、web.login.wait、sessions.usage） 確實存在且可呼叫，仍會刻意從探索結果中排除。應將此視為功能探索， 而非 src/gateway/server-methods/*.ts 的完整列舉。

常見事件系列

• chat：UI 聊天更新，例如 chat.inject 與其他僅限逐字記錄的聊天 事件。在通訊協定 v4 中，差異承載內容會攜帶 deltaText；message 仍是 累積的助理快照。非前綴替換會設定 replace=true，並使用 deltaText 作為替換文字。
• session.message、session.operation、session.tool：已訂閱工作階段的逐字記錄、進行中的 工作階段操作及事件串流更新。
• session.approval：供明確選擇加入且精確指定工作階段的訂閱者使用，經過清理的待處理與最終核准實況。 子項核准會使用已保存的祖先受眾；事件絕不會修改逐字記錄或喚醒代理程式。
• 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：外掛核准 生命週期。

節點輔助方法

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

稽核帳本 RPC

audit.activity.list 為操作端用戶端提供穩定且由新至舊排列的代理程式 執行、工具動作，以及選擇加入之訊息生命週期中繼資料檢視。它需要 operator.read。查詢會排除早於 30 天的記錄，而共用 SQLite 帳本最多保留 100,000 筆記錄。過期資料列會在 閘道啟動、每小時維護及後續寫入時刪除。資料模型與隱私語意請參閱 稽核歷程。

• 參數：選用的精確 agentId、sessionKey 或 runId；選用的 kind （"agent_run"、"tool_action" 或 "message"）；選用的 status （"started"、"succeeded"、"failed"、"cancelled"、"timed_out"、 "blocked" 或 "unknown"）；選用的訊息 direction（"inbound" 或 "outbound"）及精確 channel；選用且包含邊界值的 after / before Unix 毫秒界限；選用的 limit，範圍為 1 至 500；以及選用的 字串 cursor，來自前一頁。
• 結果：{ "events": AuditActivityEventV1[], "nextCursor"?: string }。

具名 V1 結果聯集分別具有代理程式執行、工具動作、輸入訊息 及輸出訊息結構描述。eventType 鑑別值依序為 agent_run、tool_action、inbound_message 或 outbound_message；kind 與 訊息 direction 仍可用於篩選與顯示。每個事件都有 整數 schemaVersion: 1。訊息身分參照使用精確的 hmac-sha256:v1:<32 hex key id>:<64 hex digest> 格式；頻道傳送者的動作者 ID 使用相同格式。

所有變體都需要 eventType、schemaVersion、eventId、sequence、 sourceSequence、occurredAt、kind、action、status、actor 及 redaction。各變體欄位如下：

封閉式訊息列舉如下：

• conversationKind：direct、group、channel 或 unknown。
• 輸入 outcome：completed、skipped 或 failed；選用的 reasonCode：duplicate、reply_operation_active、 reply_operation_aborted、fast_abort、plugin_bound_handled、 plugin_bound_unavailable、plugin_bound_declined、plugin_bound_error、 before_dispatch_handled、acp_dispatch_completed、acp_dispatch_failed、 acp_dispatch_empty 或 acp_dispatch_aborted。
• 輸出 outcome：sent、suppressed、failed 或 unknown；選用的 reasonCode：cancelled_by_message_sending_hook、 cancelled_by_reply_payload_sending_hook、 empty_after_message_sending_hook、empty_after_reply_payload_sending_hook 或 no_visible_payload。未傳回平台身分的轉接器會是 unknown，因為無法排除已發生外部副作用。
• deliveryKind：text、media 或 other；failureStage： platform_send、queue 或 unknown。

最終欄位彼此相關，並非各自獨立選填：

每個活動事件都包含穩定的事件 ID、單調遞增的帳本序號、 來源事件序號、時間戳記、動作者、動作、狀態、整數 schemaVersion: 1 及 redaction: "metadata_only"。執行與工具記錄 需要代理程式及執行來源資訊，並可包含工作階段來源資訊。訊息 記錄可包含代理程式及執行 ID，但刻意不包含 sessionKey 或 sessionId；因此 sessionKey 查詢篩選器僅套用於 執行與工具資料列。工具事件可包含工具呼叫 ID 與工具名稱。

訊息記錄使用 message.inbound.processed 或 message.outbound.finished，並新增方向、頻道、對話種類、 正規化結果，以及選用的傳遞種類、失敗階段、持續時間、 結果數量、原因代碼，與使用安裝環境本機金鑰產生的 帳號／對話／訊息／目標假名。這些假名有助於 建立關聯，但並非匿名化：狀態資料庫包含其金鑰， 而 RPC 與命令列介面匯出不包含。帳本不會儲存提示詞、訊息 內文、工具引數、工具結果、命令輸出或原始錯誤文字。 執行／工具的 sessionKey 值仍是原始關聯中繼資料，可能內嵌 平台帳號或對等端 ID；訊息記錄則省略工作階段金鑰。

對於輸入資料列，durationMs 衡量核心分派直到其最終狀態的時間， 而 resultCount 計算已完成定案並排入佇列的工具、封鎖與回覆承載內容數量。對於 輸出資料列，durationMs 涵蓋從取得傳遞所有權，到收到確認、 進入無法投遞佇列或完成調解的時間（包括佇列等待時間），而 resultCount 計算可識別的實體平台傳送次數。若有 deliveryKind， 它描述經過鉤子與轉譯後的有效承載內容；遭抑制或 因當機而結果不明確的資料列會省略此欄位。

目前的訊息涵蓋範圍包含抵達核心 分派的已接受輸入訊息，包括核心的重複／最終結果。輸出涵蓋範圍會為每個 抵達共用持久傳遞機制的原始邏輯回覆承載內容寫入一筆最終資料列；分塊 與轉接器扇出會彙總於 resultCount。排入佇列且可重試或結果不明確的傳送， 只有在收到確認、進入無法投遞佇列或完成調解後才會記錄。繞過這些 共用邊界的外掛本機與直接傳送路徑目前尚未涵蓋。具容量上限的工作程式佇列採盡力而為， 在失敗或飽和時可能遺失記錄，因此此介面並非 無損的合規性封存。

記錄功能預設開啟，並由 audit.enabled 控制。訊息記錄則 由 audit.messages 個別控制，預設為 "off"。停用 記錄功能時，audit.activity.list 仍會提供先前寫入的記錄， 直到它們過期為止。

已發布的 audit.list 請求、結果及 AuditEvent 結構描述維持 不變，且只會傳回代理程式執行與工具動作記錄。當閘道公布支援時，新的操作端 用戶端應呼叫 audit.activity.list。較舊的閘道可能會回報 unknown method: audit.activity.list；或者，由於已發布版本會先執行 授權再查找方法，也可能對僅具讀取範圍的請求回報 missing scope: operator.admin。只有在未公布該方法時，才將後者視為方法不存在。 接著，只有當篩選條件不需要訊息種類、方向或頻道 支援時，用戶端才能重試 audit.list。

使用 openclaw audit 進行文字查詢及有界 JSON 匯出。

工作帳本 RPC

操作端用戶端可透過工作帳本 RPC（packages/gateway-protocol/src/schema/tasks.ts） 檢查及取消閘道背景工作記錄。這些 RPC 會傳回經過清理的工作摘要，而非原始執行階段狀態。

• tasks.list 需要 operator.read。
  • 參數：選用的 status（"queued"、"running"、"completed"、 "failed"、"cancelled" 或 "timed_out"）或這些狀態的陣列、 選用的 agentId、選用的 sessionKey、從 1 到 500 的選用 limit，以及選用的字串 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 會回報執行階段是否接受或記錄了取消要求。

TaskSummary 包含 id、status，以及選用的中繼資料：kind、 runtime、title、agentId、sessionKey、childSessionKey、ownerKey、 runId、taskId、flowId、parentTaskId、sourceId、時間戳記、進度、 終止摘要，以及經過清理的錯誤文字。agentId 識別執行任務的代理程式； sessionKey 和 ownerKey 會保留要求者與控制 情境。

操作者輔助方法

• 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 檢視

models.list 接受選用的 view 參數 （src/agents/model-catalog-visibility.ts）：

• 省略或 "default"：如果已設定 agents.defaults.models， 回應會是允許的目錄，其中包含為 provider/* 項目 動態探索到的模型。否則，回應會是完整的閘道 目錄。
• "configured"：適合選擇器大小的行為。如果已設定 agents.defaults.models， 它仍會優先套用，包括針對 provider/* 項目、 限定提供者範圍的探索。如果沒有允許清單，回應會使用明確的 models.providers.<provider>.models 項目；只有在不存在已設定的模型資料列時， 才會退回完整目錄。
• "provider-config"：由來源撰寫的 models.providers.*.models 清單， 不受選擇器允許清單影響。資料列包含公開模型功能與 可辨識路由的可用性，但會省略提供者端點、驗證資料和 執行階段要求設定。
• "all"：完整的閘道目錄，略過 agents.defaults.models。用於 診斷／探索 UI，而非一般模型選擇器。

Exec 核准

• 當 exec 要求需要核准時，閘道會廣播 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 用戶端必須 包含該範圍內的目前通訊協定；目前的用戶端與伺服器執行 通訊協定 v4。
• 同時具有 role: "node" 和 client.mode: "node" 的已驗證用戶端 可以使用 N-1 節點通訊協定（目前為 v3）。輕量重新啟動探查會使用 相同的 N-1 範圍。裝置驗證、配對、範圍、命令政策和 exec 核准不受此相容性範圍影響。外掛擁有的節點 功能與命令會予以保留，直到節點升級至目前的 通訊協定，因為其託管介面不屬於 N-1 合約。
• 結構描述與模型是從 TypeBox 定義產生：
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

用戶端常數

參考用戶端實作位於 packages/gateway-client/src/ （OpenClaw 透過精簡的 src/gateway/client.ts 外觀包裝它）。這些 預設值在通訊協定 v4 中保持穩定，也是第三方用戶端的預期 基準。

伺服器會在 hello-ok 中公告實際生效的 policy.tickIntervalMs、 policy.maxPayload 與 policy.maxBufferedBytes；用戶端 應採用這些值，而不是交握前的預設值。

當每個待處理請求都有期限時，參考用戶端會讓有限請求採用其設定的期限。沒有有限 timeoutMs 的 expectFinal 請求、任何具有 timeoutMs: null 的請求，或有限與 無限期請求的混合，都會讓 tick 看門狗保持啟用。如果傳入事件與 回應持續靜默並超過 tick 逾時閾值，用戶端會以代碼 4000 關閉通訊端、拒絕所有待處理請求，然後重新連線。重新連線後不會 重播遭拒絕的請求。

驗證

• 共用密鑰閘道驗證會依設定的 gateway.auth.mode（"none" | "token" | "password" | "trusted-proxy"），使用 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" 會完全略過共用密鑰連線驗證； 請勿在公開／不受信任的入口公開此模式。
• 配對後，閘道會核發限定於連線角色與範圍的裝置權杖， 並在 hello-ok.auth.deviceToken 中傳回。用戶端應在任何成功連線後 將其保存。
• 使用已儲存的裝置權杖重新連線時，也應重複使用該權杖已儲存的 核准範圍集合。這可保留先前已授予的讀取／探測／狀態存取權， 並避免重新連線時不知不覺縮減為較窄、僅限管理員的隱含範圍。
• 用戶端連線驗證組裝（packages/gateway-client/src/client.ts 中的 selectConnectAuth）：
  • auth.password 彼此獨立，設定後一律轉送。
  • auth.token 依下列優先順序填入：先使用明確的共用權杖， 再使用明確的 deviceToken，最後使用已儲存的個別裝置權杖（以 deviceId + role 為鍵）。
  • 只有上述項目都未解析出 auth.token 時，才會傳送 auth.bootstrapToken。共用權杖或任何已解析的裝置權杖都會抑制它。
  • 在單次 AUTH_TOKEN_MISMATCH 重試中自動提升已儲存的裝置權杖， 僅限受信任的端點：回送端點， 或具有固定 tlsFingerprint 的 wss://。未固定的公開 wss:// 不符合資格。
• 內建設定代碼啟動程序會傳回主要節點 hello-ok.auth.deviceToken，以及 hello-ok.auth.deviceTokens 中有限制的操作者權杖， 供受信任的行動裝置交接使用。操作者權杖包含 operator.talk.secrets， 以供原生 Talk 設定讀取，但不包含配對變更範圍與 operator.admin。
• 非基準設定代碼啟動程序等待核准時， PAIRING_REQUIRED 詳細資料會包含 recommendedNextStep: "wait_then_retry"、 retryable: true 與 pauseReconnect: false。請使用相同的啟動權杖 持續重新連線，直到請求獲得核准或權杖失效。
• 只有在連線透過 wss:// 等受信任傳輸， 或回送／本機配對使用啟動驗證時，才保存 hello-ok.auth.deviceTokens。
• 如果用戶端提供明確的 deviceToken 或明確的 scopes， 該呼叫端要求的範圍集合仍具權威性；只有在用戶端重複使用已儲存的個別裝置權杖時， 才會重複使用快取的範圍。
• 裝置權杖可透過 device.token.rotate 與 device.token.revoke 進行輪替／撤銷（需要 operator.pairing）。輪替或撤銷 節點或其他非操作者角色時，也需要 operator.admin。
• 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 之一 （packages/gateway-protocol/src/connect-error-details.ts）。
• 用戶端對 AUTH_TOKEN_MISMATCH 的行為：
  • 受信任的用戶端可嘗試使用快取的個別裝置權杖進行一次有限重試。
  • 如果該次重試失敗，請停止自動重新連線迴圈，並顯示操作者 操作指引。
• AUTH_SCOPE_MISMATCH 表示裝置權杖已被辨識，但未涵蓋 要求的角色／範圍。請勿將此情況顯示為權杖錯誤；應提示 操作者重新配對，或核准較窄／較廣的範圍契約。

裝置身分與配對

• 節點應包含從金鑰組指紋衍生的穩定裝置身分（device.id）。
• 閘道會依裝置與角色核發權杖。
• 除非已啟用本機自動核准，否則新的裝置 ID 必須取得配對核准。
• 配對自動核准以直接的本機回送連線為核心。
• OpenClaw 也為受信任的共用密鑰輔助流程提供狹義的後端／容器本機自連線路徑。
• 同一主機的 tailnet 或 LAN 連線仍視為遠端連線，且需要核准。
• WS 用戶端通常會在 connect 期間包含 device 身分（操作者 + 節點）。唯一不含裝置的操作者例外是明確的信任路徑：
  • gateway.controlUi.allowInsecureAuth=true，用於僅限 localhost 的不安全 HTTP 相容性。
  • 成功的 gateway.auth.mode: "trusted-proxy" 操作者控制介面驗證。
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true（緊急解鎖，嚴重降低安全性）。
  • 保留的內部輔助路徑上，直接回送的 gateway-client 後端 RPC。
• 省略裝置身分會影響範圍。當不含裝置的操作者連線透過明確的信任路徑獲准時， OpenClaw 仍會將自行宣告的範圍清除為空集合，除非該路徑具有具名的範圍保留例外。 受範圍限制的方法隨後會以 missing scope 失敗。
• gateway.controlUi.dangerouslyDisableDeviceAuth=true 是控制介面的 緊急解鎖範圍保留路徑。它不會將範圍授予任意的自訂後端或命令列介面形式的 WebSocket 用戶端。
• 保留的直接回送 gateway-client 後端輔助路徑， 只會為內部本機控制層 RPC 保留範圍；自訂後端 ID 不會獲得此例外。
• 所有連線都必須簽署伺服器提供的 connect.challenge nonce。

裝置驗證遷移診斷

對於仍使用挑戰前簽署行為的舊版用戶端，connect 會在 error.details.code 下傳回 DEVICE_AUTH_* 詳細代碼，以及穩定的 error.details.reason。

常見遷移失敗：

遷移目標：

• 一律等待 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 固定閘道憑證指紋。

範圍

此通訊協定公開完整的閘道 API：狀態、頻道、模型、聊天、 代理程式、工作階段、節點、核准等。確切介面由 packages/gateway-protocol/src/schema.ts 重新匯出的 TypeBox 結構描述定義。

相關內容

• 橋接通訊協定
• 閘道操作手冊