OpenClaw Logging — Where Logs Live and How to Read Them

OpenClaw Logging

When something goes wrong, logs are your first stop. I can’t count how many times I’ve solved issues just by tailing the log file and spotting an obvious error message.

OpenClaw logs to two places: a JSON file (for parsing) and the console (for humans). Here’s how to find and use both.

---

Where Logs Live

By default, the Gateway writes a rolling log file:

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

Override in your config:

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

---

Reading Logs

CLI Tail (Recommended)

openclaw logs --follow

Output modes:

• TTY: Pretty, colorized, structured
• Non-TTY: Plain text
• --json: Line-delimited JSON
• --plain: Force plain text
• --no-color: Disable ANSI colors

Control UI

The Control UI’s Logs tab tails the same file. Open via openclaw control.

Channel-Only Logs

Filter to specific channels:

openclaw channels logs --channel whatsapp

---

Log Levels

{
  logging: {
    level: "info",           // File log level
    consoleLevel: "info",    // Console verbosity
    consoleStyle: "pretty"   // pretty | compact | json
  }
}

Levels: trace, debug, info, warn, error

--verbose flag only affects console output, not file logs.

---

Redaction

Protect sensitive data in console output:

{
  logging: {
    redactSensitive: "tools",        // off | tools
    redactPatterns: ["sk-.*"]        // Custom regex patterns
  }
}

Redaction affects console only—file logs are unredacted.

---

Diagnostics & OpenTelemetry

For production monitoring, export metrics and traces to your observability stack.

Enable Diagnostics

{
  diagnostics: {
    enabled: true
  }
}

Export via OpenTelemetry

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

What Gets Exported

Metrics:

• openclaw.tokens — Token usage counter
• openclaw.cost.usd — Cost tracking
• openclaw.run.duration_ms — Run duration histogram
• openclaw.webhook.received — Webhook activity
• openclaw.message.processed — Message throughput

Traces:

• openclaw.model.usage — Model completion spans
• openclaw.webhook.processed — Webhook processing
• openclaw.message.processed — Message handling

---

Debug Flags (Targeted Logging)

Get extra logs without raising the global level:

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

Or via environment:

OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload

Supports wildcards: telegram.* or * for everything.

---

Troubleshooting

”Gateway not reachable”

openclaw doctor

Logs empty

Check: Is the Gateway running? Is logging.file pointing to the right path?

Need more detail

Set logging.level to debug or trace:

{
  logging: {
    level: "debug"
  }
}

---

JSON Mode Details

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

Type	Description
meta	Stream metadata (file, cursor, size)
log	Parsed log entry
notice	Truncation/rotation hints
raw	Unparsed log line

---

Complete Diagnostic Event Catalog

Model Usage Events

Event	Description
model.usage	Tokens, cost, duration, context, provider/model/channel, session IDs

Message Flow Events

Event	Description
webhook.received	Webhook ingress per channel
webhook.processed	Webhook handled + duration
webhook.error	Webhook handler errors
message.queued	Message enqueued for processing
message.processed	Outcome + duration + optional error

Queue + Session Events

Event	Description
queue.lane.enqueue	Command queue lane enqueue + depth
queue.lane.dequeue	Command queue lane dequeue + wait time
session.state	Session state transition + reason
session.stuck	Session stuck warning + age
run.attempt	Run retry/attempt metadata
diagnostic.heartbeat	Aggregate counters (webhooks/queue/session)

---

Complete Exported Metrics

Model Usage

Metric	Type	Attributes
openclaw.tokens	Counter	type, channel, provider, model
openclaw.cost.usd	Counter	channel, provider, model
openclaw.run.duration_ms	Histogram	channel, provider, model
openclaw.context.tokens	Histogram	context, channel, provider, model

Message Flow

Metric	Type	Attributes
openclaw.webhook.received	Counter	channel, webhook
openclaw.webhook.error	Counter	channel, webhook
openclaw.webhook.duration_ms	Histogram	channel, webhook
openclaw.message.queued	Counter	channel, source
openclaw.message.processed	Counter	channel, outcome
openclaw.message.duration_ms	Histogram	channel, outcome

Queues + Sessions

Metric	Type	Attributes
openclaw.queue.lane.enqueue	Counter	lane
openclaw.queue.lane.dequeue	Counter	lane
openclaw.queue.depth	Histogram	lane or channel=heartbeat
openclaw.queue.wait_ms	Histogram	lane
openclaw.session.state	Counter	state, reason
openclaw.session.stuck	Counter	state
openclaw.session.stuck_age_ms	Histogram	state
openclaw.run.attempt	Counter	attempt

---

Complete Exported Spans

Span	Key Attributes
openclaw.model.usage	channel, provider, model, sessionKey, sessionId, tokens.*
openclaw.webhook.processed	channel, webhook, chatId
openclaw.webhook.error	channel, webhook, chatId, error
openclaw.message.processed	channel, outcome, chatId, messageId, sessionKey, sessionId, reason
openclaw.session.stuck	state, ageMs, queueDepth, sessionKey, sessionId

---

Sampling + Flushing

Setting	Description
diagnostics.otel.sampleRate	0.0–1.0, root spans only
diagnostics.otel.flushIntervalMs	Metric export interval (min 1000ms)

---

Protocol Notes

• OTLP/HTTP endpoints via diagnostics.otel.endpoint or OTEL_EXPORTER_OTLP_ENDPOINT
• If endpoint contains /v1/traces, /v1/metrics, or /v1/logs, used as-is
• Environment variables: OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_PROTOCOL
• Currently supports http/protobuf only (grpc is ignored)

---

Log Export Behavior

• OTLP logs use the same structured records written to logging.file
• Respects logging.level (file log level)
• Console redaction does not apply to OTLP logs
• High-volume installs should prefer OTLP collector sampling/filtering

Still stuck? Our AI Setup Assistant can help interpret your logs.

---

What’s Next?

• Debugging → — Watch mode and raw stream logging
• Testing → — Test suites and live testing
• Gateway Configuration → — Full config reference

---

Need help? Join the OpenClaw Discord or check the GitHub Issues.