嵌入 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 管線已滿而阻塞。如果宿主改為 擷取這些串流，請在啟動後立即附加消費端。

設定	嵌入效果
OPENCLAW_DISABLE_BONJOUR=1	當宿主自行管理探索時，停用由閘道管理的區域網路多播公告。
OPENCLAW_NO_RESPAWN=1	在未受管理的嵌入子程序中，防止 OpenClaw 將更新重新啟動交給已卸離的子程序。例行重新啟動仍在程序內進行，因此宿主會保有受追蹤 PID 的所有權。
OPENCLAW_EXEC_SHELL_SNAPSHOT=0	停用宿主執行命令的登入 shell 快照擷取。
OPENCLAW_SKIP_CHANNELS=1	略過頻道啟動與重新載入。僅當嵌入應用程式需要純控制平面或僅限 WebChat 的閘道時才設定此值。

--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 方法：

工作階段	RPC 方法
工作階段目錄與生命週期	sessions.list、sessions.patch、sessions.delete
對話記錄顯示	chat.history
成本與用量報告	usage.cost、sessions.usage
模型認證資訊狀態	models.authStatus
設定	config.get、config.patch

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

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

​

請安裝；不要扁平化

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

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

​

相關內容

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