Skip to main content

Gateway CLI

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

Run the Gateway

Run a local Gateway process:
Foreground alias:
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.
  • Binding beyond loopback without auth is blocked (safety guardrail).
  • SIGUSR1 triggers a 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). The restart first drains active command-queue tasks and active ACP turns (within gateway.restartResilience.drainTimeoutMs, default 30000), then closes like a stop, and only then starts a fresh process: under launchd or systemd the service supervisor restarts it (on macOS the gateway kickstarts the launchd service to skip throttling delays); otherwise the gateway spawns its own replacement and exits. Only if that respawn fails, or OPENCLAW_NO_RESPAWN is set, does it restart in-process instead.
  • 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 (also sets OPENCLAW_GATEWAY_PASSWORD for 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 without gateway.mode=local in 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 (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.
  • --role <roles>: deployment role(s): all (default), gateway, runner, scheduler, channels; comma-separated. Also read from OPENCLAW_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:
  • gateway serves HTTP/WebSocket clients; runner executes queued agent turns and task work; scheduler runs cron, heartbeat and other singletons (one leader at a time, the others stand by); channels runs chat channels.
  • scheduler and channels must be combined with gateway. all cannot be combined with other roles.
  • Any role other than all requires session.storage.backend: "postgres" and tasks.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 gateway serves only /health, /healthz, /ready and /readyz on its port; every other path and every WebSocket upgrade gets 404. In a split deployment /readyz adds roles and, for scheduler processes, standby.
  • An all Gateway and a split deployment refuse to share one database.
Design: ADR 0112 (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 (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

gateway status

gateway status shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe.
Options:
  • --url <url>: override the probe URL.
  • --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.

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 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.

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:
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 (LAN/WAB only).
Config (optional, used as defaults):
  • gateway.remote.sshTarget
  • gateway.remote.sshIdentity

gateway call <method>

Low-level RPC helper.
For scripting, pass --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.
Options: --days <n> (default: 30), --json.

Manage the Gateway service

Notes:
  • gateway install supports --port, --runtime, --token, --force, --json.
  • Lifecycle commands accept --json for 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:
Repair with 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 restart restarts 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 prints Waiting 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 restart issued from inside the gateway (for example from an agent’s exec tool) is scheduled: the CLI prints Scheduled LaunchAgent restart and Restart 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, or launchctl bootstrap gui/$UID ~/Library/LaunchAgents/<label>.plist.
  • gateway start and gateway restart reload a LaunchAgent whose plist is installed but not loaded; no reinstall is needed. gateway status reports this state as Service 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
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 (SSH port; defaults to 22 if not present)
  • tailnetDns (MagicDNS hostname, when available)
  • gatewayTls / gatewayTlsSha256 (TLS enabled + cert fingerprint)
  • cliPath (optional hint for remote installs)

gateway discover

Options:
  • --timeout <ms>: per-command timeout (browse/resolve); default 2000.
  • --json: machine-readable output (also disables styling/spinner).
Examples: