openclaw/docs/logging.md

summary, read_when, title

summary	read_when	title
File logs, console output, CLI tailing, and the Control UI Logs tab	You need a beginner-friendly overview of OpenClaw logging You want to configure log levels, formats, or redaction You are troubleshooting and need to find logs quickly	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:

/tmp/openclaw/openclaw-YYYY-MM-DD.log

The date uses the gateway host's local timezone.

You can override this in ~/.openclaw/openclaw.json:

{
  "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:

openclaw logs --follow

Useful current options:

• --local-time: render timestamps in your local timezone
• --url <url> / --token <token> / --timeout <ms>: standard Gateway RPC flags
• --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.
• --json: line-delimited JSON (one log event per line).
• --plain: force plain text in TTY sessions.
• --no-color: disable ANSI colors.

When you pass an explicit --url, the CLI does not auto-apply config or environment credentials; include --token yourself if the target Gateway requires auth.

In JSON mode, the CLI emits type-tagged objects:

• meta: stream metadata (file, cursor, size)
• log: parsed log entry
• notice: truncation / rotation hints
• raw: unparsed log line

If the local loopback Gateway asks for pairing, openclaw logs falls back to the configured local log file automatically. Explicit --url targets do not use this fallback.

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

openclaw doctor

Control UI (web)

The Control UI’s Logs tab tails the same file using logs.tail. See /web/control-ui for how to open it.

Channel-only logs

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

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).

Console output

Console logs are TTY-aware and formatted for readability:

• Subsystem prefixes (e.g. gateway/channels/whatsapp)
• Level coloring (info/warn/error)
• Optional compact or JSON mode

Console formatting is controlled by logging.consoleStyle.

Gateway WebSocket logs

openclaw gateway also has WebSocket protocol logging for RPC traffic:

• normal mode: only interesting results (errors, parse errors, slow calls)
• --verbose: all request/response traffic
• --ws-log auto|compact|full: pick the verbose rendering style
• --compact: alias for --ws-log compact

Examples:

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

Configuring logging

All logging configuration lives under logging in ~/.openclaw/openclaw.json.

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

Log levels

• logging.level: file logs (JSONL) level.
• logging.consoleLevel: console verbosity level.

You can override both via the OPENCLAW_LOG_LEVEL environment variable (e.g. OPENCLAW_LOG_LEVEL=debug). The env var takes precedence over the config file, so you can raise verbosity for a single run without editing openclaw.json. You can also pass the global CLI option --log-level <level> (for example, openclaw --log-level debug gateway run), which overrides the environment variable for that command.

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

Console styles

logging.consoleStyle:

• pretty: human-friendly, colored, with timestamps.
• compact: tighter output (best for long sessions).
• json: JSON per line (for log processors).

Redaction

Tool summaries can redact sensitive tokens before they hit the console:

• logging.redactSensitive: off | tools (default: tools)
• logging.redactPatterns: list of regex strings to override the default set

Redaction applies at the logging sinks for console output, stderr-routed console diagnostics, and file logs. File logs stay JSONL, but matching secret values are masked before the line is written to disk.

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 logging.file without raising logging.level. Flags are case-insensitive and support wildcards (telegram.*, *). Configure under diagnostics.flags or via the OPENCLAW_DIAGNOSTICS=... env override. Full guide: Diagnostics flags.

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

{
  diagnostics: { enabled: true },
}

For OTLP export to a collector, see OpenTelemetry export.

Troubleshooting tips

• Gateway not reachable? Run openclaw doctor first.
• Logs empty? Check that the Gateway is running and writing to the file path in logging.file.
• Need more detail? Set logging.level to debug or 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 diagnostics.* field reference