Skip to main content

​
日志记录

OpenClaw 在两个位置记录日志：
  • 文件日志（JSON 行），由网关写入。
  • 控制台输出，显示在终端和控制 UI 中。
本页面将介绍日志的存储位置、如何读取日志，以及如何配置日志级别和格式。

​
日志的存储位置

默认情况下，网关会将滚动日志文件写入以下路径： /tmp/openclaw/openclaw-YYYY-MM-DD.log 日期使用网关主机的本地时区。 您可以通过 ~/.openclaw/openclaw.json 覆盖此设置： 
{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}

​
如何读取日志

​
CLI：实时尾部跟踪（推荐）

使用 CLI 通过 RPC 尾部跟踪网关日志文件： 
openclaw logs --follow
输出模式：
  • TTY 会话：美观、带颜色、结构化的日志行。
  • 非 TTY 会话：纯文本。
  • --json：以换行符分隔的 JSON（每行一个日志事件）。
  • --plain：在 TTY 会话中强制使用纯文本。
  • --no-color：禁用 ANSI 颜色。
在 JSON 模式下，CLI 会发出带有 type 标签的对象：
  • meta：流元数据（文件、游标、大小）
  • log：解析后的日志条目
  • notice：截断/轮转提示
  • raw：未解析的日志行
如果网关无法访问，CLI 会打印一条简短提示，要求运行： 
openclaw doctor

​
控制 UI（Web）

控制 UI 的 日志 选项卡使用 logs.tail 尾部跟踪同一文件。有关如何打开它的信息，请参阅 /web/control-ui。

​
仅通道日志

要过滤通道活动（WhatsApp/Telegram 等），请使用： 
openclaw channels logs --channel whatsapp

​
日志格式

​
文件日志（JSONL）

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

​
控制台输出

控制台日志具有 TTY 感知性，并经过格式化以提高可读性：
  • 子系统前缀（例如 gateway/channels/whatsapp)
  • 级别着色（信息/警告/错误）
  • 可选的紧凑或 JSON 模式
控制台格式由 logging.consoleStyle 控制。

​
配置日志记录

所有日志配置都位于 logging 下的 ~/.openclaw/openclaw.json 中。 
{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": [
      "sk-.*"
    ]
  }
}

​
日志级别

  • logging.level：文件日志（JSONL）级别。
  • logging.consoleLevel：控制台详细程度级别。
--verbose 仅影响控制台输出；它不会更改文件日志级别。

​
控制台样式

logging.consoleStyle：
  • pretty：人性化、带颜色、附带时间戳。
  • compact：更紧凑的输出（最适合长时间会话）。
  • json：每行 JSON（适用于日志处理器）。

​
敏感信息屏蔽

工具摘要可以在敏感标记到达控制台之前对其进行屏蔽：
  • logging.redactSensitive：off | tools（默认：tools）
  • logging.redactPatterns：用于覆盖默认集的正则表达式字符串列表
屏蔽仅影响控制台输出，不会更改文件日志。

​
诊断 + OpenTelemetry

诊断是结构化的、机器可读的事件，用于模型运行和消息流遥测（webhook、排队、会社状态）。它们不取代日志；它们的存在是为了为指标、跟踪和其他导出器提供数据。 诊断事件是在进程中发出的，但只有在启用诊断和导出器插件时，导出器才会附加。

​
OpenTelemetry vs OTLP

  • OpenTelemetry（OTel）：用于跟踪、指标和日志的数据模型 + SDK。
  • OTLP：用于将 OTel 数据导出到收集器/后端的传输协议。
  • OpenClaw 目前通过 OTLP/HTTP（protobuf） 导出数据。

​
导出的信号

  • 指标：计数器 + 直方图（令牌使用、消息流、排队）。
  • 跟踪：用于模型使用 + webhook/消息处理的跨度。
  • 日志：当 diagnostics.otel.logs 启用时，通过 OTLP 导出。日志量可能很大；请记住 logging.level 和导出器筛选器。

​
导诊事件目录

模型使用：
  • model.usage：令牌、成本、持续时间、上下文、提供商/模型/通道、会社 ID。
消息流：
  • webhook.received：按通道划分的 webhook 入站流量。
  • webhook.processed：已处理的 webhook 及其持续时间。
  • webhook.error：webhook 处理器错误。
  • message.queued：已 queued 等待处理的消息。
  • message.processed：结果 + 持续时间 + 可选错误。
队列 + 会社：
  • queue.lane.enqueue：命令队列车道入队 + 深度。
  • queue.lane.dequeue：命令队列车道出队 + 等待时间。
  • session.state：会社状态转换 + 原因。
  • session.stuck：会社卡住警告 + 年龄。
  • run.attempt：运行重试/尝试元数据。
  • diagnostic.heartbeat：聚合计数器（webhooks/队列/会社）。

​
启用诊断（无导出器）

如果您希望插件或自定义接收器可以使用诊断事件，请使用此方法： 
{
  "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 被忽略。
  • 指标包括令牌使用、成本、上下文大小、运行持续时间以及消息流计数器/直方图（webhooks、排队、会社状态、队列深度/等待）。
  • 可通过 traces / metrics 切换跟踪/指标（默认为开启）。启用后，跟踪包括模型使用跨度以及 webhook/消息处理跨度。
  • 当您的收集器需要身份验证时，请设置 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）

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

  • openclaw.model.usage
    • openclaw.channel，openclaw.provider，openclaw.model
    • openclaw.sessionKey，openclaw.sessionId
    • openclaw.tokens.*（输入/输出/缓存读取/缓存写入/总计）
  • 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，仅根跨度）。
  • 指标导出间隔：diagnostics.otel.flushIntervalMs（最小 1000 毫秒）。

​
协议说明

  • 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 收集器的抽样/筛选。

​
故障排除提示

  • 网关无法访问？ 请先运行 openclaw doctor。
  • 日志为空？ 请检查网关是否正在运行，并且是否正在写入 logging.file 中指定的文件路径。
  • 需要更多细节？ 将 logging.level 设置为 debug 或 trace，然后重试。