Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Gateway is OpenClaw’s WebSocket server (channels, nodes, sessions, hooks). Subcommands in this page live under 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

Run a local Gateway process: 
openclaw gateway
Foreground alias: 
openclaw gateway run
  • 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).
  • 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.

​
Options

​
--port <port>
number
WebSocket port (default comes from config/env; usually 18789).
​
--bind <loopback|lan|tailnet|auto|custom>
string
Listener bind mode.
​
--auth <token|password>
string
Auth mode override.
​
--token <token>
string
Token override (also sets OPENCLAW_GATEWAY_TOKEN for the process).
​
--password <password>
string
Password override.
​
--password-file <path>
string
Read the gateway password from a file.
​
--tailscale <off|serve|funnel>
string
Expose the Gateway via Tailscale.
​
--tailscale-reset-on-exit
boolean
Reset Tailscale serve/funnel config on shutdown.
​
--allow-unconfigured
boolean
Allow gateway start without gateway.mode=local in config. Bypasses the startup guard for ad-hoc/dev bootstrap only; does not write or repair the config file.
​
--dev
boolean
Create a dev config + workspace if missing (skips BOOTSTRAP.md).
​
--reset
boolean
Reset dev config + credentials + sessions + workspace (requires --dev).
​
--force
boolean
Kill any existing listener on the selected port before starting.
​
--verbose
boolean
Verbose logs.
​
--cli-backend-logs
boolean
Only show CLI backend logs in the console (and enable stdout/stderr).
​
--ws-log <auto|full|compact>
string
default:"auto"
Websocket log style.
​
--compact
boolean
Alias for --ws-log compact.
​
--raw-stream
boolean
Log raw model stream events to jsonl.
​
--raw-stream-path <path>
string
Raw stream jsonl path.
Inline --password can be exposed in local process listings. Prefer --password-file, env, or a SecretRef-backed gateway.auth.password.

​
Startup profiling

  • Set OPENCLAW_GATEWAY_STARTUP_TRACE=1 to log phase timings during Gateway startup, including per-phase eventLoopMax delay and plugin lookup-table timings for installed-index, manifest registry, startup planning, and owner-map work.
  • Run pnpm test:startup:gateway -- --runs 5 --warmup 1 to benchmark Gateway startup. The benchmark records first process output, /healthz, /readyz, startup trace timings, event-loop delay, and plugin lookup-table timing details.

​
Query a running Gateway

All query commands use WebSocket RPC.
  • Default: human-readable (colored in TTY).
  • --json: machine-readable JSON (no styling/spinner).
  • --no-color (or NO_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

openclaw gateway health --url ws://127.0.0.1:18789
The HTTP /healthz endpoint is a liveness probe: it returns once the server can answer HTTP. The HTTP /readyz endpoint is stricter and stays red while startup sidecars, channels, or configured hooks are still settling. Local or authenticated detailed readiness responses include an eventLoop diagnostic block with event-loop delay, event-loop utilization, CPU core ratio, and a degraded flag.

​
gateway usage-cost

Fetch usage-cost summaries from session logs. 
openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json
​
--days <days>
number
default:"30"
Number of days to include.

​
gateway stability

Fetch the recent diagnostic stability recorder from a running Gateway. 
openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --bundle latest
openclaw gateway stability --bundle latest --export
openclaw gateway stability --json
​
--limit <limit>
number
default:"25"
Maximum number of recent events to include (max 1000).
​
--type <type>
string
Filter by diagnostic event type, such as payload.large or diagnostic.memory.pressure.
​
--since-seq <seq>
number
Include only events after a diagnostic sequence number.
​
--bundle [path]
string
Read a persisted stability bundle instead of calling the running Gateway. Use --bundle latest (or just --bundle) for the newest bundle under the state directory, or pass a bundle JSON path directly.
​
--export
boolean
Write a shareable support diagnostics zip instead of printing stability details.
​
--output <path>
string
Output path for --export.
  • 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 diagnostics export

Write a local diagnostics zip that is designed to attach to bug reports. For the privacy model and bundle contents, see Diagnostics Export. 
openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json
​
--output <path>
string
Output zip path. Defaults to a support export under the state directory.
​
--log-lines <count>
number
default:"5000"
Maximum sanitized log lines to include.
​
--log-bytes <bytes>
number
default:"1000000"
Maximum log bytes to inspect.
​
--url <url>
string
Gateway WebSocket URL for the health snapshot.
​
--token <token>
string
Gateway token for the health snapshot.
​
--password <password>
string
Gateway password for the health snapshot.
​
--timeout <ms>
number
default:"3000"
Status/health snapshot timeout.
​
--no-stability-bundle
boolean
Skip persisted stability bundle lookup.
​
--json
boolean
Print the written path, size, and manifest as JSON.
The export contains a manifest, a Markdown summary, config shape, sanitized config details, sanitized log summaries, sanitized Gateway status/health snapshots, and the newest stability bundle when one exists. It is meant to be shared. It keeps operational details that help debugging, such as safe OpenClaw log fields, subsystem names, status codes, durations, configured modes, ports, plugin ids, provider ids, non-secret feature settings, and redacted operational log messages. It omits or redacts chat text, webhook bodies, tool outputs, credentials, cookies, account/message identifiers, prompt/instruction text, hostnames, and secret values. When a LogTape-style message looks like user/chat/tool payload text, the export keeps only that a message was omitted plus its byte count.

​
gateway status

gateway status shows the Gateway service (launchd/systemd/schtasks) plus an optional probe of connectivity/auth capability. 
openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
​
--url <url>
string
Add an explicit probe target. Configured remote + localhost are still probed.
​
--token <token>
string
Token auth for the probe.
​
--password <password>
string
Password auth for the probe.
​
--timeout <ms>
number
default:"10000"
Probe timeout.
​
--no-probe
boolean
Skip the connectivity probe (service-only view).
​
--deep
boolean
Scan system-level services too.
​
--require-rpc
boolean
Upgrade the default connectivity probe to a read probe and exit non-zero when that read probe fails. Cannot be combined with --no-probe.
  • 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.
  • 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.
  • 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.

​
gateway probe

gateway probe is the “debug everything” command. It always probes:
  • your configured remote gateway (if set), and
  • localhost (loopback) even if remote is configured.
If you pass --url, that explicit target is added ahead of both. Human output labels the targets as:
  • URL (explicit)
  • Remote (configured) or Remote (configured, inactive)
  • Local loopback
If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.
openclaw gateway probe
openclaw gateway probe --json
  • 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.

​
Remote over SSH (Mac app parity)

The macOS app “Remote over SSH” mode uses a local port-forward so the remote gateway (which may be bound to loopback only) becomes reachable at ws://127.0.0.1:<port>. CLI equivalent: 
openclaw gateway probe --ssh user@gateway-host
​
--ssh <target>
string
user@host or user@host:port (port defaults to 22).
​
--ssh-identity <path>
string
Identity file.
​
--ssh-auto
boolean
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.
Config (optional, used as defaults):
  • gateway.remote.sshTarget
  • gateway.remote.sshIdentity

​
gateway call <method>

Low-level RPC helper. 
openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
​
--params <json>
string
default:"{}"
JSON object string for params.
​
--url <url>
string
Gateway WebSocket URL.
​
--token <token>
string
Gateway token.
​
--password <password>
string
Gateway password.
​
--timeout <ms>
number
Timeout budget.
​
--expect-final
boolean
Mainly for agent-style RPCs that stream intermediate events before a final payload.
​
--json
boolean
Machine-readable JSON output.
--params must be valid JSON.

​
Manage the Gateway service

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

​
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. 
cat > ~/.local/bin/openclaw-doppler <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart
You can also set the wrapper through the environment. gateway install validates that the path is an executable file, writes the wrapper into service ProgramArguments, and persists OPENCLAW_WRAPPER in the service environment for later forced reinstalls, updates, and doctor repairs. 
OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor
To remove a persisted wrapper, clear OPENCLAW_WRAPPER while reinstalling: 
OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw gateway restart
  • gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
  • gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
  • gateway uninstall|start|stop|restart: --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 intentionally disables the LaunchAgent before stopping it.
  • 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.

​
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.
Only gateways with Bonjour discovery enabled (default) advertise the beacon. Wide-Area discovery records include (TXT):
  • role (gateway role hint)
  • transport (transport hint, e.g. gateway)
  • gatewayPort (WebSocket port, usually 18789)
  • sshPort (optional; clients default SSH targets to 22 when it is absent)
  • tailnetDns (MagicDNS hostname, when available)
  • gatewayTls / gatewayTlsSha256 (TLS enabled + cert fingerprint)
  • cliPath (remote-install hint written to the wide-area zone)

​
gateway discover

openclaw gateway discover
​
--timeout <ms>
number
default:"2000"
Per-command timeout (browse/resolve).
​
--json
boolean
Machine-readable output (also disables styling/spinner).
Examples: 
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
  • The CLI scans local. plus the configured wide-area domain when one is enabled.
  • wsUrl in JSON output is derived from the resolved service endpoint, not from TXT-only hints such as lanHost or tailnetDns.
  • On local. mDNS, sshPort and cliPath are only broadcast when discovery.mdns.mode is full. Wide-area DNS-SD still writes cliPath; sshPort stays optional there too.