openclaw gateway bind — All 5 Modes Explained

OpenClaw’s gateway.bind setting controls which network interfaces the gateway listens on. Choosing the wrong mode is the number one reason people get locked out of their Control UI or accidentally expose it to the internet.

Here is what each mode does, when to use it, and the security implications.

The Five Bind Modes

loopback (Default)

openclaw config set gateway.bind loopback

Listens on: 127.0.0.1:18789

Use when: You only access OpenClaw from the same machine. This is the safest option — no network exposure at all.

Limitation: Cannot access Control UI from your phone, another computer, or any remote device.

lan

openclaw config set gateway.bind lan

Listens on: Your local network IP (e.g., 192.168.1.100:18789)

Use when: You want to access OpenClaw from other devices on your home or office network.

Requires: Setting gateway.controlui.allowedOrigins with your machine’s LAN IP.

openclaw config set gateway.controlui.allowedOrigins '["http://192.168.1.100:18789"]'

tailnet

openclaw config set gateway.bind tailnet

Listens on: Your Tailscale interface IP (e.g., 100.x.y.z:18789)

Use when: You use Tailscale and want secure remote access without exposing to the local network.

Requires: Tailscale installed and running. Set allowedOrigins with your Tailscale hostname:

openclaw config set gateway.controlui.allowedOrigins '["http://your-machine.tail12345.ts.net:18789"]'

auto

openclaw config set gateway.bind auto

Listens on: Automatically selects the best available interface (prefers Tailscale if available, falls back to LAN).

Use when: You want OpenClaw to figure it out. Good for laptops that switch between networks.

custom

openclaw config set gateway.bind "custom:0.0.0.0"

Listens on: Whatever address you specify.

Use when: You need to bind to a specific interface or 0.0.0.0 (all interfaces).

Warning: Binding to 0.0.0.0 exposes the gateway on ALL network interfaces. Always set allowedOrigins and consider firewall rules.

Quick Comparison

Mode	Address	Network Exposure	Requires allowedOrigins
loopback	127.0.0.1	None	No
lan	LAN IP	Local network	Yes
tailnet	Tailscale IP	Tailscale mesh	Yes
auto	Auto-detected	Varies	Yes (if non-loopback)
custom	User-specified	User-controlled	Yes (if non-loopback)

Checking Your Current Mode

# View current bind setting
openclaw config get gateway.bind

# View the actual address after resolution
openclaw gateway status

Common Mistakes

”invalid —bind” Error

invalid --bind (use "loopback", "lan", "tailnet", "auto", or "custom")

You typed an invalid value. Use one of the five modes, or custom:IP for a specific address.

Gateway Starts But Cannot Connect

Your browser URL must match allowedOrigins exactly. Check:

Protocol: http:// vs https://
Hostname: IP address vs DNS name
Port: :18789 must be included

Changed Bind But Old Address Still Works

Restart the gateway after changing bind:

openclaw gateway restart

Environment Variable

Set bind mode via environment variable (useful for Docker):

export OPENCLAW_GATEWAY_BIND=lan
# or
OPENCLAW_GATEWAY_BIND=custom:0.0.0.0

Security Recommendations

Use loopback if you only need local access
Use tailnet for remote access — encrypted, authenticated, no port forwarding
Use lan only on trusted networks
Avoid custom:0.0.0.0 unless behind a firewall or reverse proxy
Always set allowedOrigins when using non-loopback modes
Never use dangerouslyAllowHostHeaderOriginFallback in production

Frequently Asked Questions

What are the OpenClaw gateway bind modes?

OpenClaw's gateway.bind setting supports five modes: loopback (127.0.0.1 only), lan (your local network IP), tailnet (a Tailscale address), auto (pick an interface automatically), and custom (an explicit address you specify).

Which gateway bind mode is the most secure?

loopback is the safest. It listens only on 127.0.0.1:18789, so the Control UI has no network exposure and is reachable only from the same machine.

Why can't I reach the Control UI from another device?

The default loopback mode only allows connections from the gateway host. Switch to lan or tailnet so other devices can connect, then set gateway.controlui.allowedOrigins for the URL you will use.

Does changing the bind mode require allowedOrigins?

Yes. Any non-loopback bind mode (lan, tailnet, auto, or custom) requires you to set gateway.controlui.allowedOrigins, otherwise the gateway refuses to expose the Control UI off-host.