OpenClaw Debugging：掌握開發與排查的技巧

當你的程式碼出問題時，最痛苦的不是修復它，而是根本不知道發生了什麼事。眼看著模型輸出一堆亂碼，或者 Gateway 運作不如預期，你需要的不是猜測「應該」發生什麼，而是看清楚系統內部的「真實」運作狀況。

這些調試工具能讓你檢查原始的模型輸出、執行快速迭代循環，並將你的開發環境與正式環境完全隔離，避免弄亂生產數據。

需要準備的東西

• 已安裝 OpenClaw 的開發環境
• 在 config 中將 commands.debug 設為 true
• 終端機已安裝 pnpm

快速開始

想在 5 分鐘內開始調試？照著這幾步走：

1. 開啟指令權限：確保你的設定檔中開啟了 commands.debug: true。
2. 啟動監聽模式：在終端機執行 pnpm gateway:watch --force。
3. 即時修改設定：在聊天視窗輸入 /debug set messages.responsePrefix="[test]" 看看效果。
4. 查看原始輸出：加上 --raw-stream 參數來觀察模型回傳的每一絲細節。

---

執行時調試覆蓋 (Runtime Overrides)

你可以直接在聊天中使用 /debug 指令來修改設定，不需要手動編輯檔案再重啟：

/debug show                                    # 查看目前的覆蓋設定
/debug set messages.responsePrefix="[test]"    # 設定一個值
/debug unset messages.responsePrefix           # 移除覆蓋設定
/debug reset                                   # 清除所有覆蓋設定

注意： 這些設定僅儲存在記憶體中，重啟後就會消失。

Gateway Watch Mode

為了加快迭代速度，建議在執行 Gateway 時開啟檔案監控模式：

pnpm gateway:watch --force

當你儲存檔案時，Gateway 會自動重啟。這等同於執行：

tsx watch src/entry.ts gateway --force

Dev Profile（隔離狀態）

我強烈建議使用 dev profile 來隔離調試環境與正式環境：

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

Dev Profile 的特點：

• 狀態目錄位於 ~/.openclaw-dev
• Gateway Port 使用 19001
• 跳過 BOOTSTRAP.md 並建立最小化的預設設定
• 預設身份為 C3-PO (protocol droid)
• 跳過所有 channel providers

如果你想徹底重來，可以執行：

pnpm gateway:dev:reset

這會清除開發環境的設定、憑證與 session（使用 trash 刪除，而非 rm，相對安全）。

原始串流日誌 (Raw Stream Logging)

有時候你需要看到模型在經過任何過濾器之前的原始回傳內容，特別是當你想確認 reasoning 內容是否洩漏到一般文本時：

pnpm gateway:watch --force --raw-stream

預設路徑： ~/.openclaw/logs/raw-stream.jsonl

你也可以自定義路徑或使用環境變數：

# 自定義路徑
pnpm gateway:watch --force --raw-stream --raw-stream-path /custom/path.jsonl

# 使用環境變數
OPENCLAW_RAW_STREAM=1
OPENCLAW_RAW_STREAM_PATH=~/.openclaw/logs/raw-stream.jsonl

Raw Chunk Logging (pi-mono)

如果你需要擷取解析前的 OpenAI 相容 chunks：

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

環境變數參考

變數	說明
OPENCLAW_PROFILE=dev	使用開發 profile
OPENCLAW_STATE_DIR=~/.openclaw-dev	覆蓋狀態目錄路徑
OPENCLAW_GATEWAY_PORT=19001	覆蓋 Gateway Port
OPENCLAW_RAW_STREAM=1	啟用原始串流日誌
OPENCLAW_SKIP_CHANNELS=1	跳過 channel providers

疑難排解

• 推理內容洩漏到文本中？ 請使用 --raw-stream 模式啟動，檢查原始的 JSONL 日誌，確認模型回傳的格式是否正確。
• 開發環境設定亂掉了？ 執行 pnpm gateway:dev:reset 快速重置到初始狀態。
• 安全性提醒： 原始串流日誌可能包含 Prompt、工具輸出與使用者個資。請務必將日誌留在本地，並在調試結束後刪除。在分享日誌前，請記得遮蔽金鑰與 PII。

如果你仍然遇到問題，我們的 AI Setup Assistant 可以幫你診斷設定。

下一步

• Logging → — 檔案日誌與控制台輸出細節
• Testing → — 測試套件與實時測試指南
• Gateway Configuration → — 完整的設定參數參考
• OpenClaw Discord — 加入社群獲取即時協助