Gateway

Gateway is OpenClaw's WebSocket server (channels, nodes, sessions, hooks).

Subcommands in this page are under ''openclaw gateway …''.

Related docs:

- ''/gateway/bonjour''

- ''/gateway/discovery''

- ''/gateway/configuration''

Run a local gateway process:

openclaw gateway

Foreground alias:

openclaw gateway run

Notes:

- By default, gateway refuses to start unless ''gateway.mode=local'' is set in ''~/.openclaw/openclaw.json''. Use ''--allow-unconfigured'' for temporary/dev runs.

- Binding outside loopback without authorization is blocked (safety guardrails).

- ''SIGUSR1'' triggers in-process restart when authorized (enable ''commands.restart'' or use gateway tool/config apply/update).

- ''SIGINT''/''SIGTERM'' handlers stop the gateway process, but they do not restore any custom terminal state. If you use TUI or raw mode input wrappers for CLI, restore terminal before exit.

### Options

- ''--port <port>'': WebSocket port (default from config/env; typically ''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 gateway via Tailscale.

- ''--tailscale-reset-on-exit'': Reset Tailscale service/funnel config on shutdown.

- ''--allow-unconfigured'': Allow gateway to start without ''gateway.mode=local'' in config.

- ''--dev'': Create a dev config+workspace if missing (skip BOOTSTRAP.md).

- ''--reset'': Reset dev config+credentials+sessions+workspace (requires ''--dev'').

- ''--force'': Kill any existing listener on the selected port before starting.

- ''--verbose'': Verbose logging.

- ''--claude-cli-logs'': Show claude-cli logs in console only (and enable its stdout/stderr).

- ''--ws-log <auto|full|compact>'': websocket log style (default ''auto'').

All query commands use WebSocket RPC.

Output modes:

- Default: Human-readable (colored in TTY).

- ''--json'': Machine-readable JSON (no styling/spinners).

- ''--no-color'' (or ''NO_COLOR=1''): Disable ANSI while keeping human layout.

Shared options (if supported):

- ''--url <url>'': Gateway WebSocket URL.

- ''--token <token>'': Gateway token.

- ''--password <password>'': Gateway password.

- ''--timeout <ms>'': Timeout/budget (varies per command).

#

openclaw gateway health --url ws://127.0.0.1:18789

#

''gateway status'' shows gateway service (launchd/systemd/schtasks) and optional RPC probe.

openclaw gateway status
openclaw gateway status --json

Options:

- ''--url <url>'': Override probe URL.

- ''--token <token>'': Token auth for probe.

- ''--password <password>'': Password auth for probe.

- ''--timeout <ms>'': Probe timeout (default ''10000'').

- ''--no-probe'': Skip RPC probe (service view only).

- ''--deep'': Also scan system-level services.

#

''gateway probe'' is the "debug everything" command. It always probes:

- Your configured remote gateway (if set), and

- Localhost (loopback) even if remote is configured.

openclaw gateway probe
openclaw gateway probe --json

##

macOS app "Remote via SSH" mode uses local port forwarding, so remote gateway is accessible at ''ws://127.0.0.1:<port>'' (may only bind to loopback).

CLI equivalent:

openclaw 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 first discovered gateway host as SSH target (LAN/WAB only).

Config (optional, used as defaults):

- ''gateway.remote.sshTarget''

- ''gateway.remote.sshIdentity''

#

Low-level RPC helper.

openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

- ''gateway install'' supports ''--port'', ''--runtime'', ''--token'', ''--force'', ''--json''.

- Lifecycle commands accept ''--json'' for scripting.

''gateway discover'' scans for gateway beacons (''_openclaw-gw._tcp'').

- Multicast DNS-SD: ''local.''

- Unicast DNS-SD (Wide-Area Bonjour): Pick a domain (e.g., ''openclaw.internal.'') and set split DNS + DNS server; see ''/gateway/bonjour''

Only gateways with Bonjour discovery enabled (default) advertise beacons.

Wide-area discovery records include (TXT):

- ''role'' (gateway role hint)

- ''transport'' (transport hint, e.g., ''gateway'')

- ''gatewayPort'' (WebSocket port, typically ''18789'')

- ''sshPort'' (SSH port; defaults to ''22'' if absent)

- ''tailnetDns'' (MagicDNS hostname, if available)

- ''gatewayTls'' / ''gatewayTlsSha256'' (TLS enabled + cert fingerprint)

- ''cliPath'' (optional hint for remote install)

##

#

openclaw gateway discover

Options:

- ''--timeout <ms>'': Per-command timeout (browse/resolve); default ''2000''.

- ''--json'': Machine-readable output (also disables styling/spinners).

Examples:

openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'