Logging#

OpenClaw writes two main log surfaces: file logs (JSON lines) and console output. The Control UI Logs tab and CLI tail the gateway file log.

Where logs live#

By default the Gateway writes a rolling log under:

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

The date uses the gateway host's local timezone. Each file rotates at logging.maxFileBytes (default 100 MB) and keeps up to five numbered archives.

Override the path in ~/.openclaw/openclaw.json:

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

How to read logs#

CLI (recommended for live tail)#

openclaw logs --follow

Common options:

--local-time — render timestamps in your local timezone
--json — emit line-delimited JSON
--plain — force plain text even in a TTY
--no-color — disable ANSI colors

When you pass --url, include --token yourself if the target requires auth. If the implicit local Gateway is unreachable, openclaw logs falls back to the configured file log. openclaw logs --follow prefers the active user-systemd journal when available.

If the Gateway is unreachable, run:

openclaw doctor

Control UI#

The Logs tab tails the same file using the logs.tail RPC surface.

Channel-only logs#

openclaw channels logs --channel whatsapp

Log formats#

File logs (JSONL)#

Each line is a JSON object. Top-level fields when present include hostname, message, agent_id, session_id, and channel. Original structured arguments are preserved.

Console output#

Console logs are TTY-aware with subsystem prefixes (e.g. gateway/channels/whatsapp), level coloring, and optional compact or JSON rendering. Controlled by logging.consoleStyle.

Configuring logging#

All settings live under the top-level logging key.

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

logging.level — file log level
logging.consoleLevel — console verbosity
logging.consoleStyle — pretty (default), compact, or json

The OPENCLAW_LOG_LEVEL environment variable overrides the config file. The global CLI flag --log-level <level> takes precedence for that invocation.

--verbose affects only console and WebSocket protocol output; it does not raise file log levels.

Targeted model transport diagnostics#

Use these environment flags instead of raising the global level to debug:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gateway
OPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

Available flags:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 — request start, first streaming event, completion, and transport errors at info
OPENCLAW_DEBUG_MODEL_PAYLOAD=summary|tools|full-redacted
OPENCLAW_DEBUG_SSE=events|peek
OPENCLAW_DEBUG_CODE_MODE=1

These route through normal logging and appear in openclaw logs --follow and the Control UI.

Redaction#

logging.redactSensitive (off | tools, default tools) masks common API credentials and payment fields in console output, file logs, persisted transcripts, and Control UI tool payloads. logging.redactPatterns adds custom regexes on top of the built-in set.

logging.redactSensitive: "off" only disables the general policy; safety-boundary payloads (tool events, support exports, approval prompts) remain redacted.

Trace correlation and model-call measurements#

When a valid trace context is present, file logs include traceId, spanId, parentSpanId, and traceFlags. Model-call records include bounded fields such as requestPayloadBytes, responseStreamBytes, timeToFirstByteMs, and durationMs without capturing raw prompt or response content.

Troubleshooting#

Empty logs? Confirm the Gateway is running and writing to the configured logging.file.
Need more detail? Set logging.level (or OPENCLAW_LOG_LEVEL) to debug or trace.
Gateway unreachable? Run openclaw doctor first.