openclaw gateway ....
Bonjour discovery
Local mDNS + wide-area DNS-SD setup.
Discovery overview
How OpenClaw advertises and finds gateways.
Configuration
Top-level gateway config keys.
Run the Gateway
Startup behavior
Startup behavior
- Refuses to start unless
gateway.mode=localis set in~/.openclaw/openclaw.json. Use--allow-unconfiguredfor ad-hoc/dev runs; it bypasses the guard without writing or repairing config. openclaw onboard --mode localandopenclaw setupwritegateway.mode=local. If the config file exists butgateway.modeis missing, that is treated as damaged/clobbered config and the Gateway refuses to guesslocalfor you — re-run onboarding, set the key manually, or pass--allow-unconfigured.- Binding beyond loopback without auth is blocked.
--bindvalueslan,tailnet, andcustomresolve over IPv4-only paths today; IPv6-only bring-your-own-host setups need an IPv4 sidecar or proxy in front of the Gateway.SIGUSR1triggers an in-process restart when authorized.commands.restart(default: enabled) gates externally-sentSIGUSR1; set it tofalseto block manual OS-signal restarts while still allowing restart via thegateway restartcommand, the gateway tool, and config-apply/update.SIGINT/SIGTERMstop the process but do not restore custom terminal state — if you wrap the CLI in a TUI or raw-mode input, restore the terminal yourself before exit.
Options
WebSocket port (default from config/env; usually
18789).Bind mode:
loopback (default), lan, tailnet, auto, custom.Shared token for
connect.params.auth.token. Defaults to OPENCLAW_GATEWAY_TOKEN when set.Auth mode:
none, token, password, trusted-proxy.Password for
--auth password.Read the Gateway password from a file.
Tailscale exposure:
off, serve, funnel.Reset Tailscale serve/funnel config on shutdown.
Start without enforcing
gateway.mode=local. Ad-hoc/dev bootstrap only; does not persist or repair config.Create a dev config + workspace if missing (skips
BOOTSTRAP.md).Reset dev config, credentials, sessions, and workspace. Requires
--dev.Kill any existing listener on the target port before starting.
Verbose logging to stdout/stderr.
Only show CLI backend logs in the console (also enables stdout/stderr).
WebSocket log style:
auto, full, compact.Alias for
--ws-log compact.Log raw model stream events to JSONL.
Raw stream JSONL path.
--claude-cli-logs is a deprecated alias for --cli-backend-logs.
For --bind custom, set gateway.customBindHost to an IPv4 address; the Gateway falls back to 0.0.0.0 if that address is unavailable. IPv6-only bring-your-own-host setups need an IPv4 sidecar or proxy in front of the Gateway.
Restart the Gateway
--safe asks the running Gateway to preflight active work and schedule one coalesced restart after that work drains. The wait is bounded by gateway.reload.deferralTimeoutMs (default: 5 minutes / 300000); when the budget expires the restart is forced. Set deferralTimeoutMs: 0 to wait indefinitely (with periodic still-pending warnings) instead of forcing. --safe cannot combine with --force or --wait.
--skip-deferral bypasses the active-work deferral gate on a safe restart, so the Gateway restarts immediately even with reported blockers. It requires --safe — use it when a deferral is stuck on a runaway task.
--wait <duration> overrides the drain budget for a plain (non-safe) restart. Accepts bare milliseconds or unit suffixes ms, s, m, h, d (e.g. 30s, 5m, 1h30m); --wait 0 waits indefinitely. Not compatible with --force or --safe.
--force skips the active-work drain and restarts immediately. Plain restart (no flags) keeps the existing service-manager restart behavior.
Gateway profiling
OPENCLAW_GATEWAY_STARTUP_TRACE=1logs phase timings during startup, including per-phaseeventLoopMaxdelay and plugin lookup-table timings (installed-index, manifest registry, startup planning, owner-map work).OPENCLAW_GATEWAY_RESTART_TRACE=1logs restart-scopedrestart trace:lines: signal handling, active-work drain, shutdown phases, next start, ready timing, and memory metrics.OPENCLAW_DIAGNOSTICS=timelinewithOPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>writes a best-effort JSONL startup diagnostics timeline for external QA harnesses (equivalent to configdiagnostics.flags: ["timeline"]; the path is still env-only). AddOPENCLAW_DIAGNOSTICS_EVENT_LOOP=1to include event-loop samples.pnpm buildthenpnpm test:startup:gateway -- --runs 5 --warmup 1benchmarks Gateway startup against the built CLI entry: first process output,/healthz,/readyz, startup trace timings, event-loop delay, and plugin lookup-table timing.pnpm buildthenpnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5benchmarks in-process restart on macOS or Linux (not supported on Windows; restart requiresSIGUSR1). UsesSIGUSR1, enables both traces in the child process, and records next/healthz, next/readyz, downtime, ready timing, CPU, RSS, and restart trace metrics./healthzis liveness;/readyzis usable readiness. Treat trace lines and benchmark output as owner-attribution signal, not a complete performance conclusion from one span or sample.
Query a running Gateway
All query commands use WebSocket RPC.- Output modes
- Default: human-readable (colored in TTY).
--json: machine-readable JSON (no styling/spinner).--no-color(orNO_COLOR=1): disable ANSI while keeping human layout.
When you set
--url, the CLI does not fall back to config or environment credentials. Pass --token or --password explicitly. Missing explicit credentials is an error.gateway health
/healthz is a liveness probe: it returns as soon as the server can answer HTTP. /readyz is stricter and stays red while startup plugin sidecars, channels, or configured hooks are still settling. Local or authenticated detailed /readyz responses include an eventLoop diagnostic block (delay, utilization, CPU-core ratio, degraded flag).
Target a local loopback Gateway on this port. Overrides
OPENCLAW_GATEWAY_URL and OPENCLAW_GATEWAY_PORT for this call.gateway usage-cost
Fetch usage-cost summaries from session logs.
Number of days to include.
Scope the summary to one configured agent id.
Aggregate across all configured agents. Cannot combine with
--agent.gateway stability
Fetch the recent diagnostic stability recorder from a running Gateway.
Maximum recent events to include (max
1000).Filter by diagnostic event type, e.g.
payload.large or diagnostic.memory.pressure.Include only events after a diagnostic sequence number.
Read a persisted stability bundle instead of calling the running Gateway.
--bundle latest (or bare --bundle) picks the newest bundle under the state directory; you can also pass a bundle JSON path directly.Write a shareable support diagnostics zip instead of printing stability details.
Output path for
--export.Privacy and bundle behavior
Privacy and bundle behavior
- 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: falseto disable the recorder entirely. - Fatal Gateway exits, shutdown timeouts, and restart startup failures write the same diagnostic snapshot to
~/.openclaw/logs/stability/openclaw-stability-*.jsonwhen the recorder has events. Inspect the newest bundle withopenclaw gateway stability --bundle latest;--limit,--type, and--since-seqapply to bundle output too.
gateway diagnostics export
Write a local diagnostics zip designed for bug reports. For the privacy model and bundle contents, see Diagnostics Export.
Output zip path. Defaults to a support export under the state directory.
Maximum sanitized log lines to include.
Maximum log bytes to inspect.
Gateway WebSocket URL for the health snapshot.
Gateway token for the health snapshot.
Gateway password for the health snapshot.
Status/health snapshot timeout.
Skip persisted stability bundle lookup.
Print the written path, size, and manifest as JSON.
manifest.json (file inventory), summary.md (Markdown summary), diagnostics.json (top-level config/logs/discovery/stability/status/health summary), config/sanitized.json, status/gateway-status.json, health/gateway-health.json, logs/openclaw-sanitized.jsonl, and stability/latest.json when a bundle exists.
It is designed to be shared. It keeps operational details useful for debugging — safe log fields, subsystem names, status codes, durations, configured modes, ports, plugin/provider ids, non-secret feature settings, and redacted operational log messages — and omits or redacts chat text, webhook bodies, tool outputs, credentials, cookies, account/message identifiers, prompt/instruction text, hostnames, and secret values. When a log message looks like user/chat/tool payload text (e.g. “user said”, “chat text”, “tool output”, “webhook body”), the export keeps only the fact that a message was omitted plus its byte count.
gateway status
Shows the Gateway service (launchd/systemd/schtasks) plus an optional connectivity/auth probe.
Add an explicit probe target. Configured remote + localhost are still probed.
Token auth for the probe.
Password auth for the probe.
Probe timeout.
Skip the connectivity probe (service-only view).
Scan system-level services too.
Upgrade the connectivity probe to a read probe and exit non-zero if it fails. Cannot combine with
--no-probe.Status semantics
Status semantics
- 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,
--jsonreportsrpc.authWarningwhen probe connectivity/auth fails; pass--token/--passwordexplicitly or fix the secret source. Unresolved-auth warnings are suppressed once the probe succeeds. - JSON output includes
gateway.versionwhen the running Gateway reports it;--require-rpccan fall back to thestatus.runtimeVersionRPC payload if the handshake probe cannot supply version metadata. - Use
--require-rpcin scripts/automation when a listening service is not enough and you need read-scope RPC to be healthy too. --deepscans 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.--deepalso runs config validation in plugin-aware mode (pluginValidation: "full") and surfaces plugin manifest warnings (e.g. missing channel config metadata). Defaultgateway statuskeeps the fast read-only path that skips plugin validation.- Human output includes the resolved file log path plus CLI-vs-service config paths/validity to help diagnose profile or state-dir drift.
Linux systemd auth-drift checks
Linux systemd auth-drift checks
- Service auth drift checks read both
Environment=andEnvironmentFile=from the unit (including%h, quoted paths, multiple files, and optional-files). - Resolves
gateway.auth.tokenSecretRefs 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.modeexplicitlypassword/none/trusted-proxy, or mode unset where password can win and no token candidate can win).
gateway probe
The “debug everything” command. It always probes:
- your configured remote gateway (if set), and
- localhost (loopback), even if remote is configured.
--url adds that explicit target ahead of both. Human output labels targets URL (explicit), Remote (configured) / Remote (configured, inactive), and Local loopback.
If multiple probe targets are reachable, all are printed. An SSH tunnel, TLS/proxy URL, and configured remote URL can point at the same gateway even with different transport ports;
multiple_gateways is reserved for distinct or identity-ambiguous reachable gateways. Running multiple gateways is supported for isolated profiles (e.g. a rescue bot), but most installs run a single gateway.Use this port for the local loopback probe target and SSH tunnel remote port. Without
--url, this selects only the local loopback target instead of configured gateway environment URL, environment port, or remote targets.Interpretation
Interpretation
Reachable: yesmeans at least one target accepted a WebSocket connect.Capability: read-only|write-capable|admin-capable|pairing-pending|connect-onlyreports what the probe could prove about auth, separate from reachability.Read probe: okmeans read-scope detail RPC calls (health/status/system-presence/config.get) also succeeded.Read probe: limited - missing scope: operator.readmeans connect succeeded but read-scope RPC is limited. Reported as degraded reachability, not full failure.Read probe: failedafterConnect: okmeans 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.
JSON output
JSON output
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, orunknown).primaryTargetId: best target to treat as the active winner, in order: explicit URL, SSH tunnel, configured remote, local loopback.warnings[]: best-effort warning records withcode,message, optionaltargetIds.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.
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.Common warning codes
Common warning codes
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 missingoperator.read.local_tls_runtime_unavailable: local Gateway TLS is enabled but OpenClaw could not load the local certificate fingerprint.
Remote over SSH (Mac app parity)
The macOS app “Remote over SSH” mode uses a local port-forward so a loopback-only remote gateway becomes reachable atws://127.0.0.1:<port>.
CLI equivalent:
user@host or user@host:port (port defaults to 22).Identity file.
Pick the first discovered gateway host as SSH target from the resolved discovery endpoint (
local. plus the configured wide-area domain, if any). TXT-only hints are ignored.gateway.remote.sshTarget, gateway.remote.sshIdentity.
gateway call <method>
Low-level RPC helper.
JSON object string for params.
Gateway WebSocket URL.
Gateway token.
Gateway password.
Timeout budget.
Mainly for agent-style RPCs that stream intermediate events before a final payload.
Machine-readable JSON output.
--params must be valid JSON, and each method validates its own param shape (extra/misnamed fields are rejected).Manage the Gateway service
Install with a wrapper
Use--wrapper when the managed service must start through another executable, for example a secrets manager shim or a run-as helper. The wrapper receives the normal Gateway args and is responsible for eventually exec’ing openclaw or Node with those args.
gateway install validates that the path is an executable file, writes the wrapper into the service ProgramArguments, and persists OPENCLAW_WRAPPER in the service environment for later forced reinstalls, updates, and doctor repairs.
OPENCLAW_WRAPPER while reinstalling:
Command options
Command options
gateway status:--url,--token,--password,--timeout,--no-probe,--require-rpc,--deep,--jsongateway install:--port,--runtime <node|bun>(default:node),--token,--wrapper <path>,--force,--jsongateway restart:--safe,--skip-deferral,--force,--wait <duration>,--jsongateway uninstall|start:--jsongateway stop:--disable,--json
Lifecycle behavior
Lifecycle behavior
- Use
gateway restartto restart a managed service. Do not chaingateway stopandgateway startas a restart substitute. - On macOS,
gateway stopuseslaunchctl bootoutby default, which removes the LaunchAgent from the current boot session without persisting a disable — KeepAlive auto-recovery stays active for future crashes andgateway startre-enables cleanly without a manuallaunchctl enable. Pass--disableto persistently suppress KeepAlive and RunAtLoad so the gateway does not respawn until the next explicitgateway start; use this when a manual stop should survive reboots. - Lifecycle commands accept
--jsonfor scripting.
Auth and SecretRefs at install time
Auth and SecretRefs at install time
- When token auth requires a token and
gateway.auth.tokenis SecretRef-managed,gateway installvalidates 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, preferOPENCLAW_GATEWAY_PASSWORD,--password-file, or a SecretRef-backedgateway.auth.passwordover inline--password. - In inferred auth mode, shell-only
OPENCLAW_GATEWAY_PASSWORDdoes not relax install token requirements; use durable config (gateway.auth.passwordor configenv) when installing a managed service. - If both
gateway.auth.tokenandgateway.auth.passwordare configured andgateway.auth.modeis unset, install is blocked until mode is set explicitly.
Discover gateways (Bonjour)
gateway discover scans for Gateway beacons (_openclaw-gw._tcp).
- Multicast DNS-SD:
local. - Unicast DNS-SD (wide-area Bonjour): choose a domain (example:
openclaw.internal.) and set up split DNS + a DNS server; see Bonjour.
role (gateway role hint), transport (transport hint, e.g. gateway), gatewayPort (WebSocket port, usually 18789), tailnetDns (MagicDNS hostname, when available), gatewayTls / gatewayTlsSha256 (TLS enabled + cert fingerprint). sshPort and cliPath are published only in full discovery mode (discovery.mdns.mode: "full"; default is "minimal", which omits them — clients then default SSH targets to port 22).
gateway discover
Per-command timeout (browse/resolve).
Machine-readable output (also disables styling/spinner).
- Scans
local.plus the configured wide-area domain when one is enabled. wsUrlin JSON output is derived from the resolved service endpoint, not from TXT-only hints such aslanHostortailnetDns.discovery.mdns.modecontrolssshPort/cliPathpublication on bothlocal.mDNS and wide-area DNS-SD (see above).