English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Start here

除錯

除錯串流輸出的輔助工具，特別適用於供應商把推理混入一般文字時。

執行階段除錯覆寫

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

範例：

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

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

工作階段追蹤輸出

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

範例：

text
/trace/trace on/trace off

使用 /trace 查看外掛診斷資訊，例如主動記憶除錯摘要。 一般詳細狀態/工具輸出請繼續使用 /verbose，僅限執行階段的設定覆寫則繼續使用 /debug。

外掛生命週期追蹤

當外掛生命週期命令感覺緩慢，且你需要內建的階段拆解來檢視外掛中繼資料、探索、登錄檔、 執行階段鏡像、設定變更和重新整理工作時，請使用 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 分析器之前，先用這個調查外掛生命週期。 如果命令是從原始碼 checkout 執行，建議在 pnpm build 後用 node dist/entry.js ... 測量建置後的 執行階段；pnpm openclaw ... 也會測量原始碼 runner 的開銷。

命令列介面啟動與命令分析

當命令感覺很慢時，使用已納入版本控制的啟動基準測試：

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 會加入節點 CPU profile 旗標，並為該命令寫入 .cpuprofile。 在向命令程式碼加入暫時 instrumentation 之前，請先使用這個方法。

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

bash
OPENCLAW_TRACE_SYNC_IO=1 pnpm openclaw gateway --force

pnpm gateway:watch 預設會為被監看的閘道子程序停用此旗標。 當你明確想在 watch mode 中取得節點同步 I/O 追蹤輸出時，設定 OPENCLAW_TRACE_SYNC_IO=1。

閘道 watch mode

為了快速反覆開發，請在檔案 watcher 下執行閘道：

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 會執行原始 watcher：

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

在除錯啟動/執行階段熱點時，分析被監看的閘道 CPU 時間：

bash
pnpm gateway:watch --benchmark

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

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

如果你想把 profile 放在其他位置，使用 --benchmark-dir <path>。 如果你希望被基準測試的子程序跳過預設的 --force 連接埠清理，並在閘道連接埠已被使用時快速失敗，使用 --benchmark-no-force。 基準模式預設會抑制同步 I/O 追蹤雜訊。當你明確同時需要 CPU profile 和節點同步 I/O 堆疊追蹤時，搭配 --benchmark 設定 OPENCLAW_TRACE_SYNC_IO=1。在基準模式中，這些追蹤區塊會寫入基準目錄下的 gateway-watch-output.log，並從終端 pane 過濾掉；一般閘道日誌仍會顯示。

tmux wrapper 會將常見的非機密執行階段選擇器帶入 pane，例如 OPENCLAW_PROFILE、OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR、 OPENCLAW_GATEWAY_PORT 和 OPENCLAW_SKIP_CHANNELS。將供應商認證資料放在你的正常設定檔/設定中，或對一次性短暫秘密使用原始前景模式。 如果被監看的閘道在啟動期間退出，watcher 會執行一次 openclaw doctor --fix --non-interactive，然後重新啟動閘道子程序。 當你想看到原始啟動失敗，而不想經過僅限開發使用的修復流程時，使用 OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0。 受管理的 tmux pane 也預設使用彩色閘道日誌以提高可讀性； 啟動 pnpm gateway:watch 時設定 FORCE_COLOR=0 可停用 ANSI 輸出。

watcher 會在 src/ 下的建置相關檔案、extension 原始碼檔案、 extension package.json 和 openclaw.plugin.json 中繼資料、tsconfig.json、 package.json 以及 tsdown.config.ts 變更時重新啟動。Extension 中繼資料變更會重新啟動 閘道，但不強制 tsdown 重新建置；原始碼與設定變更仍會先重新建置 dist。

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

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

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

  • 全域 --dev（設定檔）： 將狀態隔離在 ~/.openclaw-dev 下，並將閘道連接埠預設為 19001（衍生連接埠會隨之位移）。
  • gateway --dev：告訴閘道在缺少時自動建立預設設定 + 工作區（並跳過 BOOTSTRAP.md）。

建議流程（開發設定檔 + 開發 bootstrap）：

bash
pnpm gateway:devOPENCLAW_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（browser/canvas 會相應位移）

  2. 開發 bootstrap（gateway --dev）

    • 如果缺少，寫入最小設定（gateway.mode=local，bind loopback）。
    • 將 agent.workspace 設為開發工作區。
    • 設定 agent.skipBootstrap=true（沒有 BOOTSTRAP.md）。
    • 如果缺少，植入工作區檔案： AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md。
    • 預設身分：C3-PO（禮儀機器人）。
    • 在開發模式中跳過頻道供應商（OPENCLAW_SKIP_CHANNELS=1）。

重設流程（全新開始）：

bash
pnpm gateway:dev:reset

--reset 會清除設定、認證資料、工作階段和開發工作區（使用 trash，不是 rm），然後重新建立預設開發設定。

原始串流記錄（OpenClaw）

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

透過命令列介面啟用：

bash
pnpm gateway:watch --raw-stream

選用路徑覆寫：

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

等效環境變數：

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

預設檔案：

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

原始 OpenAI-compatible chunk 記錄

若要在 raw OpenAI-compat chunks 被解析成 blocks 之前擷取它們，請啟用 transport logger：

bash
OPENCLAW_RAW_STREAM=1

選用路徑：

bash
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-openai-completions.jsonl

預設檔案：

~/.openclaw/logs/raw-openai-completions.jsonl

安全注意事項

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

在 VSCode 中除錯

需要 source maps 才能在 VSCode 型 IDE 中啟用除錯，因為許多產生的檔案在建置過程中會以雜湊名稱結尾。隨附的 launch.json 設定以閘道服務為目標，但可以快速調整為其他用途：

  1. 重新建置並除錯閘道 - 在建立新建置後除錯閘道服務
  2. 除錯閘道 - 除錯既有建置的閘道服務

設定

預設的 重新建置並除錯閘道 設定是完整內建的；它會自動刪除 /dist 資料夾，並在啟用除錯的情況下重新建置專案：

  1. 從 Activity Bar 開啟 Run and Debug 面板，或按 Ctrl+Shift+D
  2. 在 IDE 中，確認設定下拉選單已選取 重新建置並除錯閘道，然後按下 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 設定下拉選單選取 除錯閘道 選項，然後按下 Start Debugging 按鈕

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

注意事項

  • 如果使用 "重新建置並除錯閘道" 選項，每次啟動除錯器時，它都會在啟動閘道之前完整刪除 /dist 資料夾，並在啟用 source maps 的情況下執行完整 pnpm build
  • 如果使用 "除錯閘道" 選項，debug sessions 可以隨時啟動和停止，不會影響 /dist 資料夾，但你必須使用獨立的終端程序來同時啟用除錯並管理建置週期
  • 修改 launch.json 中 args 的設定，以除錯專案的其他區段
  • 如果你需要使用建置後的 OpenClaw 命令列介面處理其他工作（例如，如果你的 debug session 生成新的 auth token，使用 dashboard --no-open），你可以在另一個終端中以 node ./openclaw.mjs 執行它，或建立像 alias openclaw-build="node $(pwd)/openclaw.mjs" 這樣的 shell alias

相關

Was this useful?
On this page

On this page