Getting the "gateway start blocked: set gateway.mode=local (current: unset) or pass --allow-unconfigured" error? This is the most common OpenClaw setup issue — and it's a quick fix.

Why This Happens

OpenClaw's gateway requires an explicit mode configuration before it starts. This is a security measure: the gateway won't start until you tell it whether it should accept local connections, remote connections, or both.

If you see any of these messages, you're hitting the same issue:

gateway start blocked: set gateway.mode=local (current: unset)
  or pass --allow-unconfigured

Missing config. Run `openclaw setup` or set gateway.mode=local
  (or pass --allow-unconfigured).

gateway.mode unset — gateway start will be blocked

The Fix (30 Seconds)

Run this single command:

openclaw config set gateway.mode local

Then restart:

openclaw restart

That's it. Your gateway should start normally.

What Does `gateway.mode` Do?

The gateway.mode setting controls how your OpenClaw gateway accepts connections:

Mode	Description	Use Case
`local`	Only accepts connections from `localhost`	Personal use, single-machine setup
`remote`	Accepts connections from any IP	Multi-device access, reverse proxy setups
`hybrid`	Accepts both local and remote	Development + production

For most users, local is the right choice. If you're accessing OpenClaw through a reverse proxy (Caddy, Nginx, Traefik), you still want local because the proxy runs on the same machine.

What About `--allow-unconfigured`?

The --allow-unconfigured flag is a one-time bypass:

openclaw gateway start --allow-unconfigured

This starts the gateway without saving any configuration. It works for quick testing, but you'll see the same error next time you restart. Setting gateway.mode permanently is the better solution.

Still Blocked After Setting gateway.mode?

If you've set the mode but the gateway still won't start, check for other missing configuration:

# Run the diagnostic tool
openclaw doctor

# Auto-fix all detected issues
openclaw doctor --fix

Common additional issues:

Port conflict: Another process is using the gateway port
```
openclaw config set gateway.port 3002
```
Config file corruption: Reset and reconfigure
```
openclaw config validate
```
Permission issues: The config directory isn't writable
```
ls -la ~/.openclaw/
```

Verify It's Working

After the fix, confirm the gateway is running:

openclaw status

You should see gateway: running in the output. You can also check the logs:

openclaw logs --tail 20

Look for [gateway] listening on — that's the confirmed ready signal.

Skip the Configuration Entirely

If you'd rather not debug gateway configuration, ClawTank gives you a pre-configured OpenClaw instance with the gateway already set up. Deploy in under 1 minute — no terminal commands needed.