学了个寂寞

Appearance

日志 ​

OpenClaw 在两个地方记录日志：

  • 文件日志（JSON lines 格式），由 Gateway 写入。
  • 控制台输出，在终端和 Control UI 中显示。

本页介绍日志所在位置、如何阅读以及如何配置日志级别和格式。

日志位置 ​

默认情况下，Gateway 将滚动日志文件写入：

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

日期使用网关主机的本地时区。

你可以在 ~/.openclaw/openclaw.json 中覆盖此路径：

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

如何查看日志 ​

CLI：实时追踪（推荐） ​

使用 CLI 通过 RPC 追踪网关日志文件：

bash
openclaw logs --follow

输出模式：

  • TTY 会话：漂亮的彩色结构化日志行。
  • 非 TTY 会话：纯文本。
  • --json：行分隔 JSON（每行一个日志事件）。
  • --plain：在 TTY 会话中强制纯文本。
  • --no-color：禁用 ANSI 颜色。

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

  • meta：流元数据（文件、游标、大小）
  • log：解析后的日志条目
  • notice：截断/轮换提示
  • raw：未解析的日志行

若 Gateway 不可达，CLI 打印简短提示，建议运行：

bash
openclaw doctor

Control UI（Web） ​

Control UI 的日志标签使用 logs.tail 追踪同一文件。见 Control UI 了解如何打开。

仅频道日志 ​

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

bash
openclaw channels logs --channel whatsapp

日志格式 ​

文件日志（JSONL） ​

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

控制台输出 ​

控制台日志感知 TTY，格式化为可读形式：

  • 子系统前缀（如 gateway/channels/whatsapp）
  • 级别着色（info/warn/error）
  • 可选的紧凑或 JSON 模式

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

配置日志 ​

所有日志配置位于 ~/.openclaw/openclaw.json 的 logging 下。

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：控制台详细度级别。

你可以通过 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/队列/会话）。

启用诊断（无导出器） ​

若你希望诊断事件对插件或自定义接收器可用：

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

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

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

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

环境变量一次性覆盖：

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

注意：

  • 标志日志写入标准日志文件（与 logging.file 相同）。
  • 输出仍按 logging.redactSensitive 脱敏。

导出到 OpenTelemetry ​

诊断可通过 diagnostics-otel 插件（OTLP/HTTP）导出。适用于任何接受 OTLP/HTTP 的 OpenTelemetry 收集器/后端。

json
{
  "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 开关（默认：开启）。
  • 当收集器需要认证时设置 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.*（输入/输出/缓存读/缓存写/总计）
  • 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 为主 logger 输出启用 OTLP 日志导出。

日志导出行为 ​

  • OTLP 日志使用写入 logging.file 的相同结构化记录。
  • 遵守 logging.level（文件日志级别）。控制台脱敏不适用于 OTLP 日志。
  • 高流量安装应优先使用 OTLP 收集器采样/过滤。

故障排查提示 ​

  • Gateway 不可达？ 先运行 openclaw doctor。
  • 日志为空？ 检查 Gateway 是否正在运行，并向 logging.file 中的文件路径写入。
  • 需要更多详情？ 将 logging.level 设置为 debug 或 trace 并重试。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策