openclaw/docs/zh-CN/gateway/logging.md

read_when, summary, title, x-i18n

read_when	summary	title	x-i18n
更改日志输出或格式 调试 CLI 或 Gateway网关输出	日志界面、文件日志、WebSocket 日志样式和控制台格式化	日志	generated_at model provider source_hash source_path workflow 2026-02-01T20:35:06Z claude-opus-4-5 pi efb8eda5e77e3809369a8ff569fac110323a86b3945797093f20e9bc98f39b2e gateway/logging.md 14

日志

有关面向用户的概述（CLI + 控制界面 + 配置），请参阅 /logging。

OpenClaw 有两个日志"界面"：

• 控制台输出（你在终端 / 调试界面中看到的内容）。
• 文件日志（JSON 行），由 Gateway网关日志记录器写入。

基于文件的日志记录器

• 默认滚动日志文件位于 /tmp/openclaw/ 下（每天一个文件）：openclaw-YYYY-MM-DD.log
  • 日期使用 Gateway网关主机的本地时区。
• 日志文件路径和级别可通过 ~/.openclaw/openclaw.json 配置：
  • logging.file
  • logging.level

文件格式为每行一个 JSON 对象。

控制界面的日志标签页通过 Gateway网关（logs.tail）实时追踪此文件。 CLI 也可以执行相同操作：

openclaw logs --follow

详细模式与日志级别

• 文件日志 仅由 logging.level 控制。
• --verbose 仅影响控制台详细程度（以及 WebSocket 日志样式）；它不会提升文件日志级别。
• 要在文件日志中捕获仅在详细模式下显示的细节，请将 logging.level 设置为 debug 或 trace。

控制台捕获

CLI 捕获 console.log/info/warn/error/debug/trace 并将其写入文件日志，同时仍然输出到 stdout/stderr。

你可以独立调整控制台详细程度：

• logging.consoleLevel（默认 info）
• logging.consoleStyle（pretty | compact | json）

工具摘要脱敏

详细的工具摘要（例如 🛠️ Exec: ...）可以在敏感令牌进入控制台流之前对其进行掩码处理。这仅适用于工具，不会更改文件日志。

• logging.redactSensitive：off | tools（默认：tools）
• logging.redactPatterns：正则表达式字符串数组（覆盖默认值）
  • 使用原始正则字符串（自动 gi），如果需要自定义标志则使用 /pattern/flags。
  • 匹配项通过保留前 6 个和后 4 个字符进行掩码（长度 >= 18），否则显示 ***。
  • 默认覆盖常见的键赋值、CLI 标志、JSON 字段、bearer 头、PEM 块和常见的令牌前缀。

Gateway网关 WebSocket 日志

Gateway网关以两种模式打印 WebSocket 协议日志：

• 普通模式（无 --verbose）：仅打印"有意义的" RPC 结果：
  • 错误（ok=false）
  • 慢调用（默认阈值：>= 50ms）
  • 解析错误
• 详细模式（--verbose）：打印所有 WebSocket 请求/响应流量。

WebSocket 日志样式

openclaw gateway 支持按 Gateway网关设置的样式开关：

• --ws-log auto（默认）：普通模式经过优化；详细模式使用紧凑输出
• --ws-log compact：详细模式下使用紧凑输出（配对的请求/响应）
• --ws-log full：详细模式下使用完整的逐帧输出
• --compact：--ws-log compact 的别名

示例：

# 优化模式（仅错误/慢调用）
openclaw gateway

# 显示所有 WS 流量（配对）
openclaw gateway --verbose --ws-log compact

# 显示所有 WS 流量（完整元数据）
openclaw gateway --verbose --ws-log full

控制台格式化（子系统日志）

控制台格式化器具有 TTY 感知能力，打印一致的、带前缀的行。 子系统日志记录器保持输出分组且易于扫描。

行为：

• 每行带有子系统前缀（例如 [gateway]、[canvas]、[tailscale]）
• 子系统颜色（每个子系统稳定分配）加级别着色
• 当输出为 TTY 或环境看起来像富终端时启用颜色（TERM/COLORTERM/TERM_PROGRAM），遵循 NO_COLOR
• 缩短的子系统前缀：去掉前导的 gateway/ + channels/，保留最后 2 个片段（例如 whatsapp/outbound）
• 按子系统的子日志记录器（自动前缀 + 结构化字段 { subsystem }）
• logRaw() 用于 QR/UX 输出（无前缀、无格式化）
• 控制台样式（例如 pretty | compact | json）
• 控制台日志级别 与文件日志级别分离（当 logging.level 设置为 debug/trace 时，文件保留完整细节）
• WhatsApp 消息正文 以 debug 级别记录（使用 --verbose 查看）

这在保持现有文件日志稳定的同时，使交互式输出更易于扫描。