Skip to main content

​
Gateway CLI

The Gateway is OpenClaw’s WebSocket server (channels, nodes, sessions, hooks). Subcommands in this page live under openclaw gateway …. Related docs:

​
Run the Gateway

Run a local Gateway process: 
openclaw gateway
Foreground alias: 
openclaw gateway run
Notes:
  • 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>: WebSocket port (default comes from config/env; usually 18789).
  • --bind <loopback|lan|tailnet|auto|custom>: listener bind mode.
  • --auth <token|password>: auth mode override.
  • --token <token>: token override (also sets OPENCLAW_GATEWAY_TOKEN for the process).
  • --password <password>: password override. Warning: inline passwords can be exposed in local process listings.
  • --password-file <path>: read the gateway password from a file.
  • --tailscale <off|serve|funnel>: expose the Gateway via Tailscale.
  • --tailscale-reset-on-exit: reset Tailscale serve/funnel config on shutdown.
  • --allow-unconfigured: allow gateway start without gateway.mode=local in config. This bypasses the startup guard for ad-hoc/dev bootstrap only; it does not write or repair the config file.
  • --dev: create a dev config + workspace if missing (skips BOOTSTRAP.md).
  • --reset: reset dev config + credentials + sessions + workspace (requires --dev).
  • --force: kill any existing listener on the selected port before starting.
  • --verbose: verbose logs.
  • --ws-log <auto|full|compact>: websocket log style (default auto).
  • --compact: alias for --ws-log compact.
  • --raw-stream: log raw model stream events to jsonl.
  • --raw-stream-path <path>: raw stream jsonl path.

​
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 (or NO_COLOR=1): disable ANSI while keeping human layout.
Shared options (where supported):
  • --url <url>: Gateway WebSocket URL.
  • --token <token>: Gateway token.
  • --password <password>: Gateway password.
  • --timeout <ms>: timeout/budget (varies per command).
  • --expect-final: wait for a “final” response (agent calls).
Note: 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

​
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
Options:
  • --days <days>: number of days to include (default 30).

​
gateway status

gateway status shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe. 
openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc
Options:
  • --url <url>: add an explicit probe target. Configured remote + localhost are still probed.
  • --token <token>: token auth for the probe.
  • --password <password>: password auth for the probe.
  • --timeout <ms>: probe timeout (default 10000).
  • --no-probe: skip the RPC probe (service-only view).
  • --deep: scan system-level services too.
  • --require-rpc: exit non-zero when the RPC probe fails. Cannot be combined with --no-probe.
Notes:
  • gateway status stays available for diagnostics even when the local CLI config is missing or invalid.
  • 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 the Gateway RPC itself to be healthy.
  • --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
Interpretation:
  • Reachable: yes means at least one target accepted a WebSocket connect.
  • RPC: ok means detail RPC calls (health/status/system-presence/config.get) also succeeded.
  • RPC: limited - missing scope: operator.read means connect succeeded but detail RPC is scope-limited. This is reported as degraded reachability, not full failure.
  • Exit code is non-zero only when no probed target is reachable.
JSON notes (--json):
  • Top level:
    • ok: at least one target is reachable.
    • degraded: at least one target had scope-limited detail RPC.
    • 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.
Common warning codes:
  • 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 detail RPC 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
Options:
  • --ssh <target>: user@host or user@host:port (port defaults to 22).
  • --ssh-identity <path>: identity file.
  • --ssh-auto: 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}'
Options:
  • --params <json>: JSON object string for params (default {})
  • --url <url>
  • --token <token>
  • --password <password>
  • --timeout <ms>
  • --expect-final
  • --json
Notes:
  • --params must be valid JSON.
  • --expect-final is mainly for agent-style RPCs that stream intermediate events before a final payload.

​
Manage the Gateway service

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall
Command options:
  • gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
  • gateway install: --port, --runtime <node|bun>, --token, --force, --json
  • gateway uninstall|start|stop|restart: --json
Notes:
  • gateway install supports --port, --runtime, --token, --force, --json.
  • 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.
  • Lifecycle commands accept --json for scripting.

​
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 /gateway/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
Options:
  • --timeout <ms>: per-command timeout (browse/resolve); default 2000.
  • --json: machine-readable output (also disables styling/spinner).
Examples: 
openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'
Notes:
  • 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.