Gateway CLI
The Gateway is WednesdayAI’s WebSocket server (channels, nodes, sessions, hooks). Subcommands in this page live underwednesdayai gateway ….
Related docs:
Run the Gateway
Run a local Gateway process:- By default, the Gateway refuses to start unless
gateway.mode=localis set in~/.openclaw/openclaw.json. Use--allow-unconfiguredfor ad-hoc/dev runs. - Binding beyond loopback without auth is blocked (safety guardrail).
SIGUSR1triggers a restart when authorized (commands.restartis enabled by default; setcommands.restart: falseto block manual restart, while gateway tool/config apply/update remain allowed). The restart first drains active command-queue tasks and active ACP turns (withingateway.restartResilience.drainTimeoutMs, default 30000), then closes like a stop, and only then starts a fresh process: under launchd or systemd the gateway exits and the service supervisor restarts it (launchdKeepAlivewithThrottleInterval1, systemdRestart=always); otherwise the gateway spawns its own replacement and exits. Only if that respawn fails, orOPENCLAW_NO_RESPAWNis set, does it restart in-process instead.wednesdayai doctorflags a LaunchAgent with a larger or missingThrottleInterval(older installs wrote 60) and offers to rewrite it.SIGINT/SIGTERMhandlers 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; usually18789).--bind <loopback|lan|tailnet|auto|custom>: listener bind mode.--auth <token|password>: auth mode override.--token <token>: token override (also setsOPENCLAW_GATEWAY_TOKENfor the process).--password <password>: password override (also setsOPENCLAW_GATEWAY_PASSWORDfor the process).--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 withoutgateway.mode=localin config.--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.--claude-cli-logs: only show claude-cli logs in the console (and enable its stdout/stderr).--ws-log <auto|full|compact>: websocket log style (defaultauto).--compact: alias for--ws-log compact.--raw-stream: log raw model stream events to jsonl.--raw-stream-path <path>: raw stream jsonl path.--role <roles>: deployment role(s):all(default),gateway,runner,scheduler,channels; comma-separated. Also read fromOPENCLAW_GATEWAY_ROLE; the flag wins. See Deployment roles.
Deployment roles
One binary can run as several cooperating processes on one Postgres database. With no--role (or --role all) the Gateway runs everything in one process, exactly as before. A split deployment typically runs one gateway,scheduler,channels process and a pool of runner processes:
gatewayserves HTTP/WebSocket clients;runnerexecutes queued agent turns and task work;schedulerruns cron, heartbeat and other singletons (one leader at a time, the others stand by);channelsruns chat channels.schedulerandchannelsmust be combined withgateway.allcannot be combined with other roles.- Any role other than
allrequiressession.storage.backend: "postgres"andtasks.enabled; the Gateway refuses to start otherwise. - Give each role its own
OPENCLAW_STATE_DIR; a state directory used by one role set refuses another. Turn-executing roles (gateway,channels,runner) must share the same agent workspace. - A process without
gatewayserves only/health,/healthz,/readyand/readyzon its port; every other path and every WebSocket upgrade gets 404. In a split deployment/readyzaddsrolesand, for scheduler processes,standby. - An
allGateway and a split deployment refuse to share one database.
dev-docs/adr/0112-deployment-roles.md) and ADR 1168 (dev-docs/adr/1168-postgres-multi-writer-mechanism.md).
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.
--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).
--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
gateway status
gateway status shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe.
--url <url>: override the probe URL.--token <token>: token auth for the probe.--password <password>: password auth for the probe.--timeout <ms>: probe timeout (default10000).--no-probe: skip the RPC probe (service-only view).--deep: scan system-level services too.
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.
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 atws://127.0.0.1:<port>.
CLI equivalent:
--ssh <target>:user@hostoruser@host:port(port defaults to22).--ssh-identity <path>: identity file.--ssh-auto: pick the first discovered gateway host as SSH target (LAN/WAB only).
gateway.remote.sshTargetgateway.remote.sshIdentity
gateway call <method>
Low-level RPC helper.
--json. Without it the command prints a Gateway call: <method> preamble
before the payload, which breaks JSON pipes such as jq:
gateway usage-cost
Fetch the usage cost summary for the last N days from gateway session logs.
--days <n> (default: 30), --json.
Manage the Gateway service
gateway installsupports--port,--runtime,--token,--force,--json.- Lifecycle commands accept
--jsonfor scripting.
Config pre-flight gate
gateway restart (and gateway start when the service is already loaded) validates the config before stopping anything. If the config is invalid, the restart is refused with exit code 1, the running gateway stays up, and the CLI prints the exact issue path plus repair hints:
wednesdayai doctor --fix, or fix the named key manually and re-check with wednesdayai config validate, then retry the restart. gateway stop is never gated; a first start of a stopped gateway is not gated either (the failure surfaces as a normal startup error instead). On macOS, gateway start/restart on an installed but unloaded LaunchAgent are gated too; with an invalid config the CLI reports that the service stays stopped until the config is valid.
When launchd or systemd starts the gateway and it refuses to start (invalid config, remote mode, missing auth), it prints Supervised start: waiting for <config> to change… and waits until the config file changes (or a file it $includes) (checked every 2 s, up to 5 minutes) before exiting. The service manager then restarts it with the fixed config instead of restart-looping; no reinstall is needed. Stopping the service during the wait (launchctl bootout, systemctl --user stop) ends it at once with exit 0.
macOS restart behavior
gateway restartrestarts the LaunchAgent in place (launchctl kickstart -k) when launchd has it loaded and its plist is unchanged since the CLI last loaded it. When the plist changed, it unloads and reloads it; if the previous gateway is still draining (up to about 25 s after SIGTERM), the CLI printsWaiting for the previous gateway to finish shutting down (up to 40s)…and retries until launchd frees the label.- After either kind of restart, the CLI waits for a gateway with a new pid to own the port. If the old pid is still running at the timeout, the error says the previous gateway may still be draining.
- A
gateway restartissued from inside the gateway (for example from an agent’s exec tool) is scheduled: the CLI printsScheduled LaunchAgent restartandRestart scheduled: the service restarts after this command exits., and a detached helper restarts the job once the calling process exits. The helper logs to~/.openclaw/logs/gateway.restart.log. - If the reload still fails, the error says whether launchd still has the job. When it does not, it names the unchanged plist and the recovery command:
wednesdayai gateway start, orlaunchctl bootstrap gui/$UID ~/Library/LaunchAgents/<label>.plist. gateway startandgateway restartreload a LaunchAgent whose plist is installed but not loaded; no reinstall is needed.gateway statusreports this state asService is installed but not loaded.- The LaunchAgent plist is written atomically with mode
0600.
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
role(gateway role hint)transport(transport hint, e.g.gateway)gatewayPort(WebSocket port, usually18789)sshPort(SSH port; defaults to22if not present)tailnetDns(MagicDNS hostname, when available)gatewayTls/gatewayTlsSha256(TLS enabled + cert fingerprint)cliPath(optional hint for remote installs)
gateway discover
--timeout <ms>: per-command timeout (browse/resolve); default2000.--json: machine-readable output (also disables styling/spinner).