OpenClaw Logging：掌握系統狀態的必經之路

每次系統出錯，你是不是也跟我一樣，第一反應就是先去翻 log？看著終端機跳出的錯誤訊息，往往比在那裡瞎猜快得多。很多時候，只要 tail 一下 log 檔案，就能抓出那個明顯的錯誤，省下大把時間。

OpenClaw 會將日誌記錄在兩個地方：JSON 檔案（方便程式解析）和 Console（方便人類閱讀）。這篇文件會教你如何找到並使用它們。

需要準備的東西

• 已安裝並執行中的 OpenClaw Gateway
• 基本的 CLI 操作能力

快速開始

預設情況下，Gateway 會寫入一個滾動更新的 log 檔案：

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

如果你想修改路徑，可以在 config 裡設定：

{
  logging: {
    file: "/custom/path/openclaw.log"
  }
}

讀取日誌

推薦使用 CLI 的 tail 功能：

openclaw logs --follow

你可以選擇不同的輸出模式：

• TTY: 漂亮的彩色結構化輸出
• Non-TTY: 純文字
• --json: 每行一個 JSON 物件
• --plain: 強制純文字
• --no-color: 停用 ANSI 顏色

你也可以透過 openclaw control 開啟 Control UI，在 Logs 分頁查看同樣的內容。

進階設定

頻道過濾

如果你只想看特定頻道的日誌（例如 WhatsApp），可以這樣下指令：

openclaw channels logs --channel whatsapp

Log Levels

你可以針對檔案和 Console 設定不同的詳細程度：

{
  logging: {
    level: "info",           // 檔案日誌等級
    consoleLevel: "info",    // Console 日誌等級
    consoleStyle: "pretty"   // pretty | compact | json
  }
}

可選等級：trace, debug, info, warn, error。注意 --verbose 旗標只會影響 Console 輸出，不會改變檔案日誌的等級。

敏感資料遮蔽 (Redaction)

為了保護隱私，你可以遮蔽 Console 中的敏感資訊：

{
  logging: {
    redactSensitive: "tools",        // off | tools
    redactPatterns: ["sk-.*"]        // 自定義 Regex 模式
  }
}

遮蔽功能僅影響 Console，檔案日誌中的資料不會被遮蔽。

診斷與 OpenTelemetry

在生產環境中，你可以將 Metrics 和 Traces 匯出到監控系統。

啟用診斷

{
  diagnostics: {
    enabled: true
  }
}

透過 OpenTelemetry 匯出

{
  plugins: {
    allow: ["diagnostics-otel"],
    entries: {
      "diagnostics-otel": { enabled: true }
    }
  },
  diagnostics: {
    enabled: true,
    otel: {
      enabled: true,
      endpoint: "http://otel-collector:4318",
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: true
    }
  }
}

匯出內容清單

Metrics (指標):

• openclaw.tokens: Token 使用量計數
• openclaw.cost.usd: 成本追蹤
• openclaw.run.duration_ms: 執行耗時直方圖
• openclaw.webhook.received: Webhook 活動量
• openclaw.message.processed: 訊息吞吐量

Traces (追蹤):

• openclaw.model.usage: 模型生成過程
• openclaw.webhook.processed: Webhook 處理流程
• openclaw.message.processed: 訊息處理流程

Debug Flags (定向日誌)

如果你想在不提高全域日誌等級的情況下獲取特定資訊，可以使用 flags：

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

或者透過環境變數：

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

支援萬用字元：telegram.* 或 *（顯示所有內容）。

疑難排解

”Gateway not reachable”

請執行診斷指令：

openclaw doctor

日誌內容是空的

請檢查：Gateway 是否正在執行？logging.file 指向的路徑是否正確？

需要更詳細的資訊

將 logging.level 設定為 debug 或 trace：

{
  logging: {
    level: "debug"
  }
}

JSON 模式詳解

在使用 --json 模式時，CLI 會輸出帶有類型標籤的物件：

Type	說明
meta	串流元數據 (file, cursor, size)
log	解析後的日誌條目
notice	截斷或輪轉提示
raw	未解析的原始日誌行

---

還是搞不定？ 我們的 AI Setup Assistant 可以幫你解讀日誌內容。

下一步

• Debugging → — 觀察模式與原始串流日誌
• Testing → — 測試套件與即時測試
• Gateway Configuration → — 完整配置參考

需要協助？歡迎加入 OpenClaw Discord 或前往 GitHub Issues 回報問題。