ClawCN - OpenClaw 中文版

主题

日志 ​

OpenClaw 在两个位置记录日志:

  • 文件日志(JSON 行格式)由 Gateway 写入。
  • 控制台输出显示在终端和控制界面中。

本页说明日志的位置、如何读取日志,以及如何配置日志级别和格式。

日志位置 ​

默认情况下,Gateway 将滚动日志文件写入以下位置:

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

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

你可以在 ~/.openclaw/openclaw.json 中覆盖此设置:

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

如何读取日志 ​

CLI:实时跟踪(推荐) ​

使用 CLI 通过 RPC 跟踪 gateway 日志文件:

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

控制界面(Web) ​

控制界面的日志选项卡使用 logs.tail 跟踪相同的文件。 有关如何打开它,请参见 /web/control-ui。

仅通道日志 ​

要筛选通道活动(WhatsApp/Telegram 等),请使用:

bash
openclaw channels logs --channel whatsapp

日志格式 ​

文件日志(JSONL) ​

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

控制台输出 ​

控制台日志感知 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:控制台详细级别。

--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/消息处理的 span。
  • 日志:当启用 diagnostics.otel.logs 时通过 OTLP 导出。日志量可能很大;请记住 logging.level 和导出器过滤器。

诊断事件目录 ​

模型使用:

  • model.usage:令牌、成本、持续时间、上下文、提供商/模型/通道、会话 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 进行脱敏。
  • 完整指南:/diagnostics/flags。

导出到 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 被忽略。
  • 指标包括令牌使用、成本、上下文大小、运行持续时间和消息流计数器/直方图(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 并重试。