OpenClaw Error 1006 and 1008: WebSocket Connection Fix Guide

What Are WebSocket Close Codes 1006 and 1008?

WebSocket close codes are standardized numbers that indicate why a connection was closed. They are defined in RFC 6455 and used by every WebSocket implementation. When OpenClaw's gateway connection drops, the close code tells you what happened:

• 1006 — Abnormal Closure: The connection was dropped without a proper WebSocket close handshake. Something outside the WebSocket protocol interrupted the connection — a network drop, a proxy timeout, a server crash, or a VPN disconnection. This is the most common error code because it covers all "something went wrong with the network" scenarios.
• 1008 — Policy Violation: The server intentionally closed the connection because the client violated a policy. In OpenClaw, this means the gateway rejected the connection for a specific reason — bad token, payload too large, rate limit exceeded, or an unsupported message format.

The key difference: 1006 means "the connection was interrupted" (usually a network issue), while 1008 means "the server rejected your connection" (usually a configuration issue).

What Causes Error 1006 in OpenClaw?

Error 1006 is the most common WebSocket error in OpenClaw. The causes, from most to least common:

1. VPN/Tailscale idle timeout

If you access OpenClaw through Tailscale, WireGuard, or another VPN, the tunnel's relay servers have idle timeouts. When the WebSocket connection is idle (no messages being sent), the relay drops the connection after the timeout period. Tailscale's DERP relay servers typically timeout after 60 seconds of inactivity.

2. Reverse proxy timeout

Nginx, Apache, and other reverse proxies have configurable read timeout values. The default in Nginx is 60 seconds (proxy_read_timeout 60). If the WebSocket connection is idle for longer than this timeout, Nginx closes it. Since AI agent conversations can have long pauses between messages, this timeout is frequently hit.

3. Network instability

Unstable WiFi, mobile data switching, ISP routing changes, or packet loss can all interrupt WebSocket connections. Unlike HTTP requests (which are short-lived), WebSocket connections are long-lived and vulnerable to any network disruption.

4. Server restart or OOM kill

If the OpenClaw container restarts (due to an update, crash, or OOM kill), all active WebSocket connections are dropped with a 1006 code. Check docker compose logs and dmesg | grep oom if you suspect this.

5. Cloud provider network maintenance

Some VPS providers (especially budget ones) perform network maintenance that briefly interrupts connections. This is rare but can cause intermittent 1006 errors on a schedule.

What Causes Error 1008 in OpenClaw?

Error 1008 is less common but more specific. The gateway rejected the connection for a policy reason:

1. Gateway token mismatch

The OPENCLAW_GATEWAY_TOKEN provided by the client doesn't match the server. This is the most common cause of 1008. It happens after token rotation, after the 3.22 upgrade (legacy variable names), or when multiple .env files have different token values.

2. Message payload too large

WebSocket messages have a maximum size limit. If a conversation includes very long messages, large base64-encoded files, or extensive tool call results, the payload might exceed the limit. The default limit in OpenClaw is 16MB per message.

3. Rate limiting

If a client sends too many messages in a short period (typically automated scripts or misbehaving clients), the gateway may close the connection with 1008 to protect itself from abuse.

4. Protocol version mismatch

Older versions of the OpenClaw web UI or API client might use a WebSocket protocol version that the current gateway doesn't support. Update your client to match your server version.

How Do You Fix Error 1006?

Fix 1: Enable WebSocket keepalive pings

The most effective fix for idle timeout issues. Add to your .env file:

# Send a ping every 30 seconds to keep the connection alive
OPENCLAW_WS_PING_INTERVAL=30000

This tells OpenClaw to send WebSocket ping frames every 30 seconds, preventing any intermediate network device from considering the connection idle. This fixes Tailscale, proxy, and most VPN timeout issues in one setting.

Fix 2: Increase reverse proxy timeout

For Nginx, increase the read timeout:

location /ws {
    proxy_pass http://localhost:18789;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;  # 24 hours
    proxy_send_timeout 86400;
}

Setting the timeout to 86400 seconds (24 hours) effectively means "don't timeout." Combined with keepalive pings, this eliminates proxy-related 1006 errors.

Fix 3: Stabilize your network

If you're getting 1006 errors on a specific network (WiFi, mobile), the issue might be network quality. Use a wired connection for the server, and consider the auto-reconnect behavior (see below) as an acceptable solution for flaky client networks.

Fix 4: Check for OOM kills

# Check for recent OOM kills
dmesg | grep -i "oom\|killed process" | tail -10

# If OpenClaw is being OOM killed, increase the memory limit
# or add swap space:
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

How Do You Fix Error 1008?

Fix 1: Verify and align the gateway token

# Check the token
grep OPENCLAW_GATEWAY_TOKEN .env

# Make sure:
# 1. The variable name is OPENCLAW_GATEWAY_TOKEN (not CLAWDBOT_ or MOLTBOT_)
# 2. The value matches what your client is using
# 3. There are no trailing spaces or newlines in the value

# Regenerate if needed:
NEW_TOKEN=$(openssl rand -hex 32)
echo "New token: $NEW_TOKEN"
# Update .env, then restart

Fix 2: Increase the message payload limit

# In your .env file
OPENCLAW_WS_MAX_PAYLOAD=67108864  # 64MB

Only increase this if you're sending large files or very long conversations through the WebSocket. The default 16MB is sufficient for most use cases.

Fix 3: Check for rate limiting

If you're running automated scripts that send messages rapidly, add delays between messages or increase the rate limit:

# In your .env file
OPENCLAW_WS_RATE_LIMIT=100  # messages per minute per client

Fix 4: Update your client

Make sure your OpenClaw web UI version matches your server version. Clear browser cache, or access the dashboard in an incognito window to rule out cached old code.

Does OpenClaw Automatically Reconnect?

Yes. The OpenClaw web UI includes automatic WebSocket reconnection with exponential backoff:

1. First reconnect attempt: 1 second after disconnection
2. Second attempt: 2 seconds
3. Third attempt: 4 seconds
4. Fourth attempt: 8 seconds
5. Maximum backoff: 30 seconds between attempts
6. Reconnection continues indefinitely until successful

For occasional 1006 errors caused by network blips, the auto-reconnect is often sufficient — the connection drops and restores within a few seconds without any user action.

However, if you're seeing frequent reconnections (visible as brief "Disconnected" / "Connected" flashes in the UI), you should fix the root cause. Constant reconnection adds latency to every interaction and can cause messages to be lost during the brief disconnect window.

API clients and custom integrations need to implement their own reconnection logic. The OpenClaw gateway does not queue messages during disconnection — messages sent while the client is disconnected are lost. Build your client with reconnection and message acknowledgment to handle this gracefully.