Complete reference for openclaw logs, tailing live Gateway output, fetching snapshots, controlling output format, and streaming structured JSON for scripting.
What does Openclaw Logs do?
It connects to the running Gateway and streams its log output directly to your terminal, the same logs the Gateway is writing internally, delivered in real time. Without any flags, it fetches a recent snapshot and exits.
With –follow, it stays open and continuously streams new entries as they arrive, exactly like tail -f on a log file but over the Gateway’s WebSocket RPC. This is the fastest way to see what the Gateway is actually doing when messages aren’t arriving or agents aren’t responding.
Interactive vs. Scripted Use
For interactive debugging in a terminal, the default colorized output is the most readable option, just run openclaw logs –follow and watch the stream. For piping logs into jq, sending them to a log aggregator, or writing monitoring scripts, always use –json.
The JSON output emits type-tagged objects per line (meta, log, notice, raw) that are straightforward to filter and parse. If the Gateway isn’t reachable at all, the command will print a hint to run openclaw doctor, that’s your signal to switch to the diagnostics guide.
Basic Usage
Two modes, snapshot and follow. Pick based on whether you need a one-shot capture or a live stream.
| Live stream openclaw logs –follow Continuously streams new log entries as they are written. Stays open until you Ctrl+C. | Recent snapshot openclaw logs Fetches recent log output and exits. Quick check without an open stream. |
basic usage
# Follow live — stays open openclaw logs --follow # Quick snapshot — exits after printing openclaw logs
Options & Flags
All flags are additive and combinable. The formatting flags (–plain, –no-color, –json) are mutually exclusive with each other.
| Flag | Group | Description |
|---|---|---|
| –follow | stream | Continuously streams new log entries as they are written. Equivalent to tail -f behavior. |
--limit <n> | stream | Restricts the output to the last n lines. Example: openclaw logs --limit 500. |
| –local-time | stream | Formats the timestamps in the logs to match your local system’s timezone instead of the Gateway’s internal time. |
| –plain | format | Forces plain text output even in TTY sessions. Use when piping to tools that don’t handle ANSI codes. |
| –no-color | format | Disables ANSI colors while keeping structured text formatting. |
| –json | format | Outputs the logs as line-delimited JSON, one log event per line. Highly recommended for scripting. Emits type-tagged objects: meta, log, notice, and raw. |
JSON Output Mode
When using –json, the CLI emits line-delimited JSON with type-tagged objects. One event per line, pipe directly into jq or any log aggregator.
| meta Session and connection metadata events. | log Standard Gateway log entries. | notice Important status notices and alerts. | raw Unstructured or passthrough log lines. |
JSON mode with jq filtering
# Stream structured JSON logs openclaw logs --follow --json # Pipe into jq — filter to log-type events only openclaw logs --follow --json | jq 'select(.type == "log")' # Snapshot last 100 lines as JSON openclaw logs --limit 100 --json
When piping –json output through other tools, you may want to combine with –no-color even in JSON mode to ensure no stray ANSI escape sequences end up in your pipeline if the terminal detection behaves unexpectedly.
Examples
Three ready-to-run patterns for the most common log workflows.
01 Tail logs with local timestamps
openclaw logs --follow --local-time
02 Fetch the last 200 lines in plain text
openclaw logs --limit 200 --plain
03 Stream structured JSON logs
openclaw logs --follow --json
Gateway Unreachable
If the Gateway is unreachable when you run openclaw logs, the CLI will print a hint suggesting you run the diagnostic suite. This is your cue to switch from log inspection to the full Openclaw Doctor Commands and Uses guide to identify why the process is unresponsive or the RPC connection is being refused.
when logs fails — escalate to doctor
# Step 1: try logs — if Gateway unreachable, CLI prints a hint openclaw logs # Step 2: run doctor to diagnose and repair the connection openclaw doctor # Step 3: once Gateway is healthy, retry openclaw logs --follow
