Debugging 指南：別再對著 AI 串流發呆

寫 AI 應用最頭痛的就是處理串流輸出。有時候 Provider 會把思考過程（reasoning）跟一般文字混在一起吐出來，讓畫面亂成一團。如果不清楚底層到底傳了什麼，修 Bug 就像在瞎子摸象，完全不知道是你的程式碼寫錯，還是模型輸出不聽話。

這份指南會介紹 OpenClaw 內建的偵錯工具，讓你直接看透資料流，快速搞定那些煩人的串流問題。

需要準備的東西

• 已安裝 OpenClaw 專案
• pnpm 套件管理器
• 基本的 Terminal 操作經驗

Quick Start：5 分鐘開啟偵錯模式

最快的方法是在 Chat 中直接使用 /debug 指令。這能讓你修改「運行時（Runtime）」的設定，而不會動到硬碟裡的設定檔。

1. 啟用指令：確保 openclaw.json 中設定了 commands.debug: true。
2. 進入 Chat：在對話框輸入 /debug show 查看當前設定。
3. 即時修改：

   /debug set messages.responsePrefix="[openclaw]"

4. 重置：輸入 /debug reset 就會清空所有暫時修改，回到原本的設定。

---

Gateway Watch Mode

如果你正在修改程式碼，頻繁手動重啟 Gateway 會讓人瘋掉。推薦使用檔案監聽模式，只要存檔就會自動重跑：

pnpm gateway:watch --force

這條指令背後跑的是 tsx watch。如果你有額外的 CLI flags，直接加在後面即可，它們會在每次重啟時自動帶入。

使用開發 Profile (—dev)

為了不弄亂你原本的設定，我建議在偵錯時使用隔離的開發環境。OpenClaw 提供了兩個層級的 --dev 標籤：

1. 全域 --dev (Profile)：將狀態儲存在 ~/.openclaw-dev，並將 Gateway Port 改為 19001。
2. gateway --dev：告訴 Gateway 如果找不到設定檔就自動建立一個預設的 Workspace（並跳過 BOOTSTRAP.md）。

推薦的開發流程：

pnpm gateway:dev
OPENCLAW_PROFILE=dev openclaw tui

這會幫你建立一個以 C3-PO 為預設身分的環境，並自動產生 AGENTS.md、SOUL.md 等核心文件。如果你想徹底重來，可以用這個指令清空一切（使用 trash 刪除，比較安全）：

pnpm gateway:dev:reset

小撇步：如果發現 Port 被佔用，記得先用 openclaw gateway stop 停止正在背景執行的正式版 Gateway。

紀錄原始串流 (Raw Stream Logging)

想知道模型到底回傳了什麼？你可以紀錄最原始的串流內容，這對於判斷思考過程（reasoning）是純文字還是獨立區塊非常有幫助。

OpenClaw 原始串流

這會紀錄過濾前的完整內容：

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

預設日誌路徑在 ~/.openclaw/logs/raw-stream.jsonl。

pi-mono 原始 Chunk

如果你想看更底層、尚未解析成 Block 的 OpenAI 相容 Chunk，可以使用 pi-mono 的環境變數：

PI_RAW_STREAM=1

預設日誌路徑在 ~/.pi-mono/logs/raw-openai-completions.jsonl。

疑難排解

• Gateway 沒反應？ 檢查是否有非開發模式的 Gateway 正在執行。請先執行 openclaw gateway stop 確保環境乾淨。
• 忘記設定改了什麼？ 在 Chat 中輸入 /debug reset 可以立刻回到最初的設定狀態。
• 安全性提醒 原始串流日誌會包含完整的 Prompt、工具輸出與個人資料。分享日誌前請務必遮蓋敏感資訊（PII）與密鑰，並在偵錯結束後刪除本地紀錄。

遇到更複雜的配置問題？試試 AI Setup Assistant 幫你快速排查。

下一步

• CLI Reference
• Configuration Schema
• Provider Setup