skip to content

Core Runtime

The always-on Gateway process that owns every channel connection, runs agent turns, keeps sessions and routes messages to agents. Interviewers start here because everything else plugs into it.

part ofAI coding toolsread it →
on this pageshow

explore

questions

21

What is the OpenClaw Gateway, and why does a host normally run only one of it?

level: juniorimportance: must knowfreq 20%

answer

  1. one long-lived process
  2. everything else is a client
  3. owns channels and session state
  4. loopback, port 18789
  5. state lock plus exclusive port bind

basics

~20 s

The 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 s

The 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

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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.
open as a page

In OpenClaw, what do the chat commands `/new`, `/reset`, `/compact` and `/stop` each do to the current session?

level: juniorimportance: must knowfreq 16%

basics

~20 s

OpenClaw's /new and /reset start the conversation over, /compact summarizes older turns so the same conversation continues in a smaller context, and /stop aborts the current run without touching history. None of them erases the stored transcript.

open as a page

In OpenClaw, what happens between an inbound chat message reaching the Gateway and the agent's reply going back out?

level: middleimportance: must knowfreq 12%

basics

~20 s

OpenClaw turns each inbound message into a serialized agent run: it resolves the session, waits for that session's lane, builds the prompt from its base prompt, skills and workspace files, calls the model and tools, then shapes and delivers the reply.

open as a page

In OpenClaw, how do the queue modes steer, followup, collect and interrupt handle messages that arrive while an agent run is active?

level: middleimportance: must knowfreq 10%

basics

~20 s

The default steer mode injects a mid-run message into the active run; followup queues each message for its own later turn; collect merges queued messages into one later turn; interrupt aborts the active run and answers the newest message.

open as a page

In OpenClaw, how do you route a work Slack account to one agent and a family WhatsApp number to another?

level: middleimportance: must knowfreq 12%

basics

~10 s

Define both agents under agents.entries, log in a Slack account and a WhatsApp account, then add bindings whose match names the channel and accountId for each. Verify with openclaw agents list --bindings.

open as a page

A family shares one OpenClaw assistant over direct messages and one member's private details surface in another's chat — why, and what do you change?

level: middleimportance: must knowfreq 18%

basics

~10 s

OpenClaw's session.dmScope defaults to main, so every direct message joins one shared session and each sender's turns carry the others' context. Setting session.dmScope to per-channel-peer gives each sender on each channel an isolated session.

open as a page

Why does an OpenClaw agent's reply reach a chat app as a finished message or a few blocks rather than streaming token by token?

level: juniorimportance: should knowfreq 7%

basics

~20 s

OpenClaw never streams token deltas into channel messages. Block streaming, which sends finished chunks as separate messages, is off by default, and live previews depend on each channel's streaming mode, so most replies arrive complete.

open as a page

In OpenClaw, what does each agent on a multi-agent Gateway own separately, and what does it still share?

level: juniorimportance: should knowfreq 11%

basics

~20 s

Each OpenClaw agent owns a workspace (AGENTS.md, SOUL.md, notes), an agentDir with its auth profiles and model registry, and its own session store. It still shares the Gateway process, channel access policy and, by default, session-tool reach.

open as a page

How does a client connect to the OpenClaw Gateway's WebSocket API, and why must its first frame be connect?

level: middleimportance: should knowfreq 7%

basics

~20 s

A client opens a WebSocket to the Gateway, receives a connect.challenge nonce, and sends a connect request declaring its role, scopes, auth and signed device identity. The Gateway answers hello-ok; any non-connect first frame is a hard close.

open as a page

On an OpenClaw Gateway, how does an operator client differ from a role: node device, and how is each one approved?

level: middleimportance: should knowfreq 6%

basics

~20 s

Operator clients such as the CLI and Control UI steer the Gateway within granted operator scopes; node devices connect with role: node and offer commands like camera.snap or system.run. Both pair by device identity; nodes also need their command surface approved.

open as a page

In OpenClaw chat, why does a message containing only `/think high` change later replies while `/think high` inside a longer request does not?

level: middleimportance: should knowfreq 7%

basics

~20 s

OpenClaw strips directives such as /think and /verbose from a message before the model sees it. Sent alone, most directives are saved as the session's setting and acknowledged; mixed into a request, they apply to that one message only.

open as a page

In OpenClaw's default steer queue mode, what happens to a running tool call, and to the calls planned after it, when a new message arrives mid-run?

level: seniorimportance: should knowfreq 6%

basics

~20 s

Steering does not abort a tool that is already running. It finishes, any planned sequential calls that have not started are skipped with a synthetic result, and the new message is added before the next model call. Interrupt mode is the one that aborts.

open as a page

After you edit openclaw.json, why do some OpenClaw Gateway changes apply live while others restart the process, and when do you run openclaw gateway restart yourself?

level: seniorimportance: should knowfreq 8%

basics

~20 s

Under the default hybrid reload mode, the Gateway classifies each changed config path: agents, models, sessions and tools apply live, while port, bind, auth mode and TLS restart it automatically. Restart by hand in off mode or after changing an installed service's port.

open as a page

Two OpenClaw bindings cover one WhatsApp group: a channel-wide rule listed first, a rule for that group listed second — which agent answers, and why?

level: seniorimportance: should knowfreq 7%

basics

~20 s

The agent bound to that group answers, provided that binding covers the message's account. OpenClaw ranks bindings by specificity tier, with exact peer matches above account and channel-wide matches; config order only breaks ties inside one tier.

open as a page

A security reviewer asks where an OpenClaw Gateway keeps session transcripts and when they are actually removed — what do you answer?

level: seniorimportance: should knowfreq 6%

basics

~20 s

As of OpenClaw 2026.9.9, the Gateway keeps session rows and transcripts in a per-agent SQLite database under ~/.openclaw/agents/<agentId>/. Resets, compaction and the 30-day cutoff keep or archive history instead of erasing it; even a deleted session leaves an archive.

open as a page

When should you add another agent to one OpenClaw Gateway rather than run a separate Gateway, and what decides it?

level: principalimportance: should knowfreq 6%

basics

~20 s

Add an agent when everyone involved trusts each other and only persona, credentials and history need separating. Run a separate Gateway, ideally under another OS user or host, when people must not reach each other's tools, files or sessions.

open as a page

Setting up one OpenClaw Gateway for a household or small team who trust each other, how do you choose between the shared main session and per-sender DM scopes, and what must change with it?

level: principalimportance: should knowfreq 5%

basics

~20 s

Keep OpenClaw's default main session only when one person talks to the agent. For several people, set session.dmScope to per-channel-peer, narrow tools.sessions.visibility to self, and add identity links for anyone on several apps, accepting that cross-conversation recall defaults off.

open as a page

After an OpenClaw upgrade, a small host serving many busy chats hits provider rate limits and memory pressure; which limit governs concurrent agent runs, and how do you cap it?

level: seniorimportance: nice to knowfreq 4%

basics

~20 s

Inbound runs share the global main lane, capped by agents.defaults.maxConcurrent. Since OpenClaw 2026.9.5 the unset default is four runs per available CPU, at least eight, so a constrained host should set an explicit lower value.

open as a page

In OpenClaw, why can't a per-agent `tools.allow` bring back a tool that the global `tools.deny` removes?

level: seniorimportance: nice to knowfreq 5%

basics

~10 s

OpenClaw filters tools through a chain (profile, global allow/deny, provider, per-agent, sandbox, subagent) where each layer can only narrow the set. A per-agent allow cannot re-grant a globally denied tool; deny always wins.

open as a page

In OpenClaw, what does `agents.defaults.contextPruning` in `cache-ttl` mode remove from a session's context, and how does that differ from compaction?

level: seniorimportance: nice to knowfreq 4%

basics

~20 s

OpenClaw's cache-ttl pruning trims or clears old tool results in what the model sees, leaving conversation text and the stored transcript untouched. Compaction instead summarizes the older conversation itself into one entry when the context window nears its limit.

open as a page

When a host runs a second OpenClaw Gateway as a rescue bot, what must each instance own separately so the rescue lane survives the main one breaking, and how do you prove it does?

level: principalimportance: nice to knowfreq 4%

basics

~20 s

Each instance needs its own --profile, config path, state directory, workspace, channel credentials and a base port at least 120 away, since startup refuses shared state. Prove it with gateway status --deep on both profiles, gateway probe, and a test with the main Gateway stopped.

open as a page