Query a running Gateway

• Records keep operational metadata: event names, counts, byte sizes, memory readings, queue/session state, approval ids, channel/plugin names, and redacted session summaries. They exclude chat text, webhook bodies, tool outputs, raw request/response bodies, tokens, cookies, secret values, hostnames, and raw session ids. Set diagnostics.enabled: false to disable the recorder entirely.
• Fatal Gateway exits, shutdown timeouts, and restart startup failures write the same diagnostic snapshot to ~/.openclaw/logs/stability/openclaw-stability-*.json when the recorder has events. Inspect the newest bundle with openclaw gateway stability --bundle latest; --limit, --type, and --since-seq apply to bundle output too.

• Stays available for diagnostics even when the local CLI config is missing or invalid.
• Default output proves service state, WebSocket connect, and the auth capability visible at handshake time — not read/write/admin operations.
• Probes are non-mutating for first-time device auth: they reuse an existing cached device token when one exists, but never create a new CLI device identity or read-only pairing record just to check status.
• Resolves configured auth SecretRefs for probe auth when possible. If a required SecretRef is unresolved, --json reports rpc.authWarning when probe connectivity/auth fails; pass --token/--password explicitly or fix the secret source. Unresolved-auth warnings are suppressed once the probe succeeds.
• JSON output includes gateway.version when the running Gateway reports it; --require-rpc can fall back to the status.runtimeVersion RPC payload if the handshake probe cannot supply version metadata.
• Use --require-rpc in scripts/automation when a listening service is not enough and you need read-scope RPC to be healthy too.
• --deep scans for extra launchd/systemd/schtasks installs; when multiple gateway-like services are found, human output prints cleanup hints (usually run one gateway per machine) and reports a recent supervisor restart handoff when relevant.
• --deep confirms exact npm targets before suggesting repairs for official-plugin version drift. Unpublished versions or registry failures are reported without an update command; retry deep status after registry access or the release cohort is restored. Ordinary status and readiness checks do not query npm for drift repairs.
• --deep also runs config validation in plugin-aware mode (pluginValidation: "full") and surfaces plugin manifest warnings (e.g. missing channel config metadata). Default gateway status keeps the fast read-only path that skips plugin validation.
• On Linux, status reports the effective service currently loaded by systemd, including loaded drop-ins. If the unit or a drop-in changed on disk, Systemd reload: pending means you must run systemctl --user daemon-reload (or sudo systemctl daemon-reload for a system service) before those changes take effect.
• Human output includes the resolved file log path plus CLI-vs-service config paths/validity to help diagnose profile or state-dir drift.
• Install and reinstall guidance follows the invoking shell's installation rules, not the stored service environment or probe target. Nix mode, external supervision, noncanonical installation identity, and Linux sudo/user-manager mismatches show the install refusal instead of an unusable command. A diagnostic-only target is not itself a refusal. Nix mode blocks installation, not starting an existing service.
• Human output includes Gateway heap: with configured service heap controls and a separate install-time recommendation based on memory visible to the CLI. JSON output exposes the same report as service.gatewayHeap. Neither is a measurement of the running Gateway's V8 heap ceiling; use runtime memory diagnostics for that.

• Service auth drift checks read both Environment= and EnvironmentFile= from the unit (including %h, quoted paths, multiple files, and optional - files).
• Resolves gateway.auth.token SecretRefs using merged runtime env (service command env first, then process env fallback).
• Token-drift checks skip config token resolution when token auth is not effectively active (gateway.auth.mode explicitly password/none/trusted-proxy, or mode unset where password can win and no token candidate can win).

• Reachable: yes means at least one target accepted a WebSocket connect.
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only reports what the probe could prove about auth, separate from reachability.
• Read probe: ok means read-scope detail RPC calls (health/status/system-presence/config.get) also succeeded.
• Read probe: limited - missing scope: operator.read means connect succeeded but read-scope RPC is limited. Reported as degraded reachability, not full failure.
• Read probe: failed after Connect: ok means the WebSocket connected but follow-up read diagnostics timed out or failed — also degraded, not unreachable.
• Like gateway status, probe reuses existing cached device auth but does not create first-time device identity or pairing state.
• Exit code is non-zero only when no probed target is reachable.

Top level:

• ok: at least one target is reachable.
• degraded: at least one target accepted a connection but did not complete full detail RPC diagnostics.
• capability: best capability seen across reachable targets (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope, or unknown).
• primaryTargetId: best target to treat as the active winner, in order: explicit URL, SSH tunnel, configured remote, local loopback.
• warnings[]: best-effort warning records with code, message, optional targetIds.
• network: local loopback/tailnet URL hints derived from current config and host networking.
• discovery.timeoutMs / discovery.count: the actual discovery budget/result count used for this probe pass.

Per target (targets[].connect): ok (reachability + degraded classification), rpcOk (full detail RPC success), scopeLimited (detail RPC failed on missing operator scope).

Per target (targets[].auth): role and scopes reported in hello-ok when available, plus the surfaced capability classification.

• ssh_tunnel_failed: SSH tunnel setup failed; the command fell back to direct probes.
• multiple_gateways: distinct gateway identities were reachable, or OpenClaw could not prove reachable targets are the same gateway. An SSH tunnel, proxy URL, or configured remote URL to the same gateway does not trigger this.
• auth_secretref_unresolved: a configured auth SecretRef could not be resolved for a failed target.
• probe_scope_limited: WebSocket connect succeeded, but the read probe was limited by missing operator.read.
• local_tls_runtime_unavailable: local Gateway TLS is enabled but OpenClaw could not load the local certificate fingerprint.