Why does an OpenClaw Gateway bind to loopback by default, and what changes when you widen `gateway.bind`?
answer
- who can open the socket
- 127.0.0.1 and port 18789
- lan, tailnet, custom, auto
- startup refuses a wide bind without a secret
- containers flip the default
basics
~20 sOpenClaw's gateway.bind defaults to loopback (127.0.0.1, port 18789), so only same-host processes can reach the Gateway's WebSocket and Control UI. Wider modes such as lan or tailnet admit other machines and require token or password auth.
solid answer
~40 sThe Gateway is the one process that holds your channels, sessions and credentials, so `gateway.bind` decides who can even try to talk to it. The default `"loopback"` listens on `127.0.0.1:18789`, which only same-host clients can reach. `"lan"` listens on all interfaces, `"tailnet"` on the Tailnet IPv4 plus `127.0.0.1`, `"custom"` on an address in `customBindHost`, and `"auto"` prefers loopback but uses `0.0.0.0` in a detected container. Widening the bind is guarded: the Gateway refuses to start on a non-loopback address without a token or password (or trusted-proxy auth). Loopback is not a substitute for auth either; onboarding still generates a token, because any local process or a same-host reverse proxy can reach a loopback port.
code
json · 7 lines{
"gateway": {
"bind": "loopback",
"port": 18789,
"auth": { "mode": "token", "token": "replace-with-a-long-random-token" }
}
}go deeper
Recall the default: gateway.bind is loopback on 127.0.0.1 port 18789, so only same-host clients connect, and remote use goes through an SSH tunnel or Tailscale.
Explain each bind mode and the startup guard that refuses a non-loopback bind without a token or password, and why loopback still carries a token.
Show you know where exposure really comes from: container images that default to lan, a same-host reverse proxy, and the audit findings that catch each.
Argue for loopback plus a tunnel or Serve as the team standard, and say what evidence a wider bind must come with: auth, origin allowlist, firewall rule, audit run.
## What the bind decides The **Gateway** is the single long-running process at the centre of an OpenClaw install. It keeps the chat-channel connections, the sessions, the model credentials and the tool runtime, and every client (the CLI, the browser Control UI, the phone apps) talks to it over one port that carries both WebSocket and HTTP. That port is `18789` by default (`gateway.port`, `--port` or `OPENCLAW_GATEWAY_PORT`). `gateway.bind` controls **which network interface that port listens on**, and therefore which machines can even attempt a connection. It is the outermost layer of the security model: before tokens, pairing, DM policies or sandboxes matter, someone has to reach the socket. ## The modes | `gateway.bind` | Listens on | Who can connect | |---|---|---| | `"loopback"` (default) | `127.0.0.1` | Processes on the same host | | `"lan"` | `0.0.0.0` (all IPv4 interfaces) | Anything that can route to the host | | `"tailnet"` | The Tailnet IPv4, plus `127.0.0.1` | Tailnet devices and same-host clients; falls back to loopback if no Tailnet address exists at startup | | `"custom"` | The IPv4 in `gateway.customBindHost` | Whatever can reach that address | | `"auto"` | Loopback if available, `0.0.0.0` in a detected container | Depends on where it runs | The bind takes these mode names, not raw host strings: you write `"lan"`, not `"0.0.0.0"`. ## Why loopback is the default OpenClaw's trust model is **one trust boundary per Gateway**: a single operator or a team whose members trust each other. A connection authenticated to the Gateway is treated as an operator, and shared-secret operator access over HTTP is effectively full access. Listening only on `127.0.0.1` means the attack surface on a fresh install is the local machine, and anything remote has to arrive through a path you chose deliberately: - an **SSH tunnel** that forwards `127.0.0.1:18789` from your laptop to the host; - **Tailscale Serve**, which keeps the Gateway on loopback and proxies tailnet traffic to it over HTTPS; - a reverse proxy you configure, with `gateway.trustedProxies` set. ## What happens when you widen it OpenClaw guards the wider modes at startup rather than leaving them to the audit: 1. If the resolved bind address is not loopback and there is no token or password (and the auth mode is not `"trusted-proxy"`), the Gateway **refuses to bind** and exits with an error naming `gateway.auth.token`/`password` and the matching environment variables. 2. A non-loopback Control UI also needs a browser-origin allowlist (`gateway.controlUi.allowedOrigins`, or `gateway.publicOrigin` when the list is omitted), or startup fails. 3. `openclaw security audit` reports `gateway.bind_no_auth` as **critical** for a wide bind without a shared secret, which matters for configs that have not been restarted yet. So a wide bind is never unauthenticated by accident, but it does make the token or password the main barrier between the internet and an operator session, plus a firewall if you add one. ## Loopback still needs auth A common misreading is that loopback means auth can be skipped. It cannot, for two reasons: - **Every local process can reach a loopback port**, including other users' processes and anything a compromised tool started. - **A same-host reverse proxy turns loopback into remote access.** The audit's `gateway.loopback_no_auth` finding (critical) exists for exactly this: loopback bind, Control UI enabled, no auth secret. That is why onboarding generates a Gateway token even for a loopback install, and why, in token mode with no credential at all, a loopback Gateway mints a runtime-only token instead of running open. ## Containers are the deliberate exception Inside a container, `127.0.0.1` is the container's own network namespace, so a loopback-bound Gateway would be unreachable from the host. The Docker setup therefore defaults `OPENCLAW_GATEWAY_BIND=lan`, and the security overview says plainly that container images default to an exposed bind that must be paired with auth and a firewall. On a server, that is where most accidental exposure comes from. ## Exposure the bind does not cover The bind decides who can reach the port; a few neighbouring settings decide what the Gateway tells the network about itself: - **mDNS discovery.** When the bundled Bonjour plugin is enabled, the Gateway advertises itself on the local network. The default `discovery.mdns.mode` is `"minimal"`; `"full"` adds the CLI path (which reveals the username) and the SSH port, and the audit flags it as `discovery.mdns_full_mode`. `"off"` or `OPENCLAW_DISABLE_BONJOUR=1` stops advertising. - **Browser origins.** A non-loopback Control UI needs an explicit origin allowlist; `allowedOrigins: ["*"]` disables origin checks and is flagged too. ## Checking what you actually bound Do not trust memory or a config diff alone: 1. Run `openclaw security audit` and read every `gateway.*` finding. 2. From another machine, scan the host's public address for open ports; the only ones expected are those you meant to expose, usually SSH. 3. After changing the bind, restart the Gateway and repeat both steps.
- Why is a loopback-bound OpenClaw Gateway still given a token?Any process on the host can open a loopback port, and a same-host reverse proxy can forward outside traffic to it. The audit flags a loopback Control UI with no auth secret as `gateway.loopback_no_auth`, critical. Onboarding generates a token by default, and in token mode with no credential a loopback Gateway creates a runtime-only token rather than running open.
- What does `gateway.bind: "tailnet"` listen on, and what if Tailscale is not up yet?It listens on the host's Tailnet IPv4 and also on `127.0.0.1` for same-host clients, with plain `ws://` and no HTTPS. If no Tailnet address exists when the Gateway starts, it falls back to loopback only; you restart after Tailscale comes up to add the Tailnet listener. It still needs token or password auth like any non-loopback bind.
Binding to loopback is like a house phone with no outside line: anyone in the house can pick it up, nobody outside can dial in, and you still lock the doors because people inside can use it too.
- The Gateway listens on all interfaces until you lock it down.
- Loopback-only means you can safely turn Gateway auth off.
- Setting bind to lan without a token just triggers an audit warning.
- You set gateway.bind to a raw address like 0.0.0.0.
- The Docker image keeps the Gateway on loopback like a host install.