Files

Josh Palmer 5676a6b38d Docs: normalize zh-CN terminology + tone

What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording
Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style
Tests: pnpm docs:build

2026-02-02 16:38:25 +01:00

11 KiB

Raw Blame History

read_when, summary, title, x-i18n

read_when

summary

title

x-i18n

你需要一份面向初学者的日志概览

你想配置日志级别或格式

你正在故障排除，需要快速找到日志

日志概览：文件日志、控制台输出、CLI 实时追踪和控制界面

日志

generated_at	model	provider	source_hash	source_path	workflow
2026-02-01T21:17:08Z	claude-opus-4-5	pi	884fcf4a906adff34d546908e22abd283cb89fe0845076cf925c72384ec3556b	logging.md	15

日志

OpenClaw 在两个地方记录日志：

文件日志（JSON 行格式），由 Gateway网关写入。
控制台输出，显示在终端和控制界面中。

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

日志存储位置

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

输出模式：

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

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

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

如果 Gateway网关不可达，CLI 会打印简短提示，建议运行：

openclaw doctor

控制界面（Web）

控制界面的日志选项卡使用 logs.tail 追踪同一文件。请参阅 /web/control-ui 了解如何打开它。

仅渠道日志

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

openclaw channels logs --channel whatsapp

日志格式

文件日志（JSONL）

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

控制台输出

控制台日志感知 TTY，并以可读性为目标进行格式化：

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

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

日志级别

logging.level：文件日志（JSONL）级别。
logging.consoleLevel：控制台详细程度级别。

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

控制台样式

logging.consoleStyle：

pretty：人类友好的、彩色的、带时间戳。
compact：更紧凑的输出（适合长时间会话）。
json：每行一个 JSON（用于日志处理器）。

脱敏

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

logging.redactSensitive：off | tools（默认：tools）
logging.redactPatterns：正则表达式字符串列表，用于覆盖默认集合

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

诊断 + OpenTelemetry

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

诊断事件在进程内发出，但导出器仅在启用诊断和导出器插件时才会挂载。

OpenTelemetry 与 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/队列/会话）。

启用诊断（无导出器）

如果你希望诊断事件可供插件或自定义接收器使用，请使用此配置：

{
  "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
    }
  }
}