Complete Guide to Fixing OpenClaw "Device Identity Required" Error

Prerequisites

Before you begin, make sure you have:

• Latest version of OpenClaw installed and running (check with openclaw --version)
• Gateway is active (usually started via openclaw start, systemd, or Docker)
• Command-line access to run openclaw commands
• Modern browser (Chrome/Edge/Firefox recommended)
• Basic understanding of WebSocket close code 1008, secure contexts, and device fingerprinting

Error symptom: Control UI shows "device identity required" or WebSocket fails with code 1008 in logs.

Step 1: Understand the Error Cause

OpenClaw Control UI uses two-factor authentication:

1. Token authentication (via ?token=... in URL)
2. Device identity authentication (browser-generated signature + gateway approval)

The gateway disconnects with code 1008 when a valid device identity cannot be verified. Common triggers:

• Accessing via plain http:// instead of https:// or localhost
• New browser, incognito mode, or cleared site data
• Remote access without completed pairing
• Device request rejected or timed out

Step 2: Quick Access Using Token (Works in Most Cases Immediately)

Generate a fresh dashboard URL with token:

openclaw dashboard --no-open

Example output:

Control UI ready at:
http://127.0.0.1:18789/dashboard?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Copy and open the full URL in your browser.

• Local access (127.0.0.1 or localhost) usually bypasses some restrictions
• For remote servers, replace with real IP/domain and preferably use HTTPS

Step 3: Properly Pair the Device (Recommended Permanent Fix)

1. Open Control UI using the token URL from Step 2
2. In a new terminal, check pending device requests:

openclaw devices list

Example output:

ID          Status    Browser/OS            Requested
dev-7b9f2   pending   Chrome 128 / Windows   just now
...

3. Approve the device (copy the ID):

openclaw devices approve dev-7b9f2

4. Refresh the Control UI page — WebSocket should connect successfully.

Pro tip: Run devices list immediately after loading the UI to catch the fresh pairing request quickly.

Step 4: Temporarily Disable Device Identity Check (For Local/Dev Only)

Warning: For testing on localhost only — strongly not recommended in production.

Edit the config file (usually ~/.openclaw/config.json or via environment variables):

{
  "controlUi": {
    "allowInsecureAuth": true,
    "dangerouslyDisableDeviceAuth": true
  }
}

Restart the service:

openclaw restart
# or docker restart openclaw-gateway

Refresh the page — device identity validation will be skipped.

Note: In newer versions this setting may still require a secure context (https or localhost).

Step 5: Ensure Secure Context (Best Practice for Remote Access)

Modern browsers require a secure context for device fingerprint APIs:

• Use HTTPS (recommended: Caddy/Nginx reverse proxy + Let's Encrypt)
• Or access via localhost (can use SSH tunneling)

Quick SSH tunnel example:

ssh -L 18789:localhost:18789 user@your-server-ip

Then open http://localhost:18789/dashboard?token=... in your local browser.

Common Issues & Troubleshooting

• Still errors after approval → Clear browser site data (storage, cookies, IndexedDB) for that domain/port, then reopen with fresh token
• Re-pairing required on every refresh → Avoid incognito mode; token may have expired; keep one tab pinned
• Devices not visible in Docker → Ensure --network host or correct port mapping
• Remote IP always unauthorized → Make sure pairing request comes from the actual target browser (identity is browser + OS fingerprint)
• "nonce required" variant → Almost always caused by missing secure context
• Check detailed logs: openclaw logs --tail 200 | grep -i auth\|device\|websocket

Next Steps

• Install more skills via ClawHub to extend capabilities
• Set up Telegram / WhatsApp mobile control
• Configure auto-start with systemd or docker-compose
• Read the official security guide: https://docs.openclaw.ai/gateway/security
• Join the Discord community for latest tips: https://discord.gg/clawd

After following these steps, your OpenClaw Control UI should maintain a stable connection without repeatedly showing the "device identity required" error.