Fix OpenClaw 'disconnected (4008): connect failed'

By Linas Valiukas · April 13, 2026

You open your OpenClaw dashboard and see it: disconnected (4008): connect failed. Your agent is offline. Messages aren't going through. Scheduled tasks are piling up. This is the single most common OpenClaw error, and it has a straightforward fix - but the cause isn't always obvious.

What the 4008 error means

The 4008 is a WebSocket close code that means "device token mismatch." When your browser, phone, or paired device connects to OpenClaw, it presents a token. The gateway checks that token against what it has stored. If they don't match, you get 4008.

This usually happens after one of these events:

• You upgraded OpenClaw to a new version
• You rebuilt your Docker containers
• You restored from a backup
• The gateway restarted and invalidated existing sessions
• Your server ran out of memory and the gateway process crashed

The token that was valid before the event is now stale. The gateway doesn't recognize it anymore. That's the disconnect.

The fix (native install)

SSH into your server and run:

openclaw doctor --fix && openclaw restart

openclaw doctor checks for and repairs token mismatches, corrupted configs, and stale sessions. The --fix flag tells it to repair what it finds rather than just report. Then the restart picks up the clean state.

The fix (Docker install)

You need to run the same command inside the container:

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

If your container name is different, replace openclaw with whatever docker ps shows. Common names: openclaw-openclaw-1, openclaw_app, or whatever you set in docker-compose.yml.

The fix (browser-based connection)

If you're seeing 4008 in your browser's OpenClaw web interface:

1. Open your browser's developer tools (F12 or Ctrl+Shift+I)
2. Go to Application > Storage > Clear site data for your OpenClaw URL
3. Reload the page
4. Re-pair your device when prompted

This clears the stale token from your browser's storage and forces a fresh pairing handshake.

If it keeps coming back

A one-time 4008 after an upgrade is normal. If it keeps happening, something is crashing your gateway repeatedly. The usual suspects:

Not enough RAM. OpenClaw's gateway, core process, and any running cron jobs compete for memory. On a 2GB server, a few background tasks can push usage past the limit. The OS kills the gateway process, tokens get invalidated, and you see 4008 when it comes back up. Check with free -h or docker stats. If you're consistently above 80% memory usage, you need a bigger server or fewer concurrent tasks.

A crashing plugin. Some plugins - particularly third-party ones from ClawHub - can crash the gateway when they fail. The gateway goes down, reconnects, and your existing sessions are invalidated. Try disabling all non-core plugins, confirm the gateway stays stable for a few hours, then re-enable them one at a time to find the culprit. Multiple GitHub issues (#21519, #16305) document this pattern.

Firewall or port conflicts. The gateway uses WebSocket connections on ports 443 and 8443. If something else grabs port 18789 (the internal gateway port), or your firewall silently drops WebSocket upgrades, you'll get intermittent disconnects. Run ss -tlnp | grep 18789 to check if anything else is listening on that port.

GATEWAY_URL mismatch. If the GATEWAY_URL in your .env doesn't match your server's actual address - maybe your IP changed, or you're using a domain that doesn't resolve correctly - the gateway handshake fails before the token check even starts.

Related errors you might also see

The 4008 is part of a family of gateway connection errors. If you're troubleshooting one, you may also hit:

• "gateway not connected" - the WebSocket connection didn't establish at all. Same diagnostic steps, but also check if the gateway service is actually running (docker logs openclaw-gateway)
• "disconnected (1008): pairing required" - your device was never paired, or the pairing was revoked. Re-pair through the OpenClaw web UI
• "disconnected (1006)" - abnormal WebSocket closure, usually a crash. Check logs for what happened right before the disconnect

Our full troubleshooting guide covers these and other errors in detail.

Skip the debugging entirely

Every self-hoster hits 4008 eventually. It's part of the maintenance tax on running your own infrastructure. Gateway crashes, token invalidations, memory pressure, port conflicts - these don't go away. You fix one, and the next update brings a new variation.

With TryOpenClaw.ai, we manage the gateway layer, handle connection stability, and do automatic recovery. You never see a 4008 because we monitor and fix infrastructure issues before they reach your agent. That's what $39/month buys you - not just hosting, but never having to debug WebSocket close codes again.