Fix "Gateway Start Blocked" in OpenClaw — gateway.mode=local

If your OpenClaw gateway refuses to start with a "gateway start blocked" error, you need to set gateway.mode. This guide covers every variation of this error, the one-command fix, and how to prevent it from happening again.

Every "Gateway Start Blocked" Error Message

OpenClaw outputs slightly different messages depending on your version and configuration state. If you landed here from any of these, you are in the right place:

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

gateway start blocked: set gateway.mode=local --allow-unconfigured

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

gateway.mode unset — gateway start will be blocked

gateway.mode is unset

ERROR: gateway.mode not configured. Run openclaw setup or set
  gateway.mode=local to start in local-only mode.

missing config: run openclaw setup or set gateway.mode=local

gateway start blocked: gateway.mode is unset — expected local, remote, or hybrid

[gateway] start blocked — config key gateway.mode has no value

All of these mean the same thing: OpenClaw will not start its gateway until you explicitly choose a mode. This is an intentional security measure, not a bug.

30-Second Fix

Run one command:

openclaw config set gateway.mode local

Then restart:

openclaw restart

Done. Your gateway will start normally.

If you are already inside an openclaw setup wizard and hit this error, type local when prompted for the gateway mode, and the wizard will handle the rest.

What Is gateway.mode?

The gateway.mode setting tells OpenClaw which network interfaces the gateway should listen on. OpenClaw refuses to pick a default for you because each mode has different security implications.

Pick local unless you have a specific reason not to. Even if you access OpenClaw through a reverse proxy like Caddy or Nginx, local is correct because the proxy runs on the same machine and connects via localhost.

Setting the mode:

# Local-only (recommended)
openclaw config set gateway.mode local

# Remote access
openclaw config set gateway.mode remote

# Both
openclaw config set gateway.mode hybrid

You can verify your current setting at any time:

openclaw config get gateway.mode

What About --allow-unconfigured?

The error message suggests --allow-unconfigured as an alternative. This flag starts the gateway once without saving any configuration:

openclaw gateway start --allow-unconfigured

This is useful for one-off testing or quick debugging sessions. However, the next time you restart OpenClaw, you will see the same "gateway start blocked" error again because nothing was saved to the config.

Use openclaw config set gateway.mode local instead. It is permanent and you will never see this error again.

When --allow-unconfigured is passed, the gateway defaults to local-only mode for that session. It does not open remote access.

Docker Users

If you run OpenClaw in Docker, set the mode via an environment variable instead of a config command:

docker run -e OPENCLAW_GATEWAY_MODE=local openclaw-stack

Or in docker-compose.yml:

services:
  openclaw:
    image: openclaw-stack
    environment:
      - OPENCLAW_GATEWAY_MODE=local

For Docker containers behind a reverse proxy, also set the trusted proxies so the gateway accepts forwarded connections:

environment:
  - OPENCLAW_GATEWAY_MODE=local
  - OPENCLAW_GATEWAY_TRUSTED_PROXIES=127.0.0.1

If you are exec-ing into a running container, you can still use the CLI:

docker exec -it <container> openclaw config set gateway.mode local
docker exec -it <container> openclaw restart

Still Blocked? Other Causes

If you have already set gateway.mode and the gateway still will not start, the problem is something else. Run diagnostics:

openclaw doctor

Auto-fix all detected issues:

openclaw doctor --fix

Common causes beyond gateway.mode:

Port Conflict

Another process is using the gateway port (default 3001). Check and change it:

# See what's using the port
lsof -i :3001

# Switch to a different port
openclaw config set gateway.port 3002
openclaw restart

Config File Corruption

A bad config file can block startup even with gateway.mode set:

# Validate the config
openclaw config validate

# If validation fails, reset the config and reconfigure
openclaw config reset
openclaw setup

Permission Issues

The config directory or data files are not writable by the current user:

ls -la ~/.openclaw/

# Fix ownership if needed
sudo chown -R $(whoami) ~/.openclaw/

Stale PID File

A previous crash left a PID file that prevents a clean start:

rm ~/.openclaw/gateway.pid
openclaw restart

Verify It's Working

After applying the fix, confirm the gateway is running:

openclaw status

You should see gateway: running in the output. For more detail, check the logs:

openclaw logs --tail 20

The line [gateway] listening on confirms the gateway is fully started and accepting connections. If you see that line, the fix worked.

FAQ

Why does OpenClaw not just default to local mode?

OpenClaw treats gateway mode as a security-critical setting. Defaulting silently could expose the gateway on an unintended interface. By forcing an explicit choice, OpenClaw ensures you are aware of how your instance is reachable.

I set gateway.mode but still get the error after reboot

Make sure you used openclaw config set gateway.mode local (not just an environment variable in your shell). The config command writes to ~/.openclaw/config.yaml, which persists across reboots. Run openclaw config get gateway.mode to confirm it was saved.

Does gateway.mode=local work with Cloudflare Tunnel / ngrok?

Yes. Both Cloudflare Tunnel and ngrok connect to your gateway via localhost, so local mode is correct. You do not need remote mode for tunneling services.

Can I change gateway.mode without restarting?

No. The gateway reads its mode at startup. After changing the config, run openclaw restart to apply.

What is the difference between openclaw setup and openclaw config set?

openclaw setup is an interactive wizard that walks you through all configuration options including gateway mode, API keys, and integrations. openclaw config set gateway.mode local changes only the gateway mode directly. Both end up writing to the same config file.

I'm getting "gateway start blocked" inside a CI/CD pipeline

Pass --allow-unconfigured in CI since there is no persistent config. Or set the OPENCLAW_GATEWAY_MODE=local environment variable in your pipeline definition. Either approach avoids the interactive setup.

Tired of debugging gateway configuration? ClawTank gives you a fully configured OpenClaw instance — deployed in under a minute, no terminal required.