Device Identity Required + Pairing Required

There are two related but distinct 1008 errors involving device identity and pairing. They have different root causes and different fixes. Read your exact error message to identify which one you have.

# 1) Open the Dashboard from localhost/HTTPS secure context
# 2) If you also see pairing errors, approve pending requests:
openclaw devices list
openclaw devices approve <request-id>

# For Docker / LAN device — approve pending request
openclaw devices list
openclaw devices approve <request-id>

Which Error Do You Have?

Fix A: Device Identity Required

This error appears when the client cannot establish device identity, most often because the dashboard is opened in a non-secure context.

Method 1: Secure Context (Recommended)

Method 2: Approve Pairing Requests (if present)

# List pending devices
openclaw devices list

# Approve a specific device
openclaw devices approve <request-id>

# Approve all pending devices (use with care)
openclaw devices approve --all

Fix B: Pairing Required

This is a secondary device pairing error. The connecting device — usually a Docker container, a second machine on the LAN, or a sub-agent — has not been granted access.

Standard Pairing Flow

# On the Gateway host
openclaw devices list
openclaw devices approve <request-id>

Docker-Specific Pairing

Docker containers get a new device ID on every redeploy. If you see pairing required after a docker compose up, the container is a new device.

# Option 1: Use a persistent device ID via env variable
# docker-compose.yml
environment:
  - OPENCLAW_DEVICE_ID=my-docker-agent-prod

# Option 2: Mount device identity file
volumes:
  - ./openclaw-device:/app/.openclaw/device

# Option 3: Auto-approve all in trusted environments (dev only)
openclaw devices approve --all

Sub-Agent Pairing (1008)

Sub-agents spawned by OpenClaw tasks also need to authenticate with the Gateway. If a sub-agent triggers pairing required, it's because it inherited a session that isn't registered.

# In your OpenClaw config, allow sub-agents to inherit the parent session
{
  "gateway": {
    "session": {
      "inheritParentDevice": true
    }
  }
}

For a full sub-agent pairing walkthrough, see the Sub-Agent Pairing (1008) guide.

Decision Flowchart