嵌入 OpenClaw

嵌入宿主應監督已安裝的 openclaw 可執行檔、使用 閘道 WebSocket 協定作為其控制平面，並將子程序視為可替換的 執行階段。如此可明確管理程序所有權、就緒狀態、故障復原 與升級，而不依賴 OpenClaw 的私有狀態配置。

如需用戶端驗證與重新連線狀態的資訊，請閱讀 建置閘道用戶端。

使用嵌入預設啟動子程序

請使用實際的 node_modules 安裝並啟動套件可執行檔。對於自行管理 探索、重新啟動與頻道生命週期的宿主，實用的基準設定如下：

import { spawn } from "node:child_process";import { dirname, resolve } from "node:path";import { fileURLToPath } from "node:url"; // 提供由宿主應用程式管理之實際 Node 執行階段的絕對路徑。declare const hostNodeExecutable: string; const packageEntry = fileURLToPath(import.meta.resolve("openclaw"));const openclawEntry = resolve(dirname(packageEntry), "..", "openclaw.mjs");const gateway = spawn(hostNodeExecutable, [openclawEntry, "gateway", "--allow-unconfigured"], {  env: {    ...process.env,    OPENCLAW_DISABLE_BONJOUR: "1",    OPENCLAW_EXEC_SHELL_SNAPSHOT: "0",    OPENCLAW_NO_RESPAWN: "1",    OPENCLAW_SKIP_CHANNELS: "1",  },  stdio: ["ignore", "inherit", "inherit"],});

請依照範例透過已安裝的套件解析 OpenClaw；不要假設宿主程序的 PATH 中存在專案本機的 openclaw 二進位檔。範例會 繼承輸出，避免子程序因 stdout 或 stderr 管線已滿而阻塞。如果宿主改為 擷取這些串流，請在啟動後立即附加消費端。

--allow-unconfigured 只會略過 gateway.mode=local 啟動防護。 它不會寫入設定或修復無效檔案。當嵌入應用程式透過初始設定流程、設定命令列介面 或閘道 RPC 佈建一般本機設定時，請省略此選項。

Electron shell 快照警告

Shell 快照擷取會從登入 shell 執行 process.execPath -e <script>。在 一般 Node 程序中，process.execPath 是 Node 可執行檔。在 Electron 下， 它是 Electron 二進位檔，可能會將該叫用解讀為啟動應用程式， 並顯示 "Unable to find Electron app" 彈出視窗。請在閘道子程序的環境中設定 OPENCLAW_EXEC_SHELL_SNAPSHOT=0，而不是只在 renderer 程序中設定。基於相同原因，hostNodeExecutable 必須指向 實際的 Node 執行階段，而非 Electron 的 process.execPath。

依結束代碼處理無效設定

閘道啟動會針對設定類別的啟動失敗（包括無效設定）使用結束代碼 78（EX_CONFIG）。請依結束代碼分支處理，而不要剖析 供人閱讀的 stderr：

1. 使用與閘道子程序相同的設定與 狀態環境執行 openclaw doctor --fix --yes --non-interactive。
2. doctor 成功結束後，重試啟動閘道一次。
3. 如果子程序再次以 78 結束，請停止修復迴圈，並向使用者呈現設定 失敗。

保留 stderr 以供診斷，但不要根據其中的措辭做出生命週期決策。

成功啟動後，無效的即時設定編輯所造成的破壞較小。 設定監看器會記錄已略過重新載入，並繼續使用最後接受的 記憶體內設定提供服務。修復檔案後，讓監看器接受下一個有效的 快照。

等待協定就緒

請使用 WebSocket 訊號，而不是比對記錄子字串：

1. 開啟閘道 WebSocket。
2. 等待 connect.challenge 事件。此事件證明接聽程式已接受 WebSocket，且挑戰交握可以開始。
3. 傳送 connect，並附上與挑戰綁定的裝置簽章。
4. 將 hello-ok 視為已驗證 RPC 的應用程式就緒訊號。

挑戰刻意早於完整初始化。如果啟動 附屬程序仍在等待中，connect 會傳回可重試的 UNAVAILABLE 錯誤，其中包含 details.reason: "startup-sidecars" 與有界的 retryAfterMs，接著以 代碼 1013 和原因 gateway starting 關閉。請使用 @openclaw/gateway-protocol/startup-unavailable 中的 resolveGatewayStartupRetryAfterMs 或參考用戶端的內建 原則，然後重新連線。

解讀重新啟動與關閉

在有序關閉前，閘道會廣播帶有 reason 與 restartExpectedMs 的 shutdown 事件。非 null 的 restartExpectedMs 表示預期會進行程序內或 受監督的重新啟動；null 表示終止性關閉。

這兩種情況後續的 WebSocket 關閉代碼皆為 1012。一般用戶端 在這兩種情況下的關閉原因也都是 service restart，因此關閉代碼與 原因都無法區分重新啟動和關閉。若先前的 shutdown 承載資料有送達，請予以保留，並將其與宿主本身的停止意圖及 子程序結束狀態結合判斷。如果連線在未收到事件的情況下中斷，請採用一般的 有界重新連線與子程序監督原則。

使用 RPC 而非狀態檔案

讓閘道成為 OpenClaw 狀態的唯一擁有者。常見的嵌入操作 已有對應的 RPC 方法：

config.get 會先遮蔽敏感值與 SecretRef 識別碼，再傳回 快照。寫入方法也會傳回已遮蔽的設定。用戶端必須將 遮蔽哨兵值視為不透明值，並使用有文件說明的設定寫入合約； 絕不可預期閘道傳回純文字祕密。

不要透過讀取或變更 ~/.openclaw 下的檔案、SQLite 資料表、 對話記錄檔案或快取目錄來實作應用程式功能。這些配置屬於私有的執行階段 實作細節，可能在不保持協定相容性的情況下移動或變更。

請安裝；不要扁平化

根 openclaw 套件不是單一檔案的內嵌目標。位於 dist/extensions 下的隨附執行階段檔案會保留 openclaw/plugin-sdk/* 等裸自我匯入，而 npm 套件刻意排除 各擴充功能的 node_modules 樹狀結構。

請透過 npm、pnpm 或其他一般 Node 套件安裝方式安裝 OpenClaw，讓 Node 可以解析套件匯出與根相依性樹。啟動已安裝的 openclaw 可執行檔。不要只複製 dist、將套件扁平化至應用程式 套件組合，或內嵌選定的擴充功能檔案。

相關內容

• 建置閘道用戶端
• 閘道協定
• 閘道命令列介面
• 外部應用程式的閘道整合