日志配置

日志

OpenClaw 在两个地方记录日志：

本文档解释日志的位置、如何读取它们，以及如何配置日志级别和格式。

日志位置

默认情况下，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

输出模式：

在 JSON 模式下，CLI 发出带 type 标签的对象：

如果 Gateway 不可达，CLI 会打印一个简短提示来运行：

openclaw doctor

控制台 UI（网页）

控制台 UI 的 Logs 标签页使用 logs.tail 跟踪同一文件。
打开方式详见 /web/control-ui。

仅频道日志

要过滤频道活动（WhatsApp/Telegram 等），使用：

openclaw channels logs --channel whatsapp

日志格式

文件日志（JSONL）

日志文件中的每一行都是一个 JSON 对象。CLI 和控制台 UI 解析这些条目以渲染结构化输出（时间、级别、子系统、消息）。

控制台输出

控制台日志是 TTY 感知 的，并为可读性格式化：

控制台格式由 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-.*"
    ]
  }
}

日志级别

--verbose 仅影响控制台输出；不会更改文件日志级别。

控制台样式

logging.consoleStyle：

脱敏

工具摘要可以在输出到控制台之前脱敏敏感令牌：

脱敏仅影响控制台输出，不会更改文件日志。

诊断 + OpenTelemetry

诊断是用于模型运行和消息流遥测（webhook、队列、会话状态）的结构化、机器可读事件。它们不会取代日志；它们的存在是为了向指标、跟踪和其他导出器提供数据。

诊断事件在进程内发出，但只有在启用了诊断 + 导出器插件时，导出器才会附加。

OpenTelemetry vs OTLP

导出的信号

诊断事件目录

模型使用：

消息流：

队列 + 会话：

启用诊断（无导出器）

如果你希望诊断事件可用于插件或自定义接收器，使用此选项：

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

诊断标志（有针对性的日志）

使用标志在不提高 logging.level 的情况下打开额外的有针对性的调试日志。标志不区分大小写，支持通配符（例如 telegram.* 或 *）。

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

环境变量覆盖（一次性）：

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

注意：

导出到 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
    }
  }
}

注意：

导出的指标（名称 + 类型）

模型使用：

消息流：

队列 + 会话：

导出的跨度（名称 + 关键属性）

采样 + 刷新

协议说明

日志导出行为

故障排除技巧