> ## 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.

# 偵錯

串流輸出、閘道反覆開發及啟動效能分析的偵錯輔助工具。

## 執行階段偵錯覆寫

`/debug` 會設定**僅限執行階段**的設定覆寫（儲存於記憶體，而非磁碟）。預設停用；請使用 `commands.debug: true` 啟用。

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/debug show
/debug set channels.whatsapp.responsePrefix="[openclaw]"
/debug unset channels.whatsapp.responsePrefix
/debug reset
```

`/debug reset` 會清除所有覆寫並恢復使用磁碟上的設定。

## 工作階段追蹤輸出

`/trace` 可顯示單一工作階段中由外掛產生的追蹤／偵錯行，而無須啟用完整詳細模式。可用於外掛診斷，例如主動記憶偵錯摘要；一般狀態／工具輸出請使用 `/verbose`。

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/trace
/trace on
/trace off
```

## 外掛生命週期追蹤

設定 `OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1`，即可逐階段檢視外掛中繼資料、探索、登錄、執行階段鏡像、設定變更及重新整理作業的細目。輸出會寫入 stderr，因此 JSON 命令輸出仍可解析。
啟用此追蹤時，外掛載入失敗訊息會包含其堆疊追蹤。

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force
```

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
[plugins:lifecycle] phase="config read" ms=6.83 status=ok command="install"
[plugins:lifecycle] phase="slot selection" ms=94.31 status=ok command="install" pluginId="tokenjuice"
[plugins:lifecycle] phase="registry refresh" ms=51.56 status=ok command="install" reason="source-changed"
```

請先使用此功能，再考慮使用 CPU 效能分析器。若從原始碼簽出版本執行，請在 `pnpm build` 之後使用 `node dist/entry.js ...` 測量建置後的執行階段；`pnpm openclaw ...` 也會測量原始碼執行器的額外負擔。

若要測量同步模組載入時間，請使用共用診斷介面，而非另外設定僅限外掛的環境變數：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_DIAGNOSTICS=plugin.load-profile openclaw plugins list
```

## 命令列介面啟動與命令效能分析

已簽入版本庫的啟動基準測試：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm test:startup:bench:smoke
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
```

若要透過一般原始碼執行器進行一次性效能分析，請設定 `OPENCLAW_RUN_NODE_CPU_PROF_DIR`：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status
```

原始碼執行器會加入 Node CPU 效能分析旗標，並為該命令寫入一個 `.cpuprofile`。請先使用此方式，再考慮在命令程式碼中加入暫時性的檢測程式碼。

對於看似由同步檔案系統或模組載入器作業造成的啟動停滯，可透過原始碼執行器加入 Node 的同步 I/O 追蹤旗標：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force
```

`pnpm gateway:watch` 預設會讓受監看閘道子程序停用此旗標；若也想在監看模式中取得同步 I/O 追蹤輸出，請設定 `OPENCLAW_TRACE_SYNC_IO=1`。

## 閘道監看模式

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch
```

預設情況下，此命令會啟動或重新啟動名為 `openclaw-gateway-watch-<profile>` 的 tmux 工作階段（例如 `openclaw-gateway-watch-main`）；只有當 `OPENCLAW_GATEWAY_PORT` 與預設連接埠 `18789` 不同時，才會加入如 `openclaw-gateway-watch-dev-19001` 的連接埠後綴。在互動式終端機中會自動附加；非互動式 shell、CI 及代理程式 exec 呼叫則會保持分離，並改為印出附加操作指示：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
tmux attach -t openclaw-gateway-watch-main
# 在不附加的情況下讀取近期輸出
tmux capture-pane -ep -t openclaw-gateway-watch-main -S -200
```

窗格會使用 tmux `remain-on-exit`，因此啟動失敗資訊仍可供附加或擷取，而不會刪除工作階段。重新執行 `pnpm gateway:watch` 會重新產生該窗格。

tmux 窗格會執行原始監看器：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
node scripts/watch-node.mjs gateway --force
```

在開始監看已設定／預設的連接埠之前，tmux 包裝器會停止目前設定檔中作用中的已安裝閘道服務。如此便可將連接埠交給原始碼監看器，而不會由 launchd、systemd 或 Scheduled Task 重新產生程序並加以取代。服務仍會保持安裝；監看工作階段結束後，請使用以下命令將其還原：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm openclaw gateway start
```

當明確指定的 `--port` 或 `OPENCLAW_GATEWAY_PORT` 與已安裝服務的有效連接埠不同時，包裝器會讓該服務繼續執行，使兩個閘道可並行運作。

不使用 tmux 的前景模式：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch:raw
# 或
OPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch
```

原始模式不會管理已安裝的服務。若服務使用相同連接埠，請先執行 `pnpm openclaw gateway stop`。

保留 tmux 管理功能，但停用自動附加：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch
```

偵錯啟動／執行階段效能熱點時，分析受監看閘道的 CPU 時間：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --benchmark
```

監看包裝器會在叫用閘道前取用 `--benchmark`，並在每個閘道子程序結束時，於 `.artifacts/gateway-watch-profiles/` 下寫入一個 V8 `.cpuprofile`。停止或重新啟動受監看的閘道以寫出目前的效能分析檔，然後使用 Chrome DevTools 或 Speedscope 開啟：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile
```

* `--benchmark-dir <path>`：將效能分析檔寫入其他位置。
* `--benchmark-no-force`：略過預設的 `--force` 連接埠清理；若閘道連接埠已被占用，則立即失敗。

基準測試模式預設會抑制同步 I/O 追蹤的冗長輸出。設定 `OPENCLAW_TRACE_SYNC_IO=1` 與 `--benchmark`，即可同時取得 CPU 效能分析檔和同步 I/O 堆疊追蹤；在基準測試模式下，這些追蹤區塊會寫入基準測試目錄下的 `gateway-watch-output.log`（並從終端機窗格中濾除），一般閘道記錄則仍會顯示。

tmux 包裝器會將常用的非機密執行階段選擇器帶入窗格，包括 `OPENCLAW_PROFILE`、`OPENCLAW_CONFIG_PATH`、`OPENCLAW_STATE_DIR`、`OPENCLAW_GATEWAY_PORT` 及 `OPENCLAW_SKIP_CHANNELS`。請將供應商認證資訊存放於一般設定檔／設定中，或針對一次性的暫時機密資料使用原始前景模式。

如果受監看的閘道在啟動期間結束，監看器會執行一次 `openclaw doctor --fix --non-interactive`，然後重新啟動閘道子程序。設定 `OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0`，即可查看未經僅限開發環境修復流程處理的原始啟動失敗。

受管理的 tmux 窗格預設會顯示彩色閘道記錄；啟動 `pnpm gateway:watch` 時設定 `FORCE_COLOR=0`，即可停用 ANSI 輸出。

當 `src/` 下與建置相關的檔案、擴充功能原始碼檔案、擴充功能的 `package.json` 與 `openclaw.plugin.json` 中繼資料、`tsconfig.json`、`package.json` 及 `tsdown.config.ts` 發生變更時，監看器會重新啟動。擴充功能中繼資料變更會重新啟動閘道，但不會強制重新建置；原始碼和設定變更仍會先重新建置 `dist`。

將閘道命令列介面旗標加在 `gateway:watch` 之後，每次重新啟動時都會原樣傳遞。重新執行相同的監看命令會重新產生具名 tmux 窗格；原始監看器會維持單一監看器鎖定，因此重複的監看器父程序會被取代，而不會持續累積。

## 開發設定檔 + 開發閘道（--dev）

這裡有兩個**彼此獨立**的 `--dev` 旗標：

* \*\*全域 `--dev`（設定檔）：\*\*將狀態隔離於 `~/.openclaw-dev` 下，並將閘道連接埠預設為 `19001`（衍生連接埠會隨之位移）。
* \*\*`gateway --dev`：\*\*指示閘道在缺少預設設定與工作區時自動建立（並略過啟動程序）。

建議流程（開發設定檔 + 開發啟動程序）：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui
```

若未進行全域安裝，請透過 `pnpm openclaw ...` 執行命令列介面。

此流程會執行下列作業：

1. **設定檔隔離**（全域 `--dev`）
   * `OPENCLAW_PROFILE=dev`
   * `OPENCLAW_STATE_DIR=~/.openclaw-dev`
   * `OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json`
   * `OPENCLAW_GATEWAY_PORT=19001`（瀏覽器／畫布連接埠也會相應位移）

2. **開發啟動程序**（`gateway --dev`）
   * 若設定不存在，則寫入最小設定（`gateway.mode=local`，繫結至回送介面）。
   * 將 `agents.defaults.workspace` 設為開發工作區及 `agents.defaults.skipBootstrap=true`。
   * 若工作區檔案不存在，則建立初始檔案：`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`。
   * 預設身分：**C3-PO**（禮儀機器人）。
   * `pnpm gateway:dev` 也會設定 `OPENCLAW_SKIP_CHANNELS=1`，以略過頻道供應商。

開發閘道預設會忽略環境中的頻道觸發條件，因此從 shell 繼承的認證資訊不會讓開發執行個體連線至實際頻道服務。明確的 `channels.<id>` 設定仍可正常運作。搭配 `--dev` 傳入 `--dev-ambient-channels`，即可在該次執行中恢復依據環境自動設定頻道的功能。

重設流程（全新開始）：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:dev:reset
```

<Note>
  `--dev` 是**全域**設定檔旗標，某些執行器會將其取用。如果需要明確指定，請改用環境變數形式：

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  OPENCLAW_PROFILE=dev openclaw gateway --dev --reset
  ```
</Note>

`--reset` 會清除設定、認證資訊、工作階段及開發工作區（移至垃圾桶，而非刪除），然後重新建立預設開發環境。

<Tip>
  如果非開發用閘道已在執行（launchd 或 systemd），請先將其停止：

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  openclaw gateway stop
  ```
</Tip>

## 原始串流記錄

OpenClaw 可在進行任何篩選／格式化之前，記錄**原始助理串流**。這是確認推理內容究竟以純文字差異片段到達，還是以獨立思考區塊到達的最佳方式。

透過命令列介面啟用：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --raw-stream
```

選用的路徑覆寫：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl
```

對應的環境變數：

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl
```

預設檔案：`~/.openclaw/logs/raw-stream.jsonl`

## 安全注意事項

* 原始串流記錄可能包含完整提示、工具輸出及使用者資料。
* 請將記錄保留在本機，並在偵錯完成後刪除。
* 若要分享記錄，請先移除機密資料及個人識別資訊。

## 在 VSCode 中偵錯

由於建置程序會對產生的檔名進行雜湊，因此必須使用原始碼對應。內附的 `launch.json` 以閘道服務為目標：

1. **重新建置並偵錯閘道** - 刪除 `/dist`，並在啟動閘道前啟用偵錯功能重新建置。
2. **偵錯閘道** - 對現有建置進行偵錯，而不變更 `/dist`。

### 設定

1. 開啟 **Run and Debug**（Activity Bar，或 `Ctrl`+`Shift`+`D`）。
2. 選取 **Rebuild and Debug Gateway**，然後按下 **Start Debugging**。

若要改為手動管理建置／偵錯週期：

1. 在終端機中啟用原始碼對應：
   * **Linux/macOS**：`export OUTPUT_SOURCE_MAPS=1`
   * **Windows (PowerShell)**：`$env:OUTPUT_SOURCE_MAPS="1"`
   * **Windows (CMD)**：`set OUTPUT_SOURCE_MAPS=1`
2. 重新建置：`pnpm clean:dist && pnpm build`
3. 選取 **Debug Gateway**，然後按下 **Start Debugging**。

請在 `src/` TypeScript 檔案中設定中斷點；偵錯工具會透過原始碼對應將它們對應至已編譯的 JavaScript。

### 注意事項

* **重新建置並偵錯閘道**會刪除 `/dist`，並在每次啟動時執行已啟用原始碼對應的完整 `pnpm build`。
* **偵錯閘道**可在不影響 `/dist` 的情況下啟動／停止，但你必須在另一個終端機中管理建置週期。
* 編輯 `launch.json` 的 `args`，以偵錯其他命令列介面子命令。
* 若要使用建置後的命令列介面執行其他工作（例如，當偵錯工作階段產生新的驗證權杖時執行 `dashboard --no-open`），請從另一個終端機執行：`node ./openclaw.mjs`，或使用 `alias openclaw-build="node $(pwd)/openclaw.mjs"` 之類的別名。

## 相關內容

* [疑難排解](/zh-TW/help/troubleshooting)
* [常見問題](/zh-TW/help/faq)