> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 嵌入 OpenClaw

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

如需用戶端驗證與重新連線狀態的資訊，請閱讀
[建置閘道用戶端](https://docs.openclaw.ai/gateway/clients)。

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

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

```ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`、將套件扁平化至應用程式
套件組合，或內嵌選定的擴充功能檔案。

## 相關內容

* [建置閘道用戶端](https://docs.openclaw.ai/gateway/clients)
* [閘道協定](https://docs.openclaw.ai/gateway/protocol)
* [閘道命令列介面](https://docs.openclaw.ai/cli/gateway)
* [外部應用程式的閘道整合](https://docs.openclaw.ai/gateway/external-apps)