openclaw gateway

Run, inspect, and query the WebSocket Gateway

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

Basic

# 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

Related Commands

• daemon - Manage gateway as a system service
• logs - View gateway logs
• doctor - Diagnose gateway issues