What is the OpenClaw Gateway, and why does a host normally run only one of it?
answer
- one long-lived process
- everything else is a client
- owns channels and session state
- loopback, port 18789
- state lock plus exclusive port bind
basics
~20 sThe Gateway is OpenClaw's single long-lived process: it holds every chat-channel connection, owns all session state and runs agent turns. The CLI, Control UI, apps and paired devices are only clients of its WebSocket API, by default at 127.0.0.1:18789.
solid answer
~50 sThe Gateway is the daemon, started as `openclaw gateway` or as an installed service, that keeps the provider connections to WhatsApp, Telegram, Slack, Discord, Signal, iMessage and WebChat and serves a typed WebSocket API of requests, responses and pushed events. Everything you touch is a client: the CLI, the Control UI served on the same port, the macOS app, and phones or headless machines that connect as `role: node` devices. It owns all session state, so clients ask it instead of keeping their own. The docs fix one Gateway per host because it is the only place that opens a WhatsApp session, and a state-directory lock plus an exclusive port bind refuse a second instance on the same state. It binds `loopback` on port `18789` by default; a second Gateway needs its own profile, state and port.
go deeper
Recall that the Gateway is the one process that holds the chat connections and sessions, that every app and the CLI is a client, and that it listens on 127.0.0.1:18789 unless changed.
Explain what the Gateway owns, from channel connections and session state to agent turns and scheduled wakeups, and how operator clients, node devices and the Control UI all reach it over one port.
Show how single ownership is enforced: the state-directory lock, the exclusive bind, the GatewayLockError messages, and why a second instance needs its own profile, state and port.
Frame the Gateway as the unit of trust and failure: one process per boundary, several agents inside it, and a deliberate second instance only for rescue or separation.
## What the Gateway is The **Gateway** is OpenClaw's always-on daemon. You can start it in the foreground with `openclaw gateway`, which logs to stdout, or run it as an installed service that launchd, systemd or Windows Scheduled Tasks keeps alive. Whatever starts it, it is one long-lived process, and every other piece of OpenClaw you touch talks to it instead of doing the work itself. That matters the first time an operator sees three surfaces at once: an app on the phone, the `openclaw` CLI on a laptop and a dashboard in the browser. None of them is "the assistant". Each is a window onto one process running on the home server, and closing any of them leaves the assistant exactly where it was. ## What it owns - **Channel connections.** The Gateway maintains the provider connections for WhatsApp, Telegram, Slack, Discord, Signal, iMessage and WebChat. The architecture page states that it is the only place that opens a WhatsApp session. - **Session state.** All session state is owned by the Gateway; UI clients query the Gateway for session data rather than keeping a copy of their own. - **Agent turns.** An `agent` request is accepted, run and streamed back by the Gateway, which also emits events such as `agent`, `chat`, `presence`, `health`, `heartbeat` and `cron`. - **Timed work.** One scheduler inside the Gateway drives its registered maintenance and cron wakeups. - **The control plane.** A typed WebSocket API of requests, responses and server-push events, with inbound frames validated against JSON Schema generated from the protocol's TypeBox definitions. ## Who talks to it | Client | How it connects | Examples | | --- | --- | --- | | Operator client | WebSocket, declaring `role: operator` and scopes | the CLI, the Control UI, the macOS app, automations | | Node device | WebSocket, declaring `role: node` with caps and commands | macOS, iOS, Android or headless hosts offering `camera.*`, `screen.record`, `location.get` | | Browser dashboard | Pages served by the Gateway's own HTTP server, then its WebSocket | the Control UI at `http://127.0.0.1:18789/` | All of them share one multiplexed port, which also carries the Gateway's HTTP APIs and its hook endpoints. There is no separate web server to run for the dashboard. ## Why one per host The docs put it plainly: one Gateway per host, and a single Gateway can host several agents and several channels. Three facts make a casual second copy on the same state fail or misbehave rather than help: 1. **One owner for channel sessions.** The architecture invariant is that exactly one Gateway controls a given WhatsApp (Baileys) session per host; two processes holding the same account would fight over it. 2. **One owner for state.** At startup the Gateway takes exclusive ownership of its state directory through a lock sidecar. A second process pointed at the same state waits up to five minutes for ownership and then fails with a `GatewayLockError`. 3. **One owner for the port.** The listener is an exclusive TCP bind. If the port is still busy after about ten seconds of retries, startup reports `another gateway instance is already listening on ws://127.0.0.1:<port>`. A second Gateway on the same machine is supported only as a deliberate act: its own profile, config path, state directory, workspace and port, usually for a rescue bot or a separate trust boundary. Setting `OPENCLAW_ALLOW_MULTI_GATEWAY=1` permits several instances; it never permits two of them to share mutable state. ## Where it listens - **Port:** `--port`, then `OPENCLAW_GATEWAY_PORT`, then `gateway.port`, then the built-in default `18789`. - **Bind:** a CLI override, then `gateway.bind`, then `loopback`. Inside a detected container the effective default is `auto`, so that port-forwarding works, unless Tailscale Serve or Funnel is active, which forces loopback. A stock install outside a container therefore listens on `127.0.0.1:18789` and answers only the machine it runs on. Opening it to other machines, and the authentication that has to come with that, is a separate subject. ## A first look at a running Gateway 1. `openclaw gateway status` shows the installed service plus a connectivity probe; a healthy baseline reads `Runtime: running` and `Connectivity probe: ok`. 2. `openclaw status` gives the broader picture as the Gateway reports it. 3. `openclaw logs --follow` tails the Gateway's file logs over RPC, so it works against a remote Gateway as well as a local one. If those three agree, the process is up, and the phone, the laptop and the browser are only clients of it.
- What stops a second OpenClaw Gateway from starting against the same state?Startup takes exclusive ownership of the state directory through a lock sidecar, then binds the port exclusively. A second process on the same state waits up to five minutes for ownership and fails with a `GatewayLockError`; one that finds the port taken retries for about ten seconds and reports `another gateway instance is already listening`. Under a service supervisor it first probes the existing Gateway's `/healthz` and, if that one is healthy, leaves it in control.
- Does the OpenClaw Control UI need a web server of its own?No. The Gateway's HTTP server serves the Control UI on the same port, at `http://127.0.0.1:18789/` by default or under `gateway.controlUi.basePath`, and the page then talks directly to the Gateway's WebSocket. `gateway.controlUi.enabled` hot-applies, so you can stop serving the dashboard while channels and connected clients keep running.
The Gateway is the switchboard of an old office: the desk phones never hold the outside lines themselves, they ring the switchboard, and it alone keeps every outside line open. Unplug a desk phone and the calls in progress carry on.
- The CLI and the dashboard each keep their own connection to WhatsApp.
- Every chat app you connect needs a Gateway process of its own.
- A fresh Gateway outside a container listens on all interfaces by default.
- Conversation history lives in the browser dashboard, so closing the tab loses it.
- Two Gateways can share one state directory as long as their ports differ.