Run OpenClaw Gateway: CLI Commands & Configuration Guide

Managing a WebSocket server often feels like a chore. You spend more time debugging connection strings and auth tokens than actually building your project. If you’ve ever had to hunt down a ghost process or guess why a port is blocked, you’ll appreciate a CLI that actually tells you what’s going on.

The OpenClaw Gateway handles your channels, nodes, and sessions. This guide walks you through the CLI commands you need to keep your server running smoothly.

Run the Gateway

If you want to get a local Gateway process up and running immediately, use the base command. It’s the quickest way to start testing.

openclaw gateway

If you prefer an alias that makes it clear the process is running in the foreground, use this:

openclaw gateway run

A few things to keep in mind:

• The Gateway usually won’t start unless you have gateway.mode=local in your ~/.openclaw/openclaw.json. If you’re just doing a quick dev run, use the --allow-unconfigured flag.
• For safety, the CLI blocks binding to anything other than loopback if you haven’t set up authentication.
• You can trigger an in-process restart by sending a SIGUSR1 signal, provided commands.restart is enabled.
• If you stop the process with SIGINT or SIGTERM, it won’t automatically fix your terminal state. If you’re running this inside a TUI, make sure to handle the terminal restoration yourself.

Options

• --port <port>: WebSocket port (default comes from config/env; usually 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. Warning: inline passwords can be exposed in local process listings.
• --password-file <path>: read the gateway password from a file.
• --tailscale <off|serve|funnel>: expose the Gateway via Tailscale.
• --tailscale-reset-on-exit: reset Tailscale serve/funnel config on shutdown.
• --allow-unconfigured: allow gateway start without gateway.mode=local in config.
• --dev: create a dev config + workspace if missing (skips BOOTSTRAP.md).
• --reset: reset dev config + credentials + sessions + workspace (requires --dev).
• --force: kill any existing listener on the selected port before starting.
• --verbose: verbose logs.
• --cli-backend-logs: only show CLI backend logs in the console (and enable stdout/stderr).
• --claude-cli-logs: deprecated alias for --cli-backend-logs.
• --ws-log <auto|full|compact>: websocket log style (default auto).
• --compact: alias for --ws-log compact.
• --raw-stream: log raw model stream events to jsonl.
• --raw-stream-path <path>: raw stream jsonl path.

Query a running Gateway

Once the Gateway is active, you can query it using WebSocket RPC. By default, the output is designed for humans with colors and clear formatting, but you can switch to --json if you’re piping data into another tool.

If you use the --url flag, the CLI won’t look at your config for credentials. You’ll need to provide the --token or --password manually in that case.

gateway health

Check if the Gateway is responding at a specific URL:

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

gateway status

This command checks the service status (like systemd or launchd) and can perform an RPC probe to make sure the server is actually functional.

openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc

Options:

• --url <url>: override the probe URL.
• --token <token>: token auth for the probe.
• --password <password>: password auth for the probe.
• --timeout <ms>: probe timeout (default 10000).
• --no-probe: skip the RPC probe (service-only view).
• --deep: scan system-level services too.
• --require-rpc: exit non-zero when the RPC probe fails. Cannot be combined with --no-probe.

gateway probe

When things go wrong, gateway probe is your best friend. It checks your configured remote gateway and your local loopback simultaneously.

openclaw gateway probe
openclaw gateway probe --json

If you see Reachable: yes, the connection worked. If you see RPC: limited, it means you connected but don’t have the right permissions (like operator.read) to see all the details.

Remote over SSH (Mac app parity)

If you’re used to the “Remote over SSH” mode in the macOS app, you can do the same thing here. It sets up a local port-forward so you can reach a remote gateway as if it were local.

openclaw gateway probe --ssh user@gateway-host

gateway call <method>

For low-level debugging, you can call RPC methods directly.

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

Manage the Gateway service

Instead of running the process manually in a shell, you can manage it as a background service.

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

When installing, the CLI checks that your authentication (like SecretRefs) is valid. It won’t let you install a service with broken auth references, which prevents the “it works in my shell but not as a service” headache. If you’re using passwords, I recommend using OPENCLAW_GATEWAY_PASSWORD or a --password-file instead of typing it directly into the command.

Discover gateways (Bonjour)

You don’t always want to type in IP addresses. The Gateway uses Bonjour to broadcast its presence on the network. This works for both local discovery and Wide-Area Bonjour if you have a DNS server set up.

gateway discover

Run this to see what Gateways are currently visible on your network.

openclaw gateway discover

You can adjust the timeout if your network is slow or use JSON output to script the discovery process.

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

下一步

• Learn more about /gateway/bonjour
• Dive into /gateway/discovery
• Fine-tune your /gateway/configuration

Need help getting started? Check out the AI Setup Assistant.