Logging: File Logs, Console Output, and Control UI Logs Tab

OpenClaw exposes two distinct logging surfaces:

• File logs (JSON lines) produced by the Gateway.
• Console output shown in the terminal where the Gateway runs.

The Logs tab in the Control UI follows the gateway file log. This page covers log storage locations, reading techniques, and level/format configuration.

Where logs live

By default, the Gateway rotates a log file daily. The default profile retains the historical path:

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

Named profiles use a profile-qualified filename within the same directory:

/tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log

The profile segment in the filename is lowercase, restricted to letters, numbers, and dashes. Straightforward lowercase names remain legible, so the --dev shorthand produces openclaw-dev-YYYY-MM-DD.log. For cases, underscores, and literal dashes, a reversible dash escape keeps distinct profile names from colliding on a single log file. When oversized values are set directly via environment variables, a bounded hash suffix ensures filenames stay within filesystem limits. An explicit logging.file takes precedence over these defaults.

The date reflects the gateway host's local timezone. If /tmp/openclaw is unsafe or unavailable (and always on Windows), OpenClaw falls back to a user-scoped openclaw-<uid> directory under the OS temp folder. Dated log files are removed after 24 hours.

Rotation occurs when the next write would surpass logging.maxFileBytes (default: 100 MB). OpenClaw retains up to five numbered archives alongside the active file, such as openclaw-YYYY-MM-DD.1.log or openclaw-dev-YYYY-MM-DD.1.log, and continues writing to a fresh active log rather than suppressing diagnostics.

You can override the path in ~/.openclaw/openclaw.json:

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

How to read logs

CLI: live tail (recommended)

Follow the gateway log file via RPC:

openclaw logs --follow
openclaw --dev logs --follow
openclaw --profile work logs --follow

The root profile selector resolves the same profile-specific file the Gateway uses, including CLI fallback reads when local RPC is unavailable.

Options:

Output modes:

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

When you supply an explicit --url, the CLI skips auto-applying config or environment credentials; include --token yourself, or the call fails with gateway url override requires explicit credentials.

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

• meta: stream metadata (file, source, sourceKind, service, cursor, size)
• log: parsed log entry
• notice: truncation / rotation hints
• raw: unparsed log line
• error: gateway connection failures (written to stderr)

If the implicit local loopback Gateway requests pairing, closes during connect, or times out before logs.tail answers, openclaw logs falls back to the configured Gateway file log automatically. Explicit --url targets do not use this fallback. openclaw logs --follow is stricter: on Linux it uses the active user-systemd Gateway journal by PID when available, and otherwise retries the live Gateway with backoff instead of following a potentially stale side-by-side file.

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 Control UI for how to open it.

Channel-only logs

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

openclaw channels logs --channel whatsapp

--channel defaults to all; --lines <n> (default 200) and --json are also available.

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:

• hostname: the host name of the gateway.
• message: the flattened log message text, intended for full-text search.
• agent_id: the active agent id, present when the log call includes agent context.
• session_id: the active session id or key, present when the log call includes session context.
• channel: the active channel, present when the log call includes channel context.

Alongside these fields, OpenClaw keeps the original structured log arguments intact, so parsers that rely on numbered tslog argument keys continue to function without changes.

Lifecycle log records for Talk, realtime voice, and managed-room activity flow through this same file-log pipeline, with bounded output. These records capture event type, mode, transport, provider, and size or timing measurements when those are available, while deliberately excluding transcript text, audio payloads, turn ids, call ids, and provider item ids.

Console output

Console logs are TTY-aware and laid out for readability:

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

The logging.consoleStyle setting governs console formatting.

Gateway WebSocket logs

For RPC traffic, openclaw gateway additionally provides WebSocket protocol logging:

• normal mode: only noteworthy results (errors, parse errors, slow calls)
• --verbose: all request and response traffic
• --ws-log auto|compact|full: choose the verbose rendering style
• --compact: shorthand for --ws-log compact

Examples:

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

Configuring logging

All logging settings are grouped under logging within ~/.openclaw/openclaw.json.

{
  "logging": {
    "level": "info",
    "file": "/path/to/openclaw.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactPatterns": ["sk-.*"]
  }
}

Log levels

Levels: silent, fatal, error, warn, info, debug, trace.

• logging.level: level for file logs (JSONL), defaulting to info.
• logging.consoleLevel: verbosity level for the console.

Both can be overridden through the OPENCLAW_LOG_LEVEL environment variable (for instance, OPENCLAW_LOG_LEVEL=debug). The environment variable takes priority over the config file, letting you increase verbosity for a single run without touching openclaw.json. Alternatively, the global CLI option --log-level <level> (e.g. openclaw --log-level debug gateway run) can be passed, and it supersedes the environment variable for that specific command.

--verbose influences only console output and WS log verbosity; file log levels remain unaffected.

Targeted model transport diagnostics

When debugging provider calls, prefer targeted environment flags over setting everything 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: logs request start, fetch response, SDK headers, first streaming event, stream completion, and transport errors at the info level.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: adds a bounded request payload summary to model request logs.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: includes every model-facing tool name in the payload summary.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: adds a redacted, capped JSON payload snapshot. Use this only during debugging; secrets are redacted, but prompts and message text may still appear.
• OPENCLAW_DEBUG_SSE=events: logs first-event and stream-completion timing.
• OPENCLAW_DEBUG_SSE=peek: also logs the first five redacted SSE event payloads, each capped per event.
• OPENCLAW_DEBUG_CODE_MODE=1: emits code-mode model-surface diagnostics, covering bounded activation facts, the final visible surface, and names of provider-native tools filtered out because code mode owns the tool surface.

These flags write through the normal OpenClaw logging path, so openclaw logs --follow and the Control UI Logs tab display them. For backward compatibility, OPENCLAW_DEBUG_CODE_MODE also raises general model-transport diagnostics to info; dedicated code-mode diagnostics appear only when that flag is turned on.

Start and response metadata for [model-fetch] (provider, API, model, status, latency, and request fields like method, URL, timeout, proxy, and policy) is always logged at the info level, independent of OPENCLAW_DEBUG_MODEL_TRANSPORT, so basic model transport hygiene stays visible without any debug flags.

Trace correlation

File logs use JSONL format. When a log call includes a valid diagnostic trace context, OpenClaw writes the trace fields as top-level JSON keys (traceId, spanId, parentSpanId, traceFlags) so external log processors can tie the line to OTEL spans and provider traceparent propagation.

Gateway HTTP requests and Gateway WebSocket frames set up an internal request trace scope. When no explicit trace context is supplied, logs and diagnostic events generated inside that async scope pick up the request trace. Agent run and model-call traces sit underneath the active request trace, which lets local logs, diagnostic snapshots, OTEL spans, and trusted provider traceparent headers be linked together by traceId without logging raw request or model content.

Talk lifecycle log records also reach the diagnostics-otel log export when OpenTelemetry log export is switched on, using the same bounded attributes as file logs. Set diagnostics.otel.logsExporter to pick OTLP, stdout JSONL, or both sinks.

Model call size and timing

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

• requestPayloadBytes: UTF-8 byte size of the final model request payload
• responseStreamBytes: UTF-8 byte size of streamed model response chunk payloads. High-frequency text, thinking, and tool-call delta events count only the incremental delta bytes instead of full partial snapshots.
• timeToFirstByteMs: elapsed time before the first streamed response event
• 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

logging.consoleStyle accepts pretty or json:

• pretty: human-friendly, colored, with timestamps.
• json: JSON per line (for log processors).

A third rendering style, compact (tighter output, best for long sessions), is applied automatically when stdout is not a TTY. It is no longer a settable config value; openclaw doctor --fix maps a stored consoleStyle: "compact" to "pretty".

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

• Sensitive-value redaction is always enabled.
• logging.redactPatterns: list of regex strings that replaces the default set for log/transcript output. For Control UI tool payloads, custom patterns apply on top of the built-in defaults, 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.

OpenClaw also redacts safety-boundary payloads shown to UI clients, support bundles, diagnostics observers, approval prompts, or agent tools. Custom logging.redactPatterns can 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 by default (set diagnostics.enabled: false to turn them off); exporting them is separate.

Two adjacent surfaces:

• OpenTelemetry export, send metrics, traces, and logs over OTLP/HTTP to any OpenTelemetry-compatible collector or backend (Datadog, Grafana, 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.

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