閘道通訊協定

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

npm 套件

這些套件會隨 OpenClaw 發行系列一併提供。在初始推出期間，首次發布包含套件的版本之前，npm 可能會傳回 E404。

• @openclaw/gateway-protocol 發布結構描述、驗證器、TypeScript 型別、輕量級訊框與錯誤輔助工具，以及版本常數。其 tarball 包含產生的 protocol.schema.json 機器可讀合約。
• @openclaw/gateway-client 發布參考用節點用戶端，以及位於 @openclaw/gateway-client/browser 的瀏覽器安全進入點。

如需應用程式生命週期指引，請參閱 建置 Gateway 用戶端。若應用程式會將 Gateway 作為子程序監督執行，請參閱 嵌入 OpenClaw。

傳輸與訊框

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

回應錯誤使用 { code, message, details?, retryable?, retryAfterMs? }。 用戶端應依據 code 與 details.code 分支處理；message 保持人類可讀，除非相容性註記另有說明，否則可能變更。方法層級的授權失敗會使用頂層 code: "FORBIDDEN"，並附上結構化的缺少範圍詳細資料：

• 缺少範圍：{ code: "MISSING_SCOPE", missingScope, requiredScopes }。 requiredScopes 是所請求操作完整的已知範圍集合。 為支援較舊的用戶端，仍保留舊版 missing scope: <scope> 訊息。

用戶端應先讀取 details，僅將舊版訊息作為相容性備援。readMissingScopeError 與 readMissingScopeErrorDetails 由 @openclaw/gateway-protocol/gateway-error-details 匯出；瀏覽器安全的閘道用戶端會從 @openclaw/gateway-client/browser 重新匯出它們。

結構描述會從 @openclaw/gateway-protocol/schema 匯出為 GatewayErrorDetailsSchema、MissingScopeErrorDetailsSchema。 HTTP 範圍失敗會在 error.details 下鏡像 MISSING_SCOPE 物件，並使用 HTTP 狀態 403。

具有副作用的方法需要等冪鍵（請參閱結構描述）。

交握

閘道會傳送連線前挑戰：

{  "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；該項目可能會過期，因此節點會使用 { "surface": "canvas" } 呼叫 node.pluginSurface.refresh 以取得新的項目。 已棄用的 canvasHostUrl / canvasCapability / node.canvas.capability.refresh 路徑不受支援；請使用外掛介面。 快照中的選用 appliedConfigHash 是作用中 Gateway 執行階段所接受、解析後的來源設定修訂版本。用戶端可將其與 config.get.configRevisionHash 比較，以判斷較新的已儲存設定是否仍需重新啟動。config.get.hash 仍是設定寫入衝突防護所使用的原始根檔案修訂版本。

閘道仍在完成啟動附屬程序時，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 會驗證靜態雜湊、短效認證資訊；該認證資訊繫結至環境、套件組合雜湊、擁有者 epoch、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。

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

用戶端能力

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

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

用戶端能力描述的是已連線的用戶端，而非授權。代理程式工具可以宣告所需能力；除非所有需求都出現在來源用戶端的 caps 中，否則 Gateway 會省略這些工具。源自頻道的執行沒有 Gateway 用戶端能力，因此即使工具政策明確允許，受能力限制的工具仍無法使用。

節點連線範例

{  "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 發布其完整的 Skills 替代目錄。 這個節點角色方法是唯一的節點 Skills 發布途徑；connect 參數不接受 Skills。 每個描述元都包含安全的名稱、說明及有界的 SKILL.md 內容。閘道會使用一般的 Skills 載入器解析該內容，在節點連線期間將其納入代理程式 Skills 快照，並在中斷連線時將其移除。設定 gateway.nodes.allowSkills: false 可忽略節點發布的 Skills。

在線狀態

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

原生 macOS 節點也能傳送經驗證的 node.presence.activity 事件， 其中包含有界的輸入閒置時間。閘道會依自身時鐘推導活動時間戳記，透過 node.list 和 node.describe 公開最新連線的 Mac，並向具有讀取範圍的用戶端廣播 node.presence 更新。 當使用者停用活動分享時，應用程式會傳送 { "action": "clear" }； 閘道只會清除該特定已驗證節點連線的時間戳記。 早於這個已確認動作的閘道會將其傳回為未處理，因此 Mac 節點會重新連線一次，讓中斷連線清理移除舊的連線狀態。 如需選取、隱私權、模型 情境及通知路由行為，請參閱使用中電腦的在線狀態。

節點背景存活事件

節點會使用 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：使用者介面聊天更新，例如 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：喚醒詞觸發設定已變更。
• config.changed：設定寫入已持久保存（承載資料包含設定路徑、 新的快照雜湊和時間戳記，絕不包含設定內容）。範圍限定為操作員讀取； 用戶端透過 config.get 重新整理。
• exec.approval.requested / exec.approval.resolved：執行核准 生命週期。
• plugin.approval.requested / plugin.approval.resolved：外掛核准 生命週期。

節點輔助方法

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

稽核分類帳 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、選用的 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 回報執行階段是否接受或記錄了取消動作。

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）擷取代理程式的可見 Skills 清單。
  • 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 安裝。
  • 閘道安裝程式模式：{ 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.modelPolicy.allow， 回應為允許的目錄，包括針對 provider/* 項目動態探索到的模型。否則，回應為完整的閘道 目錄。
• "configured"：符合選擇器大小的行為。若已設定 agents.defaults.modelPolicy.allow， 它仍具有優先權，包括針對 provider/* 項目的提供者範圍探索。若沒有允許清單，回應會使用明確的 models.providers.<provider>.models 項目，且僅在沒有已設定的模型資料列時，才會退回使用完整 目錄。
• "provider-config"：由來源編寫的 models.providers.*.models 清單， 不受選擇器允許清單影響。資料列包含公開模型功能和 可感知路由的可用性，但省略提供者端點、驗證資料及 執行階段請求設定。
• "all"：完整的閘道目錄，繞過 agents.defaults.modelPolicy.allow。用於 診斷／探索 UI，而非一般模型選擇器。

執行核准

• 當 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 允許在無法解析出可對外傳遞的路由時， 備援為僅限工作階段的執行（例如內部/webchat 工作階段或有歧義的多頻道設定）。
• 要求傳遞時，最終的 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 的請求，或有限期限與無期限請求的混合，都會讓偵測監控程式保持啟用。 若傳入事件與回應持續靜默並超過偵測逾時門檻，用戶端會使用代碼 4000 關閉通訊端、拒絕所有待處理請求，並重新連線。重新連線後不會 重新執行遭拒絕的請求。

驗證

• 共用密鑰閘道驗證會使用 connect.params.auth.token 或 connect.params.auth.password，取決於已設定的 gateway.auth.mode（"none" | "token" | "password" | "trusted-proxy"）。
• 具備身分資訊的模式，例如 Tailscale Serve（gateway.auth.allowTailscale: true） 或非回送的 gateway.auth.mode: "trusted-proxy"，會透過請求標頭滿足連線 驗證檢查，而非使用 connect.params.auth.*。
• 私人輸入的 gateway.auth.mode: "none" 會完全略過共用密鑰連線驗證； 請勿在公開或不受信任的輸入上公開此模式。
• 配對完成後，閘道會核發範圍限定於連線 角色與範圍的裝置權杖，並在 hello-ok.auth.deviceToken 中傳回。用戶端應在 任何成功連線後將其持久保存。
• 使用已儲存的裝置權杖重新連線時，也應重複使用該權杖已儲存且 獲核准的範圍集合。這會保留已授予的讀取／探查／狀態存取權， 並避免重新連線在未告知的情況下縮減為更狹窄的 隱含僅限管理員範圍。
• 用戶端連線驗證組裝（selectConnectAuth，位於 packages/gateway-client/src/client.ts）：
  • 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.auth.mode: "trusted-proxy" 操作者 Control UI 驗證。
  • 在保留的內部輔助路徑上，直接回送的 gateway-client 後端 RPC。
• 省略裝置身分會影響範圍。當不具裝置資訊的 操作者連線經由明確的信任路徑獲准時，除非該路徑具有 指定的範圍保留例外，OpenClaw 仍會將自行宣告的範圍清除為空集合。 受範圍管控的方法隨後會以 missing scope 失敗。
• 保留的直接回送 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）， 除了裝置／用戶端／角色／範圍／權杖／nonce 欄位外，也會繫結 platform 與 deviceFamily。
• 為了相容性，仍接受舊版 v2 簽章，但已配對裝置的 中繼資料固定機制仍會控制重新連線時的命令政策。

TLS 與固定指紋

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

範圍

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

相關內容

• 建置閘道用戶端
• 嵌入 OpenClaw
• 橋接通訊協定
• 閘道操作手冊