#Diagnose OpenClaw Sub-agent Spawning & Pairing Failure

1 messages · Page 1 of 1 (latest)

errant willow
#

Context:
User is attempting to use sessions_spawn (runtime="subagent", mode="run") to delegate tasks. These attempts consistently fail with a gateway closed (1008): pairing required error.

Technical Environment:

  • OS: Windows 10

  • Gateway: Local loopback (127.0.0.1:18789)

  • Config: gateway.auth.mode = "token", gateway.controlUi.allowInsecureAuth = true

  • Logs Analysis:** The gateway logs explicitly show a security audit: device access upgrade requested. The reason is scope-upgrade. The sub-agent attempts to transition from operator.read to operator.admin (or operator.pairing), which the gateway rejects because the ephemeral sub-agent session lacks a paired identity/token.
    Observed Failure Pattern:

    sessions_spawn is called.
    Sub-agent attempts to initialize/use tools.
    Gateway intercepts the request for elevated scopes.
    Connection is terminated with Error 1008 (Pairing Required).

Problem Statement:
The current sub-agent orchestration model creates a "Catch-22": the sub-agents require slightly elevated permissions to perform standard automated tasks (like complex tool usage), but because they are ephemeral, they cannot be "paired" in a way that satisfies the gateway's security requirements for scope upgrades.

Objective:

Determine if there is a way to spawn sub-agents with pre-authorized scopes without manual pairing.
Identify if the operator.admin request is an unnecessary side-effect of the sub-agent's initialization or a requirement of the requested task.
Provide a configuration or workflow fix to allow seamless, secure, and automated sub-agent orchestration.
rich juniperBOT
oak egretBOT
#

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

rich juniperBOT
blissful brambleBOT
#

I’m digging into the actual auth/pairing code now, because this smells like a scope negotiation issue rather than a generic sessions_spawn failure.

#

I found the relevant code path. There’s an explicit comment in src/agents/subagent-spawn.ts about headless scope upgrades causing close(1008): pairing required, so I’m checking whether that fix is already in the version Kevin is running or if he’s hitting a pre-fix build.

#

First, can you paste openclaw --version?

I found the relevant code path, and this is very likely a real versioned bug plus pairing-state issue, not user error.

Short version:

  • sessions_spawn itself does not have a knob to grant pre-authorized scopes to the ephemeral child.
  • The thing being authorized is the local gateway backend device identity, not the spawned sub-agent session.
  • operator.admin is partly required for subagent lifecycle, because sessions.patch and sessions.delete are admin-only. The actual child agent run stays write-scoped.
  • gateway.controlUi.allowInsecureAuth is not the fix here. It does not bypass pairing.

The big clue is this fix landed in 2026.4.1-beta.1:

  • “pin admin-only subagent gateway calls to operator.admin ... so sessions_spawn no longer dies on loopback scope-upgrade pairing with close(1008) "pairing required"” (#59555)

So:

#
  1. If you’re older than 2026.4.1-beta.1, upgrade first.
  2. If you’re already on 2026.4.1-beta.1 or newer, your local backend device was probably already paired earlier with a narrower scope like operator.read, and now subagent spawn is hitting a real scope-upgrade denial.

What I’d run next:

openclaw --version
openclaw devices list

If you see a pending request for that local operator/backend device, approve it:

openclaw devices approve <requestId>

If it still keeps reusing a stale narrow pairing baseline, repair it by removing that device entry and reconnecting/restarting so it re-pairs cleanly:

#

…I can tell you pretty quickly whether this is “needs upgrade” or “needs pairing reset.”

errant willow
#

openclaw --version
OpenClaw 2026.4.14 (323493f)

I do see a pending operator request.
I could approve it, but what is the consequence? Why is this request needed in the first place and would approval impact security by any means?

Also, will future subagent spawns need those approvals again?

#

please respond

blissful brambleBOT
#

Yep, this is a real auth/pairing edge, not you.

The key bit is: the thing that needs approval is not the ephemeral sub-agent, it’s the local backend device identity that sessions_spawn uses to talk to the gateway.

So to your 3 questions:

  1. Can subagents be spawned with pre-authorized scopes?
    Not directly. There is no sessions_spawn flag that grants the child extra scopes. The durable auth unit is the paired device/backend client, not the spawned session.

  2. Is operator.admin unnecessary?
    Not entirely. In current code, subagent lifecycle uses admin-only gateway methods like:

    • sessions.patch
    • sessions.delete

    The actual child agent run is still write-scoped, but the spawn/cleanup path does need admin.

  3. What fixes it?

#

First, check:

openclaw --version

There was an explicit fix in 2026.4.1-beta.1 for:

sessions_spawn dying on loopback scope-upgrade pairing with close(1008) "pairing required"

So:

  • If you’re older than 2026.4.1-beta.1, upgrade first.
  • If you’re already on that or newer, the likely issue is that your local backend device was already paired earlier with a narrower baseline like operator.read, and now subagent spawn is hitting a real scope-upgrade denial.

Next commands I’d use:

# 
openclaw --version
openclaw devices list

If you see a pending device request, approve it:

openclaw devices approve <requestId>

If it keeps reusing a stale low-scope pairing, repair that device entry and re-pair:

openclaw devices remove <deviceId>
openclaw gateway restart
#

…I can narrow it down pretty fast to either “needs upgrade” or “needs pairing reset.”

errant willow
#

logs:
17:42:10 [gateway] security audit: device access upgrade requested reason=scope-upgrade device=a2db8970aba2b534c3ff841ad0f625450251c90e83de730f916a0d9aea153d60 ip=unknown-ip auth=token roleFrom=operator roleTo=operator scopesFrom=operator.read scopesTo=operator.admin,operator.approvals,operator.pairing,operator.read,operator.talk.secrets,operator.write client=cli conn=6faf72c8-34a2-4149-ae2b-3436fd1c83a0
17:42:10 [ws] closed before connect conn=6faf72c8-34a2-4149-ae2b-3436fd1c83a0 peer=127.0.0.1:50812->127.0.0.1:18789 remote=127.0.0.1 fwd=n/a origin=n/a host=127.0.0.1:18789 ua=n/a code=1008 reason=connect failed

openclaw --version
OpenClaw 2026.4.14 (323493f)

blissful brambleBOT
#

Nice, this narrows it down a lot.

That log says the failing principal is client=cli, not the spawned child:

  • scopesFrom=operator.read
  • scopesTo=operator.admin,operator.approvals,operator.pairing,operator.read,operator.talk.secrets,operator.write

That scopesTo set is basically the full CLI operator bundle. So this is not “the ephemeral sub-agent can’t be paired”. It’s:

your CLI device identity is already paired at operator.read, and now a CLI-backed flow used by sessions_spawn is trying to reconnect with the normal full operator scope set, which the gateway treats as a scope-upgrade and rejects.

Since you’re on 2026.4.14, this is not the old pre-2026.4.1-beta.1 subagent bug anymore. It’s a stale/narrow paired-device baseline.

What to do

First try:

# 
openclaw devices list --json

Look for a pending request for device:

a2db8970aba2b534c3ff841ad0f625450251c90e83de730f916a0d9aea153d60

Then approve that request:

openclaw devices approve <requestId>

Important: devices list / devices approve have a local loopback fallback, so they should still work even when normal gateway auth is stuck in this pairing-required state.

#

If it keeps looping

Then repair the paired CLI device entry itself:

openclaw devices remove a2db8970aba2b534c3ff841ad0f625450251c90e83de730f916a0d9aea153d60
openclaw gateway restart
openclaw devices list --json
openclaw devices approve <newRequestId>

What will not help

  • gateway.controlUi.allowInsecureAuth, unrelated here
  • sessions_spawn params, there is no per-spawn “pre-authorize scopes” flag
  • devices rotate alone, because rotation cannot mint scopes broader than the approved pairing baseline
errant willow
#

{"pending":[{"requestId":"8b796ecc-ba50-427a-b3ff-19c4c5377692","deviceId":"a2db8970aba2b534c3ff841ad0f625450251c90e83de730f916a0d9aea153d60","publicKey":"VIzlZVE18Fi0CUyJSmtR1DtAxpQCl_yIX-j7vtzKUFI","platform":"win32","clientId":"cli","clientMode":"cli","role":"operator","roles":["operator"],"scopes":["operator.admin","operator.read","operator.write","operator.approvals","operator.pairing","operator.talk.secrets"],"silent":false,"isRepair":true,"ts":1776614440458}],"paired":[{"deviceId":"a2db8970aba2b534c3ff841ad0f625450251c90e83de730f916a0d9aea153d60","publicKey":"VIzlZVE18Fi0CUyJSmtR1DtAxpQCl_yIX-j7vtzKUFI","platform":"win32","clientId":"cli","clientMode":"probe","role":"operator","roles":["operator"],"scopes":["operator.read"],"approvedScopes":["operator.read"],"createdAtMs":1775678286116,"approvedAtMs":1775678286116,"tokens":[{"role":"operator","scopes":["operator.read"],"createdAtMs":1775678286116}]},{"deviceId":"0a715a56a4241ae1583ed2dfa153726634094b49692da187dfa8c94e58ddfd13","publicKey":"6VoIU5jN79RjD31t6AcX1EADlX_wkubpn4tt8y1vICA","platform":"Win32","clientId":"openclaw-control-ui","clientMode":"webchat","role":"operator","roles":["operator"],"scopes":["operator.admin","operator.read","operator.write","operator.approvals","operator.pairing"],"approvedScopes":["operator.admin","operator.read","operator.write","operator.approvals","operator.pairing"],"createdAtMs":1775677617883,"approvedAtMs":1775677617883,"tokens":[{"role":"operator","scopes":["operator.admin","operator.approvals","operator.pairing","operator.read","operator.write"],"createdAtMs":1775677617883,"lastUsedAtMs":1776610466097}]}]}

blissful brambleBOT
#

Perfect, this confirms it.

You have:

  • a stale paired CLI device
    a2db... with only approvedScopes=["operator.read"]
  • a pending repair request for that same device
    requestId="8b796ecc-ba50-427a-b3ff-19c4c5377692"
    with the full CLI scope bundle
    and isRepair: true

So the fix is simply to approve that repair request:

openclaw devices approve 8b796ecc-ba50-427a-b3ff-19c4c5377692
#

Then retry your sessions_spawn.

If it still fails on the first retry, do one restart to clear any stale live connection state:

openclaw gateway restart

Then retry again.

A couple of useful takeaways from that JSON:

  • This is not the Control UI device, that one looks fine.
  • This is not really an “ephemeral subagent can’t pair” problem.
  • It’s specifically the CLI device that was originally paired in a narrow probe/read-only shape, and now needs to be repaired to the normal full operator CLI scope set.

So, no config change needed here. The concrete workflow fix is just:

#
  1. approve the repair request
  2. restart once if needed
  3. rerun sessions_spawn

Docs: https://docs.openclaw.ai/cli/devices

If that works, glad we caught it 🎉
If this fixed it, please right-click the solution message → Apps → ✅ Mark Solution so Answer Overflow can index it for the next person.

errant willow
#

openclaw devices approve 8b796ecc-ba50-427a-b3ff-19c4c5377692

🦞 OpenClaw 2026.4.14 (323493f) — Your .zshrc wishes it could do what I do.

|
gateway connect failed: GatewayClientRequestError: pairing required
o
Direct scope access failed; using local fallback.
unknown requestId

blissful brambleBOT
#

That unknown requestId almost certainly means the pending repair request was superseded between list and approve.

OpenClaw does this on device retries, it can replace the old pending entry with a new requestId.

So the safe sequence is:

openclaw devices list --json

Grab the current pending requestId, then approve it immediately:

openclaw devices approve <fresh-requestId>

If you want, you can also preview the newest one first:

# 
openclaw devices approve --latest

That only shows the current pending request, then rerun approve with the exact ID it prints.

Important

While doing this, don’t keep retrying sessions_spawn in another terminal, or you can keep churning the repair request and invalidating the ID.

If the request keeps getting replaced anyway

Then I’d do a clean repair of that stale CLI device:

openclaw devices remove a2db8970aba2b534c3ff841ad0f625450251c90e83de730f916a0d9aea153d60
openclaw gateway restart
openclaw devices list --json
#

If there’s no pending request yet, trigger one fresh CLI connect, then list again:

openclaw status
openclaw devices list --json
openclaw devices approve <fresh-requestId>

So the updated diagnosis is:

  • your CLI device pairing record is stale
  • the gateway is issuing a repair request
  • the request ID you tried was already outdated by the time approval happened

Docs: https://docs.openclaw.ai/cli/devices

If you paste the next openclaw devices list --json, I can tell you exactly whether to approve the fresh request or go straight to removing the stale CLI device.