OpenClaw Error: Gateway Not Connected — How to Fix

What Is the OpenClaw Gateway?

The OpenClaw gateway is the WebSocket server that connects the web UI, API clients, and external services to the OpenClaw backend. It runs on port 18789 by default and handles real-time communication — sending messages to the agent, receiving responses, and streaming conversation updates.

When you open the OpenClaw dashboard in your browser, it establishes a WebSocket connection to the gateway. If that connection can't be established, you see the "Gateway Not Connected" error. The dashboard might load its static HTML, but it can't communicate with your agent.

The gateway is separate from the main OpenClaw HTTP API (which typically runs on port 3000 or 8080). You need both to be accessible for full functionality. The HTTP API handles REST requests (configuration, skill management), while the gateway handles real-time WebSocket connections (conversations, live monitoring).

What Causes the Gateway Not Connected Error?

There are four main causes, in order of likelihood:

1. Port 18789 is blocked

The most common cause. Your VPS provider's firewall (security group), your OS firewall (ufw, iptables, firewalld), or your network configuration is blocking incoming connections on port 18789. The gateway is running fine, but clients can't reach it.

2. Gateway token mismatch

The OPENCLAW_GATEWAY_TOKEN in your .env file must match between the OpenClaw backend and any connecting client. If you recently changed the token or regenerated your .env file, the UI might be using a cached old token. This also happens after the 3.22 upgrade if legacy CLAWDBOT_GATEWAY_TOKEN wasn't migrated properly.

3. Gateway process not running

The gateway container or process crashed, ran out of memory, or wasn't started. This can happen after a Docker update, a server reboot, or if the gateway isn't defined in your docker-compose.yml (some older configurations used a separate gateway service).

4. Reverse proxy not forwarding WebSocket

If you're running OpenClaw behind Nginx, Caddy, or another reverse proxy, the proxy needs to be configured to upgrade HTTP connections to WebSocket on the gateway path. A missing Upgrade header or incorrect proxy_pass directive will break the WebSocket connection.

How Do You Diagnose the Issue?

Run these checks in order to identify the cause:

Check 1: Is the gateway process running?

# List all OpenClaw containers
docker compose ps

# Look for the gateway service — it should show "Up"
# If it's not listed or shows "Exited", that's the problem

Check 2: Can you reach the gateway locally?

# Test from the server itself
curl -s http://localhost:18789/health

# Expected response: {"status":"ok"}
# If connection refused: gateway isn't running or wrong port
# If no response: gateway is hung

Check 3: Is the port open externally?

# From your local machine (replace with your server IP)
curl -s http://YOUR_SERVER_IP:18789/health

# If this fails but Check 2 passed, it's a firewall issue

Check 4: Check the gateway logs

docker compose logs --tail 50 gateway

# Or if gateway is part of the main container:
docker compose logs --tail 50 openclaw | grep -i gateway

Check 5: Verify the token

# Check your .env file
grep GATEWAY_TOKEN .env

# Make sure there's only one GATEWAY_TOKEN variable
# and it uses the OPENCLAW_ prefix (not CLAWDBOT_ or MOLTBOT_)

How Do You Fix a Blocked Port?

Open port 18789 in every layer of your network stack:

Ubuntu/Debian (ufw):

sudo ufw allow 18789/tcp
sudo ufw reload

CentOS/RHEL (firewalld):

sudo firewall-cmd --permanent --add-port=18789/tcp
sudo firewall-cmd --reload

Oracle Cloud (security list):

Go to VCN → Security Lists → Default → Add Ingress Rule. Set source CIDR to 0.0.0.0/0, protocol TCP, destination port 18789. Oracle Cloud has both a cloud firewall and an OS firewall — you need to open both.

AWS (security group):

Go to EC2 → Security Groups → your instance's group → Inbound Rules → Add Rule. Type: Custom TCP, Port: 18789, Source: 0.0.0.0/0 (or restrict to your IP).

Hetzner / Contabo / Vultr:

Most of these providers don't have a cloud-level firewall by default — the OS firewall is the only layer. Use the ufw commands above.

How Do You Fix a Token Mismatch?

Verify and align your gateway token:

# Check what token is configured
grep OPENCLAW_GATEWAY_TOKEN .env

# If you see CLAWDBOT_GATEWAY_TOKEN or MOLTBOT_GATEWAY_TOKEN,
# rename it to OPENCLAW_GATEWAY_TOKEN (3.22+ requirement)

# If the token looks wrong or you want to regenerate:
# Generate a new random token
openssl rand -hex 32

# Update .env with the new token
# Then restart OpenClaw
docker compose down && docker compose up -d

After changing the token, clear your browser cache or open the dashboard in an incognito window. The old token might be cached in the browser's WebSocket connection state.

If you're using the OpenClaw mobile app or external API clients, update the gateway token there too. Every client connecting to the gateway must use the same token.

How Do You Fix a Reverse Proxy Issue?

If you're running OpenClaw behind a reverse proxy, the proxy must support WebSocket upgrade for the gateway. Here are the correct configurations:

Nginx:

location /ws {
    proxy_pass http://localhost:18789;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 86400;
}

The critical lines are proxy_http_version 1.1, Upgrade $http_upgrade, and Connection "upgrade". Without these, Nginx will treat the WebSocket connection as a regular HTTP request and fail.

Caddy:

your-domain.com {
    reverse_proxy /ws localhost:18789
    reverse_proxy localhost:3000
}

Caddy handles WebSocket upgrade automatically — no special configuration needed. If it's not working with Caddy, the issue is likely upstream (port, token, or process).

Traefik:

Traefik also handles WebSocket upgrade automatically. Make sure the gateway service has the correct labels in your docker-compose.yml for Traefik routing.

After updating your reverse proxy configuration, reload it:

# Nginx
sudo nginx -t && sudo systemctl reload nginx

# Caddy
sudo systemctl reload caddy

Test the WebSocket connection directly in your browser's developer tools (Network tab → WS tab) to see the exact error when the connection fails. Common proxy errors include 502 Bad Gateway (proxy can't reach backend) and 400 Bad Request (missing upgrade headers).