OpenClaw 日誌管理指南：設定與即時監控技巧

當你的機器人在半夜突然沒反應，或者 API 串接莫名其妙噴錯時，日誌（Logs）就是你唯一的救命稻草。如果日誌亂成一團，找問題簡直像在海底撈針。

OpenClaw 的日誌系統設計得很直覺，讓你不管是想快速看一眼當前狀態，還是要做深度的效能分析，都能輕鬆搞定。這份指南會帶你了解日誌的存放位置、讀取方式，以及如何配置 OpenTelemetry 來監控你的系統。

Logging

OpenClaw 的日誌會出現在兩個地方：

File logs：由 Gateway 寫入的 JSON lines 檔案。
Console output：顯示在終端機（Terminal）和 Control UI 上的內容。

這篇文件會解釋日誌存放在哪裡、如何讀取，以及如何配置日誌等級與格式。

日誌存放在哪裡

預設情況下，Gateway 會在以下路徑寫入滾動式的日誌檔案：

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

日期使用的是 Gateway 主機的在地時區。

你可以在 ~/.openclaw/openclaw.json 中修改這個路徑：

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

如何讀取日誌

CLI：即時追蹤（推薦方式）

使用 CLI 透過 RPC 來即時追蹤 Gateway 的日誌檔案：

openclaw logs --follow

輸出模式包括：

TTY sessions：美化過、帶有顏色且結構化的日誌行。
Non-TTY sessions：純文字。
--json：每行一個 JSON 物件。
--plain：在 TTY 中強制使用純文字。
--no-color：停用 ANSI 顏色。

在 JSON 模式下，CLI 會輸出帶有 type 標籤的物件：

meta：串流元數據（檔案、游標位置、大小）
log：解析後的日誌條目
notice：截斷或輪轉的提示
raw：未經解析的原始日誌行

如果 Gateway 無法連線，CLI 會提示你執行：

openclaw doctor

Control UI (web)

Control UI 的 Logs 分頁會使用 logs.tail 來追蹤同一個檔案。參考 /web/control-ui 了解如何開啟它。

特定 Channel 的日誌

如果你只想過濾特定 Channel 的活動（例如 WhatsApp 或 Telegram），可以使用：

openclaw channels logs --channel whatsapp

日誌格式

File logs (JSONL)

日誌檔案中的每一行都是一個 JSON 物件。CLI 和 Control UI 會解析這些條目來呈現結構化的輸出（時間、等級、子系統、訊息）。

Console output

控制台日誌具備 TTY 感知，並為了可讀性進行了格式化：

子系統前綴（例如 gateway/channels/whatsapp）
等級顏色（info/warn/error）
可選的緊湊模式或 JSON 模式

控制台的格式由 logging.consoleStyle 控制。

配置日誌

所有的日誌配置都位在 ~/.openclaw/openclaw.json 中的 logging 區塊。

{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

日誌等級

logging.level：File logs (JSONL) 的等級。
logging.consoleLevel：Console 的詳細程度等級。

你可以透過 OPENCLAW_LOG_LEVEL 環境變數來覆蓋這兩者（例如 OPENCLAW_LOG_LEVEL=debug）。環境變數的優先級高於配置文件，所以你可以在不修改 openclaw.json 的情況下，針對單次執行提高詳細程度。你也可以傳遞全域 CLI 選項 --log-level <level>（例如 openclaw --log-level debug gateway run），這會覆蓋該命令的環境變數。

--verbose 只會影響控制台輸出，不會改變檔案日誌的等級。

Console styles

logging.consoleStyle 可選值：

pretty：人類友善、帶顏色且有時間戳記。
compact：更緊湊的輸出（適合長時間作業）。
json：每行一個 JSON（適合日誌處理器）。

敏感資訊遮蔽（Redaction）

工具摘要可以在進入控制台前遮蔽敏感的 token：

logging.redactSensitive：off | tools（預設為 tools）
logging.redactPatterns：用來覆蓋預設值的正則表達式（Regex）列表

遮蔽功能 僅影響控制台輸出，不會修改檔案日誌。

診斷與 OpenTelemetry

診斷（Diagnostics）是針對模型執行以及訊息流遙測（Webhooks、排隊、Session 狀態）的結構化、機器可讀事件。它們不是用來取代日誌的，而是為了提供數據給 Metrics、Traces 和其他匯出工具。

診斷事件是在進程內發出的，但只有在啟用診斷和匯出插件時，匯出工具才會掛載。

OpenTelemetry vs OTLP

OpenTelemetry (OTel)：用於 Traces、Metrics 和 Logs 的數據模型與 SDK。
OTLP：將 OTel 數據匯出到收集器或後端的傳輸協定。
OpenClaw 目前透過 OTLP/HTTP (protobuf) 進行匯出。

匯出的訊號

Metrics：計數器與直方圖（Token 使用量、訊息流、排隊情況）。
Traces：模型使用以及 Webhook/訊息處理的 Spans。
Logs：當 diagnostics.otel.logs 啟用時，會透過 OTLP 匯出。日誌量可能會很大，請留意 logging.level 和匯出過濾器。

診斷事件目錄

模型使用：

model.usage：Tokens、成本、持續時間、上下文、Provider/Model/Channel、Session IDs。

訊息流：

webhook.received：每個 Channel 的 Webhook 入口。
webhook.processed：Webhook 處理完成與持續時間。
webhook.error：Webhook 處理器錯誤。
message.queued：訊息進入處理隊列。
message.processed：結果、持續時間與選填的錯誤資訊。

隊列與 Session：

queue.lane.enqueue：命令隊列通道入隊與深度。
queue.lane.dequeue：命令隊列通道出隊與等待時間。
session.state：Session 狀態切換與原因。
session.stuck：Session 卡住警告與時長。
run.attempt：執行重試/嘗試的元數據。
diagnostic.heartbeat：聚合計數器（Webhooks/隊列/Session）。

啟用診斷（無匯出工具）

如果你希望插件或自定義接收端可以使用診斷事件，請使用此配置：

{
  "diagnostics": {
    "enabled": true
  }
}

診斷標記（針對性日誌）

使用標記（Flags）來開啟額外的、針對性的除錯日誌，而不需要提高整體的 logging.level。標記不區分大小寫，並支援萬用字元（例如 telegram.* 或 *）。

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

環境變數覆蓋（單次使用）：

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

注意：

標記日誌會進入標準日誌檔案（與 logging.file 相同）。
輸出仍會根據 logging.redactSensitive 進行遮蔽。
完整指南請參考：/diagnostics/flags。

匯出至 OpenTelemetry

診斷數據可以透過 diagnostics-otel 插件 (OTLP/HTTP) 匯出。這適用於任何接受 OTLP/HTTP 的 OpenTelemetry 收集器或後端。

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

注意：

你也可以使用 openclaw plugins enable diagnostics-otel 來啟用插件。
protocol 目前僅支援 http/protobuf。grpc 會被忽略。
Metrics 包括 Token 使用量、成本、上下文大小、執行時間，以及訊息流的計數器/直方圖。
Traces/Metrics 可以透過 traces / metrics 切換（預設為開啟）。
當收集器需要認證時，請設置 headers。
支援的環境變數：OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL。

匯出的 Metrics（名稱與類型）