Gateway

• By default, the Gateway refuses to start unless gateway.mode=local is set in ~/.openclaw/openclaw.json. Use --allow-unconfigured for ad-hoc/dev runs.
• openclaw onboard --mode local and openclaw setup are expected to write gateway.mode=local. If the file exists but gateway.mode is missing, treat that as a broken or clobbered config and repair it instead of assuming local mode implicitly.
• If the file exists and gateway.mode is missing, the Gateway treats that as suspicious config damage and refuses to "guess local" for you.
• Binding beyond loopback without auth is blocked (safety guardrail).
• lan, tailnet, and custom currently resolve over IPv4-only BYOH paths.
• IPv6-only BYOH is not natively supported on this path today. Use an IPv4 sidecar or proxy if the host itself is IPv6-only.
• SIGUSR1 triggers an in-process restart when authorized (commands.restart is enabled by default; set commands.restart: false to block manual restart, while gateway tool/config apply/update remain allowed).
• SIGINT/SIGTERM handlers stop the gateway process, but they don't restore any custom terminal state. If you wrap the CLI with a TUI or raw-mode input, restore the terminal before exit.

• Records keep operational metadata: event names, counts, byte sizes, memory readings, queue/session state, channel/plugin names, and redacted session summaries. They do not keep chat text, webhook bodies, tool outputs, raw request or response bodies, tokens, cookies, secret values, hostnames, or raw session ids. Set diagnostics.enabled: false to disable the recorder entirely.
• On fatal Gateway exits, shutdown timeouts, and restart startup failures, OpenClaw writes 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 also apply to bundle output.

• gateway status stays available for diagnostics even when the local CLI config is missing or invalid.
• Default gateway status proves service state, WebSocket connect, and the auth capability visible at handshake time. It does not prove read/write/admin operations.
• Diagnostic probes are non-mutating for first-time device auth: they reuse an existing cached device token when one exists, but they do not create a new CLI device identity or read-only device pairing record just to check status.
• gateway status resolves configured auth SecretRefs for probe auth when possible.
• If a required auth SecretRef is unresolved in this command path, gateway status --json reports rpc.authWarning when probe connectivity/auth fails; pass --token/--password explicitly or resolve the secret source first.
• If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
• When probing is enabled, JSON output includes gateway.version when the running Gateway reports it; --require-rpc can fall back to the status.runtimeVersion RPC payload if the follow-up handshake probe cannot provide version metadata.
• Use --require-rpc in scripts and automation when a listening service is not enough and you need read-scope RPC calls to be healthy too.
• --deep adds a best-effort scan for extra launchd/systemd/schtasks installs. When multiple gateway-like services are detected, human output prints cleanup hints and warns that most setups should run one gateway per machine.
• --deep also reports a recent Gateway supervisor restart handoff when the service process exited cleanly for an external supervisor restart.
• --deep runs config validation in plugin-aware mode (pluginValidation: "full") and surfaces configured plugin manifest warnings (for example missing channel config metadata) so install and update smoke checks catch them. Default gateway status keeps the fast read-only path that skips plugin validation.
• Human output includes the resolved file log path plus the CLI-vs-service config paths/validity snapshot to help diagnose profile or state-dir drift.

• On Linux systemd installs, service auth drift checks read both Environment= and EnvironmentFile= values from the unit (including %h, quoted paths, multiple files, and optional - files).
• Drift checks resolve gateway.auth.token SecretRefs using merged runtime env (service command env first, then process env fallback).
• If token auth is not effectively active (explicit gateway.auth.mode of password/none/trusted-proxy, or mode unset where password can win and no token candidate can win), token-drift checks skip config token resolution.

• 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. It is 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. This is reported as degraded reachability, not full failure.
• Read probe: failed after Connect: ok means the Gateway accepted the WebSocket connection, but follow-up read diagnostics timed out or failed. This is also degraded reachability, not an unreachable Gateway.
• 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 this order: explicit URL, SSH tunnel, configured remote, then local loopback.
• warnings[]: best-effort warning records with code, message, and optional targetIds.
• network: local loopback/tailnet URL hints derived from current config and host networking.
• discovery.timeoutMs and discovery.count: the actual discovery budget/result count used for this probe pass.

Per target (targets[].connect):

• ok: reachability after connect + degraded classification.
• rpcOk: full detail RPC success.
• scopeLimited: detail RPC failed due to missing operator scope.

Per target (targets[].auth):

• role: auth role reported in hello-ok when available.
• scopes: granted scopes reported in hello-ok when available.
• capability: the surfaced auth capability classification for that target.

• ssh_tunnel_failed: SSH tunnel setup failed; the command fell back to direct probes.
• multiple_gateways: more than one target was reachable; this is unusual unless you intentionally run isolated profiles, such as a rescue bot.
• 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.

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• Use gateway restart to restart a managed service. Do not chain gateway stop and gateway start as a restart substitute.
• On macOS, gateway stop uses launchctl bootout by default, which removes the LaunchAgent from the current boot session without persisting a disable — KeepAlive auto-recovery remains active for future crashes and gateway start re-enables cleanly without a manual launchctl enable. Pass --disable to persistently suppress KeepAlive and RunAtLoad so the gateway does not respawn until the next explicit gateway start; use this when a manual stop should survive reboots or system restarts.
• gateway restart --safe asks the running Gateway to preflight active OpenClaw work and defer the restart until reply delivery, embedded runs, and task runs drain. --safe cannot be combined with --force or --wait.
• gateway restart --wait 30s overrides the configured restart drain budget for that restart. Bare numbers are milliseconds; units such as s, m, and h are accepted. --wait 0 waits indefinitely.
• gateway restart --safe --skip-deferral runs the OpenClaw-aware safe restart but bypasses the deferral gate so the Gateway emits the restart immediately even when blockers are reported. Operator escape hatch for stuck-task-run deferrals; requires --safe.
• gateway restart --force skips the active-work drain and restarts immediately. Use it when an operator has already inspected the listed task blockers and wants the gateway back now.
• Lifecycle commands accept --json for scripting.

• When token auth requires a token and gateway.auth.token is SecretRef-managed, gateway install validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
• If token auth requires a token and the configured token SecretRef is unresolved, install fails closed instead of persisting fallback plaintext.
• For password auth on gateway run, prefer OPENCLAW_GATEWAY_PASSWORD, --password-file, or a SecretRef-backed gateway.auth.password over inline --password.
• In inferred auth mode, shell-only OPENCLAW_GATEWAY_PASSWORD does not relax install token requirements; use durable config (gateway.auth.password or config env) when installing a managed service.
• If both gateway.auth.token and gateway.auth.password are configured and gateway.auth.mode is unset, install is blocked until mode is set explicitly.