Fix Sub-Agent "Pairing Required (1008)"

There are two distinct causes for this error in a sub-agent context: a scope upgrade block (the sub-agent needs operator.write but your device only has operator.read), or a vdev token invalidation (the config was edited while the gateway was running).

What the Error Looks Like

You'll see one of these in the gateway logs or Telegram/Discord when the sub-agent tries to connect:

The key clue is that the main session works normally — only the spawned sub-agent fails. If your primary connection also fails, see Pairing Required instead.

Cause A: Scope Upgrade Blocked

When a sub-agent spawns via sessions_spawn, it requests operator.write permissions. If your current device was only granted operator.read, the gateway logs a scope upgrade request and blocks the sub-agent.

Fix: Add operator.write Scope

openclaw gateway stop

Open your paired devices file:

cat ~/.openclaw/devices/paired.json

Find your device entry and add "operator.write" to its scopes array. It should look like:

{
  "devices": [
    {
      "id": "your-device-id",
      "scopes": ["operator.read", "operator.write"]
    }
  ]
}

openclaw gateway start

Cause B: vdev Token Invalidated (Hot Reload)

Sub-agents use an embedded virtual device (vdev) token to authenticate. This token is generated when the gateway starts and is embedded in the session context. If you edit openclaw.json directly while the gateway is running, the gateway performs a hot reload that invalidates the vdev token — the main session continues to work (it has a persistent connection) but any new sub-agent spawn will fail with a token mismatch.

Prevent This in the Future

Always stop the gateway before editing config files:

# Stop gateway first
openclaw gateway stop

# Edit your config
# ... make changes to openclaw.json ...

# Restart
openclaw gateway start

How Sub-Agent Auth Works

Still Stuck?

Or update to the latest version — scope upgrade handling has been improved in recent releases:

npm install -g openclaw@latest