OpenClaw Error: refusing to bind gateway … without auth (Security Guardrail Fix) | Mac, Linux, WSL2

Service Initialization

Last Updated: April 22, 2026 | Author: DevOps Engineering Team | Platforms: Linux / Raspberry Pi / macOS / WSL2

This is an intentional security guardrail, not a bug. It occurs when you configure the Gateway to bind to a non-loopback address without enabling authentication. Can be fixed in 1 minute.

Quick Answer (3-Step Fix)

Run these commands in order to resolve the refusing to bind gateway ... without auth error immediately:

# Step 1 (Recommended): Revert to secure default loopback binding
openclaw config set gateway.bind loopback && openclaw gateway restart

# Step 2 (If you need non-loopback access): Generate and set a secure token
openclaw doctor --generate-gateway-token
openclaw gateway restart

Critical Security Warning: Never expose an unauthenticated OpenClaw Gateway to any network. The Gateway has full tool execution and filesystem access on your host.

Why This Error Occurs

Binding beyond loopback without auth is blocked by a mandatory safety guardrail. Reference: OpenClaw CLI Gateway Documentation

This is a critical security measure to prevent unauthorized access to your Gateway. Any bind mode other than loopback requires explicit authentication configuration.

Typical Error Output

[ERROR] Gateway Initialization Failed
[ERROR] refusing to bind gateway to 0.0.0.0:18789 without auth
[INFO] Non-loopback binds require explicit authentication
[INFO] Set gateway.auth.token or gateway.auth.password in your config
[INFO] Or revert to gateway.bind=loopback for local-only access

Common triggers:

Changed gateway.bind to lan, tailnet, custom or 0.0.0.0 without adding auth
Upgraded OpenClaw and old gateway.token config is no longer recognized (now uses gateway.auth.token)
Enabled Tailscale Serve/Funnel without configuring authentication
Used --bind CLI flag without matching --token or --password
Configured a reverse proxy without setting up trusted proxy auth

Important clarification: There is no flag to bypass this security check. --allow-unconfigured only bypasses the gateway.mode check, not authentication.

If You Need Non-Loopback Access

Only use these methods if you explicitly need to access the Gateway from other devices. Always prefer the most restrictive option that meets your needs.

1. Configure Token Authentication (Recommended)

Token authentication is the most secure and recommended method for non-loopback access:

# 1. Generate a secure random token (auto-saves to config)
openclaw doctor --generate-gateway-token

# 2. Set your desired bind mode
openclaw config set gateway.bind lan # or tailnet/custom

# 3. Restart the Gateway
openclaw gateway restart

# 4. Verify status
openclaw gateway status
# Expected output: "Runtime: running" and "RPC probe: ok"

Manual config example (if you prefer editing the file):

{
  "gateway": {
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "your-long-random-token-here"
    }
  }
}

2. Configure Password Authentication (Alternative)

Password authentication is available as an alternative to tokens:

# Set password via CLI
openclaw config set gateway.auth.mode password
openclaw config set gateway.auth.password "your-strong-password"

# Restart Gateway
openclaw gateway restart

Security Note: Prefer token authentication over password authentication. Tokens are longer, random, and easier to rotate.

3. Tailscale Serve Configuration

For remote access, Tailscale Serve is the recommended method. It provides built-in identity authentication:

# Enable Tailscale Serve mode
openclaw config set gateway.tailscale serve

# Generate and set token (still recommended for extra security)
openclaw doctor --generate-gateway-token

# Restart Gateway
openclaw gateway restart

Reference: OpenClaw Gateway Security Guide

4. Trusted Proxy Authentication

If running behind an identity-aware reverse proxy, use trusted proxy auth mode:

{
  "gateway": {
    "bind": "loopback",
    "auth": {
      "mode": "trusted-proxy"
    },
    "trustedProxies": [
      "127.0.0.1",
      "your-proxy-ip"
    ]
  }
}

Platform-Specific Notes

macOS

Ensure the macOS firewall allows incoming connections on port 18789 if using bind=lan
Use gateway.bind=tailnet instead of lan for remote access
Verify no other process is using port 18789: lsof -i :18789

Linux / Raspberry Pi

Configure UFW to allow port 18789 only from trusted IPs: sudo ufw allow from 192.168.1.0/24 to any port 18789
Never expose port 18789 directly to the public internet
Use systemd to manage the Gateway service: systemctl status openclaw-gateway

WSL2

To access the Gateway from Windows, set gateway.bind=lan and configure authentication
WSL2 requires port forwarding to access from other devices on the network
Always work inside the Linux file system (~/), not the Windows file system (/mnt/c/)

Common Search Variants

OpenClaw refusing to bind gateway without auth
openclaw gateway bind lan auth required
openclaw 0.0.0.0 without auth error
openclaw tailscale funnel authentication
openclaw gateway.auth.token config

FAQ

Q: Why can’t I bind to 0.0.0.0 without authentication?

A: This is a mandatory security guardrail. An unauthenticated Gateway would allow anyone on the network to execute arbitrary commands and access your filesystem.

Q: Why doesn’t my old gateway.token config work anymore?

A: OpenClaw v1.0+ uses the new gateway.auth.token configuration path. The old gateway.token path is deprecated and no longer recognized.

Q: Do I still need a token if I’m using Tailscale Serve?

A: While Tailscale provides identity authentication, adding an additional Gateway token is recommended for defense-in-depth security.

Q: How do I rotate my Gateway token?

A: Run openclaw doctor --generate-gateway-token to generate a new token and automatically update your config. Then restart the Gateway.

Q: Can I access the Gateway from other devices without changing the bind mode?

A: Yes. Use Tailscale Serve to expose the Gateway securely over the Tailnet without changing the bind mode from loopback.

Summary

The refusing to bind gateway ... without auth error is an intentional security guardrail that prevents unauthenticated access to your OpenClaw Gateway. It occurs when you configure a non-loopback bind address without enabling authentication.

The recommended fix is to revert to the secure default loopback bind mode. If you need non-loopback access, configure token authentication using openclaw doctor --generate-gateway-token.

Official Security Best Practices

✅ Always use gateway.bind=loopback unless you explicitly need remote access
✅ Prefer Tailscale Serve over LAN binds for remote access
✅ Use token authentication instead of password authentication
✅ Rotate your Gateway token every 90 days
✅ Never expose the Gateway directly to the public internet
✅ Restrict port access to trusted IP addresses only
✅ Run openclaw security audit --deep regularly

Quick Navigation