Complete reference for openclaw gateway, running foreground processes, managing background services, diagnostics, network discovery, and low-level RPC invocation.
What is the Gateway?
The Gateway is the central process that connects OpenClaw’s CLI, agent runtimes, and external chat channels. Everything routes through it, incoming messages from WhatsApp, Slack, or Telegram; outgoing agent replies; cron jobs; device pairing; browser control.
It exposes a WebSocket/HTTP interface that both the CLI and client apps communicate with. Without a running Gateway, no channel traffic flows and no agents respond. The gateway command surface covers four distinct concerns: starting the process, managing it as a background service, querying its live state, and invoking internal methods directly.
Finding the Right Command Group
If you’re starting the Gateway for the first time or need a quick foreground run, go to Run. If you want it running persistently across reboots without a terminal window, Service Management is what you need.
When something’s broken or behaving unexpectedly, Diagnostics covers status, health, probe, and network discovery, start with gateway status and escalate to gateway probe if the basic check isn’t surfacing the issue. RPC is for power users who need to trigger internal Gateway methods without a full CLI command wrapper.
Running the Gateway
Starts the Gateway process in the foreground. Useful for development, one-off runs, or when you want to see live log output in the terminal.
run variants
# Both are identical — run is the default subcommand openclaw gateway openclaw gateway run # Common launch configurations openclaw gateway --port 19000 openclaw gateway --bind lan --tailscale serve openclaw gateway --force # kill any existing process on the port first openclaw gateway --dev # dev config, skips bootstrap checks
Launch Flags
| Flag | Description |
|---|---|
--port <port> | Overrides the WebSocket/HTTP port. Defaults to 18789. |
--bind <mode> | Sets the listener bind mode. Options: loopback lan tailnet auto custom. |
--auth <token|password> | Overrides the auth mode for this run. |
--token <token> / --password <password> | Provides the Gateway credentials inline. Useful for scripted or temporary runs. |
--tailscale <mode> | Exposes the Gateway via Tailscale. Options: off serve funnel. |
| –force | Kills any existing listener on the selected port before starting. Prevents EADDRINUSE errors when a stale process is holding the port. |
| –allow-unconfigured | Allows the Gateway to start even if gateway.mode=local is missing from your config. Useful for ad-hoc or dev runs. |
| –dev | Boots a dev config and workspace, skipping the normal bootstrap checks. For local development only. |
The –force flag kills any existing process listening on the selected port, including other applications that happen to be on that port. Verify nothing else owns the port before using it in shared environments.
Managing the Background Service
Register the Gateway with your OS supervisor for persistent background operation. Auto-starts on login or boot, survives terminal sessions closing.
macOS launchdLinux systemdWindows schtasks
| install Installs the Gateway as a supervised background service. Accepts –port, --runtime <node|bun>, –token, and –force. | start Starts the installed service. Service must be registered via install first. | stop Stops the running service without removing the registration. |
| restart Recommended after any config change or plugin update. Equivalent to stop + start in one command. | uninstall Removes the Gateway service from the OS supervisor entirely. Config files are preserved. |
service lifecycle examples
# Initial install with specific port and runtime openclaw gateway install --port 18789 --runtime node # Standard lifecycle openclaw gateway start openclaw gateway stop openclaw gateway restart # after config changes openclaw gateway uninstall
Querying & Diagnostics
These commands communicate with a running Gateway via WebSocket RPC. All support connection overrides: –url, –token, and –password.
| openclaw gateway status Shows both the background service’s state (e.g. systemd status) and runs a live RPC probe to verify the Gateway is actually answering requests. The go-to first diagnostic command. –deep | –json |
| openclaw gateway health Asks the running Gateway for a full health snapshot. Append –verbose to run live probes against configured channel providers and see per-account response timings. More detailed than status. –verbose |
| openclaw gateway probe The “debug everything” command. Simultaneously probes your configured remote Gateway (if set) and your localhost Gateway. Supports a --ssh user@host flag to tunnel and probe a remote Gateway exactly as the macOS companion app does, useful for diagnosing unreachable remote instances.–ssh user@host |
| openclaw gateway discover Scans your local network (mDNS) or Tailnet (DNS-SD) for actively broadcasting OpenClaw Gateways and prints their connection URLs and capabilities. Useful for finding a Gateway on a network where you don’t know the IP, or for verifying that the DNS-SD setup from openclaw dns setup is working correctly. |
Note: If the service is “Active” but the RPC probe fails with an unauthorized error, you are likely Resolving Gateway Token Mismatch issues between your CLI configuration and the running background service.
When debugging connectivity issues: start with status (is the service running?), escalate to health –verbose (are channels responding?), then probe (is the remote vs. local Gateway reachable?). Each step exposes progressively more detail.
Low-Level RPC Invocation
For power users who need to trigger internal Gateway methods directly without a dedicated CLI command wrapper.
| openclaw gateway call <method> A low-level helper that lets you trigger internal Gateway RPC methods directly from the terminal. Pass JSON arguments using --params <json>. Useful for operations not yet wrapped by a dedicated subcommand, or for scripting specific internal actions.status | logs.tail | config.apply | update.run |
RPC call examples
# Call status directly via RPC
openclaw gateway call status
# Tail logs via RPC
openclaw gateway call logs.tail
# Apply config changes via RPC
openclaw gateway call config.apply
# Pass JSON params to a method
openclaw gateway call update.run --params '{"force":true}'
gateway call uses the same WebSocket RPC connection as all other diagnostic commands and accepts –url, –token, and –password overrides to target a specific Gateway instance.
