日志

用户向的概览（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

详细模式 vs. 日志级别

  • 文件日志完全由 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 块和流行的 Token 前缀

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

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

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

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

控制台格式化器支持 TTY 检测，打印一致的、带前缀的行。 子系统日志记录器保持输出分组和可扫描性。

行为特性：

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

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