Gateway logging

Logging

For a user-facing overview (CLI + Control UI + config), see /logging.

OpenClaw has two log “surfaces”:

• Console output (what you see in the terminal / Debug UI).
• File logs (JSON lines) written by the gateway logger.

File-based logger

• Default rolling log file is under
  text

  Copy

  /tmp/openclaw/
  (one file per day):
  text

  Copy

  openclaw-YYYY-MM-DD.log
  • Date uses the gateway host's local timezone.
• Active log files rotate at
  text

  Copy

  logging.maxFileBytes
  (default: 100 MB), keeping up to five numbered archives and continuing to write a fresh active file.
• The log file path and level can be configured via
  text

  Copy

  ~/.openclaw/openclaw.json
  :
  • text

    Copy

    logging.file
  • text

    Copy

    logging.level

The file format is one JSON object per line.

The Control UI Logs tab tails this file via the gateway (

). CLI can do the same:

bash
Copy
openclaw logs --follow

Verbose vs. log levels

• File logs are controlled exclusively by
  text

  Copy

  logging.level
  .
• text

  Copy

  --verbose
  only affects console verbosity (and WS log style); it does not raise the file log level.
• To capture verbose-only details in file logs, set
  text

  Copy

  logging.level
  to
  text

  Copy

  debug
  or
  text

  Copy

  trace
  .

Console capture

The CLI captures

and writes them to file logs, while still printing to stdout/stderr.

You can tune console verbosity independently via:

• text

  Copy

  logging.consoleLevel
  (default
  text

  Copy

  info
  )
• text

  Copy

  logging.consoleStyle
  (
  text

  Copy

  pretty
  |
  text

  Copy

  compact
  |
  text

  Copy

  json
  )

Redaction

OpenClaw can mask sensitive tokens before log or transcript output leaves the process. This logging redaction policy is applied at console, file-log, OTLP log-record, and session transcript text sinks, so matching secret values are masked before JSONL lines or messages are written to disk.

• text

  Copy

  logging.redactSensitive
  :
  text

  Copy

  off
  |
  text

  Copy

  tools
  (default:
  text

  Copy

  tools
  )
• text

  Copy

  logging.redactPatterns
  : array of regex strings (overrides defaults)
  • Use raw regex strings (auto
    text

    Copy

    gi
    ), or
    text

    Copy

    /pattern/flags
    if you need custom flags.
  • Matches are masked by keeping the first 6 + last 4 chars (length >= 18), otherwise
    text

    Copy

    ***
    .
  • Defaults cover common key assignments, CLI flags, JSON fields, bearer headers, PEM blocks, popular token prefixes, and payment credential field names such as card number, CVC/CVV, shared payment token, and payment credential.

Some safety boundaries always redact regardless of

. That includes Control UI tool-call events, tool output, diagnostics support exports, provider error observations, exec approval command display, and Gateway WebSocket protocol logs. These surfaces may still use as additional patterns, but does not make them emit raw secrets.

Gateway WebSocket logs

The gateway prints WebSocket protocol logs in two modes:

• Normal mode (no
  text

  Copy

  --verbose
  ): only “interesting” RPC results are printed:
  • errors (
    text

    Copy

    ok=false
    )
  • slow calls (default threshold:
    text

    Copy

    >= 50ms
    )
  • parse errors
• Verbose mode (
  text

  Copy

  --verbose
  ): prints all WS request/response traffic.

WS log style

supports a per-gateway style switch:

• text

  Copy

  --ws-log auto
  (default): normal mode is optimized; verbose mode uses compact output
• text

  Copy

  --ws-log compact
  : compact output (paired request/response) when verbose
• text

  Copy

  --ws-log full
  : full per-frame output when verbose
• text

  Copy

  --compact
  : alias for
  text

  Copy

  --ws-log compact

Examples:

bash
Copy
# optimized (only errors/slow)
openclaw gateway

# show all WS traffic (paired)
openclaw gateway --verbose --ws-log compact

# show all WS traffic (full meta)
openclaw gateway --verbose --ws-log full

Console formatting (subsystem logging)

The console formatter is TTY-aware and prints consistent, prefixed lines. Subsystem loggers keep output grouped and scannable.

Behavior:

• Subsystem prefixes on every line (e.g.
  text

  Copy

  [gateway]
  ,
  text

  Copy

  [canvas]
  ,
  text

  Copy

  [tailscale]
  )
• Subsystem colors (stable per subsystem) plus level coloring
• Color when output is a TTY or the environment looks like a rich terminal (
  text

  Copy

  TERM
  /
  text

  Copy

  COLORTERM
  /
  text

  Copy

  TERM_PROGRAM
  ), respects
  text

  Copy

  NO_COLOR
• Shortened subsystem prefixes: drops leading
  text

  Copy

  gateway/
  +
  text

  Copy

  channels/
  , keeps last 2 segments (e.g.
  text

  Copy

  whatsapp/outbound
  )
• Sub-loggers by subsystem (auto prefix + structured field
  text

  Copy

  { subsystem }
  )
• text

  Copy

  logRaw()
  for QR/UX output (no prefix, no formatting)
• Console styles (e.g.
  text

  Copy

  pretty | compact | json
  )
• Console log level separate from file log level (file keeps full detail when
  text

  Copy

  logging.level
  is set to
  text

  Copy

  debug
  /
  text

  Copy

  trace
  )
• WhatsApp message bodies are logged at
  text

  Copy

  debug
  (use
  text

  Copy

  --verbose
  to see them)

This keeps existing file logs stable while making interactive output scannable.

Related

• Logging
• OpenTelemetry export
• Diagnostics export