Neura Market Logo

openclaw logs CLI Reference: Tail Gateway Logs via RPC

This page covers the openclaw logs command for streaming Gateway log files over RPC. Developers and operators use it to remotely view, filter, and follow log entries with options for JSON output and timezone control.

Read this when

  • You need to tail Gateway logs remotely (without SSH)
  • You want JSON log lines for tooling

openclaw logs

View Gateway log files remotely by streaming them over RPC. This command operates in remote mode.

Options

  • --limit <n>: maximum number of log lines returned (default 200)
  • --max-bytes <n>: maximum bytes read from the log file (default 250000)
  • --follow: continuously stream new log entries
  • --interval <ms>: delay between polls when following (default 1000)
  • --json: output events as line-delimited JSON
  • --plain: disable styled formatting for plain text output
  • --no-color: suppress ANSI color codes
  • --local-time: display timestamps in your local timezone (default behavior)
  • --utc: display timestamps in Coordinated Universal Time

Shared Gateway RPC options

  • --url <url>: WebSocket address for the Gateway
  • --token <token>: authentication token for the Gateway
  • --timeout <ms>: request timeout in milliseconds (default 30000)
  • --expect-final: wait for a final response when the Gateway call uses an agent

Using --url bypasses automatically applied config credentials; if the target Gateway requires authentication, provide --token explicitly.

Examples

openclaw logs
openclaw logs --follow
openclaw --dev logs --follow
openclaw --profile work logs --follow
openclaw logs --follow --interval 2000
openclaw logs --limit 500 --max-bytes 500000
openclaw logs --json
openclaw logs --plain
openclaw logs --no-color
openclaw logs --utc
openclaw logs --follow --local-time
openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

The active root profile determines which rolling file the Gateway uses: the default profile reads from openclaw-YYYY-MM-DD.log, whereas named profiles read from openclaw-<profile>-YYYY-MM-DD.log (for instance, openclaw-dev-YYYY-MM-DD.log).

Fallback and recovery behavior

  • When the implicit local loopback Gateway requests pairing, closes during connection, or times out before logs.tail responds, openclaw logs automatically switches to the configured Gateway file log. This fallback never applies to explicit --url targets.
  • After an implicit local Gateway RPC failure, --follow does not fall back to the configured file log, since a stale side-by-side file could misrepresent a live stream. On Linux, it instead uses the active user-systemd Gateway journal by PID when available (the selected source is printed); otherwise, it continues retrying the live Gateway.
  • With --follow, transient disconnects (WebSocket closure, timeout, dropped connection) trigger automatic reconnection using exponential backoff: up to 8 retries, with a maximum 30s interval between attempts. Each retry prints a warning to stderr, and a [logs] gateway reconnected notice prints once a poll succeeds. In --json mode, both messages appear as {"type":"notice"} records on stderr. Non-recoverable errors (authentication failure, invalid configuration) still cause immediate exit.
  • In --follow --json mode, transitions between log sources appear as {"type":"meta"} records. Track cursors per sourceKind: a stream may shift from Gateway file output (sourceKind: "file") to local journal fallback (sourceKind: "journal", localFallback: true, with service.pid/service.unit) and back to Gateway file output after recovery. Do not assume a single stable source or cursor for the entire session, and allow for overlapping lines when recovery replays the Gateway file cursor.