Skip to main content

​
openclaw gateway

Manage the OpenClaw WebSocket Gateway server.

​
Usage

openclaw gateway [command] [options]

​
Commands

​
run

Run the WebSocket Gateway in the foreground. 
openclaw gateway run [options]

​
Options

​
--port <port>
number
Port for the gateway WebSocket server (default: 18789)
​
--bind <mode>
string
Bind mode: loopback, lan, tailnet, auto, or custom
  • loopback: Bind to 127.0.0.1 (local only)
  • lan: Bind to LAN interface
  • tailnet: Expose via Tailscale
  • auto: Choose automatically
  • custom: Use custom bind address
Defaults to config gateway.bind or loopback
​
--token <token>
string
Shared token required in connect.params.auth.token. Defaults to OPENCLAW_GATEWAY_TOKEN env if set
​
--auth <mode>
string
Gateway auth mode: token or password
​
--password <password>
string
Password for auth mode=password
​
--tailscale <mode>
string
Tailscale exposure mode: off, serve, or funnel
​
--tailscale-reset-on-exit
boolean
Reset Tailscale serve/funnel configuration on shutdown
​
--allow-unconfigured
boolean
Allow gateway start without gateway.mode=local in config
​
--force
boolean
Kill any existing listener on the target port before starting
​
--verbose
boolean
Enable verbose logging to stdout/stderr
​
--ws-log <style>
string
WebSocket log style: auto, full, or compact (default: auto)
​
--compact
boolean
Alias for --ws-log compact
​
--dev
boolean
Create a dev config + workspace if missing (no BOOTSTRAP.md)
​
--reset
boolean
Reset dev config + credentials + sessions + workspace (requires —dev)

​
status

Show gateway service status and probe reachability. 
openclaw gateway status [options]
​
--json
boolean
Output JSON format

​
start

Start the gateway as a background service. 
openclaw gateway start

​
stop

Stop the gateway background service. 
openclaw gateway stop

​
restart

Restart the gateway background service. 
openclaw gateway restart

​
discover

Discover gateways via Bonjour (local + wide-area if configured). 
openclaw gateway discover [options]
​
--timeout <ms>
number
Per-command timeout in ms (default: 2000)
​
--json
boolean
Output JSON format

​
call

Call a Gateway RPC method directly. 
openclaw gateway call <method> [options]
​
method
string
required
Method name: health, status, system-presence, or cron.*
​
--params <json>
string
JSON object string for params (default: )
​
--json
boolean
Output JSON format

​
health

Fetch Gateway health status. 
openclaw gateway health [options]
​
--json
boolean
Output JSON format

​
probe

Show gateway reachability + discovery + health + status summary (local + remote). 
openclaw gateway probe [options]
​
--url <url>
string
Explicit Gateway WebSocket URL (still probes localhost)
​
--ssh <target>
string
SSH target for remote gateway tunnel (user@host or user@host:port)
​
--ssh-identity <path>
string
SSH identity file path
​
--ssh-auto
boolean
Try to derive an SSH target from Bonjour discovery
​
--token <token>
string
Gateway token (applies to all probes)
​
--password <password>
string
Gateway password (applies to all probes)
​
--timeout <ms>
number
Overall probe budget in ms (default: 3000)

​
Examples

# Run gateway on default port
openclaw gateway run

# Run with custom port
openclaw gateway run --port 18790

# Run with verbose output
openclaw gateway run --verbose
When binding to anything other than loopback, you must configure authentication (--token or --password) to prevent unauthorized access.
The gateway runs as a WebSocket server that agents and channels connect to. For production use, run it as a background service with openclaw gateway start.

​
Authentication

The gateway supports three authentication modes:
  1. Token: Clients must provide a shared token
  2. Password: Clients must provide a shared password
  3. None: No authentication (only for loopback)
Configure authentication in ~/.openclaw/openclaw.json: 
{
  gateway: {
    auth: {
      mode: "token",
      token: "your-secret-token"
    }
  }
}
Or use environment variables: 
export OPENCLAW_GATEWAY_TOKEN=your-secret-token
openclaw gateway run

​
Bind Modes

  • loopback: Bind to 127.0.0.1 (local connections only)
  • lan: Bind to LAN interface (accessible from local network)
  • tailnet: Expose via Tailscale (requires Tailscale setup)
  • auto: Automatically choose based on config
  • custom: Use custom bind address from config

​
Troubleshooting

If the gateway fails to start:
  1. Check if another process is using the port: lsof -i :18789
  2. Use --force to kill existing listeners
  3. Check configuration: openclaw config get gateway
  4. Run diagnostics: openclaw doctor
  • daemon - Manage gateway as a system service
  • logs - View gateway logs
  • doctor - Diagnose gateway issues