sick geyser Feb 20, 2026, 2:11 PM

#

Why do i get this any time i want to spawn a sub agent?

gateway closed (1008): pairing required
Gateway target: ws://127.0.0.1:18789
Source: local loopback
Config: /home/zso/.openclaw/openclaw.json
Bind: loopback
Ezt írja ki minden sessions_spawn próbálkozásnál. A 1008 kód WebSocket close code, a "pairing required" pedig az auth layer válasza.

dense coralBOT Feb 20, 2026, 2:11 PM

#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

civic sparrow Feb 20, 2026, 2:17 PM

#

hey zso — we just spent half a day debugging this exact error, here's what we found:

The error is NOT about subagent permissions. It's a device auth issue — your CLI device is missing the operator.write scope after an OpenClaw 2.19 upgrade.

Quick diagnosis:
openclaw devices list --json

Check if your CLI device (clientId: "cli") has operator.write in its scopes. If not, that's your problem.

Fix that worked for us:
bash

1. Stop + disable gateway (prevent auto-restart)

systemctl --user stop openclaw-gateway.service
systemctl --user disable openclaw-gateway.service

2. Delete stale device identity

rm -rf ~/.openclaw/devices/
rm -rf ~/.openclaw/identity/

3. Reinstall + re-enable

openclaw gateway install --force
systemctl --user enable openclaw-gateway.service
systemctl --user daemon-reload
systemctl --user start openclaw-gateway.service

After restart, check for pending device pairing:
openclaw devices list --json

If you see a pending request, approve it:
openclaw devices approve <requestId>

Key insight: "pairing required" means scope upgrade was blocked, not that you need to re-pair from scratch. v2.19 changed auth to token mode — existing device identities lose operator.write in the process.

Hat tip to @krill and @nkosi for the original fix 🙏

weak larkBOT Feb 20, 2026, 2:17 PM

#

That error is Gateway device pairing, not a “sub-agent” problem.

When you (or the Control UI / CLI) connect to the Gateway WebSocket, the Gateway now requires the connecting device/browser/CLI instance to be approved once. If it’s not approved yet, the WS handshake is closed with:

1008 + “pairing required”

Fix (approve the device)

On the machine/profile where the Gateway is running:

openclaw devices list
openclaw devices approve <requestId>

Then retry the thing that triggers sessions_spawn.

Docs:

#

If it keeps happening every time

That usually means you’re effectively a “new device” each time (e.g. different --profile, different OPENCLAW_STATE_DIR, browser data being cleared/incognito, container without a persisted state dir). Pairing state is stored under:

~/.openclaw/devices/paired.json

If you run `devices list` and see nothing

Please paste:

openclaw --version
openclaw gateway status
openclaw devices list

…and mention how you’re using it when it fails (Control UI in browser vs CLI/TUI, same machine vs remote/tailnet).

#

Yep — this tracks with what we’ve seen: “gateway closed (1008): pairing required” is device auth/pairing, and after some upgrades you can end up with a stale CLI device token (often clientId: "cli") that no longer has the scopes the Gateway expects (e.g. operator.write). It then looks like “needs pairing again” even on loopback.

A safer/cleaner path than nuking dirs first:

1) Inspect what the Gateway thinks your CLI device has

openclaw devices list --json

Look for the entry that corresponds to your CLI device (often shows clientId: "cli"). Check its scopes for operator.write.

2) Fix by rotating the operator token (preferred if you can)

If you can identify the device id, rotate the operator role token with the right scopes:

openclaw devices rotate --device <deviceId> --role operator \

#

  --scope operator.read --scope operator.write

(Then retry the sub-agent spawn.)

3) If rotation isn’t possible / things are wedged

Instead of rm -rf, I’d move aside the identity/device state (reversible), restart, then approve the new pending request:

mv ~/.openclaw/devices  ~/.openclaw/devices.bak
mv ~/.openclaw/identity ~/.openclaw/identity.bak
openclaw gateway restart
openclaw devices list
openclaw devices approve <requestId>

#

Docs for the pairing/approve flow: https://docs.openclaw.ai/web/control-ui#device-pairing-first-connection and https://docs.openclaw.ai/cli/devices

If zso can paste the output of:

openclaw --version
openclaw devices list --json

…we can say immediately whether it’s “pending approval” vs “paired but missing operator.write”.

lilac knoll Feb 20, 2026, 4:19 PM

#

similar issue since last update, problem is I can't run the device list command becasue the cli isn't paired. I can see in the pending.json the request for cli to pair, but can't actually get it to pair

weak larkBOT Feb 20, 2026, 4:28 PM

#

Yeah, that’s the nasty part: an unpaired CLI can’t approve/inspect pairing, because openclaw devices list/approve calls device.pair.* and those require an already-authorized operator (scope operator.pairing). So if no operator device is currently trusted, you need to get the Gateway to auto-approve a local connect again.

The key detail: the Gateway only auto-approves when it considers the connection local. If it sees proxy headers / a non-local Host header, it will refuse to treat it as local and you’ll get “pairing required” forever.

1) Make sure you’re connecting as real localhost

On the gateway machine, try using the literal loopback URL (not a hostname, not your domain):

openclaw devices list --url ws://127.0.0.1:18789 --token <your gateway.auth.token>

If you were using something like ws://mybox.lan:18789 (even if it resolves to 127.0.0.1), the Gateway will treat it as remote and won’t silent/auto-approve.

2) If you’re behind a reverse proxy / Tailscale Serve / tunnel

Check openclaw logs --follow while you attempt to connect — the Gateway logs a very specific warning like:

“Proxy headers detected from untrusted address… configure gateway.trustedProxies…”

#

or “Loopback connection with non-local Host header…”

Fix: add your proxy IP to gateway.trustedProxies (common case: proxy runs on localhost):

{
  gateway: {
    trustedProxies: ["127.0.0.1"],
  },
}

Then restart the gateway and retry the command above.

(See the security doc section on reverse proxies: https://docs.openclaw.ai/gateway/security#reverse-proxy-configuration)

3) If the device/identity state is stale (post-upgrade weirdness)

#

Do a reversible “nuke” (move aside, don’t rm):

mv ~/.openclaw/devices  ~/.openclaw/devices.bak
mv ~/.openclaw/identity ~/.openclaw/identity.bak
systemctl --user restart openclaw-gateway.service

Then reconnect from ws://127.0.0.1:18789 so it can auto-approve locally.

If you paste:

openclaw --version
the few relevant lines from openclaw logs --follow right when it closes with “pairing required”

…I can tell you which branch you’re in (non-local Host vs proxy headers vs something else).

lilac knoll Feb 20, 2026, 4:36 PM

#

gateway via web is accessible and functioning with the token generated, it's the cli that is stuck

sick geyser Feb 20, 2026, 6:59 PM

#

i couldnt find the solution i deleted, reinstalled and now it can not start 😂

weak larkBOT Feb 20, 2026, 7:12 PM

#

If it won’t start after a wipe/reinstall, it’s almost always one of: wrong/missing config, gateway.mode not local, auth/bind guardrail, or service metadata pointing at the wrong profile/path.

First: what version are you on?

openclaw --version

Then paste the output of these (they’re the fastest to pinpoint the exact blocker):

openclaw gateway status
openclaw logs --follow
# in another terminal, or after it fails:
journalctl --user -u openclaw-gateway.service -n 200 --no-pager

#

Common quick fixes depending on what you see:

“Gateway start blocked: set gateway.mode=local”

openclaw config get gateway.mode
# if not local:
openclaw config set gateway.mode local
openclaw gateway restart

Service/profile mismatch after deleting stuff
Reinstall the service metadata from the current state dir:

openclaw gateway install --force
openclaw gateway restart

#Gateway closed (1008)