OpenClaw logs

OpenClaw has two log surfaces: JSON-lines files written by the Gateway, and the console output of the terminal running it. The Control UI’s Logs tab tails the file, and the logs command does the same over RPC. Most troubleshooting in the docs ends with one of those three, so here is where the files live, how they rotate and disappear, how to tail them, and what to read when the Gateway itself will not boot.

Where they live

• A rolling file per day under a temp directory named after OpenClaw, with the date in the filename; named profiles get a profile-qualified name, and the dev shorthand writes its own file.
• When that directory is unsafe or unavailable, and always on Windows, a user-scoped directory under the OS temp dir is used instead; the date follows the host’s local timezone.
• A file rotates when the next write would exceed 100 megabytes, with up to five numbered archives kept beside the active one, and the path can be overridden in the config’s logging block.

Dated log files are pruned after 24 hours.

How to read them

The logs command with the follow flag tails the Gateway file over RPC, reconnecting with backoff, and the dev and profile selectors resolve the same file the Gateway writes, with a fallback to reading the file directly when local RPC is unavailable. The flags cover the lines per fetch, 200 by default, the bytes per fetch, the poll interval, line-delimited JSON, plain text, no colour and UTC timestamps. The Control UI shows the same tail in its Logs tab.

When something is wrong

• An invalid config means the Gateway does not boot and only the diagnostic commands work: doctor, logs, health and status, in that order of usefulness.
• On a systemd host the service journal is the other place to look, and the platform pages say so for every install path from a VPS to a Pi.
• Pruning after a day means a problem from last week has no file left; copy the file out when a failure is intermittent.

OpenClaw not responding is the symptom-first ladder that ends in these files, and OpenClaw terminal commands lists the commands beside logs.

Levels, formats, redaction

The rest of the logging page is configuration: log levels, the file and console formats, and redaction of secrets in log lines, all under the logging block that The OpenClaw config file describes.

On Diali

On Diali you do not go looking for a file under a temp directory: the assistant’s activity is in the dashboard, and the Gateway’s own logs are kept by us for the instance. Hosted OpenClaw on Diali is the assistant.

• One JSON-lines file per day, rotated at 100 MB, gone after 24 hours.
• Tail with the logs command or the Control UI.
• Doctor first when the Gateway will not boot.