Run the Gateway

openclaw gateway run options, startup behavior, and revealing the configured token

Starting the Gateway process and reading its configured token. Part of the openclaw gateway reference.

Run the Gateway

openclaw gateway
openclaw gateway run   # equivalent, explicit form

Startup behavior

Refuses to start unless gateway.mode=local is set in ~/.openclaw/openclaw.json. Use --allow-unconfigured for ad-hoc/dev runs; it bypasses the guard without writing or repairing config.
Startup automatically applies deterministic, prompt-free legacy-key migrations to eligible invalid single-file configs, including in non-interactive service runs. It writes only after full validation, including plugins, and keeps the previous config in the .bak ring. Configs using $include, Nix-managed configs, and configs written by a newer version are excluded. See Legacy config key migrations.
If automatic migration cannot make the config valid, an interactive terminal can offer to run openclaw doctor --fix and retry startup once after consent. Non-interactive runs print the command instead. If the repaired config is still invalid, startup remains stopped.
Configuration read failures, including unavailable storage during SQLite inspection, stop startup with exit code 1 so service supervision can retry. They do not trigger config repair. Invalid configuration and required offline migrations retain exit code 78, which prevents systemd restart loops; resolve the reported problem before restarting.
Before reading its shared-state snapshot, startup waits up to five minutes for a temporary schema owner in another OpenClaw process to finish. Explicit offline maintenance still blocks access, and exhausted contention remains a read failure with exit code 1.
Startup does not load plugin Doctor modules just to collect advisory repair rules for valid config. Invalid config still includes plugin repair guidance; openclaw doctor inspects repair rules even when the config is valid.
Config recovery, shared-state readiness, and pending plugin migration reads share the current admission snapshot. Registry refresh rechecks admission while holding both migration and plugin lifecycle leases, then verifies the persisted replacement. Repairs still compare current state before writing. This does not change update migrations or stored data.
openclaw onboard --mode local and openclaw setup write gateway.mode=local. If the config file exists but gateway.mode is missing, that is treated as damaged/clobbered config and the Gateway refuses to guess local for you — re-run onboarding, set the key manually, or pass --allow-unconfigured.
Binding beyond loopback without auth is blocked.
--bind values lan, tailnet, and custom resolve over IPv4-only paths; IPv6-only bring-your-own-host setups need an IPv4 sidecar or proxy in front of the Gateway.
SIGUSR2 triggers an in-process restart when authorized. commands.restart (default: enabled) gates externally-sent SIGUSR2; set it to false to block manual OS-signal restarts. The agent-facing gateway tool is read-only; agents request restart through the openclaw delegation tool. Effective Full Access, including Default (Full Access), authorizes permitted delegated changes without an approval prompt; restricted runs require human approval. See Delegated setup and repair.
SIGUSR1 is reserved for Node's inspector, so attaching a debugger does not restart the Gateway. Prefer openclaw gateway restart for restarts; update manual restart scripts to send SIGUSR2.
SIGINT/SIGTERM stop the process but do not restore custom terminal state — if you wrap the CLI in a TUI or raw-mode input, restore the terminal yourself before exit.

Options

WebSocket port (default from config/env; usually 18789).

Bind mode: loopback (default), lan, tailnet, auto, custom.

Shared token for connect.params.auth.token. Defaults to OPENCLAW_GATEWAY_TOKEN when set.

Auth mode: none, token, password, trusted-proxy.

Password for --auth password.

Read the Gateway password from a file.

Tailscale exposure: off, serve, funnel.

Start without enforcing gateway.mode=local. Ad-hoc/dev bootstrap only; does not persist or repair config.

Create a dev config + workspace if missing (skips BOOTSTRAP.md).

Allow the Gateway to auto-configure channels from ambient environment variables for this process, including config reloads. By default, foreground, dev, and service Gateways require explicit channels.<id> configuration, such as channels.discord.enabled=true. Configured channels can still read credentials from environment variables. For managed services, add the channel config block; this flag is not persisted by service installation.

Deprecated alias for --ambient-channels.

Reset dev config, credentials, sessions, and workspace. Requires --dev.

Kill any existing listener on the target port before starting. In a non-interactive shell, this refuses to kill a verified Gateway listener; use --dev or an isolated --profile with a free port instead.

Verbose logging to stdout/stderr.

Only show CLI backend logs in the console (also enables stdout/stderr).

WebSocket log style: auto, full, compact.

Alias for --ws-log compact.

Log raw model stream events to JSONL.

Raw stream JSONL path.

--claude-cli-logs is a deprecated alias for --cli-backend-logs.

For --bind custom, set gateway.customBindHost to an IPv4 address. Any address other than 127.0.0.1 or 0.0.0.0 also requires 127.0.0.1 on the same port for same-host clients; startup fails if either listener cannot bind. Wildcard 0.0.0.0 does not add a separate required alias. IPv6-only bring-your-own-host setups need an IPv4 sidecar or proxy in front of the Gateway.

Reveal the configured token

Run this on the Gateway host when a client needs the configured shared token:

openclaw gateway auth-token --show

The command resolves gateway.auth.token, OPENCLAW_GATEWAY_TOKEN, and configured SecretRefs, then prints only the token. It requires an interactive terminal and refuses redirected or piped output so the credential does not silently enter command logs. Treat the terminal output as a secret.

If no persistent token is configured, run openclaw doctor --generate-gateway-token, restart the Gateway, and then rerun the command. Generic openclaw config get output remains redacted, including --json.