日志（Logging）

用户界面层面（CLI + 控制 UI + 配置）的概览，请参见 /openclaw/logging。

OpenClaw 有两个日志"界面"：

• 控制台输出（终端 / Debug UI 中可见）。
• 文件日志（JSON 行），由 Gateway logger 写入。

文件日志

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

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

控制 UI 的"日志"选项卡通过 Gateway（logs.tail）追踪该文件。CLI 也可执行相同操作：

openclaw logs --follow

Verbose 与日志级别的区别

• 文件日志完全由 logging.level 控制。
• --verbose 只影响控制台输出（以及 WS 日志样式）；它不会提升文件日志级别。
• 如需将 verbose 级别的详情写入文件日志，将 logging.level 设为 debug 或 trace。

控制台捕获

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

可独立调整控制台输出详细程度：

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

工具摘要脱敏

详细工具摘要（如 🛠️ Exec: ...）可在到达控制台流之前屏蔽敏感 Token。此功能仅针对工具，不修改文件日志。

• logging.redactSensitive：off | tools（默认：tools）
• logging.redactPatterns：正则字符串数组（覆盖默认规则）
  • 使用原始正则字符串（自动 gi），或使用 /pattern/flags 格式自定义标志。
  • 匹配项保留前 6 + 后 4 个字符（长度 ≥ 18 时），否则替换为 ***。
  • 默认规则覆盖常见的 key 赋值、CLI 标志、JSON 字段、Bearer 头、PEM 块和常见 Token 前缀。

Gateway WebSocket 日志

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

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

WS 日志样式

openclaw gateway 支持每次 Gateway 的样式切换：

• --ws-log auto（默认）：正常模式优化输出；verbose 模式使用紧凑输出
• --ws-log compact：verbose 时输出紧凑格式（请求/响应配对）
• --ws-log full：verbose 时输出完整单帧格式
• --compact：--ws-log compact 的别名

示例：

# 优化模式（仅错误/慢请求）
openclaw gateway

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

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

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

控制台格式化器感知 TTY，输出带前缀的统一格式行。子系统 logger 使输出分组且易于扫描。

行为特性：

• 子系统前缀：每行带前缀（如 [gateway]、[canvas]、[tailscale]）
• 子系统颜色：每个子系统固定颜色，加上级别颜色
• TTY 检测或富终端环境时启用颜色（TERM/COLORTERM/TERM_PROGRAM），尊重 NO_COLOR
• 缩短的子系统前缀：去掉开头的 gateway/ + channels/，保留最后 2 段（如 whatsapp/outbound）
• 子系统子 logger（自动前缀 + 结构化字段 { subsystem }）
• logRaw()：用于 QR/UX 输出（无前缀、无格式）
• 控制台样式（如 pretty | compact | json）
• 控制台日志级别独立于文件日志级别（logging.level 设为 debug/trace 时文件保留完整详情）
• WhatsApp 消息正文在 debug 级别记录（使用 --verbose 可查看）

这样可在保持文件日志稳定的同时，让交互式输出易于扫描。