Logging

Để xem tổng quan hướng tới người dùng (CLI + Control UI + config), các bạn xem /logging.

OpenClaw có hai “bề mặt” log:

  • Console output (những gì các bạn thấy trong terminal / Debug UI).
  • File logs (dạng JSON lines) được ghi bởi gateway logger.

File-based logger

  • File log rolling mặc định nằm trong /tmp/openclaw/ (một file mỗi ngày): openclaw-YYYY-MM-DD.log
    • Ngày tháng dùng timezone local của gateway host.
  • Đường dẫn và level của log file có thể config qua ~/.openclaw/openclaw.json:
    • logging.file
    • logging.level

Format của file là một JSON object trên mỗi dòng.

Tab Logs trong Control UI sẽ tail file này qua gateway (logs.tail). CLI cũng làm được tương tự:

openclaw logs --follow

Verbose vs. log levels

  • File logs được kiểm soát hoàn toàn bởi logging.level.
  • --verbose chỉ ảnh hưởng đến console verbosity (và kiểu log WS); nó không tăng level của file log.
  • Để capture các chi tiết verbose-only vào file logs, các bạn set logging.level thành debug hoặc trace.

Console capture

CLI capture console.log/info/warn/error/debug/trace và ghi chúng vào file logs, đồng thời vẫn in ra stdout/stderr.

Các bạn có thể điều chỉnh console verbosity độc lập qua:

  • logging.consoleLevel (mặc định info)
  • logging.consoleStyle (pretty | compact | json)

Tool summary redaction

Các tool summary verbose (ví dụ 🛠️ Exec: ...) có thể che các token nhạy cảm trước khi chúng xuất hiện trên console stream. Tính năng này chỉ áp dụng cho tools và không thay đổi file logs.

  • logging.redactSensitive: off | tools (mặc định: tools)
  • logging.redactPatterns: mảng các regex string (ghi đè mặc định)
    • Dùng raw regex strings (tự động gi), hoặc /pattern/flags nếu các bạn cần custom flags.
    • Các kết quả khớp sẽ được che bằng cách giữ 6 ký tự đầu + 4 ký tự cuối (nếu độ dài >= 18), nếu không thì thành ***.
    • Mặc định bao gồm các key assignment phổ biến, CLI flags, JSON fields, bearer headers, PEM blocks, và các token prefix phổ biến.

Gateway WebSocket logs

Gateway in các log giao thức WebSocket theo hai chế độ:

  • Normal mode (không có --verbose): chỉ in các kết quả RPC “đáng chú ý”:
    • errors (ok=false)
    • slow calls (ngưỡng mặc định: >= 50ms)
    • parse errors
  • Verbose mode (--verbose): in tất cả traffic WS request/response.

WS log style

openclaw gateway hỗ trợ chuyển đổi style cho từng gateway:

  • --ws-log auto (mặc định): normal mode được tối ưu; verbose mode dùng compact output
  • --ws-log compact: compact output (request/response được ghép đôi) khi verbose
  • --ws-log full: full per-frame output khi verbose
  • --compact: alias cho --ws-log compact

Ví dụ:

# optimized (chỉ errors/slow)
openclaw gateway

# hiển thị tất cả WS traffic (ghép đôi)
openclaw gateway --verbose --ws-log compact

# hiển thị tất cả WS traffic (full meta)
openclaw gateway --verbose --ws-log full

Console formatting (subsystem logging)

Console formatter có TTY-aware và in các dòng nhất quán với prefix. Các subsystem logger giữ output được nhóm lại và dễ quét.

Hành vi:

  • Subsystem prefixes trên mỗi dòng (ví dụ [gateway], [canvas], [tailscale])
  • Subsystem colors (ổn định cho mỗi subsystem) cộng với level coloring
  • Màu sắc khi output là TTY hoặc môi trường trông giống rich terminal (TERM/COLORTERM/TERM_PROGRAM), tôn trọng NO_COLOR
  • Subsystem prefixes được rút ngắn: bỏ gateway/ + channels/ ở đầu, giữ 2 segment cuối (ví dụ whatsapp/outbound)
  • Sub-loggers theo subsystem (tự động prefix + structured field { subsystem })
  • logRaw() cho QR/UX output (không có prefix, không có formatting)
  • Console styles (ví dụ pretty | compact | json)
  • Console log level tách biệt với file log level (file giữ đầy đủ chi tiết khi logging.level được set thành debug/trace)
  • WhatsApp message bodies được log ở level debug (dùng --verbose để xem chúng)

Điều này giữ cho các file log hiện có ổn định trong khi làm cho interactive output dễ quét.