日誌

OpenClaw 的日誌輸出分為兩個地方：

  • 檔案日誌（JSON 行格式），由 Gateway 寫入。
  • 主控台輸出，顯示在終端機和 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 終端：格式化、上色的結構化日誌行。
  • 非 TTY 終端：純文字。
  • --json：每行一筆 JSON 格式的日誌事件。
  • --plain：在 TTY 終端中強制使用純文字。
  • --no-color：停用 ANSI 色彩。

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

  • meta：串流後設資料（檔案、游標、大小）
  • log：解析後的日誌條目
  • notice：截斷／輪替提示
  • raw：未解析的日誌行

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

openclaw doctor

Control UI（網頁）

Control UI 的 Logs 分頁透過 logs.tail 串流追蹤同一份日誌檔。 開啟方式請參閱 /web/control-ui。

頻道專屬日誌

若要篩選特定頻道的活動（WhatsApp/Telegram 等），使用：

openclaw channels logs --channel whatsapp

日誌格式

檔案日誌（JSONL）

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

主控台輸出

主控台日誌會偵測 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：檔案日誌（JSONL）的等級。
  • logging.consoleLevel：主控台的詳細程度。

你可以透過環境變數 OPENCLAW_LOG_LEVEL 覆蓋兩者（例如 OPENCLAW_LOG_LEVEL=debug）。環境變數的優先順序高於設定檔，方便你在單次執行時提高詳細程度而不用修改 openclaw.json。也可以使用全域 CLI 選項 --log-level <level>（例如 openclaw --log-level debug gateway run），它會覆蓋該指令的環境變數設定。

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

主控台樣式

logging.consoleStyle：

  • pretty：人類友善、上色、帶時間戳記。
  • compact：較緊湊的輸出（適合長時間使用）。
  • json：每行一筆 JSON（供日誌處理器使用）。

遮罩

工具摘要可在輸出到主控台前遮蔽敏感 token：

  • logging.redactSensitive：off | tools（預設：tools）
  • logging.redactPatterns：用於覆蓋預設集的正規表示式字串列表

遮罩僅影響主控台輸出，不會改動檔案日誌。

診斷與 OpenTelemetry

診斷是結構化、機器可讀的事件，涵蓋模型執行以及訊息流遙測（webhook、佇列、工作階段狀態）。它們不會取代日誌，而是用來餵給指標、追蹤與其他匯出器。

診斷事件在程序內發射，但匯出器只有在啟用診斷與匯出器外掛時才會掛載。

OpenTelemetry 與 OTLP

  • OpenTelemetry（OTel）：追蹤、指標和日誌的資料模型與 SDK。
  • OTLP：將 OTel 資料匯出到收集器／後端的線路協定。
  • OpenClaw 目前透過 OTLP/HTTP（protobuf） 匯出。

匯出的訊號

  • 指標：計數器與直方圖（token 用量、訊息流、佇列）。
  • 追蹤：模型使用與 webhook／訊息處理的 span。
  • 日誌：啟用 diagnostics.otel.logs 時透過 OTLP 匯出。日誌量可能很大，請留意 logging.level 和匯出器篩選設定。

診斷事件目錄

模型使用：

  • model.usage：token、成本、時長、上下文、供應商/模型/頻道、工作階段 ID。

訊息流：

  • webhook.received：每個頻道的 webhook 進入事件。
  • webhook.processed：webhook 處理完成 + 時長。
  • webhook.error：webhook 處理器錯誤。
  • message.queued：訊息進入佇列等待處理。
  • message.processed：結果 + 時長 + 可選錯誤。

佇列與工作階段：

  • queue.lane.enqueue：命令佇列車道入列 + 深度。
  • queue.lane.dequeue：命令佇列車道出列 + 等待時間。
  • session.state：工作階段狀態轉換 + 原因。
  • session.stuck：工作階段卡住的警告 + 存活時間。
  • run.attempt：執行重試／嘗試的後設資料。
  • diagnostic.heartbeat：彙總計數器（webhook/佇列/工作階段）。

啟用診斷（不含匯出器）

如果你只想讓外掛或自訂接收器取得診斷事件：

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

診斷旗標（鎖定特定日誌）

使用旗標來開啟針對性的除錯日誌，而不需提高 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 會被忽略。
  • 指標包含 token 用量、成本、上下文大小、執行時長，以及訊息流計數器／直方圖（webhook、佇列、工作階段狀態、佇列深度／等待時間）。
  • 追蹤與指標可透過 traces / metrics 開關（預設開啟）。追蹤包含模型使用 span，以及啟用時的 webhook／訊息處理 span。
  • 收集器需要驗證時，設定 headers。
  • 支援的環境變數：OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_SERVICE_NAME、OTEL_EXPORTER_OTLP_PROTOCOL。

匯出的指標（名稱 + 型別）

模型使用：

  • openclaw.tokens（計數器，屬性：openclaw.token、openclaw.channel、openclaw.provider、openclaw.model）
  • openclaw.cost.usd（計數器，屬性：openclaw.channel、openclaw.provider、openclaw.model）
  • openclaw.run.duration_ms（直方圖，屬性：openclaw.channel、openclaw.provider、openclaw.model）
  • openclaw.context.tokens（直方圖，屬性：openclaw.context、openclaw.channel、openclaw.provider、openclaw.model）

訊息流：

  • openclaw.webhook.received（計數器，屬性：openclaw.channel、openclaw.webhook）
  • openclaw.webhook.error（計數器，屬性：openclaw.channel、openclaw.webhook）
  • openclaw.webhook.duration_ms（直方圖，屬性：openclaw.channel、openclaw.webhook）
  • openclaw.message.queued（計數器，屬性：openclaw.channel、openclaw.source）
  • openclaw.message.processed（計數器，屬性：openclaw.channel、openclaw.outcome）
  • openclaw.message.duration_ms（直方圖，屬性：openclaw.channel、openclaw.outcome）

佇列與工作階段：

  • openclaw.queue.lane.enqueue（計數器，屬性：openclaw.lane）
  • openclaw.queue.lane.dequeue（計數器，屬性：openclaw.lane）
  • openclaw.queue.depth（直方圖，屬性：openclaw.lane 或 openclaw.channel=heartbeat）
  • openclaw.queue.wait_ms（直方圖，屬性：openclaw.lane）
  • openclaw.session.state（計數器，屬性：openclaw.state、openclaw.reason）
  • openclaw.session.stuck（計數器，屬性：openclaw.state）
  • openclaw.session.stuck_age_ms（直方圖，屬性：openclaw.state）
  • openclaw.run.attempt（計數器，屬性：openclaw.attempt）

匯出的 Span（名稱 + 關鍵屬性）

  • openclaw.model.usage
    • openclaw.channel、openclaw.provider、openclaw.model
    • openclaw.sessionKey、openclaw.sessionId
    • openclaw.tokens.*（input/output/cache_read/cache_write/total）
  • openclaw.webhook.processed
    • openclaw.channel、openclaw.webhook、openclaw.chatId
  • openclaw.webhook.error
    • openclaw.channel、openclaw.webhook、openclaw.chatId、openclaw.error
  • openclaw.message.processed
    • openclaw.channel、openclaw.outcome、openclaw.chatId、openclaw.messageId、openclaw.sessionKey、openclaw.sessionId、openclaw.reason
  • openclaw.session.stuck
    • openclaw.state、openclaw.ageMs、openclaw.queueDepth、openclaw.sessionKey、openclaw.sessionId

取樣與排清

  • 追蹤取樣：diagnostics.otel.sampleRate（0.0–1.0，僅根 span）。
  • 指標匯出間隔：diagnostics.otel.flushIntervalMs（最小 1000ms）。

協定備註

  • OTLP/HTTP 端點可透過 diagnostics.otel.endpoint 或 OTEL_EXPORTER_OTLP_ENDPOINT 設定。
  • 如果端點已包含 /v1/traces 或 /v1/metrics，會直接使用。
  • 如果端點已包含 /v1/logs，日誌匯出也會直接使用。
  • diagnostics.otel.logs 啟用主要日誌器輸出的 OTLP 日誌匯出。

日誌匯出行為

  • OTLP 日誌使用與寫入 logging.file 相同的結構化記錄。
  • 遵循 logging.level（檔案日誌等級）。主控台遮罩不適用於 OTLP 日誌。
  • 高流量環境建議使用 OTLP 收集器端的取樣／篩選。

疑難排解技巧

  • Gateway 無法連線？ 先執行 openclaw doctor。
  • 日誌是空的？ 確認 Gateway 正在執行，且正確寫入 logging.file 指定的路徑。
  • 需要更多細節？ 將 logging.level 設為 debug 或 trace 再試一次。
下一頁
Overview
arrow_forward