Best possible solution:

Land one canonical focused CLI fix that retries transient follow-mode Gateway disconnects, preserves fatal auth/pairing behavior and implicit-loopback fallback, keeps JSON output machine-readable, includes tests/docs/changelog, and supersedes the competing PR if needed.

Do we have a high-confidence way to reproduce the issue?

Yes. Current main has a source-level reproduction: an explicit --url follow fetch that raises a closed GatewayTransportError reaches the catch path and exits, and the existing explicit-URL test asserts that fatal behavior.

Is this the best way to solve the issue?

No, not as-is. The retry loop is the right boundary, but this branch should emit retry notices as JSON under --json and add the required changelog entry before it is the best merge candidate.

Full review comments:

• [P2] Emit retry notices as JSON in --json mode — src/cli/logs-cli.ts:343-348
  The new retry branch always writes a styled text line to stderr. In openclaw logs --json, existing errors and notices are JSON records and the docs advertise line-delimited JSON events, so this plain text breaks machine consumers during a recoverable disconnect. Branch on jsonMode and emit a notice JSON record instead.
  Confidence: 0.86
• [P3] Add the required changelog entry — src/cli/logs-cli.ts:339
  This is a user-facing CLI fix, but the PR head only changes docs, the logs CLI, and tests. Add a single-line active CHANGELOG.md Fixes entry for the reconnect behavior with appropriate human credit before merge.
  Confidence: 0.92

Overall correctness: patch is incorrect
Overall confidence: 0.86

Acceptance criteria:

• pnpm test src/cli/logs-cli.test.ts
• pnpm exec oxfmt --check --threads=1 src/cli/logs-cli.ts src/cli/logs-cli.test.ts docs/cli/logs.md CHANGELOG.md
• git diff --check
• pnpm check:changed in Testbox before merge if the branch is promoted

What I checked:

• Current main exits on follow fetch failures: The current follow loop catches fetchLogs errors, emits the Gateway error, calls process.exit(1), and returns with no retry path. (src/cli/logs-cli.ts:313, 9fff2b779159)
• Explicit URL path bypasses local fallback: shouldUseLocalLogsFallback returns false when opts.url is set, so explicit Gateway targets still reach the fatal catch path on closed or timed-out transport errors. (src/cli/logs-cli.ts:105, 9fff2b779159)
• Existing test asserts current fatal explicit-URL behavior: The current explicit Gateway URL test mocks a closed GatewayTransportError, verifies no local fallback, and expects process.exit(1). (src/cli/logs-cli.test.ts:274, 9fff2b779159)
• PR retry branch emits plain text in JSON mode: The PR retry branch writes the reconnect warning through errorLine(...); it does not branch on jsonMode or use emitJsonLine for the recoverable notice. (src/cli/logs-cli.ts:343, 64babc30eed9)
• JSON contract is documented and used by existing code: Docs describe --json as line-delimited JSON events, and current Gateway errors/notices use emitJsonLine rather than styled text. Public docs: docs/cli/logs.md. (docs/cli/logs.md:24, 9fff2b779159)
• Changelog entry is missing from this PR: The PR diff touches only docs/cli/logs.md, src/cli/logs-cli.test.ts, and src/cli/logs-cli.ts; there is no CHANGELOG.md entry for the user-facing CLI fix. (CHANGELOG.md:33, 64babc30eed9)

Likely related people:

• steipete: History and shortlog point to Peter Steinberger as the dominant maintainer for logs-cli, tests, docs, and gateway/call, including the commits that added local logs fallback and typed Gateway transport failures. (role: current logs CLI and Gateway transport maintainer; confidence: high; commits: 306fe841f54b, e25b54210097, 023d3371a533; files: src/cli/logs-cli.ts, src/cli/logs-cli.test.ts, docs/cli/logs.md)
• shakkernerd: Recent adjacent history includes the lazy CLI Gateway helper runtime split used by the callGatewayFromCli path that logs.tail relies on. (role: adjacent CLI Gateway helper maintainer; confidence: medium; commits: 36c8282795; files: src/cli/gateway-rpc.ts, src/cli/gateway-rpc.runtime.ts)
• vincentkoc: Shortlog and recent commits show related maintenance in src/gateway/call.ts, especially credential and secret-input handling around the shared Gateway request path used by the logs CLI. (role: adjacent Gateway call maintainer; confidence: medium; commits: 935bd6de7f, 74e7b8d47b, 42e3d8d693; files: src/gateway/call.ts)

Remaining risk / open question:

• PR feat(cli/logs): announce --follow gateway reconnect and add JSON notice parity #75372 overlaps the same retry surface and may be the cleaner canonical branch because it already includes JSON notices and a changelog entry.
• No live gateway-restart soak was run in this read-only review; the verdict is based on current source, the PR diff, docs, tests, and related PR context.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 9fff2b779159.