掌握 OpenClaw 日誌系統：從 Console 到檔案紀錄

當你的服務在背景跑了一整晚卻突然報錯，或是 API 回傳不如預期時，最崩潰的就是翻遍紀錄卻找不到關鍵資訊。有時候日誌太雜亂讓你抓不到重點，有時候卻又簡短到看不出問題發生在哪個環節。

OpenClaw 設計了一套完整的日誌機制，讓你在開發時能看到漂亮的 Console 輸出，同時在後台保留詳盡的 JSON 紀錄。

需要準備的東西

• OpenClaw 已安裝並正常執行
• 具備基本的 CLI 操作經驗
• 知道如何編輯 ~/.openclaw/openclaw.json 設定檔

快速開始

想要快速上手 OpenClaw 的日誌功能，你可以參考以下路徑：

1. 即時監控：在終端機輸入 openclaw logs --follow 即可追蹤目前的日誌。
2. 調整等級：編輯 ~/.openclaw/openclaw.json，修改 logging.level（影響檔案）或 logging.consoleLevel（影響終端機）。
3. 啟動詳細模式：執行 Gateway 時加上 --verbose 參數，查看完整的 WebSocket 通訊。
4. 檢查檔案：到 /tmp/openclaw/ 找尋當天的 .log 檔案。

檔案紀錄 (File-based logger)

OpenClaw 預設會將日誌寫入 /tmp/openclaw/ 資料夾，檔名格式為 openclaw-YYYY-MM-DD.log（使用 Gateway 主機的在地時區）。這些檔案採用 JSON lines 格式，每一行都是一個獨立的 JSON 物件，方便後續用工具分析。

你可以透過 ~/.openclaw/openclaw.json 調整以下設定：

• logging.file: 指定日誌路徑
• logging.level: 設定寫入檔案的詳細程度

Verbose 與日誌等級的差異

這是一個常見的誤解：--verbose 旗標只會影響 Console 的顯示內容，它不會改變寫入檔案的日誌等級。如果你想在檔案中紀錄更多細節（如 debug 或 trace），你必須修改設定檔中的 logging.level。

Console 輸出與格式化

OpenClaw 的 CLI 會擷取所有的 console.log、warn、error 等輸出並寫入檔案，同時維持終端機的可讀性。

顏色與子系統 (Subsystem)

為了讓你一眼看出是哪個組件在說話，Console 輸出會自動加上前綴，例如 [gateway] 或 [whatsapp/outbound]。這些前綴有固定的顏色辨識，且會自動縮短路徑。

你可以獨立調整 Console 的風格：

• logging.consoleStyle: 可選 pretty（預設）、compact 或 json。
• logging.consoleLevel: 預設為 info。

敏感資訊遮罩

為了保護你的 API Keys 或 Token，OpenClaw 內建了 logging.redactSensitive 功能（預設開啟）。這會針對 Tool Summary（例如 🛠️ Exec: ...）進行遮罩。

• 如果字串長度大於等於 18，會保留前 6 後 4 個字元，中間隱藏。
• 其餘情況則直接顯示 ***。
• 你可以在 logging.redactPatterns 自定義 Regex 來增加遮罩範圍。

Gateway WebSocket 日誌

當你執行 openclaw gateway 時，可以監控 WebSocket 的通訊狀況。

運作模式

1. 一般模式：只會顯示「有趣」的訊息，例如錯誤（ok=false）、處理超過 50ms 的慢請求，或解析錯誤。
2. Verbose 模式 (--verbose)：顯示所有的 WS 請求與回應流量。

日誌風格切換

你可以透過 --ws-log 參數調整顯示方式：

• auto: 預設模式，Verbose 時使用簡潔輸出。
• compact: 強制使用成對的請求/回應簡潔輸出。
• full: 顯示完整的 Frame 中繼資料。

# 僅顯示錯誤或慢請求
openclaw gateway

# 顯示所有成對的 WS 流量
openclaw gateway --verbose --ws-log compact

# 顯示最完整的 WS 資訊
openclaw gateway --verbose --ws-log full

疑難排解

為什麼我看不到 WhatsApp 的訊息內容？

WhatsApp 的訊息主體預設是在 debug 等級紀錄的。如果你想在 Console 看到它們，請在啟動時加上 --verbose 旗標。

檔案裡的紀錄太少了，我想看到更多細節

請檢查你的 ~/.openclaw/openclaw.json。確保 logging.level 設定為 debug 或 trace。單純在 CLI 使用 --verbose 並不會增加檔案紀錄的詳細度。

如果你在設定過程中遇到任何問題，可以詢問 AI Setup Assistant 獲取即時協助。

下一步

• 深入了解 Logging 配置細節
• 查看 Gateway API 文件