Master OpenClaw Logging: Debug and Monitor in Seconds

Ever spent an hour debugging a message that just… vanished? We’ve all been there. When you’re building with OpenClaw, you need to know exactly what’s happening under the hood without digging through a haystack.

OpenClaw keeps things simple by logging in two specific spots: file logs (JSON lines) written by the Gateway, and the console output you see in your terminal or the Control UI. Here is how you can find, read, and tweak those logs to make your life easier.

Where logs live

By default, the Gateway writes a rolling log file. You can find it here:

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

The date follows your gateway host’s local timezone. If you want to put these logs somewhere else, you can override the path in your ~/.openclaw/openclaw.json file:

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

How to read logs

CLI: live tail (recommended)

The best way to see what’s happening right now is using the CLI to tail the log file via RPC. It’s fast and gives you exactly what you need:

openclaw logs --follow

You have a few different output modes depending on your setup:

• TTY sessions: You get pretty, colorized, and structured log lines.
• Non-TTY sessions: You get plain text.
• --json: This gives you line-delimited JSON (one log event per line).
• --plain: Use this to force plain text even in TTY sessions.
• --no-color: This disables ANSI colors.

When you use JSON mode, the CLI emits objects tagged by type. You’ll see meta for stream metadata, log for the actual entries, notice for things like rotation hints, and raw for lines that couldn’t be parsed.

If the Gateway isn’t reachable, the CLI will suggest you run this command:

openclaw doctor

Control UI (web)

If you prefer a browser, the Control UI has a Logs tab that tails the same file using logs.tail. Check out /web/control-ui to see how to open it.

Channel-only logs

Sometimes you only care about a specific platform like WhatsApp or Telegram. You can filter for just that activity:

openclaw channels logs --channel whatsapp

Log formats

File logs (JSONL)

Every line in your log file is a JSON object. This is great because the CLI and Control UI can parse these entries to show you structured data like the timestamp, log level, subsystem, and the message itself.

Console output

Console logs are smart enough to know if you’re in a TTY. They are formatted to be easy on the eyes:

• You get subsystem prefixes (like gateway/channels/whatsapp).
• Levels are color-coded (info, warn, or error).
• You can choose compact or JSON modes.

You can control how this looks using the logging.consoleStyle setting.

Configuring logging

You can find all the logging settings under the logging key in your ~/.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: This controls the file logs (JSONL).
• logging.consoleLevel: This controls how much you see in the console.

If you need to change things on the fly, use the OPENCLAW_LOG_LEVEL environment variable (for example, OPENCLAW_LOG_LEVEL=debug). This variable takes priority over your config file, so you can increase verbosity for a single run without touching your permanent settings. You can also use the global CLI option --log-level <level>, which overrides the environment variable.

Note that --verbose only changes what you see in the console; it won’t change your file log levels.

Console styles

You can set logging.consoleStyle to:

• pretty: This is human-friendly, colored, and includes timestamps.
• compact: A tighter output that works well for long sessions.
• json: One JSON object per line, perfect for log processors.

Redaction

To keep your secrets safe, tool summaries can hide sensitive tokens before they hit your screen:

• logging.redactSensitive: Set to off or tools (the default is tools).
• logging.redactPatterns: A list of regex strings if you want to override the defaults.

Keep in mind that redaction only affects your console output. It does not change the raw file logs.

Diagnostics + OpenTelemetry

Diagnostics are different from standard logs. They are structured, machine-readable events meant for model runs and message-flow telemetry. They don’t replace your logs; they provide the data needed for metrics and traces.

These events happen in-process, but exporters only start working when you enable both diagnostics and an exporter plugin.

OpenTelemetry vs OTLP

• OpenTelemetry (OTel) is the data model and SDK for your traces and metrics.
• OTLP is the protocol used to send that data to a collector.
• OpenClaw uses OTLP/HTTP (protobuf).

Signals exported

You can export Metrics (like token usage and message flow) and Traces (spans for model usage and processing). You can also export Logs over OTLP if you enable diagnostics.otel.logs. Just be careful with log volume and check your filters.

Diagnostic event catalog

For model usage, you get model.usage which tracks tokens, cost, and session IDs.

For message flow, you can track:

• webhook.received and webhook.processed.
• webhook.error for handler issues.
• message.queued and message.processed.

For queue and session monitoring, you have:

• queue.lane.enqueue and queue.lane.dequeue.
• session.state and session.stuck.
• run.attempt and diagnostic.heartbeat.

Enable diagnostics (no exporter)

If you just want diagnostics available for plugins or custom sinks without an external collector, use this:

{
  "diagnostics": {
    "enabled": true
  }
}

Diagnostics flags (targeted logs)

If you need extra debug info without turning on debug level for everything, use flags. These are case-insensitive and support wildcards.

{
  "diagnostics": {
    "flags": ["telegram.http"]
  }
}

You can also do a one-off override with an environment variable:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

These flag logs go to your standard log file and follow your redaction rules. You can find the full guide at /diagnostics/flags.

Export to OpenTelemetry

To send data to an OTel collector, use the diagnostics-otel plugin. This works with any backend that accepts OTLP/HTTP.

{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": {
        "enabled": true
      }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "http://otel-collector:4318",
      "protocol": "http/protobuf",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": true,
      "sampleRate": 0.2,
      "flushIntervalMs": 60000
    }
  }
}

You can also enable this via the CLI with openclaw plugins enable diagnostics-otel. Currently, protocol only supports http/protobuf. Metrics cover everything from token costs to queue depth, and you can toggle traces or metrics individually.

Exported metrics (names + types)

Model usage metrics include openclaw.tokens, openclaw.cost.usd, openclaw.run.duration_ms, and openclaw.context.tokens.

Message flow metrics track openclaw.webhook.received, openclaw.webhook.error, openclaw.webhook.duration_ms, openclaw.message.queued, openclaw.message.processed, and openclaw.message.duration_ms.

Queue and session metrics provide openclaw.queue.lane.enqueue, openclaw.queue.lane.dequeue, openclaw.queue.depth, openclaw.queue.wait_ms, openclaw.session.state, openclaw.session.stuck, openclaw.session.stuck_age_ms, and openclaw.run.attempt.

Exported spans (names + key attributes)

• openclaw.model.usage: Tracks providers, models, and token counts.
• openclaw.webhook.processed: Tracks channels and chat IDs.
• openclaw.webhook.error: Includes error details.
• openclaw.message.processed: Tracks outcomes and session keys.
• openclaw.session.stuck: Helps identify hanging sessions.

Sampling + flushing

You can control the trace sampling rate with diagnostics.otel.sampleRate (0.0 to 1.0). The metric export interval is set by diagnostics.otel.flushIntervalMs, with a minimum of 1000ms.

Protocol notes

You can set your OTLP/HTTP endpoints via the config or the OTEL_EXPORTER_OTLP_ENDPOINT environment variable. If your endpoint already includes paths like /v1/traces, OpenClaw will use it exactly as provided.

Log export behavior

OTLP logs use the same structured records as your file logs. They respect your logging.level setting, but console redaction rules do not apply here. If you have a high-volume setup, it is better to handle sampling at the collector level.

Troubleshooting tips

• Gateway not reachable? Run openclaw doctor first to check the basics.
• Logs empty? Make sure the Gateway is actually running and has permission to write to the path in logging.file.
• Need more detail? Bump your logging.level to debug or trace and try again.
• Config not loading? Double-check your JSON syntax in openclaw.json.

Related

• Gateway Logging Internals — Learn about WS log styles and subsystem prefixes.
• Diagnostics — Deep dive into OpenTelemetry and cache traces.

Still stuck? Ask the AI Setup Assistant for help.

Next Steps

• Explore Gateway Configuration for more settings.
• Check out the CLI Reference for more log commands.