Fix: WebSocket 1006 and 1008 Errors in OpenClaw Gateway

Getting constant 1006 or 1008 errors in your OpenClaw Gateway? You're not alone—these are the most common WebSocket troubleshooting questions in the Discord #help channel. Here's a complete guide to diagnosing and fixing them.

What These Codes Mean

Both 1006 and 1008 are WebSocket close codes, not OpenClaw-specific errors:

• 1006 (Abnormal Closure): The connection closed without a proper close frame—usually means the gateway crashed or never started listening
• 1008 (Policy Violation): The gateway is rejecting your connection—often due to device pairing or authentication issues

Key insight: 1008 is usually not a crash—it's the gateway refusing the connection on purpose.

Quick Diagnosis

First, determine what is actually happening:

openclaw gateway status

Look for these clues in the output:

• Runtime: running but Gateway port 18789 is not listening → Gateway crashed or never started
• RPC probe: failed with 1006 → Same as above
• disconnected (1008): pairing required → Device pairing issue (most common!)

The 4 Most Common Causes (and Fixes)

1. Device Pairing Required (Most Common)

After upgrades, new browser profiles, or clearing site data, the Control UI needs to be re-paired:

# On the gateway host
openclaw devices list
openclaw devices approve --latest

Then refresh your dashboard tab. See the Control UI docs for details.

2. Insecure HTTP Access

If you're connecting remotely via http://<lan-ip>:18789 instead of HTTPS, some setups get blocked due to secure-context constraints.

Recommended solutions:

• Local access: Use http://127.0.0.1:18789/ (always works)
• Remote access: Use Tailscale serve:

  openclaw gateway --tailscale serve

  Then open the https URL it provides.

3. Wrong Handshake (Custom Gateway URL)

If you're pointing a client at HTTP instead of WS, you'll get 1008. The gateway expects a WebSocket client that sends a proper connect frame first.

See the FAQ entry on invalid handshake.

4. Gateway Crash Loop

If openclaw gateway status shows the process is "running" but the port isn't listening, the gateway is likely crashing on startup. Check the logs:

tail -n 200 ~/.openclaw/logs/gateway.err.log
tail -n 200 ~/.openclaw/logs/gateway.log
openclaw logs --follow

Common crash causes:

• Port already in use by another process
• Node.js version incompatibility
• Corrupted config file
• Missing dependencies after upgrade

Full Triage Commands

When asking for help in Discord, paste the output of these:

openclaw --version
openclaw gateway status
openclaw status --all

Plus where you're seeing the error (browser UI toast? console? gateway logs?) and the exact log lines.

Still Stuck?

Try the nuclear option:

openclaw doctor --fix
openclaw gateway stop
openclaw gateway start

If that doesn't work, head to the #help forum with your diagnostic output—the community is incredibly helpful.

This guide was compiled from the OpenClaw Discord #help channel. Thanks to the community members who shared their troubleshooting experiences!