English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Start here

偵錯

Edit source

串流輸出的偵錯輔助工具，特別適用於提供者將推理混入一般文字時。

執行階段偵錯覆寫

在聊天中使用 /debug 來設定僅限執行階段的設定覆寫（記憶體，不寫入磁碟）。 /debug 預設為停用；使用 commands.debug: true 啟用。 當你需要切換冷門設定而不想編輯 openclaw.json 時，這很方便。

範例：

Code
/debug show/debug set messages.responsePrefix="[openclaw]"/debug unset messages.responsePrefix/debug reset

/debug reset 會清除所有覆寫，並回到磁碟上的設定。

工作階段追蹤輸出

當你想在單一工作階段中查看 Plugin 擁有的追蹤/偵錯行， 但不想開啟完整詳細模式時，請使用 /trace。

範例：

text
/trace/trace on/trace off

使用 /trace 進行 Plugin 診斷，例如 Active Memory 偵錯摘要。 一般詳細狀態/工具輸出請繼續使用 /verbose，僅限執行階段的設定覆寫則繼續使用 /debug。

Plugin 生命週期追蹤

當 Plugin 生命週期命令感覺緩慢，而你需要內建的階段拆解來檢查 Plugin 中繼資料、探索、登錄、 執行階段鏡像、設定變更與重新整理工作時，請使用 OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1。 追蹤是選擇性啟用，並寫入 stderr，因此 JSON 命令輸出仍可解析。

範例：

bash
OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

輸出範例：

text
[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 分析器之前，先用這個調查 Plugin 生命週期。 如果命令是從原始碼 checkout 執行，請在 pnpm build 後優先用 node dist/entry.js ... 測量建置後的 執行階段；pnpm openclaw ... 也會測到原始碼 runner 的額外成本。

CLI 啟動與命令分析

當命令感覺很慢時，使用已提交的啟動基準測試：

bash
pnpm test:startup:bench:smokepnpm tsx scripts/bench-cli-startup.ts --preset real --case status --runs 3pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu

若要透過一般原始碼 runner 進行一次性分析，請設定 OPENCLAW_RUN_NODE_CPU_PROF_DIR：

bash
OPENCLAW_RUN_NODE_CPU_PROF_DIR=.artifacts/cli-cpu pnpm openclaw status

原始碼 runner 會加入 Node CPU profile 旗標，並為該命令寫入 .cpuprofile。 在替命令程式碼加入暫時性 instrumentation 之前，先使用這個方法。

對於看起來像同步檔案系統或模組載入器工作的啟動停滯，請透過原始碼 runner 加入 Node 的同步 I/O 追蹤旗標：

bash
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch 預設會讓受監看 Gateway 子程序停用此旗標。 當你明確想在監看模式中取得 Node 同步 I/O 追蹤輸出時，請設定 OPENCLAW_TRACE_SYNC_IO=1。

Gateway 監看模式

若要快速迭代，請在檔案監看器下執行 Gateway：

bash
pnpm gateway:watch

預設情況下，這會啟動或重新啟動名為 openclaw-gateway-watch-main 的 tmux 工作階段（或設定檔/連接埠專用的變體，例如 openclaw-gateway-watch-dev-19001），並從互動式終端機自動附加。 非互動式 shell、CI 和 agent exec 呼叫會保持分離，改為列印附加指示。 需要時可手動附加：

bash
tmux attach -t openclaw-gateway-watch-main

tmux pane 會執行原始監看器：

bash
node scripts/watch-node.mjs gateway --force

不想使用 tmux 時，請使用前景模式：

bash
pnpm gateway:watch:raw# orOPENCLAW_GATEWAY_WATCH_TMUX=0 pnpm gateway:watch

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

bash
OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch

在偵錯啟動/執行階段熱點時，分析受監看 Gateway 的 CPU 時間：

bash
pnpm gateway:watch --benchmark

監看 wrapper 會在叫用 Gateway 前消耗 --benchmark，並在 .artifacts/gateway-watch-profiles/ 下，為每次 Gateway 子程序結束寫入一個 V8 .cpuprofile。 停止或重新啟動受監看的 gateway 以 flush 目前 profile，然後用 Chrome DevTools 或 Speedscope 開啟：

bash
npx speedscope .artifacts/gateway-watch-profiles/*.cpuprofile

當你想把 profile 放到其他地方時，使用 --benchmark-dir <path>。 當你希望被基準測試的子程序略過預設的 --force 連接埠清理，並在 Gateway 連接埠已被使用時快速失敗，使用 --benchmark-no-force。 基準測試模式預設會抑制同步 I/O 追蹤雜訊。當你明確想同時取得 CPU profile 和 Node 同步 I/O stack trace 時，搭配 --benchmark 設定 OPENCLAW_TRACE_SYNC_IO=1。在基準測試模式中，這些追蹤區塊會寫入基準目錄下的 gateway-watch-output.log，並從終端機 pane 中過濾；一般 Gateway 記錄仍會可見。

tmux wrapper 會將常見的非祕密執行階段選擇器帶入 pane，例如 OPENCLAW_PROFILE、OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、 OPENCLAW_GATEWAY_PORT 和 OPENCLAW_SKIP_CHANNELS。請把 提供者認證放在一般 profile/config 中，或針對一次性的暫時祕密使用原始前景模式。 如果受監看的 Gateway 在啟動期間結束，監看器會執行一次 openclaw doctor --fix --non-interactive，並重新啟動 Gateway 子程序。 當你想保留原始啟動失敗，而不要開發專用修復流程時，使用 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0。 受管理的 tmux pane 也預設使用彩色 Gateway 記錄以提升可讀性；啟動 pnpm gateway:watch 時設定 FORCE_COLOR=0 可停用 ANSI 輸出。

監看器會在 src/ 下的建置相關檔案、extension 原始碼檔案、 extension package.json 和 openclaw.plugin.json 中繼資料、tsconfig.json、 package.json 與 tsdown.config.ts 變更時重新啟動。Extension 中繼資料變更會在不強制 tsdown 重建的情況下重新啟動 gateway；原始碼與設定變更仍會先重建 dist。

在 gateway:watch 後加入任何 gateway CLI 旗標，它們會在每次重新啟動時傳遞。 重新執行相同的監看命令會重新產生具名 tmux pane，而原始監看器仍會保留其單一監看器鎖， 因此重複的監看器父程序會被取代，而不是累積。

開發 profile + 開發 Gateway（--dev）

使用開發 profile 隔離狀態，並啟動安全、可拋棄的設定來進行偵錯。 有兩個 --dev 旗標：

  • 全域 --dev（profile）： 會將狀態隔離在 ~/.openclaw-dev 下，並將 gateway 連接埠預設為 19001（衍生連接埠會隨之位移）。
  • gateway --dev：告訴 Gateway 在缺少時自動建立預設 config + workspace（並略過 BOOTSTRAP.md）。

建議流程（開發 profile + 開發 bootstrap）：

bash
pnpm gateway:devOPENCLAW_PROFILE=dev openclaw tui

如果你尚未全域安裝，請透過 pnpm openclaw ... 執行 CLI。

這會做的事：

  1. Profile 隔離（全域 --dev）

    • OPENCLAW_PROFILE=dev
    • OPENCLAW_STATE_DIR=~/.openclaw-dev
    • OPENCLAW_CONFIG_PATH=~/.openclaw-dev/openclaw.json
    • OPENCLAW_GATEWAY_PORT=19001（browser/canvas 會相應位移）

  2. 開發 bootstrap（gateway --dev）

    • 若缺少則寫入最小設定（gateway.mode=local、bind loopback）。
    • 將 agent.workspace 設為開發 workspace。
    • 設定 agent.skipBootstrap=true（無 BOOTSTRAP.md）。
    • 若缺少則植入 workspace 檔案： AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md。
    • 預設身分：C3-PO（禮儀機器人）。
    • 在開發模式中略過 channel providers（OPENCLAW_SKIP_CHANNELS=1）。

重設流程（全新開始）：

bash
pnpm gateway:dev:reset

--reset 會清除 config、credentials、sessions 和開發 workspace（使用 trash，不是 rm），然後重新建立預設開發設定。

原始串流記錄（OpenClaw）

OpenClaw 可以在任何過濾/格式化之前記錄原始 assistant stream。 這是查看推理是否以純文字 delta 抵達（或以獨立 thinking block 抵達）的最佳方式。

透過 CLI 啟用：

bash
pnpm gateway:watch --raw-stream

選用路徑覆寫：

bash
pnpm gateway:watch --raw-stream --raw-stream-path ~/.openclaw/logs/raw-stream.jsonl

等效 env vars：

bash
OPENCLAW_RAW_STREAM=1OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

預設檔案：

~/.openclaw/logs/raw-stream.jsonl

原始 chunk 記錄（pi-mono）

若要在 raw OpenAI-compat chunks 被解析成 blocks 之前擷取它們， pi-mono 提供一個獨立 logger：

bash
PI_RAW_STREAM=1

選用路徑：

bash
PI_RAW_STREAM_PATH=~/.pi-mono/logs/raw-openai-completions.jsonl

預設檔案：

~/.pi-mono/logs/raw-openai-completions.jsonl

注意：這只會由使用 pi-mono 的 openai-completions provider 的程序發出。

安全注意事項

  • 原始串流記錄可能包含完整 prompts、工具輸出與使用者資料。
  • 將記錄保留在本機，並在偵錯後刪除。
  • 如果你分享記錄，請先清除 secrets 和 PII。

在 VSCode 中偵錯

在 VSCode 系列 IDE 中啟用偵錯需要 source maps，因為許多產生的檔案在建置流程中最終會帶有 hashed names。內含的 launch.json 設定以 Gateway 服務為目標，但可以快速調整用於其他目的：

  1. 重建並偵錯 Gateway - 建立新建置後偵錯 Gateway 服務
  2. 偵錯 Gateway - 偵錯既有建置的 Gateway 服務

設定

預設的 重建並偵錯 Gateway 設定已包含必要項目，會自動刪除 /dist 資料夾，並在啟用偵錯的情況下重新建置專案：

  1. 從 Activity Bar 開啟 Run and Debug 面板，或按 Ctrl+Shift+D
  2. 在 IDE 中，確認設定下拉選單已選取 重建並偵錯 Gateway，然後按下 Start Debugging 按鈕

或者，如果你偏好手動管理建置和偵錯流程：

  1. 開啟終端機並啟用 source maps：
    • 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. 在 IDE 中，在 Run and Debug 設定下拉選單中選取 偵錯 Gateway 選項，然後按下 Start Debugging 按鈕

你現在可以在 TypeScript 原始碼檔案（src/ 目錄）中設定中斷點，debugger 會透過 source maps 正確地將中斷點對應到編譯後的 JavaScript。你將能如預期檢查變數、逐步執行程式碼，並檢查呼叫堆疊。

注意事項

  • 如果使用 "重建並偵錯 Gateway" 選項，每次啟動 debugger 時，都會完整刪除 /dist 資料夾，並在啟用 source maps 的情況下執行完整 pnpm build，然後才啟動 Gateway
  • 如果使用 "偵錯 Gateway" 選項，偵錯工作階段可以隨時啟動和停止，且不會影響 /dist 資料夾，但你必須使用獨立的終端機程序來同時啟用偵錯並管理建置循環
  • 修改 launch.json 的 args 設定，以偵錯專案的其他區段
  • 如果你需要使用建置後的 OpenClaw CLI 執行其他任務（例如，如果你的偵錯工作階段產生新的 auth token，則執行 dashboard --no-open），你可以在另一個終端機中以 node ./openclaw.mjs 執行，或建立 shell alias，例如 alias openclaw-build="node $(pwd)/openclaw.mjs"

相關

Was this useful?