mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-05 13:23:34 +00:00
bd5bf4820a
* fix(cli): retry logs.tail after journal fallback in logs follow Rebase #88159 onto current main and keep systemd journal fallback temporary in follow mode. Preserve the journal cursor across repeated fallback outages, but retry logs.tail on the next loop so recovered Gateway RPC returns to normal log output. This refresh also replaces the stale red checks-node-core-fast result from the old head with a current-head CI run. * Keep log source metadata explicit * ci: retrigger checks for PR #88159 * docs: clarify logs follow JSON source transitions * fix(cli): keep journal logs responsive during recovery --------- Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
70 lines
3.5 KiB
Markdown
70 lines
3.5 KiB
Markdown
---
|
|
summary: "CLI reference for `openclaw logs` (tail gateway logs via RPC)"
|
|
read_when:
|
|
- You need to tail Gateway logs remotely (without SSH)
|
|
- You want JSON log lines for tooling
|
|
title: "Logs"
|
|
---
|
|
|
|
# `openclaw logs`
|
|
|
|
Tail Gateway file logs over RPC (works in remote mode).
|
|
|
|
Related:
|
|
|
|
- Logging overview: [Logging](/logging)
|
|
- Gateway CLI: [gateway](/cli/gateway)
|
|
|
|
## Options
|
|
|
|
- `--limit <n>`: maximum number of log lines to return (default `200`)
|
|
- `--max-bytes <n>`: maximum bytes to read from the log file (default `250000`)
|
|
- `--follow`: follow the log stream
|
|
- `--interval <ms>`: polling interval while following (default `1000`)
|
|
- `--json`: emit line-delimited JSON events
|
|
- `--plain`: plain text output without styled formatting
|
|
- `--no-color`: disable ANSI colors
|
|
- `--local-time`: render timestamps in your local timezone (default)
|
|
- `--utc`: render timestamps in UTC
|
|
|
|
## Shared Gateway RPC options
|
|
|
|
`openclaw logs` also accepts the standard Gateway client flags:
|
|
|
|
- `--url <url>`: Gateway WebSocket URL
|
|
- `--token <token>`: Gateway token
|
|
- `--timeout <ms>`: timeout in ms (default `30000`)
|
|
- `--expect-final`: wait for a final response when the Gateway call is agent-backed
|
|
|
|
When you pass `--url`, the CLI does not auto-apply config or environment credentials. Include `--token` explicitly if the target Gateway requires auth.
|
|
|
|
## Examples
|
|
|
|
```bash
|
|
openclaw logs
|
|
openclaw 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 --limit 500
|
|
openclaw logs --local-time
|
|
openclaw logs --utc
|
|
openclaw logs --follow --local-time
|
|
openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Timestamps render in your local timezone by default. Use `--utc` for UTC output.
|
|
- If the implicit local loopback Gateway asks for pairing, closes during connect, or times out before `logs.tail` answers, `openclaw logs` falls back to the configured Gateway file log automatically. Explicit `--url` targets do not use this fallback.
|
|
- `openclaw logs --follow` does not follow configured-file fallbacks after implicit local Gateway RPC failures. On Linux, it uses the active user-systemd Gateway journal by PID when available and prints the selected log source; otherwise it keeps retrying the live Gateway instead of tailing a potentially stale side-by-side file.
|
|
- When using `--follow`, transient gateway disconnects (WebSocket close, timeout, connection drop) trigger automatic reconnection with exponential backoff (up to 8 retries, capped at 30 s between attempts). A warning is printed to stderr on each retry, and a `[logs] gateway reconnected` notice is printed once a poll succeeds. In `--json` mode both the retry warning and the reconnect transition are emitted as `{"type":"notice"}` records on stderr. Non-recoverable errors (auth failure, bad configuration) still exit immediately.
|
|
- In `--follow --json` mode, log source transitions are emitted as `{"type":"meta"}` records. Consumers should track cursors per `sourceKind`: a stream can move 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 one stable source or cursor for the whole follow session, and tolerate overlapping lines when recovery replays the Gateway file cursor.
|
|
|
|
## Related
|
|
|
|
- [CLI reference](/cli)
|
|
- [Gateway logging](/gateway/logging)
|