Neura Market Logo

openclaw logs: Follow Gateway Logs via RPC

This page covers the openclaw logs command for streaming Gateway logs over RPC. It details options for limiting, following, formatting, and timestamp display, useful for CLI users in remote mode.

Read this when

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

openclaw logs

File logs from the Gateway can be followed over RPC with this command. It functions when operating in remote mode.

Options

  • --limit <n>: upper bound on the number of log lines returned (defaults to 200)
  • --max-bytes <n>: byte cap for reading from the log file (defaults to 250000)
  • --follow: keep streaming the log as new entries arrive
  • --interval <ms>: how often to check for new entries while following (defaults to 1000)
  • --json: output events as JSON with one record per line
  • --plain: produce plain text output, skipping any styled formatting
  • --no-color: turn off ANSI color codes
  • --local-time: display timestamps according to your local timezone (this is the default)
  • --utc: display timestamps in Coordinated Universal Time

Shared Gateway RPC options

  • --url <url>: WebSocket endpoint for the Gateway
  • --port <port>: pick a local Gateway port, which overrides the configured remote URL and OPENCLAW_GATEWAY_URL; this option conflicts with --url
  • --token <token>: authentication token for the Gateway
  • --timeout <ms>: timeout duration in milliseconds (defaults to 30000)
  • --expect-final: when the Gateway call is backed by an agent, hold for a concluding response

Supplying --url prevents auto-applied configuration credentials from being used; if the target Gateway demands authentication, pass --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 --port 19083 --json
openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

The chosen root profile corresponds to the Gateway's rolling log file: the default profile points to openclaw-YYYY-MM-DD.log, whereas named profiles reference 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, terminates during connection, or fails to respond within logs.tail, openclaw logs automatically switches to the configured Gateway file log. Explicit --url targets never trigger this fallback behavior.
  • After an implicit local Gateway RPC failure, --follow will not fall back to that configured file, since a stale adjacent file could misrepresent a live tail. On Linux, it instead consults the active user-systemd Gateway journal by PID when that is available (the chosen source is printed); otherwise it continues retrying the live Gateway.
  • While --follow is active, short-lived interruptions (WebSocket closure, timeout, dropped connection) cause automatic reconnection using exponential backoff: at most 8 attempts, with a 30s maximum gap between tries. Each retry logs a warning to stderr, and a [logs] gateway reconnected notification appears once a poll succeeds. In --json mode, both of these are sent as {"type":"notice"} records to stderr. Unrecoverable issues, such as authentication failures or invalid configuration, still cause an immediate exit.
  • Under --follow --json mode, shifts in the log source are reported as {"type":"meta"} records. Cursors are tracked per sourceKind: a stream may begin as Gateway file output (sourceKind: "file"), move to the local journal fallback (sourceKind: "journal", localFallback: true, with service.pid/service.unit), and then return to Gateway file output once recovery happens. Do not expect a single consistent source or cursor across the entire session, and be ready for overlapping lines when recovery replays the Gateway file cursor.

When --json mode is used, malformed --port, --limit, --interval, or --max-bytes entries, along with conflicting --url/--port flags, result in the standard CLI failure envelope on stdout: {"ok":false,"error":{"type":"cli_error","message":"..."}}. Terminal log-fetch errors, by contrast, produce {"type":"error",...} on stderr. In both cases, the exit code is 1.

For text mode, terminal log-fetch errors print the sanitized error message, the chosen Gateway connection details, and a doctor suggestion on stderr. An RPC rejection that is received is displayed as the error itself, not as a Gateway connectivity problem.

644 words · updated Aug 28, 2026