日志

OpenClaw 在两个位置记录日志：

文件日志（JSON 行）�?Gateway 写入�?
**控制台输�?*显示在终端和控制 UI 中�?

本页解释日志的位置、如何读取日志，以及如何配置日志级别和格式�?

日志位置

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

Control UI（Web�?

Control UI �?Logs 选项卡使�?logs.tail 尾随同一文件�? 有关如何打开它，请参�?/zh/docs/web/control-ui�?

仅通道日志

要过滤通道活动（WhatsApp/Telegram/等），请使用�?

openclaw channels logs --channel whatsapp

日志格式

文件日志（JSONL�?

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

控制台输�?

控制台日�?感知 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�?*控制�?*详细级别�?

您可以通过 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（用于日志处理器）�?

编辑

工具摘要可以在到达控制台之前编辑敏感令牌�?

logging.redactSensitive：off | tools（默认：tools�?
logging.redactPatterns：正则字符串列表以覆盖默认集

编辑仅影响控制台输出，不会更改文件日志�?

诊断 + OpenTelemetry

诊断是模型运�?�?消息流遥测（webhook、排队、会话状态）的结构化机器可读事件。它�?�? 替代日志；它们存在是为了供给指标、追踪和其他导出器�?

诊断事件在进程内发出，但导出器仅在诊�? 和导出器插件启用时附加�?

OpenTelemetry �?OTLP 的区�?

OpenTelemetry (OTel)：追踪、指标和日志的数据模�?+ SDK�?
OTLP：用于将 OTel 数据导出到收集器/后端的线协议�?
OpenClaw 目前通过 OTLP/HTTP (protobuf) 导出�?

导出的信�?

指标：计数器 + 直方图（token 使用、消息流、排队）�?
追踪：模型使�?+ webhook/消息处理的跨度�?
日志：当 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/排队/会话）�?

启用诊断（无导出器）

如果您希望诊断事件可供插件或自定义接收器使用�?

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

诊断标志（定向日志）

使用标志打开额外的定向调试日志，而不提高 logging.level�? 标志不区分大小写并支持通配符（例如 telegram.* �?*）�?

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

环境变量覆盖（一次性）�?

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

注意�?

标志日志进入标准日志文件（与 logging.file 相同）�?
输出仍根�?logging.redactSensitive 进行编辑�?
完整指南：/zh/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 被忽略�?
指标包括 token 使用、成本、上下文大小、运行时长，以及消息�? 计数�?直方图（webhook、排队、会话状态、队列深�?等待）�?
追踪/指标可以通过 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.*（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，仅根跨度）�?
指标导出间隔：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 然后重试�?