OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

RPC and API

外部應用程式的閘道整合

外部應用程式透過閘道協定與 OpenClaw 通訊：使用 WebSocket 傳輸加上 RPC 方法。當指令碼、儀表板、CI 作業、IDE 擴充功能或其他程序需要啟動代理程式執行、串流事件、等待結果、取消工作或檢查閘道資源時，請使用此協定。

目前可用的功能

介面 狀態 用途
閘道協定 可用 WebSocket 傳輸、連線交握、驗證範圍、協定版本控制及事件。
閘道 RPC 參考 可用 目前適用於代理程式、工作階段、任務、模型、工具、成品及核准的閘道方法。
openclaw agent 可用 當透過殼層呼叫命令列介面已足夠時，用於單次指令碼整合。
openclaw message 可用 從指令碼傳送訊息或頻道動作。

未來的用戶端程式庫套件目前正在內部開發，但尚未成為公開的安裝介面。在版本發布資訊宣布已有公開且具版本控制的套件之前，請將其視為預覽階段的實作細節。

建議流程

  1. 執行或探索閘道。
  2. 透過閘道協定連線。
  3. 呼叫閘道 RPC 參考中已有文件說明的 RPC 方法。
  4. 鎖定測試時使用的 OpenClaw 版本。
  5. 升級 OpenClaw 時，重新查看 RPC 參考。

若要執行代理程式，請先使用 agent RPC，並搭配 agent.wait 取得最終結果。若需要持久的對話狀態，請使用 sessions.* 方法。若要進行使用者介面整合，請訂閱閘道事件，並僅呈現應用程式能理解的事件類別。

協作式主機暫停

凍結或建立執行中程序快照的託管控制器，可以使用不限定主機類型的暫停交握：

  1. 停止接受由主機控制的外部傳入流量。
  2. 使用穩定且唯一的 requestId 呼叫 gateway.suspend.prepare。
  3. 若回應為 busy，請讓程序繼續執行，稍後再重試。
  4. 若回應為 ready，請儲存傳回的 suspensionId，然後在 expiresAtMs 之前凍結程序或建立其快照。
  5. 解凍後，或放棄暫停時，透過現有的 WebSocket 或管理 HTTP 控制路徑，使用該 suspensionId 呼叫 gateway.suspend.resume。

已準備暫停的閘道會拒絕新的 WebSocket 交握。WebSocket 控制器必須在主機作業期間保持其已驗證連線開啟。若無法保證這一點，請在準備暫停之前啟用並使用管理 HTTP RPC 外掛。若控制路徑中斷，請等待兩分鐘的租約到期後再重新連線；到期時會自動重新開放連入。

RPC 合約如下：

  • gateway.suspend.prepare — operator.admin；參數 { "requestId": "stable-host-operation-id" }
  • gateway.suspend.status — operator.read；參數 { "suspensionId": "id-from-prepare" }
  • gateway.suspend.resume — operator.admin；參數 { "suspensionId": "id-from-prepare" }

識別碼會移除前後空白，必須包含至少一個非空白字元，且長度上限為 128 個字元。忙碌中的準備結果包含 status: "busy"、reason、retryAfterMs、activeCount 和 blockers。就緒結果的格式如下：

json
{  "status": "ready",  "suspensionId": "2c3f...",  "expiresAtMs": 1770000000000,  "activeCount": 0,  "blockers": []}

狀態查詢會傳回 {"status":"running"}，或包含 expiresAtMs 的就緒結果。恢復會傳回 {"ok":true,"status":"running","resumed":true}；成功恢復後再次呼叫則會傳回 resumed: false。

相衝突的要求識別碼或暫時性的排程器恢復失敗，會傳回可重試的 UNAVAILABLE，並包含 retryAfterMs。排程器恢復期間，準備、狀態與恢復都會傳回此錯誤；閘道會維持未就緒並採取失敗關閉策略，主機不得凍結閘道或建立其快照。OpenClaw 會自動重試排程器，且只會在恢復成功後重新開放連入。不相符的恢復識別碼會傳回 INVALID_REQUEST。準備作業與閘道共用每分鐘三次嘗試的控制平面寫入額度；請遵守傳回的重試延遲。WebSocket 用戶端會依裝置與 IP 分組計算額度。管理 HTTP 控制器會依解析出的用戶端 IP 分組，因此位於同一個 Proxy 後方的控制器可能共用額度。

準備作業只會拒絕新工作：OpenClaw 會關閉新的根層級、工作階段與命令連入、暫停自動排程觸發，並同步檢查工作。若有任何工作正在進行，它會先恢復排程器並重新開放連入，再傳回 busy；不會中斷或排空該工作。就緒租約會維持兩分鐘。使用相同的 requestId 重複呼叫 prepare 會續約；租約到期時，會先恢復排程器再重新開放連入。 在就緒租約期間到期而應觸發的重新啟動動作，會等到租約恢復後才執行；若重新啟動正在進行，準備作業會傳回 busy。

處於就緒狀態時，/healthz 仍維持存活，而 /readyz 會傳回 503。本機或已驗證的就緒回應會包含 gateway-draining；未經驗證的遠端探測只會收到 { "ready": false }。HTTP 健康狀態探測、現有 WebSocket 連線上的暫停方法，以及已啟用的管理 HTTP RPC 路由仍可使用。其他 RPC 會傳回可重試的 UNAVAILABLE。內建 HTTP 使用者工作路由與一般外掛 HTTP 路由，包括與 OpenAI 相容的 API、工具／工作階段操作、節點監看及已設定的網路鉤子，都會傳回 503，並包含 error.code: "gateway_unavailable"。外掛擁有的新 WebSocket 升級也會傳回 503；這涵蓋升級的所有權，不涵蓋稍後透過已建立之外掛通訊端執行的工作。

此交握不會持久保存傳入訊息、停止第三方頻道傳輸，或控制託管平台。主機必須在準備前封鎖其傳入流量，且仍須負責喚醒、建立快照／凍結及停止。activeCount 是追蹤中工作的總計數，而 blockers 則包含非零類別計數及數量受限的任務詳細資料。這不是通用的程序靜止屏障。background-exec 阻擋項目僅提供彙總資訊：命令文字、程序識別碼、輸出，以及工作階段或範圍識別碼絕不會跨越此協定傳輸。頻道健康狀態、維護、快取重新整理、已建立的外掛 WebSocket 工作階段，以及未註冊且由外掛擁有的背景工作，仍可能保持活動。 託管平台必須以一致的方式凍結完整的程序樹及其檔案系統，或建立其快照；此初始合約無法證明未註冊的工作已閒置。

應用程式碼與外掛程式碼

當程式碼位於 OpenClaw 外部時，請使用閘道 RPC：

  • 啟動或觀察代理程式執行的節點指令碼
  • 呼叫閘道的 CI 作業
  • 儀表板與管理面板
  • IDE 擴充功能
  • 不需要成為頻道外掛的外部橋接器
  • 使用模擬或真實閘道傳輸的整合測試

當程式碼在 OpenClaw 內部執行時，請使用外掛 SDK：

  • 供應商外掛
  • 頻道外掛
  • 工具或生命週期鉤子
  • 代理程式執行框架外掛
  • 受信任的執行階段輔助工具

外部應用程式不應匯入 openclaw/plugin-sdk/*；這些子路徑供 OpenClaw 載入的外掛使用。

相關內容

Was this useful?
On this page

On this page