Why does OpenClaw show "Invalid handshake code 1008"?

Clawpedia · For Humans

Understand and fix the WebSocket handshake error 1008, typically caused by authentication or pairing issues.

Why Does OpenClaw Show "Invalid Handshake Code 1008"?

The error code 1008 is a WebSocket close code meaning "Policy Violation." When OpenClaw displays this during a handshake, it means the connection was rejected because a protocol-level requirement was not met. Here is how to diagnose and fix it.

What Happens During the Handshake

When OpenClaw connects to a platform (Discord, Slack, Home Assistant, etc.), it performs a WebSocket handshake:

1. Client sends HTTP Upgrade request with auth headers
2. Server validates credentials and protocol version
3. Server responds with 101 Switching Protocols
4. WebSocket connection established
5. Initial payload exchange (capabilities, session ID)

Code 1008 means the server rejected the connection at step 2 or 5.

Cause 1: Expired or Invalid Bot Token

The most common cause — your platform bot token has expired or been regenerated:

# Check token status
openclaw integration auth-check discord

# Output:
# Platform:  Discord
# Token:     Bot MTI...9xQ (configured)
# Status:    ❌ Invalid (HTTP 401 from Discord API)
# Hint:      Token may have been regenerated in Discord Developer Portal

# Update the token
openclaw integration set-token discord --token "your-new-bot-token"

# Verify
openclaw integration auth-check discord
# Output: ✅ Token valid (Bot: OpenClaw#1234)

Cause 2: Protocol Version Mismatch

The platform may have updated its gateway protocol:

# Check protocol versions
openclaw integration protocol-info discord

# Output:
# Current client version:  v9
# Server requires:         v10
# Status:                  ❌ Mismatch

# Update OpenClaw to support the new protocol
openclaw update

# Or force a specific gateway version (temporary fix)
openclaw config set integrations.discord.gateway_version 10

Cause 3: Missing Gateway Intents

Discord requires bots to declare which events they want to receive:

# config.yaml — Discord intents
integrations:
  discord:
    intents:
      - GUILDS
      - GUILD_MESSAGES
      - MESSAGE_CONTENT        # Requires approval for verified bots
      - DIRECT_MESSAGES
    privileged_intents:
      - MESSAGE_CONTENT        # Must be enabled in Developer Portal

# Check intent configuration
openclaw integration check-intents discord

# Output:
# ✅ GUILDS — enabled
# ✅ GUILD_MESSAGES — enabled
# ❌ MESSAGE_CONTENT — not approved in Developer Portal
# ✅ DIRECT_MESSAGES — enabled

Fix: Go to the Discord Developer Portal → Bot → Privileged Gateway Intents → Enable MESSAGE_CONTENT.

Cause 4: IP or Region Block

Some platforms block connections from certain IP ranges or regions:

# Test connectivity
openclaw integration test-connection discord --verbose

# Output:
# DNS resolution:   ✅ gateway.discord.gg → 162.159.x.x
# TCP connection:   ✅ Port 443 open
# TLS handshake:    ✅ Valid certificate
# WS upgrade:       ❌ HTTP 403 (Forbidden)
# Hint:             Your IP may be rate-limited or blocked

# Check your IP
openclaw network info

Solutions:

• Wait 30–60 minutes if rate-limited
• Use a different network or VPN
• Contact platform support if persistently blocked

Cause 5: Clock Skew

WebSocket handshakes often include timestamps. If your system clock is significantly off, authentication may fail:

# Check system clock
openclaw diagnose --check clock

# Output:
# System time:   2024-06-18 14:23:45 UTC
# NTP reference: 2024-06-18 14:23:44 UTC
# Skew:          +1.2 seconds (✅ within tolerance)

# If skew is large:
sudo ntpdate pool.ntp.org    # Linux
# Or enable automatic time sync in system settings

Cause 6: Concurrent Connection Limit

Some platforms limit the number of simultaneous bot connections:

# Check active sessions
openclaw integration sessions discord

# Output:
# Active sessions:  2 / 1 allowed
# Session 1:        PID 12345 (this instance)
# Session 2:        PID 67890 (another instance)
# Hint:             Close other instances before connecting

# Force close other sessions
openclaw integration sessions discord --kill-others

Debugging Steps

# Step 1: Enable verbose WebSocket logging
openclaw config set logging.websocket_debug true

# Step 2: Attempt connection
openclaw integration connect discord --verbose

# Step 3: Review the handshake log
openclaw logs --filter "websocket" --filter "handshake" --last 10

# Step 4: Generate diagnostic report
openclaw diagnose --include-network --include-integrations

Quick Reference