> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# gateway

# Gateway CLI

The Gateway is WednesdayAI’s WebSocket server (channels, nodes, sessions, hooks).

Subcommands in this page live under `wednesdayai gateway …`.

Related docs:

* [/gateway/bonjour](https://docs.wednesdayai.dev/next/admin/gateway/bonjour.md)
* [/gateway/discovery](https://docs.wednesdayai.dev/next/admin/gateway/discovery.md)
* [/gateway/configuration](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md)

## Run the Gateway

Run a local Gateway process:

```bash theme={"dark"}
wednesdayai gateway
```

Foreground alias:

```bash theme={"dark"}
wednesdayai 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.
* 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 gateway exits and the service supervisor restarts it (launchd `KeepAlive` with `ThrottleInterval` 1, systemd `Restart=always`); 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. `wednesdayai doctor` flags a LaunchAgent with a larger or missing `ThrottleInterval` (older installs wrote 60) and offers to rewrite it.
* `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).

### 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:

```bash theme={"dark"}
openclaw gateway run --role gateway,scheduler,channels
openclaw gateway run --role runner
```

* `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`

```bash theme={"dark"}
wednesdayai gateway health --url ws://127.0.0.1:18789
```

### `gateway status`

`gateway status` shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe.

```bash theme={"dark"}
wednesdayai gateway status
wednesdayai gateway status --json
```

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.

```bash theme={"dark"}
wednesdayai gateway probe
wednesdayai gateway probe --json
```

#### 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:

```bash theme={"dark"}
wednesdayai 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 (LAN/WAB only).

Config (optional, used as defaults):

* `gateway.remote.sshTarget`
* `gateway.remote.sshIdentity`

### `gateway call <method>`

Low-level RPC helper.

```bash theme={"dark"}
wednesdayai gateway call status
wednesdayai gateway call logs.tail --params '{"sinceMs": 60000}'
```

For scripting, pass `--json`. Without it the command prints a `Gateway call: <method>` preamble
before the payload, which breaks JSON pipes such as `jq`:

```bash theme={"dark"}
wednesdayai gateway call sessions.runs.list --params '{"limit": 10}' --json | jq '.runs[0]'
```

### `gateway usage-cost`

Fetch the usage cost summary for the last N days from gateway session logs.

```bash theme={"dark"}
wednesdayai gateway usage-cost
wednesdayai gateway usage-cost --days 7 --json
```

Options: `--days <n>` (default: 30), `--json`.

## Manage the Gateway service

```bash theme={"dark"}
wednesdayai gateway install
wednesdayai gateway start
wednesdayai gateway stop
wednesdayai gateway restart
wednesdayai gateway uninstall
```

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:

```bash theme={"dark"}
wednesdayai gateway restart
# Config invalid
# File: ~/.openclaw/openclaw.json
# Problem:
#   - plugins.entries.<id>.config: invalid config: must NOT have additional properties
# Run: wednesdayai doctor --fix
# Or: wednesdayai config validate
```

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 `$include`s) (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](https://docs.wednesdayai.dev/next/admin/gateway/bonjour.md)

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`

```bash theme={"dark"}
wednesdayai gateway discover
```

Options:

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

Examples:

```bash theme={"dark"}
wednesdayai gateway discover --timeout 4000
wednesdayai gateway discover --json | jq '.beacons[].wsUrl'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.