日誌記錄

OpenClaw 有兩個主要的日誌表面：

• 檔案日誌 (JSON 行) 由 Gateway 寫入。
• 主控台輸出 顯示在終端機和 Gateway Debug UI 中。

控制 UI 的 日誌 分頁會追蹤 gateway 的檔案日誌。本頁面說明日誌存在於何處、如何閱讀日誌，以及如何設定日誌層級和格式。

日誌存放位置

根據預設，Gateway 會在以下位置寫入輪替日誌檔案：

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

日期使用 gateway 主機的當地時區。

每個檔案在達到 logging.maxFileBytes 時會進行輪替（預設：100 MB）。 OpenClaw 會在作用中檔案旁保留最多五個編號的封存檔，例如 openclaw-YYYY-MM-DD.1.log，並持續寫入新的作用中日誌，而不是 停止輸出診斷資訊。

您可以在 ~/.openclaw/openclaw.json 中覆寫此設定：

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

如何閱讀日誌

CLI：即時追蹤（推薦）

使用 CLI 透過 RPC 追蹤 gateway 日誌檔案：

openclaw logs --follow

有用的目前選項：

• --local-time：以您當地的時區顯示時間戳記
• --url <url> / --token <token> / --timeout <ms>：標準 Gateway RPC 標誌
• --expect-final：agent-backed RPC 最終回應等待標誌（此處透過共用的客戶端層接受）

輸出模式：

• TTY sessions（TTY 工作階段）：美觀、色彩化、結構化的記錄行。
• Non-TTY sessions（非 TTY 工作階段）：純文字。
• --json：換行分隔的 JSON（每行一個記錄事件）。
• --plain：在 TTY 工作階段中強制使用純文字。
• --no-color：停用 ANSI 顏色。

當您傳遞明確的 --url 時，CLI 不會自動套用設定或環境認證；如果目標 Gateway 需要認證，請自行包含 --token。

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

• meta：串流中繼資料（檔案、游標、大小）
• log：已解析的記錄項目
• notice：截斷 / 輪替提示
• raw：未解析的記錄行

如果隱含的本機回送 Gateway 要求配對、在連線期間關閉， 或在 logs.tail 回應前逾時，openclaw logs 會自動回退至 已設定的 Gateway 檔案日誌。明確的 --url 目標不會使用 此回退機制。

如果 Gateway 無法連線，CLI 會印出一個簡短的提示來執行：

openclaw doctor

Control UI (web)

控制 UI 的 日誌 分頁會使用 logs.tail 來追蹤同一個檔案。 請參閱 Control UI 以了解如何開啟它。

僅限 Channel 的記錄

若要過濾管道活動（WhatsApp/Telegram/等），請使用：

openclaw channels logs --channel whatsapp

日誌格式

檔案日誌 (JSONL)

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

檔案日誌 JSONL 記錄在可用時也包含可機器過濾的頂層欄位：

• hostname：Gateway 主機名稱。
• message：用於全文搜尋的扁平化日誌訊息文字。
• agent_id：當日誌呼叫包含 Agent 內容時的作用中 Agent ID。
• session_id：當日誌呼叫包含 Session 內容時的作用中 Session ID/金鑰。
• channel：當日誌呼叫包含 Channel 內容時的作用中 Channel。

OpenClaw 會在這些欄位旁保留原始的結構化日誌引數，以便現有讀取編號 tslog 引數金鑰的剖析器 (parser) 能繼續運作。

Talk、即時語音和 managed-room 活動會透過同一個檔案日誌管線發出有限的生命週期日誌記錄。這些記錄包含事件類型、模式、傳輸、提供者，以及可用的時機/大小測量值，但會省略逐字稿文字、音訊負載、回合 ID、通話 ID 和提供者項目 ID。

主控台輸出

主控台日誌具有 TTY 感知 且格式化為易於閱讀：

• 子系統前綴（例如 gateway/channels/whatsapp）
• 層級著色（info/warn/error）
• 可選的精簡或 JSON 模式

主控台格式設定由 logging.consoleStyle 控制。

Gateway WebSocket 日誌

openclaw gateway 也具有針對 RPC 流量的 WebSocket 通訊協定日誌記錄：

• 正常模式：僅顯示有趣的結果（錯誤、解析錯誤、慢速呼叫）
• --verbose：所有請求/回應流量
• --ws-log auto|compact|full：選擇詳細的呈現樣式
• --compact：--ws-log compact 的別名

範例：

openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full

設定日誌記錄

所有日誌設定都位於 ~/.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 僅影響主控台輸出和 WS 日誌詳細程度；它不會變更檔案日誌層級。

目標模型傳輸診斷

當除錯提供者呼叫時，請使用目標環境旗標，而不是將所有日誌提升至 debug：

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

可用的旗標：

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1：在 info 層級發出請求開始、擷取回應、SDK 標頭、第一個串流事件、串流完成以及傳輸錯誤。
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary：在模型請求日誌中包含有限的請求載荷摘要。
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools：在載荷摘要中包含所有面向模型的工具名稱。
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted：包含一個經過編修且限制大小的 JSON 載荷快照。僅在除錯時使用；機密資訊雖已編修，但提示詞和訊息文字可能仍然存在。
• OPENCLAW_DEBUG_SSE=events：發出第一個事件和串流完成的時間。
• OPENCLAW_DEBUG_SSE=peek：也發出前五個經過編修的 SSE 事件載荷，並限制每個事件的大小。
• OPENCLAW_DEBUG_CODE_MODE=1：發出程式碼模式的模型表面診斷，包括當原生提供者工具因程式碼模式擁有工具表面而被隱藏時。

這些旗標透過正常的 OpenClaw 日誌記錄，因此 openclaw logs --follow 和控制 UI 日誌分頁會顯示它們。如果沒有這些旗標，相同的診斷資訊仍可在 debug 層級取得。

追蹤關聯

檔案日誌採用 JSONL 格式。當日誌呼叫攜帶有效的診斷追蹤上下文時，OpenClaw 會將追蹤欄位寫入頂層 JSON 鍵 (traceId, spanId, parentSpanId, traceFlags)，以便外部日誌處理器能將該行與 OTEL spans 和提供商 traceparent 傳播相關聯。

Gateway HTTP 請求和 WebSocket 框架會建立一個內部請求追蹤範圍。在該非同步範圍內發出的日誌和診斷事件，若未傳遞明確的追蹤上下文，將會繼承請求追蹤。Agent 執行和模型呼叫追蹤會成為作用中請求追蹤的子項，因此本機日誌、診斷快照、OTEL spans 和可信任的提供商 traceparent 標頭可以透過 traceId 進行關聯，而無需記錄原始請求或模型內容。

當啟用 OpenTelemetry 日誌匯出時，對話生命週期日誌記錄也會流傳至 OTLP 日誌，並使用與檔案日誌相同的邊界屬性。

模型呼叫大小與計時

模型呼叫診斷會記錄有邊界的請求/回應測量數據，而不會擷取原始提示詞或回應內容：

• requestPayloadBytes：最終模型請求內容的 UTF-8 位元組大小
• responseStreamBytes：串流模型回應事件的 UTF-8 位元組大小
• timeToFirstByteMs：第一次串流回應事件之前的經過時間
• durationMs：模型呼叫總持續時間

當啟用診斷匯出時，這些欄位可用於診斷快照、模型呼叫外掛程式掛鉤以及 OTEL 模型呼叫 spans/metrics。

主控台樣式

logging.consoleStyle：

• pretty：易於閱讀、彩色，並帶有時間戳記。
• compact：更緊湊的輸出 (適合長時間工作階段)。
• json：逐行 JSON (適用於日誌處理器)。

資訊編輯

OpenClaw 可以在敏感權杖輸出到主控台、檔案日誌、OTLP 日誌記錄、持久化的工作階段逐字稿文字，或 Control UI 工具事件內容 (工具啟動引數、部分/最終結果內容、衍生的執行輸出和修補摘要) 之前，將其編輯：

• logging.redactSensitive: off | tools (預設: tools)
• logging.redactPatterns：用於覆蓋預設集的 Regex 字串清單。自訂模式會套用在控制 UI 工具負載的內建預設值之上，因此新增模式絕不會削弱已被預設值捕捉到之值的編校。

檔案日誌和會話記錄保持 JSONL 格式，但在該行或訊息寫入磁碟之前，相符的秘密值會被遮蔽。編校為盡力而為：它適用於包含文字的訊息內容和日誌字串，而非每個識別碼或二進位負載欄位。

內建預設值涵蓋常見的 API 憑證和付款憑證欄位名稱，例如卡號、CVC/CVV、共用付款權杖和付款憑證，當它們以 JSON 欄位、URL 參數、CLI 標誌或指派形式出現時。

logging.redactSensitive: "off" 僅停用此一般日誌/記錄政策。OpenClaw 仍會編校可顯示給 UI 用戶端、支援組合、診斷觀察器、核准提示或代理工具的安全性邊界負載。範例包括控制 UI 工具呼叫事件、sessions_history 輸出、診斷支援匯出、提供者錯誤觀察、exec 核准命令顯示和 Gateway WebSocket 協定日誌。自訂 logging.redactPatterns 仍可在這些介面上新增專案特定的模式。

診斷和 OpenTelemetry

診斷是針對模型執行和訊息流程遙測（webhooks、佇列、會話狀態）的結構化、機器可讀取事件。它們不會取代日誌——它們提供指標、追蹤和匯出器。無論您是否匯出事件，都會在程序內發出事件。

兩個相鄰的介面：

• OpenTelemetry 匯出 — 透過 OTLP/HTTP 將指標、追蹤和日誌傳送到任何與 OpenTelemetry 相容的收集器或後端（Grafana、Datadog、Honeycomb、New Relic、Tempo 等）。完整組態、訊號目錄、指標/範圍名稱、環境變數和隱私模型位於專屬頁面：OpenTelemetry 匯出。
• 診斷旗標 — 目標偵錯日誌旗標，可將額外日誌路由至 logging.file 而不提高 logging.level。旗標不區分大小寫 並支援萬用字元 (telegram.*, *)。可在 diagnostics.flags 下設定 或透過 OPENCLAW_DIAGNOSTICS=... 環境變數覆寫。完整指南： 診斷旗標。

若要在不進行 OTLP 匯出的情況下為外掛或自訂接收器啟用診斷事件：

{
  diagnostics: { enabled: true },
}

若要將 OTLP 匯出至收集器，請參閱 OpenTelemetry 匯出。

疑難排解提示

• 無法連線到 Gateway？ 先執行 openclaw doctor。
• 日誌是空的？ 請檢查 Gateway 是否正在執行，並正在寫入至 logging.file 中的檔案路徑。
• 需要更多細節？ 將 logging.level 設定為 debug 或 trace 並重試。

相關

• OpenTelemetry 匯出 — OTLP/HTTP 匯出、指標/追蹤範圍目錄、隱私權模型
• 診斷旗標 — 目標偵錯日誌旗標
• Gateway 日誌內部機制 — WS 日誌樣式、子系統前綴與主控台擷取
• 設定參考 — 完整的 diagnostics.* 欄位參考