Logging

OpenClaw has two main log surfaces:

• File logs (JSON lines) written by the Gateway.
• Console output shown in terminals and the Gateway Debug UI.

The Control UI Logs tab tails the gateway file log. This page explains where logs live, how to read them, and how to configure log levels and formats.

Where logs live

By default, the Gateway writes a rolling log file under:

The date uses the gateway host's local timezone.

Each file rotates when it reaches

(default: 100 MB). OpenClaw keeps up to five numbered archives beside the active file, such as , and keeps writing to a fresh active log instead of suppressing diagnostics.

You can override this in

:

json
Copy
{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}

How to read logs

CLI: live tail (recommended)

Use the CLI to tail the gateway log file via RPC:

bash
Copy
openclaw logs --follow

Useful current options:

• text

  Copy

  --local-time
  : render timestamps in your local timezone
• text

  Copy

  --url <url>
  /
  text

  Copy

  --token <token>
  /
  text

  Copy

  --timeout <ms>
  : standard Gateway RPC flags
• text

  Copy

  --expect-final
  : agent-backed RPC final-response wait flag (accepted here via the shared client layer)

Output modes:

• TTY sessions: pretty, colorized, structured log lines.
• Non-TTY sessions: plain text.
• text

  Copy

  --json
  : line-delimited JSON (one log event per line).
• text

  Copy

  --plain
  : force plain text in TTY sessions.
• text

  Copy

  --no-color
  : disable ANSI colors.

When you pass an explicit

, the CLI does not auto-apply config or environment credentials; include yourself if the target Gateway requires auth.

In JSON mode, the CLI emits

-tagged objects:

• text

  Copy

  meta
  : stream metadata (file, cursor, size)
• text

  Copy

  log
  : parsed log entry
• text

  Copy

  notice
  : truncation / rotation hints
• text

  Copy

  raw
  : unparsed log line

If the implicit local loopback Gateway asks for pairing, closes during connect, or times out before

answers, falls back to the configured Gateway file log automatically. Explicit targets do not use this fallback.

If the Gateway is unreachable, the CLI prints a short hint to run:

bash
Copy
openclaw doctor

Control UI (web)

The Control UI’s Logs tab tails the same file using

. See /web/control-ui for how to open it.

Channel-only logs

To filter channel activity (WhatsApp/Telegram/etc), use:

bash
Copy
openclaw channels logs --channel whatsapp

Log formats

File logs (JSONL)

Each line in the log file is a JSON object. The CLI and Control UI parse these entries to render structured output (time, level, subsystem, message).

File-log JSONL records also include machine-filterable top-level fields when available:

• text

  Copy

  hostname
  : gateway host name.
• text

  Copy

  message
  : flattened log message text for full-text search.
• text

  Copy

  agent_id
  : active agent id when the log call carries agent context.
• text

  Copy

  session_id
  : active session id/key when the log call carries session context.
• text

  Copy

  channel
  : active channel when the log call carries channel context.

OpenClaw preserves the original structured log arguments alongside these fields so existing parsers that read numbered tslog argument keys keep working.

Console output

Console logs are TTY-aware and formatted for readability:

• Subsystem prefixes (e.g.
  text

  Copy

  gateway/channels/whatsapp
  )
• Level coloring (info/warn/error)
• Optional compact or JSON mode

Console formatting is controlled by

.

Gateway WebSocket logs

also has WebSocket protocol logging for RPC traffic:

• normal mode: only interesting results (errors, parse errors, slow calls)
• text

  Copy

  --verbose
  : all request/response traffic
• text

  Copy

  --ws-log auto|compact|full
  : pick the verbose rendering style
• text

  Copy

  --compact
  : alias for
  text

  Copy

  --ws-log compact

Examples:

bash
Copy
openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full

Configuring logging

All logging configuration lives under

in .

json
Copy
{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools",
    "redactPatterns": ["sk-.*"]
  }
}

Log levels

• text

  Copy

  logging.level
  : file logs (JSONL) level.
• text

  Copy

  logging.consoleLevel
  : console verbosity level.

You can override both via the

environment variable (e.g. ). The env var takes precedence over the config file, so you can raise verbosity for a single run without editing . You can also pass the global CLI option

text

Copy

--log-level <level>

(for example, ), which overrides the environment variable for that command.

only affects console output and WS log verbosity; it does not change file log levels.

Trace correlation

File logs are JSONL. When a log call carries a valid diagnostic trace context, OpenClaw writes the trace fields as top-level JSON keys (

, , , ) so external log processors can correlate the line with OTEL spans and provider propagation.

Gateway HTTP requests and Gateway WebSocket frames establish an internal request trace scope. Logs and diagnostic events emitted inside that async scope inherit the request trace when they do not pass an explicit trace context. Agent run and model-call traces become children of the active request trace, so local logs, diagnostic snapshots, OTEL spans, and trusted provider

headers can be joined by without logging raw request or model content.

Model call size and timing

Model-call diagnostics record bounded request/response measurements without capturing raw prompt or response content:

• text

  Copy

  requestPayloadBytes
  : UTF-8 byte size of the final model request payload
• text

  Copy

  responseStreamBytes
  : UTF-8 byte size of streamed model response events
• text

  Copy

  timeToFirstByteMs
  : elapsed time before the first streamed response event
• text

  Copy

  durationMs
  : total model-call duration

These fields are available to diagnostic snapshots, model-call plugin hooks, and OTEL model-call spans/metrics when diagnostics export is enabled.

Console styles

:

• text

  Copy

  pretty
  : human-friendly, colored, with timestamps.
• text

  Copy

  compact
  : tighter output (best for long sessions).
• text

  Copy

  json
  : JSON per line (for log processors).

Redaction

OpenClaw can redact sensitive tokens before they hit console output, file logs, OTLP log records, persisted session transcript text, or Control UI tool event payloads (tool start args, partial/final result payloads, derived exec output, and patch summaries):

• text

  Copy

  logging.redactSensitive
  :
  text

  Copy

  off
  |
  text

  Copy

  tools
  (default:
  text

  Copy

  tools
  )
• text

  Copy

  logging.redactPatterns
  : list of regex strings to override the default set. Custom patterns apply on top of the built-in defaults for Control UI tool payloads, so adding a pattern never weakens redaction of values already caught by the defaults.

File logs and session transcripts stay JSONL, but matching secret values are masked before the line or message is written to disk. Redaction is best-effort: it applies to text-bearing message content and log strings, not every identifier or binary payload field.

The built-in defaults cover common API credentials and payment-credential field names such as card number, CVC/CVV, shared payment token, and payment credential when they appear as JSON fields, URL parameters, CLI flags, or assignments.

only disables this general log/transcript policy. OpenClaw still redacts safety-boundary payloads that can be shown to UI clients, support bundles, diagnostics observers, approval prompts, or agent tools. Examples include Control UI tool-call events, output, diagnostics support exports, provider error observations, exec approval command display, and Gateway WebSocket protocol logs. Custom can still add project-specific patterns on those surfaces.

Diagnostics and OpenTelemetry

Diagnostics are structured, machine-readable events for model runs and message-flow telemetry (webhooks, queueing, session state). They do not replace logs — they feed metrics, traces, and exporters. Events are emitted in-process whether or not you export them.

Two adjacent surfaces:

• OpenTelemetry export — send metrics, traces, and logs over OTLP/HTTP to any OpenTelemetry-compatible collector or backend (Grafana, Datadog, Honeycomb, New Relic, Tempo, etc.). Full configuration, signal catalog, metric/span names, env vars, and privacy model live on a dedicated page: OpenTelemetry export.
• Diagnostics flags — targeted debug-log flags that route extra logs to
  text

  Copy

  logging.file
  without raising
  text

  Copy

  logging.level
  . Flags are case-insensitive and support wildcards (
  text

  Copy

  telegram.*
  ,
  text

  Copy

  *
  ). Configure under
  text

  Copy

  diagnostics.flags
  or via the
  text

  Copy

  OPENCLAW_DIAGNOSTICS=...
  env override. Full guide: Diagnostics flags.

To enable diagnostics events for plugins or custom sinks without OTLP export:

json5
Copy
{
  diagnostics: { enabled: true },
}

For OTLP export to a collector, see OpenTelemetry export.

Troubleshooting tips

• Gateway not reachable? Run
  text

  Copy

  openclaw doctor
  first.
• Logs empty? Check that the Gateway is running and writing to the file path in
  text

  Copy

  logging.file
  .
• Need more detail? Set
  text

  Copy

  logging.level
  to
  text

  Copy

  debug
  or
  text

  Copy

  trace
  and retry.

Related

• OpenTelemetry export — OTLP/HTTP export, metric/span catalog, privacy model
• Diagnostics flags — targeted debug-log flags
• Gateway logging internals — WS log styles, subsystem prefixes, and console capture
• Configuration reference — full
  text

  Copy

  diagnostics.*
  field reference