OpenClaw Logging Guide: openclaw logs, Levels, Redaction, and the 24-Hour Window

Your gateway keeps a detailed diary of everything it does. It keeps it in /tmp, and it throws each day's pages out after 24 hours.

The guides that rank for openclaw logs are long and mostly correct. They cover the file location, every flag on the command, levels versus --verbose, a few jq one-liners, and token masking. I cover the same ground here in less space. None of them mention retention, which is the thing that actually bites: the cron job that failed at 3am on Saturday left a perfect record of why, and by Monday morning that record no longer exists. The last section fixes that.

Where the Files Are

The gateway writes one JSON object per line to a rolling daily file:

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

The date follows the gateway host's local timezone, so a gateway on a VPS set to UTC rolls over at a different hour than your laptop does. If /tmp/openclaw is unsafe (owned by someone else, say, or world-writable), OpenClaw quietly switches to a user-scoped openclaw-<uid> folder under the OS temp directory. Windows always uses that fallback. When a file would pass logging.maxFileBytes (100 MB by default) it rotates, keeping up to five numbered archives like openclaw-2026-10-12.1.log.

Dated files are pruned after 24 hours. That sentence sits in the middle of a paragraph in the official docs, and it changes how you should think about everything else on this page.

Tailing With openclaw logs

openclaw logs --follow
openclaw --profile work logs --follow
openclaw logs --limit 500 --max-bytes 500000
openclaw logs --follow --json | jq -c 'select(.type == "log")'

The command reads the file over the gateway's RPC (logs.tail), which is why it works against a remote gateway with no SSH session. Defaults are 200 lines and 250,000 bytes per fetch, polling every 1,000 ms while following. The Control UI Logs tab reads the same file the same way, so the two never disagree.

Remote targets have one trap. Pass --url and the CLI stops applying your configured credentials, so you need --token too, or you get gateway url override requires explicit credentials. When the implicit local gateway asks for pairing or times out, the CLI falls back to reading the file directly. An explicit --url never falls back.

If you script against --follow --json, read the meta records. On Linux a follow can switch from the gateway file (sourceKind: "file") to the user-systemd journal (sourceKind: "journal") when the gateway drops, then switch back after recovery, replaying some lines. Track cursors per sourceKind and dedupe. A watcher that assumes one stable stream will double-count errors during exactly the incident you built it for.

For one channel only, openclaw channels logs --channel telegram takes --lines and --json.

Levels, and Why --verbose Lies to You

Levels run silent, fatal, error, warn, info, debug, trace. Two settings, independent of each other: logging.level for the file (default info) and logging.consoleLevel for the terminal.

--verbose changes the console and the WebSocket log style. It does not touch the file. People run openclaw gateway --verbose, watch a wall of detail scroll past, reproduce the bug, then open the log file expecting the same detail and find ordinary info lines.

To raise the file level for one run, OPENCLAW_LOG_LEVEL=debug beats the config file, and --log-level debug on the command beats the env var. With hot reload on, editing logging.level applies to the next log record. No restart.

My strong preference is to leave the level at info and reach for targeted flags instead. Global debug on a busy gateway fills the 100 MB rotation budget fast, and the five archives roll over before you have read any of them. If the problem is the model provider, use the transport flags:

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

The first logs request start, response headers, first streaming event and completion at info, which is usually all you need when a call hangs. For a channel, set diagnostics.flags to something like ["telegram.*"], which routes extra detail into the file without raising logging.level. The model failover guide covers what to do once the transport lines show a provider is the culprit.

Querying the JSONL

File records carry top-level fields whenever the log call has the context for them: hostname, message, agent_id, session_id and channel, plus traceId and spanId when a trace is active. That turns jq into a real query tool:

LOG=/tmp/openclaw/openclaw-$(date +%F).log

# one agent's lines, message text only
jq -r 'select(.agent_id == "main") | .message' "$LOG"

# everything one session did
jq -c 'select(.session_id == "SESSION_ID")' "$LOG"

# every line from one request, across agent run and model call
jq -c 'select(.traceId == "TRACE_ID")' "$LOG"

Some messages worth grepping for by name. slow chat send appears when acknowledgement or startup takes a second or more, and its stage field says which. chat pending input aborted tells you a message was accepted and then dropped, with a cause such as timeout or restart. And [anthropic] replayed thinking dropped is a warning you get with no debug flag at all.

Redaction Has a Sharp Edge

Some older guides tell you to toggle logging.redactSensitive. The current docs say sensitive-value redaction is always enabled, and the setting you actually control is logging.redactPatterns. Read its description carefully: the list you supply replaces the default string list for log and transcript output. The built-in structural protections, the one for authorization headers for example, survive. The rest of the default list does not, unless you copy it in.

So adding ["sk-.*"] to catch one key format can loosen masking for everything else. Leave the setting unset unless you have a token format the defaults miss. Register real secrets through the secrets workflow instead, because registered values stay masked regardless of key names.

Also: OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted masks secrets but keeps prompts and message text. Turn it off when you are done.

Keeping Logs Longer Than a Day

Here is the gap. A dated file lives 24 hours, in a directory the operating system is free to clear on reboot. If you are reading this because something broke two days ago, the evidence is already gone.

The fix is boring and it works. Copy the log directory somewhere durable on a schedule shorter than the pruning window:

# crontab -e  (system cron, not an agent job)
15 * * * * rsync -a /tmp/openclaw/ "$HOME/openclaw-logs/"

Hourly gives you 23 hours of slack. Gzip the archive weekly if disk matters. Run this from system cron or launchd rather than from the gateway, because the job exists to capture the times the gateway itself fell over; the cron automation guide explains which jobs belong where. If you run a collector already, set diagnostics.otel.logsExporter and ship records over OTLP instead. The observability guide covers what to do with them once they arrive.

The copies carry everything the redactor did not catch. Treat the folder like a backup.

Common Failure Modes

Final Verdict

Set up the hourly copy today, before you need it, and leave logging.level at info with targeted flags for the bad days. Everything else in OpenClaw logging is a flag you can look up when the moment comes. The 24-hour window is different, because it only punishes people who learn about it afterwards.