openclaw 文档

简体中文

English

简体中文

English

Appearance

日志 ​

面向用户的总览（CLI + Control UI + config）见：/logging。

OpenClaw 有两类日志“输出面”（surfaces）：

  • 控制台输出（你在终端 / Debug UI 里看到的内容）。
  • 文件日志（JSON lines），由 gateway logger 写入。

基于文件的 logger ​

  • 默认滚动日志目录在 /tmp/openclaw/（每天一个文件）：openclaw-YYYY-MM-DD.log
    • 日期使用 gateway host 的本地时区。
  • 日志文件路径与级别可以通过 ~/.openclaw/openclaw.json 配置：
    • logging.file
    • logging.level

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

Control UI 的 Logs 标签页会通过 gateway（logs.tail）tail 这个文件。CLI 也可以：

bash
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）

Tool 摘要脱敏 ​

verbose 的 tool 摘要（例如 🛠️ Exec: ...）可以在进入控制台流之前遮罩敏感 token。该机制 只作用于 tools 输出，不会改变文件日志。

  • logging.redactSensitive: off | tools（默认：tools）
  • logging.redactPatterns: regex 字符串数组（会覆盖默认规则）
    • 使用原始 regex 字符串（自动加 gi），或使用 /pattern/flags 以自定义 flags。
    • 匹配到的内容会被遮罩：长度 >= 18 时保留前 6 + 后 4 个字符；否则替换为 ***。
    • 默认规则覆盖常见的 key 赋值、CLI flags、JSON 字段、bearer headers、PEM blocks，以及常见 token 前缀。

Gateway WebSocket 日志 ​

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

  • 普通模式（不带 --verbose）：只打印“有价值”的 RPC 结果：
    • errors（ok=false）
    • 慢调用（默认阈值：>= 50ms）
    • 解析错误
  • Verbose 模式（--verbose）：打印所有 WS request/response 流量。

WS 日志样式 ​

openclaw gateway 支持按 gateway 设置样式：

  • --ws-log auto（默认）：普通模式做优化；verbose 模式使用紧凑输出
  • --ws-log compact：在 verbose 时用紧凑输出（配对的 request/response）
  • --ws-log full：在 verbose 时输出每帧的完整信息
  • --compact：--ws-log compact 的别名

示例：

bash
# optimized（仅 errors/slow）
openclaw gateway

# 显示全部 WS 流量（配对输出）
openclaw gateway --verbose --ws-log compact

# 显示全部 WS 流量（完整 meta）
openclaw gateway --verbose --ws-log full

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

控制台 formatter 感知 TTY，并输出一致的、带前缀的行。子系统 logger 会让输出更易扫读。

行为：

  • 每行都有 子系统前缀（例如 [gateway]、[canvas]、[tailscale]）
  • 子系统颜色（每个子系统固定颜色）+ level 颜色
  • 当输出是 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 才能看到）

这样既能保持现有文件日志稳定，也能让交互式输出更易扫读。