Every OpenClaw Gateway Error — Complete Fix Guide [2026]

This guide covers every gateway error you will encounter in OpenClaw. Each section is self-contained: find your error message, copy the fix, and move on. If you want deeper context on a specific error, follow the links to our dedicated guides.

Table of Contents

• Gateway Start Blocked
• Gateway Did Not Become Ready
• Device Token Mismatch
• Connect Failed
• Send Failed: Gateway Not Connected
• Disconnected (4008)
• Access Not Configured
• Pairing Required
• Docker Gateway Troubleshooting
• The Nuclear Option: Full Reset
• Prevention Checklist
• Skip Gateway Configuration Entirely

Gateway Start Blocked

The most common OpenClaw gateway error. The gateway refuses to start because gateway.mode is not set.

Error Messages

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

Quick Fix

openclaw config set gateway.mode local
openclaw restart

That is the entire fix for most people. The gateway now starts.

What Is gateway.mode?

This setting controls which network interfaces the gateway listens on. OpenClaw refuses to pick a default because each mode has different security implications.

Pick local unless you have a specific reason to pick something else. Even behind a reverse proxy, local is correct because the proxy connects via localhost.

Docker Users

Set the mode via environment variable:

docker run -e OPENCLAW_GATEWAY_MODE=local openclaw-stack

Or in docker-compose.yml:

environment:
  - OPENCLAW_GATEWAY_MODE=local

For the full deep dive, see our dedicated guide: Fix "Gateway Start Blocked" in OpenClaw.

Gateway Did Not Become Ready

The gateway process started but never finished initialization.

Error Messages

gateway did not become ready

Error: gateway did not become ready within 60s

gateway startup timeout — did not become ready

[entrypoint] gateway did not become ready in time

timeout waiting for gateway: did not become ready

FAIL: gateway health check failed — not ready

Cause 1: Port Conflict

Another process is using the gateway port (default 3001).

Diagnose:

lsof -i :3001

Fix:

# Kill the conflicting process, or switch ports
openclaw config set gateway.port 3002
openclaw restart

Cause 2: Permission Issues

The OpenClaw data directory or config files are not writable.

Diagnose:

ls -la ~/.openclaw/

Fix:

sudo chown -R $(whoami) ~/.openclaw/
openclaw restart

Cause 3: Config Corruption

A broken openclaw.json or config.yaml prevents initialization.

Fix:

openclaw config validate

If validation fails:

openclaw doctor --fix
openclaw restart

If doctor --fix cannot repair the config:

openclaw config reset
openclaw setup

Cause 4: Slow Startup (Docker)

In Docker containers the gateway takes approximately 40 seconds to fully initialize. The log line [entrypoint] Starting OpenClaw gateway does not mean the gateway is ready. You must wait for this line:

[gateway] listening on :3001

Only after that line appears is the gateway accepting connections. If you are scripting or polling, wait for this string before sending requests.

Check startup progress:

openclaw logs --follow

Cause 5: Insufficient Memory

The gateway needs at least 256MB of available RAM.

Check:

free -h       # Linux
vm_stat       # macOS

If the system is memory-constrained, stop other processes or increase the VM/container memory limit.

Cause 6: Stale PID File

A previous crash left a PID file that blocks a clean start.

Fix:

rm ~/.openclaw/gateway.pid
openclaw restart

Device Token Mismatch

The token stored on your device (browser, Telegram bot, mobile app) no longer matches what the gateway expects.

Error Messages

device token mismatch

connect failed: device token mismatch

disconnected (4008): connect failed — device token mismatch

openclaw gateway device token mismatch

Error: device token mismatch — please re-pair this device

WebSocket connection failed: device token mismatch

connect failed (4008): device identity rejected

Quick Fix

openclaw doctor --fix && openclaw restart

This regenerates matching tokens and restarts the gateway. Works for most cases.

Manual Fix: Remove and Re-Approve

If doctor --fix does not resolve it:

# List all devices
openclaw devices list

# Remove the broken device
openclaw devices remove DEVICE_ID

# Restart the gateway
openclaw restart

Then reconnect from your browser or Telegram. A new pairing request will appear:

openclaw devices approve NEW_DEVICE_ID

Prevention: Pin Your Gateway Token

OpenClaw regenerates the gateway token on every restart unless you pin it. Pin it once and token mismatches stop:

openclaw config set gateway.token "your-stable-token-here"

Or via environment variable (recommended for Docker):

docker run -e OPENCLAW_GATEWAY_TOKEN=your-stable-token-here openclaw-stack

For the full walkthrough including Docker Compose configuration: Fix "Device Token Mismatch" in OpenClaw.

Connect Failed

Your client can see the gateway address but cannot establish a connection.

Error Messages

connection error

gateway connect failed

Error: connect ECONNREFUSED 127.0.0.1:3001

connect failed: connection refused

WebSocket connection to 'ws://localhost:3001' failed

openclaw connection error: gateway unreachable

failed to connect to gateway at localhost:3001

Fix 1: Gateway Not Running

openclaw status

If it shows gateway: stopped:

openclaw gateway start

Or simply:

openclaw restart

Fix 2: Wrong Host or Port

Verify your configuration matches where the gateway actually listens:

openclaw config get gateway.host
openclaw config get gateway.port

Default is localhost:3001. If you changed these, make sure your client, reverse proxy, or Telegram webhook URL matches.

Fix 3: Firewall Blocking

Linux:

sudo ufw status
# If port 3001 is not allowed:
sudo ufw allow 3001

macOS:

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps

Fix 4: Reverse Proxy Misconfiguration

If you run behind Caddy, Nginx, or Traefik, the proxy might not be forwarding correctly. The most common mistake is forgetting to set trustedProxies:

openclaw config set gateway.trustedProxies '["127.0.0.1"]'
openclaw restart

For a complete reverse proxy setup, see our reverse proxy and trusted proxies guide.

Send Failed: Gateway Not Connected

You tried to send a message (via Telegram, API, browser) but the gateway connection was down at the time of sending.

Error Messages

send failed: gateway not connected

Error: send failed — gateway not connected

send failed: Error: gateway not connected

message delivery failed: gateway not connected

[telegram] send failed: gateway not connected

Error: cannot send — no active gateway connection

Cause 1: Gateway Crashed Mid-Session

The gateway was running when you connected but crashed afterward.

Fix:

openclaw restart

Check what caused the crash:

openclaw logs --tail 100

Look for panic, fatal, OOM, or killed in the output.

Cause 2: Network Interruption

The connection between your client and the gateway dropped. This is common on unstable networks or when a server changes IP.

Fix:

# Verify gateway is reachable
curl -v http://localhost:3001/health

# If unreachable, restart
openclaw restart

Cause 3: Gateway Stopped by Process Manager

PM2, systemd, or Docker restart policies might have stopped the gateway.

# PM2
pm2 status

# systemd
systemctl status openclaw

# Docker
docker ps -a | grep openclaw

Restart through your process manager and monitor the logs:

openclaw logs --follow

Wait for [gateway] listening on before retrying your message.

Disconnected (4008)

WebSocket error code 4008 indicates a protocol-level disconnect. This is usually tied to a device token mismatch or a connection timeout.

Error Messages

disconnected (4008): connect failed

disconnected (4008): connect failed — device token mismatch

disconnected (4008): device identity rejected

WebSocket closed with code 4008

connection closed: 4008

If Token-Related

This is a device token mismatch. Jump to the Device Token Mismatch section above.

If Timeout-Related

The WebSocket connection timed out due to inactivity or network issues.

Fix:

# Check network connectivity
ping your-openclaw-host
curl -v http://localhost:3001/health

# Restart the gateway
openclaw restart

If disconnections happen frequently, check for:

• Network instability between client and server
• Firewall or proxy timeouts dropping idle WebSocket connections (many proxies close idle connections after 60 seconds)
• Memory pressure causing the OOM killer to terminate the gateway process

For proxies that close idle connections, configure WebSocket ping/pong keep-alives in your proxy:

# Caddy example
reverse_proxy localhost:3001 {
    transport http {
        keepalive 30s
    }
}

Access Not Configured

The gateway is not set up to accept web or API connections.

Error Messages

OpenClaw: access not configured.

Error: web login provider is not available.

Device identity required.

TUI gateway disconnected — closed idle.

Quick Fix

openclaw config set gateway.mode local
openclaw restart

If you are accessing from a different machine:

openclaw config set gateway.mode remote
openclaw config set gateway.host "0.0.0.0"
openclaw restart

"Web Login Provider Is Not Available"

This means web authentication is disabled. Set the gateway mode:

openclaw config set gateway.mode local
openclaw restart

"TUI Gateway Disconnected — Closed Idle"

The terminal UI connection timed out. Restart and reopen:

openclaw restart
openclaw tui

For the full guide on access configuration: OpenClaw "Access Not Configured" Fix.

Pairing Required

Every new browser or device that connects to OpenClaw needs approval. This is a security feature, not an error.

Error Messages

pairing required

device not paired — approve this device to connect

Error: device identity required

new device detected — waiting for approval

[gateway] pairing request from device DEVICE_ID

Telegram pairing required — approve code XXXXXX

Fix: Approve the Device

Browser or API client:

openclaw devices list
openclaw devices approve DEVICE_ID

Telegram bot:

openclaw pairing approve telegram CODE

You can see the pairing code in the Telegram chat or in the gateway logs:

openclaw logs --tail 20

See All Devices

openclaw devices list

This shows every paired device, its status (connected, pending, disconnected), and its ID.

Remove a Device

If a device should no longer have access:

openclaw devices remove DEVICE_ID

Docker Gateway Troubleshooting

Docker adds an extra layer between your client and the gateway. These are the most common Docker-specific issues.

Gateway Starts But Is Unreachable From Outside the Container

The gateway is binding to 127.0.0.1 inside the container, which is not accessible from the host.

Fix:

docker exec -it YOUR_CONTAINER openclaw config set gateway.bind "0.0.0.0"
docker restart YOUR_CONTAINER

Port Not Mapped

The container port is not exposed to the host.

Check:

docker port YOUR_CONTAINER

Fix: Re-run with the correct port mapping:

docker run -p 3001:3001 openclaw-stack

Or in docker-compose.yml:

ports:
  - "3001:3001"

Container Restart Regenerates Gateway Token

Every time a Docker container restarts, the gateway generates a new token. This invalidates all paired devices.

Fix: Pin the token via environment variable:

services:
  openclaw:
    image: openclaw-stack
    environment:
      - OPENCLAW_GATEWAY_TOKEN=your-stable-token-here
    volumes:
      - openclaw-data:/app/data

volumes:
  openclaw-data:

Data Not Persisted Across Rebuilds

Without a volume mount, rebuilding the container wipes all config, device pairings, and memory.

Fix: Mount the data directory:

volumes:
  - openclaw-data:/app/data

Running openclaw doctor Inside Docker

docker exec -it YOUR_CONTAINER bash
openclaw doctor --fix
exit
docker restart YOUR_CONTAINER

Slow Startup in Docker

The gateway takes approximately 40 seconds to become ready inside Docker. Do not send requests until you see this line in the logs:

[gateway] listening on :3001

Monitor startup:

docker logs -f YOUR_CONTAINER

The Nuclear Option: Full Reset

When openclaw doctor --fix has not worked, device removal has not worked, config changes have not worked, and you need to start completely fresh.

Warning: This removes your configuration, paired devices, memory, and stored data. You will need to re-enter API keys, re-pair devices, and reconfigure integrations.

Native Install

# 1. Stop everything
openclaw gateway stop
pkill -f openclaw

# 2. Back up important data (optional)
cp ~/.openclaw/openclaw.json ~/openclaw-backup.json
cp -r ~/.openclaw/memory ~/openclaw-memory-backup

# 3. Remove the data directory
rm -rf ~/.openclaw

# 4. Reconfigure from scratch
openclaw setup

Docker

# 1. Stop and remove the container
docker stop YOUR_CONTAINER
docker rm YOUR_CONTAINER

# 2. Remove the data volume (WARNING: destroys all data)
docker volume rm openclaw-data

# 3. Start fresh
docker run -d \
  -p 3001:3001 \
  -e OPENCLAW_GATEWAY_MODE=local \
  -e OPENCLAW_GATEWAY_TOKEN=your-stable-token \
  -v openclaw-data:/app/data \
  openclaw-stack

After the reset, run openclaw setup or set your configuration via environment variables, then approve your devices again.

For a complete walkthrough: OpenClaw Factory Reset Guide.

Prevention Checklist

Stop gateway errors before they happen.

• Pin your gateway token. Set OPENCLAW_GATEWAY_TOKEN as an environment variable or run openclaw config set gateway.token "your-stable-token". This prevents token regeneration on restart and eliminates device token mismatch errors.

• Set gateway.mode explicitly. Run openclaw config set gateway.mode local once and you will never see "gateway start blocked" again.

• Persist your data directory. For Docker, mount a volume at /app/data. Without this, every container rebuild wipes config, pairings, and memory.

• Run openclaw doctor after updates. Major version upgrades can change config formats or token structures. openclaw doctor --fix catches and repairs these automatically.

• Monitor with openclaw status. Add openclaw status to your healthcheck scripts or Docker HEALTHCHECK instruction. Catch problems before users report them.

• Keep one instance per machine. Running multiple OpenClaw instances on the same machine with the same data directory causes token collisions and intermittent errors.

• Configure WebSocket keep-alives. If you use a reverse proxy, set keep-alive intervals to prevent idle connection timeouts that cause disconnected (4008) errors.

• Clear browser cache after major changes. If you change your gateway URL, domain, or token, clear site data in every browser that connects to OpenClaw.

Skip Gateway Configuration Entirely

Every error in this guide comes down to the same thing: managing the gateway is manual work. You configure the mode, pin the token, map the ports, approve the devices, fix the mismatches, and restart when things break.

ClawTank handles all of it automatically. Gateway startup, health checks, token management, device pairing, TLS, and reconnection are managed for you. Deploy an OpenClaw instance in under a minute and connect from any device without touching a terminal.