OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI commands

Run the Gateway

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

Run the Gateway

bash
openclaw gatewayopenclaw 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.
  • 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 today; IPv6-only bring-your-own-host setups need an IPv4 sidecar or proxy in front of the Gateway.
  • SIGUSR1 triggers an in-process restart when authorized. commands.restart (default: enabled) gates externally-sent SIGUSR1; 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.
  • 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

"--port

" type="number"> WebSocket port (default from config/env; usually 18789).

"--bind

" type="string"> Bind mode: loopback (default), lan, tailnet, auto, custom.

"--token

" type="string"> Shared token for connect.params.auth.token. Defaults to OPENCLAW_GATEWAY_TOKEN when set.

"--auth

" type="string"> Auth mode: none, token, password, trusted-proxy.

"--password

" type="string"> Password for --auth password.

" type="string"> Read the Gateway password from a file.

"--tailscale

" type="string"> Tailscale exposure: off, serve, funnel.

--allow-unconfiguredboolean

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

--devboolean

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

--ambient-channelsboolean

Allow the Gateway to auto-configure channels from ambient environment variables. By default, channels require an explicit channels.<id> config block.

--dev-ambient-channelsboolean

Deprecated alias for --ambient-channels.

--resetboolean

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

--forceboolean

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.

--verboseboolean

Verbose logging to stdout/stderr.

--cli-backend-logsboolean

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

"--ws-log

" type="string" default="auto"> WebSocket log style: auto, full, compact.

--compactboolean

Alias for --ws-log compact.

--raw-streamboolean

Log raw model stream events to JSONL.

" type="string"> 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:

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

Was this useful?
On this page

On this page