古法编程

Appearance

文件日志默认写入 /tmp/openclaw/openclaw-YYYY-MM-DD.log，CLI 日志使用 openclaw logs --follow 实时追踪。若 Gateway 不可达请先运行 openclaw doctor。可配置 logging.level（环境变量 OPENCLAW_LOG_LEVEL 可覆盖）和 logging.redactSensitive 控制脱敏。调试模型调用用 OPENCLAW_DEBUG_MODEL_TRANSPORT 等标志，无需把全局日志级别提到 debug。诊断事件通过 diagnostics 插件配合 OTLP/HTTP 导出。

OpenClaw 日志配置与排查完全指南 ​

OpenClaw 有两个主日志面：

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

Control UI 的 日志 标签页会跟随（tail）Gateway 文件日志。本文说明日志在哪里、怎么读、怎么配级别、格式和脱敏，以及诊断与 OpenTelemetry 导出。

日志文件保存路径 ​

默认情况下 Gateway 把滚动日志文件写到：

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

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

每个文件达到 logging.maxFileBytes（默认 100 MB）就轮转一次。OpenClaw 最多保留 5 个带编号的归档文件（如 openclaw-YYYY-MM-DD.1.log），继续写一个新的活跃日志，不会停止输出诊断信息。

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

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

怎么查看日志（CLI / Web / 渠道） ​

CLI：实时追踪（推荐） ​

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

bash
openclaw logs --follow

输出模式：

  • TTY 会话：带颜色的结构化日志。
  • 非 TTY 会话：纯文本。
  • --json：每行一个 JSON 日志事件。
  • --plain：在 TTY 会话中强制纯文本。
  • --no-color：去掉 ANSI 颜色。

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

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

如果隐式本地环回 Gateway 要求配对、连接时关闭、或在 logs.tail 应答前超时，openclaw logs 会自动回退到配置的 Gateway 文件日志。显式传了 --url 的目标不会使用这个回退。

Gateway 不可达时，CLI 会打印提示，建议先运行：

bash
openclaw doctor

Web：Control UI ​

Control UI 的 日志 标签页用 logs.tail 跟随同一个文件。参见 Control UI 打开。

渠道专用日志 ​

只过滤某个渠道的活动（如 WhatsApp、Telegram）：

bash
openclaw channels logs --channel whatsapp

日志格式 ​

文件日志（JSONL） ​

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

每条 JSONL 记录在可用时还会带上机器可过滤的顶层字段：

  • hostname：网关主机名。
  • message：扁平化的日志消息文本，便于全文搜索。
  • agent_id：日志携带智能体上下文时的智能体 ID。
  • session_id：日志携带会话上下文时的会话 ID/Key。
  • channel：日志携带渠道上下文时的渠道名称。

OpenClaw 保留原始的结构化日志字段，已有的 tslog 数字键解析器不会受影响。

Talk 语音、实时语音和受管房间活动也会通过同一个文件日志管道输出有限的生命周期记录。这些记录包含事件类型、模式、传输方式、提供商以及尺寸/耗时测量值，但不会包含会话文本、音频载荷、轮次 ID、通话 ID 和提供商 item ID。

控制台输出 ​

控制台日志 感知 TTY，格式化后可读性更好：

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

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

Gateway WebSocket 日志 ​

openclaw gateway 还提供 WebSocket 协议日志，用于 RPC 流量：

  • 普通模式：只显示感兴趣的结果（错误、解析错误、慢调用）
  • --verbose：显示所有请求/响应流量
  • --ws-log auto|compact|full：选择详细查看方式的渲染样式
  • --compact：--ws-log compact 的别名

示例：

bash
openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full

日志配置详解 ​

所有日志配置都在 ~/.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 只影响控制台输出和 WS 日志详细度，不会改变文件日志级别。

目标模型传输诊断 ​

调试 provider 调用时，用针对性环境标志好过把整个日志提到 debug：

bash
OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

可用标志：

  • OPENCLAW_DEBUG_MODEL_TRANSPORT=1：以 info 级别输出请求开始、fetch 响应、SDK 头、首次流事件、流结束、传输错误。
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=summary：模型请求日志中携带一个定长的请求载荷摘要。
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=tools：在载荷摘要中包含所有模型端工具名。
  • OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted：包含一个脱敏、截断的 JSON 载荷快照。仅调试时使用；密钥会脱敏，但 prompt 和消息文本可能仍保留。
  • OPENCLAW_DEBUG_SSE=events：输出首次事件和流结束时间。
  • OPENCLAW_DEBUG_SSE=peek：额外输出前五个脱敏 SSE 事件载荷，每个事件限制大小。
  • OPENCLAW_DEBUG_CODE_MODE=1：输出代码模式下模型表面的诊断，包括原生 provider 工具因代码模式拥有工具表面而被隐藏的情况。

这些标志通过正常的 OpenClaw 日志输出，所以 openclaw logs --follow 和 Control UI 的日志标签都能看到。不设标志时，同一诊断在 debug 级别也可用。

控制台样式 ​

logging.consoleStyle：

  • pretty：人类友好、彩色、带时间戳。
  • compact：更紧凑（适合长会话）。
  • json：每行 JSON（给日志处理程序用）。

敏感信息脱敏 ​

OpenClaw 可以在敏感 token 到达控制台、文件日志、OTLP 日志记录、持久化会话文本、或 Control UI 工具事件载荷（工具 start 参数、部分/最终结果载荷、派生执行输出和 patch 摘要）之前进行脱敏：

  • logging.redactSensitive：off | tools（默认 tools）
  • logging.redactPatterns：自定义的正则字符串列表，覆盖默认集合。自定义规则在默认规则之上生效，所以加一条规则不会削弱已经匹配的值。

文件日志和会话文本仍然是 JSONL，但匹配的密钥值会在写入磁盘前遮盖掉。脱敏是尽力而为的：它作用于带文本的消息内容和日志字符串，不会覆盖每个标识符或二进制载荷字段。

内置默认规则覆盖常见 API 凭证和支付凭证字段名（如卡号、CVC/CVV、共享支付 token、支付凭证），当它们出现在 JSON 字段、URL 参数、CLI 标志或赋值语句中时会被匹配。

logging.redactSensitive: "off" 只关闭这个常规日志/文本策略。OpenClaw 仍然会脱敏安全边界载荷——即那些可以展示给 UI 客户端、支持包、诊断观察者、审批提示或智能体工具的内容。例子包括 Control UI 工具调用事件、sessions_history 输出、诊断支持导出、provider 错误观察、exec 审批命令显示和 Gateway WebSocket 协议日志。自定义 logging.redactPatterns 可以在这类表面上添加项目特定的规则。

诊断 + OpenTelemetry ​

诊断是结构化、机器可读的事件，用于模型运行和消息流遥测（webhook、队列、会话状态）。它们不取代日志——它们给指标、追踪和导出器提供数据。事件在进程内发出，无论你是否导出它们。

两个相关面：

  • OpenTelemetry 导出——通过 OTLP/HTTP 发送指标、追踪和日志到任何兼容的收集器或后端（Grafana、Datadog、Honeycomb、New Relic、Tempo 等）。完整配置、信号目录、指标/span 名称、环境变量和隐私模型见专用页面：OpenTelemetry 导出。
  • 诊断标志——在不提 logging.level 的前提下，把额外日志路由到 logging.file 的有针对性的调试日志标志。标志不区分大小写，支持通配（telegram.*、*）。在 diagnostics.flags 下配置，或用 OPENCLAW_DIAGNOSTICS=... 环境变量覆盖。完整指南：诊断标志。

若只想让诊断事件对插件或自定义接收器可用，不启用 OTLP 导出：

json5
{
  diagnostics: { enabled: true },
}

OTLP 导出到收集器参见 OpenTelemetry 导出。

Gateway 不可达或日志为空怎么解决 ​

  • Gateway 不可达？ 先运行 openclaw doctor。
  • 日志为空？ 确认 Gateway 正在运行并且写的路径就是 logging.file 配置的值。
  • 需要更多详情？ 把 logging.level 设成 debug 或 trace 再试一次。

相关文档 ​

常见问题 ​

怎么临时开启 OpenClaw 的 debug 日志而不修改配置文件？ ​

用环境变量 OPENCLAW_LOG_LEVEL=debug 启动 Gateway。也可以在命令前加 --log-level debug，例如 openclaw --log-level debug gateway run。环境变量优先级高于配置文件，--log-level 又覆盖环境变量。

openclaw doctor 检查后依然连接不上 Gateway 怎么办？ ​

确认 Gateway 进程在运行，检查 logging.file 指向的路径是否存在且可写。如果用的是显式 --url 调用 openclaw logs，需要同时传 --token。查看 ~/.openclaw/openclaw.json 里的 logging.file 值，手动查看那个文件有没有新写入的内容。

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

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策