OpenClaw Gateway bind modes: how to prove what is exposed

Your OpenClaw configuration can say loopback while a service, container, reverse proxy, or stale process creates a different network path. The opposite problem is common too: a remote client cannot connect because the Gateway is listening only inside a container or only on the local machine.

Short answer: gateway.bind selects the interface on which the Gateway listens. It changes who can potentially reach the Gateway, but it does not decide who is trusted after the connection arrives. A credible security check therefore needs more than the value in openclaw.json. You need the effective configuration, the live socket, the intended client path, the denied path, and the controls in front of them.

OpenClaw puts WebSocket control and RPC traffic, HTTP APIs, plugin routes, the Control UI, and hooks on the Gateway port. The Gateway runbook describes this as one multiplexed port. Changing the bind mode can therefore expose more than a dashboard. It can make the same operator surface reachable on another interface.

The setting changes the listener, not the whole security model

OpenClaw's security guidance describes loopback as the normal default for a regular host installation. It also documents an exposed-bind exception for container images. The field reference lists symbolic bind modes, not arbitrary host strings. Use loopback, lan, tailnet, custom, or auto; do not copy 0.0.0.0 or 127.0.0.1 into the field as if those were the supported mode names.

These behaviors come from the current Gateway configuration reference and the Tailscale documentation. A resolved Tailnet or custom address can create a second local listener on 127.0.0.1. That is useful for local clients, but it also means a socket listing may show more than one address by design.

Tailscale Serve is a separate choice from a direct Tailnet bind. With gateway.bind: 'loopback' and gateway.tailscale.mode: 'serve', the Gateway stays on loopback while Tailscale supplies HTTPS, routing, and Tailnet identity headers. A direct tailnet bind exposes the Gateway on the Tailnet address itself and does not add HTTPS. The documentation recommends Serve when HTTPS is preferable. Funnel is different again: it creates a public path and requires a shared password.

Choose the smallest reachable surface

Start with the client that actually needs access.

• If the operator and the Gateway share one machine, use loopback. Do not turn on a LAN bind merely because the Control UI is convenient.
• If a personal laptop needs administrative access, keep the Gateway on loopback and use SSH or Tailscale Serve. This preserves a narrow backend listener while adding a deliberate access path.
• If a private device must connect directly over Tailscale, use tailnet with Gateway authentication and verify the Tailnet interface. Prefer Serve when the client needs HTTPS.
• If known devices on a private LAN need direct access, use lan or a specific custom address, then add a firewall allowlist for the expected source addresses. The bind mode alone does not identify trusted devices.
• If public access is unavoidable, put an identity-aware reverse proxy, TLS, rate limits, and strict allowlists in front of the Gateway. The network exposure guidance says not to expose an unauthenticated Gateway on 0.0.0.0 and advises against direct public port forwarding.

Authentication is not a replacement for a narrow bind. It protects the application after traffic reaches the port; it does not stop an accidental LAN listener from being scanned, or prevent a proxy from forwarding a path you forgot to document. Conversely, loopback is not a complete trust boundary if a local process, browser, tunnel, or reverse proxy can reach the service.

Build an evidence chain

A configuration screenshot proves intent. It does not prove that the running service read that file or that a firewall and proxy preserve the intended boundary. The useful evidence answers four questions: what did you choose, what is actually listening, can the intended client reach it, and are unintended clients denied?

1. Record the effective configuration

Use the documented openclaw config get pattern for the relevant paths:

openclaw config get gateway.bind
openclaw config get gateway.port
openclaw config get gateway.auth.mode

Do not print or save the token or password. Record the profile, state directory, config path, bind mode, port, authentication mode, Tailscale mode, reverse-proxy address, and firewall policy. Check the port precedence too: the current order is CLI override, OPENCLAW_GATEWAY_PORT, gateway.port, then 18789. The OpenClaw FAQ warns that the CLI and the service can use different profiles, environment variables, or config files.

2. Ask the running Gateway what it is using

Run the status and health checks from the same profile and environment as the service:

openclaw gateway status --json
openclaw health --verbose

The health documentation distinguishes a local summary, a live Gateway health snapshot, and a verbose probe that shows connection details. The Gateway runbook describes a healthy status as a running runtime, an successful connectivity probe, and a capability line that matches expectations. Status output also helps expose the common case where a supervisor says the process is running but the RPC probe is using the wrong URL.

Treat Runtime: running as process evidence, not exposure evidence. A process can be alive while it listens on the wrong port, the wrong interface, or a different config path.

3. Inspect the operating system socket

Use a host-level listener check as an operator test. It is not an OpenClaw result and it should not be treated as one:

# macOS
lsof -nP -iTCP:18789 -sTCP:LISTEN

# Linux
ss -ltnp | grep ':18789'

Compare the addresses with the decision you recorded. Loopback should show a loopback-only listener. LAN should show the wildcard IPv4 address. Tailnet or custom should show the selected address, plus the local loopback listener when OpenClaw requires it. If another process owns the port, stop and identify that process before drawing a conclusion. A port number by itself says nothing about the interface.

4. Test both the allowed and denied paths

For the positive test, use the exact URL a real client will use and pass credentials explicitly. The exposure runbook gives this pattern:

openclaw gateway probe --url ws://127.0.0.1:18789 --token '$OPENCLAW_GATEWAY_TOKEN'

For a Tailnet deployment, substitute the intended Tailnet URL. For Serve or a reverse proxy, test the HTTPS or WSS origin that users will actually open. The runbook specifically warns that an explicit remote URL should not be assumed to inherit local config credentials.

Then perform a negative test from outside the allowed path. A device outside the LAN or Tailnet should fail to establish a TCP connection, or should reach an authentication denial if the network is intentionally routable but the application is protected. Both results can be correct. What matters is that the result matches the design. A successful health response proves that a server answered; it does not prove that the source was authorized.

5. Check the route and the audit findings

Run the documented deep audit after changing the bind, proxy, or Tailscale route:

openclaw security audit --deep

The security audit catalog includes checks such as gateway.bind_no_auth, gateway.tailscale_funnel, gateway.control_ui.allowed_origins_required, and gateway.probe_failed. Resolve critical findings. Keep intentional warnings with a written reason and an owner.

For Tailscale, inspect tailscale serve status --json and confirm that the hostname, path, and proxy target point to the Gateway you meant to expose. For a reverse proxy, verify the immediate proxy source, TLS termination, forwarded-header handling, allowed browser origins, and the configured authentication mode. Run the deep audit again after those changes. The Gateway exposure runbook recommends validating an authorized connection, an unauthorized sender or browser session, log redaction, routing, and high-impact tool policy after each exposure change.

A small acceptance packet

Suppose the requirement is simple personal access from a laptop on the same Tailnet, with no LAN or public exposure. The narrower design is usually loopback plus Tailscale Serve:

gateway: {
  bind: 'loopback',
  tailscale: { mode: 'serve' },
  auth: { mode: 'token' }
}

The acceptance packet for that design should contain the redacted effective config, the service status output, the operating system socket listing, the Tailscale route status, a successful authenticated probe from the laptop, and a failed direct-LAN or off-Tailnet test. It should also include the deep audit output and a note explaining any remaining warning. This is a proposed acceptance test, not a hands-on result from this article.

The packet is stronger because each artifact proves something different. The config says what was intended. The socket says what the process opened. The positive probe says the useful client can complete the Gateway protocol. The negative probe tests the boundary from the outside. The route and audit records cover the infrastructure around the process.

Failure paths and limits

The service is running, but the port is wrong

OpenClaw documents separate supervisor and RPC views. A service may have been installed with a resolved port or a different profile, while your interactive CLI reads another config. Check the probe target, config path, environment, and port precedence before changing the bind again. Reinstall or repair the service only after you have identified which configuration it should own.

Docker publishes a port, but the Gateway is unreachable

The configuration reference says that loopback inside a container means 127.0.0.1 inside that container. With Docker bridge networking, published traffic arrives on the container's network interface instead. The documented choices are host networking or an exposed bind such as lan, with authentication and host firewall controls. Do not widen the bind just to make a health check pass without checking who can reach the host.

Tailnet mode is set, but no Tailnet listener exists

If no usable Tailscale IPv4 address exists when the Gateway starts, the documented behavior falls back to loopback. Restart after Tailscale becomes available and repeat the socket and remote-path checks. A configuration value of tailnet is not evidence that a Tailnet route currently exists.

Loopback is still reachable from outside

A reverse proxy, SSH tunnel, Tailscale route, or container port mapping can make a loopback service reachable through another path. That is not automatically wrong, but it means the local socket is only one part of the exposure story. With trusted-proxy authentication, the proxy becomes part of the identity boundary. With Tailscale Serve, the identity-header path is limited to the documented Control UI and WebSocket surfaces; other HTTP APIs still follow the Gateway's normal authentication mode.

The network is private, but the trust boundary is too large

OpenClaw's trust model assumes one trusted operator or one mutually trusting team per Gateway. A Tailnet or LAN address does not turn an agent into a hostile multi-tenant boundary. If users are adversarial or need separate authority, use separate Gateways and preferably separate operating-system users or hosts. Bind hardening reduces reachability; it does not create tenant isolation.

What to keep for the next operator

Store a short, redacted record with the verification date, host and profile, config path, effective bind and port, authentication mode, Tailscale or proxy route, firewall source range, socket output, authorized and unauthorized test results, audit findings, and rollback command. Never put a token, password, browser session, or copied secret in the evidence packet.

The decision is straightforward once the evidence is separated. Use loopback when local access is enough. Add SSH or Serve when remote access is needed without widening the Gateway listener. Use LAN, Tailnet, or custom binds only when the reachable devices, authentication path, firewall, and failure response are explicit. Then prove the running state from the host and from the network, rather than trusting the configuration line alone.

Sources

• Configuration — gateway: bind modes, port precedence, authentication requirements, Docker behavior, and local listener rules.
• Security — OpenClaw: regular-host defaults, container exceptions, and the one-trusted-boundary model.
• Network exposure — OpenClaw: LAN firewall guidance, unauthenticated wildcard-bind warning, and remote connection semantics.
• Gateway exposure runbook — OpenClaw: exposure patterns, baseline checks, post-change validation, and rollback.
• Health checks — OpenClaw: status, health, verbose probes, and the difference between reachability and channel state.
• Security audit checks — OpenClaw: bind, proxy, Tailnet, Control UI, and live-probe findings.
• Tailscale — OpenClaw: Serve, Funnel, direct Tailnet binding, fallback behavior, and route inspection.
• Gateway runbook — OpenClaw and OpenClaw FAQ: the multiplexed Gateway port, status evidence, service configuration, and troubleshooting paths.
• All sources accessed 2026-09-13.