使用 Diagnostics Flags 精準除錯

每次想排查某個特定的 API 對接問題，打開 Log 卻發現滿螢幕都是無關的訊息？這種在資料大海裡撈針的感覺真的很累。你可能只想看 Telegram 的請求細節，但系統卻把所有 Gateway 的運作紀錄通通塞給你，導致真正重要的資訊被洗掉。

這就是 Diagnostics Flags 出場的時候了。它讓你可以針對特定的子系統開啟偵錯日誌，而不需要把整個系統的 Logging 等級調到最鬆。這些 Flag 是手動開啟的（Opt-in），除非子系統有檢查這些 Flag，否則不會產生額外影響。

需要準備的東西

• 修改 Gateway 設定檔或環境變數的權限
• 能夠存取 Log 檔案所在的伺服器或終端機

快速開始

想在 5 分鐘內精準抓到問題？照著這幾步做：

1. 修改設定：在你的設定檔中加入你想追蹤的 Flag。例如你想看 Telegram 的 HTTP 請求：

   {
     "diagnostics": {
       "flags": ["telegram.http"]
     }
   }

2. 重啟服務：存檔後，記得重啟 Gateway 讓設定生效。
3. 觀察 Log：預設情況下，Log 會輸出到 /tmp/openclaw/ 目錄。
4. 即時追蹤：使用 tail 指令配合 rg (ripgrep) 過濾你要的內容。

運作邏輯

• Flag 本身是字串，而且不分大小寫。
• 你可以同時開啟多個 Flag。
• 支援萬用字元（Wildcards）：
  • telegram.* 會匹配 telegram.http 及其相關 Flag。
  • * 會直接開啟所有 Diagnostics Flags。

透過環境變數快速開啟

如果你只是想臨時測試，不想改設定檔，可以用環境變數：

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

如果測試完了想關閉所有 Flag，直接設為 0 即可：

OPENCLAW_DIAGNOSTICS=0

Log 放在哪裡？

這些 Flag 產生的日誌會進入標準的 Diagnostics Log 檔案。如果你沒有特別設定 logging.file，預設路徑會是：

/tmp/openclaw/openclaw-YYYY-MM-DD.log

Log 格式為 JSONL（每一行都是一個獨立的 JSON 物件）。別擔心敏感資訊，logging.redactSensitive 的脫敏機制在這裡同樣有效。

提取日誌的小技巧

你可以用這行指令找出最新的一份 Log 檔案：

ls -t /tmp/openclaw/openclaw-*.log | head -n 1

或者在重現問題時，直接即時監控：

tail -f /tmp/openclaw/openclaw-$(date +%F).log | rg "telegram http error"

如果你是在遠端運行 Gateway，也可以利用 CLI 工具： openclaw logs --follow

疑難排解

• 看不到 Flag 輸出的 Log？ 請檢查你的 logging.level。如果設定得比 warn 還高（例如設為 error），這些偵錯 Log 可能會被攔截。預設的 info 等級是可以正常運行的。
• 改了設定沒反應？ Diagnostics Flags 在設定檔更改後，必須重啟 Gateway 才會生效。如果是用環境變數啟動，也請確認變數有正確傳入進程。

---

有任何設定上的疑問嗎？可以直接詢問 AI Setup Assistant。

下一步

• /logging - 了解如何更改 Log 目的地、等級與脫敏設定
• /cli/logs - 學習使用 CLI 工具遠端查看日誌