嵌入 OpenClaw

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

關於用戶端驗證與重新連線狀態，請參閱 建置閘道用戶端。

使用嵌入預設集啟動子程序

使用真正的 node_modules 安裝，並啟動套件可執行檔。對於 自行管理探索、重新啟動及頻道生命週期的宿主，以下是實用的基準：

   // 提供由宿主應用程式管理之真正 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 殼層快照警告

殼層快照擷取會從登入殼層執行 process.execPath -e <script>。在 一般 Node 程序中，process.execPath 是 Node 可執行檔。在 Electron 下， 它是 Electron 二進位檔，可能會將此叫用解讀為啟動應用程式， 並顯示 "Unable to find Electron app" 彈出視窗。請在閘道子程序的環境中設定 OPENCLAW_EXEC_SHELL_SNAPSHOT=0，而不是只在 轉譯器程序中設定。基於相同原因，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、將套件扁平化至應用程式 套件組合中，或內嵌特定擴充功能檔案。

相關內容

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