OpenClaw 1008 WebSocket Error Explained (Causes, Fixes, Prevention)

If your OpenClaw dashboard or Control UI shows an error like:

disconnected (1008): pairing required
disconnected (1008): unauthorized: gateway token missing
disconnected (1008): control ui requires HTTPS or localhost (secure context)
gateway closed (1008)

You are dealing with a WebSocket policy rejection.

OpenClaw uses the gateway WebSocket connection to power the dashboard. When the gateway decides the browser session is not authorized, not paired, or not running in a secure context, it closes the socket with code 1008.

This post explains exactly what the error means, why it happens, and the safest way to fix it without weakening your setup.

If you are new to OpenClaw, start here first:
OpenClaw Beginner’s Guide

Video walkthrough

What does WebSocket error 1008 mean in OpenClaw?

1008 is a WebSocket close code that typically means policy violation.

In OpenClaw terms, it usually means:

The gateway is reachable
The dashboard tried to connect
The gateway rejected the connection for security reasons

This is why 1008 errors are common after:

A fresh install
An update
Moving to a VPS
Running behind a proxy
Opening the dashboard from a different device/network
Switching tokens or auth modes

The 3 most common OpenClaw 1008 messages

1) disconnected (1008): pairing required

This is the most common one.

It means the gateway received your connection attempt but requires you to approve the device identity (your browser or node host) before allowing the WebSocket session.

Fix guide:
Gateway Connect Pairing Required

2) disconnected (1008): unauthorized: gateway token missing

This means the dashboard is not providing the expected token, or the token values in your configuration do not match what the gateway expects.

Common causes:

You opened the dashboard URL without a token
Token variables changed after an update
You are using a reverse proxy that strips query params or headers
You have mismatched config values (auth token vs remote token)

3) disconnected (1008): control ui requires HTTPS or localhost (secure context)

This happens when you open the dashboard over plain HTTP on a remote domain/IP.

Some parts of browser-based device identity and auth flows require a secure context (HTTPS) or localhost access.

Common causes:

Opening the dashboard from http://your-vps-ip:port
Running behind a reverse proxy without HTTPS
Using a remote hostname without TLS

This is especially common on VPS setups.

VPS guide:
Best VPS for OpenClaw

Quick diagnosis checklist (find your root cause fast)

Before changing anything, answer these:

Are you running OpenClaw on a VPS or locally?
Are you accessing the dashboard from the same machine or a different device?
Are you using Docker?
Are you behind a reverse proxy (Nginx, Cloudflare, Railway, tunnel)?
What is the exact 1008 message?

If you can answer those, you can usually fix this in minutes.

Fix path that works for most users

Step 1: Confirm your gateway is actually running

If the gateway is down, the dashboard won’t connect at all.

If you are still installing OpenClaw, use:
How to Install OpenClaw

Step 2: Fix “pairing required” first

If your message includes “pairing required”, follow the official pairing flow:

List pending devices
Approve the pending device request
Refresh the dashboard

Full walkthrough:
Gateway Connect Pairing Required

This resolves the majority of 1008 errors.

Step 3: Fix token alignment if you see “token missing” or “unauthorized”

If your dashboard says token missing, do this:

Confirm you are using the correct dashboard URL that includes token support (or token input via UI)
Confirm your token values are consistent across gateway settings

Common pattern:

gateway.auth.token must match what the dashboard provides
If you have a gateway.remote.token value in your config, it should match the auth token you intend to use

After updating token values:

Restart the gateway
Refresh the dashboard (hard refresh is often needed)
Re-pair devices if prompted

Step 4: Fix secure context errors (HTTPS or localhost)

If you see “control ui requires HTTPS or localhost” you have three practical options:

Option A: Access from localhost on the server

SSH into your VPS
Use an SSH tunnel to forward the dashboard port to your local machine
Open the dashboard as http://127.0.0.1:<port> on your computer

Option B: Put the dashboard behind HTTPS

Use a reverse proxy with TLS
Use a proper certificate
Ensure WebSocket upgrade headers are supported

Option C: Use a managed host/deployer (fastest for non-technical users)
If you do not want to manage TLS and proxy edge cases, use a managed deployer instead.

Deployer comparison:
Best OpenClaw Deployer
How to decide:
How to Choose the Right OpenClaw Deployer

Why this happens more on VPS and proxies

OpenClaw’s dashboard is not just a static page. It requires:

WebSocket upgrades
Device identity checks
Token or pairing approval
Consistent origin behavior

VPS and proxies often introduce problems like:

HTTP instead of HTTPS
WebSocket headers not forwarded
Origin mismatches
NAT makes the gateway think the dashboard is “remote”
Query params stripped by routing layers

That’s why stable infrastructure matters.

Hosting strategy:
Best OpenClaw Hosting (Managed vs DIY Compared)

How to prevent 1008 errors from coming back

Once you fix it, prevention is mostly operational discipline:

Keep your gateway access predictable

Avoid switching between multiple dashboard URLs
Avoid mixing direct IP access and domain access
Prefer one stable access method

Avoid insecure remote dashboard access

Use HTTPS if remote
Or use SSH tunnel + localhost

Keep versions aligned

If you update OpenClaw, update all related components consistently. Inconsistent versions can trigger pairing re-requests and token confusion.

Monitor your system like production

If you are running multiple agents or hosting OpenClaw for real workflows, you need visibility.

Command centre overview:
What Is an OpenClaw Command Centre?

Reduce runaway retries (saves tokens)

When OpenClaw repeatedly retries due to disconnects, token spend can spike.

Cost control guide:
How to Reduce OpenClaw Token Usage by 40%
AI API selection:
Best AI API for OpenClaw

Quick FAQ

Is 1008 a bug?

Sometimes it can be triggered by environment quirks, but most of the time it is the gateway enforcing security requirements.

Why did it happen after it was working?

Usually one of these:

Update changed auth behavior
Token got reset or mismatched
Browser device identity changed
You changed how you access the dashboard (IP vs domain vs proxy)
Proxy removed WebSocket headers or HTTPS

What is the fastest fix?

If your error says pairing required, follow the pairing guide and approve the pending device. That resolves the majority of cases.

Guide:
Gateway Connect Pairing Required

Final checklist

If you want the shortest path:

If it says pairing required, approve the device and refresh
If it says token missing, align token configuration and restart gateway
If it says requires HTTPS or localhost, use SSH tunnel or add HTTPS
If you keep hitting proxy issues, consider a deployer/managed host

Once you treat OpenClaw like a production system (stable hosting, secure access, monitoring), 1008 errors become rare.