Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Bug]: sessions_spawn sub-agent fails with "pairing required" (1008) on v2026.4.1 [2 pull requests, 3 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#59428•Fetched 2026-04-08 02:23:57
View on GitHub
Comments
3
Participants
3
Timeline
23
Reactions
0
Author
TheBlippoTheBlippo
Participants
5o15o1openperfopenperfTheBlippoTheBlippo
Timeline (top)
referenced ×8subscribed ×4commented ×3cross-referenced ×2

sessions_spawn with runtime=subagent fails 100% of the time with WebSocket 1008 "pairing required" after upgrading to v2026.4.1.

Error Message

Gateway log output (redacted): [gateway] security audit: device access upgrade requested reason=scope-upgrade device=<REDACTED> ip=unknown-ip auth=token roleFrom=operator roleTo=operator scopesFrom=operator.read scopesTo=operator.admin client=gateway-client conn=<REDACTED> gateway connect failed: GatewayClientRequestError: pairing required [ws] closed before connect ... code=1008 reason=pairing required Gateway target: ws://127.0.0.1:18789 Source: local loopback Config: ~/.openclaw/openclaw.json Bind: auto Sessions API response: {"ok":false,"error":"GatewayClientRequestError: pairing required","code":1008}

Root Cause

Actual behavior

Sub-agent spawn fails immediately with WebSocket code 1008 "pairing required". No sub-agent session is created. Gateway logs show the gateway-client fails to connect because the scope upgrade from operator.read to operator.admin is denied with "pairing required".

Fix Action

Fix / Workaround

Workaround: None reliable. Long-running tasks must run in the main session.

PR fix notes

PR #59503: fix(gateway): allow silent scope upgrades for local loopback clients

Description (problem / solution / changelog)

Summary

  • Problem: sessions_spawn sub-agent connections fail 100% of the time with WebSocket close(1008) "pairing required" on v2026.4.1. The gateway-client connects from loopback with scopes: ["operator.write"], triggering a scope-upgrade pairing reason when pairedScopes is empty (post-v2026.3.31 device records). The connection is rejected because the pairing request is forced to be non-silent.

  • Root Cause: In src/gateway/server/ws-connection/message-handler.ts line 806–809, requestDevicePairing() contains a hard-coded ternary that forces silent: false whenever reason === "scope-upgrade", regardless of whether the client is a local loopback connection. This discards the return value of shouldAllowSilentLocalPairing(), which correctly returns true for local loopback clients requesting scope upgrades. The non-silent pairing request then requires interactive confirmation that headless gateway-clients cannot provide.

  • Fix: Remove the reason === "scope-upgrade" ? false override so that shouldAllowSilentLocalPairing() || allowSilentBootstrapPairing uniformly controls the silent flag for all pairing reasons. The existing shouldAllowSilentLocalPairing() guard already independently rejects remote clients (isLocalClient: false), browser-origin clients (hasBrowserOriginHeader: true), and metadata-upgrade reasons, so no security boundary is weakened.

  • What changed:

    • src/gateway/server/ws-connection/message-handler.ts: removed the reason === "scope-upgrade" ? false ternary override on the silent parameter of requestDevicePairing() (line 806–809, net −3 lines)
    • src/gateway/server/ws-connection/handshake-auth-helpers.test.ts: added 2 test cases confirming shouldAllowSilentLocalPairing() rejects scope-upgrade for remote clients and browser-origin local clients

  • What did NOT change (scope boundary):

    • shouldAllowSilentLocalPairing() implementation is untouched — its existing reason/client/origin checks are the sole authority
    • Remote client pairing behavior is unchanged (still requires interactive confirmation)
    • Browser-origin client pairing behavior is unchanged
    • metadata-upgrade pairing behavior is unchanged
    • Bootstrap token pairing logic is unchanged
    • No changes to callGateway(), callGatewayLeastPrivilege(), or scope resolution in method-scopes.ts
    • No changes to connect-policy.ts or Control UI pairing skip logic

Reproduction

  1. Install openclaw v2026.4.1
  2. Start gateway with default config
  3. In any agent session, call sessions_spawn with runtime: "subagent"
  4. Observe WebSocket close(1008) with "pairing required" in gateway logs
  5. Sub-agent never starts; 100% reproduction rate

Risk / Mitigation

  • Risk: Removing the scope-upgrade silent override could theoretically allow a local process to silently escalate scopes without user confirmation.
  • Mitigation: shouldAllowSilentLocalPairing() already gates silent pairing on isLocalClient && !hasBrowserOriginHeader (or Control UI / Webchat), which is the same trust boundary used for not-paired and role-upgrade reasons. Two new test cases explicitly verify that remote clients and browser-origin local clients are still rejected for scope-upgrade. The scope-upgrade silent override was an additional restriction that predates the shouldAllowSilentLocalPairing() guard and is now redundant.

Change Type (select all)

  • Bug fix

Scope (select all touched areas)

  • Gateway
  • Subagent / Sessions
  • Device Pairing / Auth

Linked Issue/PR

Fixes #59428 Related: #59092 (prior fix for role-upgrade path) Related: #59393 (may share root cause for subagent tool call failures)

Changed files

  • src/gateway/server/ws-connection/handshake-auth-helpers.test.ts (modified, +24/-0)
  • src/gateway/server/ws-connection/message-handler.ts (modified, +1/-4)

PR #59555: fix(agents): pin subagent gateway calls to admin scope to prevent scope-upgrade pairing failures

Description (problem / solution / changelog)

Summary

  • Problem: sessions_spawn sub-agent calls fail with close(1008) "pairing required" on v2026.4.1. Every callSubagentGateway invocation in src/agents/subagent-spawn.ts delegates to callGateway without explicit scopes, causing callGatewayLeastPrivilege to negotiate the minimum scope per method independently. The first connection (e.g. agent → operator.write) silently pairs the device at a lower tier. Subsequent calls requiring a higher tier (e.g. sessions.patch → operator.admin) trigger a scope-upgrade handshake that the headless gateway-client cannot complete interactively.

  • Root Cause: callSubagentGateway (line 148–152 of subagent-spawn.ts) forwards params to callGateway without scopes. callGateway falls through to callGatewayLeastPrivilege, which resolves the minimum scope for each method via resolveLeastPrivilegeOperatorScopesForMethod. Because subagent lifecycle spans multiple scope tiers (sessions.patch/sessions.delete → operator.admin, agent → operator.write), the device gets paired at a lower tier on the first call, and every subsequent higher-tier call triggers scope-upgrade. The gateway's message-handler.ts:806 intentionally forces silent: false for scope-upgrade to prevent silent privilege escalation by external devices — this is correct security behavior, but it blocks the legitimate local gateway-client self-connection.

  • Fix: Pin callSubagentGateway to scopes: [ADMIN_SCOPE] so the device is paired at the ceiling scope (operator.admin) on the very first (silent, local-loopback) handshake. All subsequent calls match the already-paired scope and never trigger scope-upgrade. This preserves the security-critical silent: false enforcement in message-handler.ts for external devices.

  • What changed:

    • src/agents/subagent-spawn.ts: callSubagentGateway now injects scopes: params.scopes ?? [ADMIN_SCOPE] before forwarding to callGateway, bypassing per-method least-privilege negotiation and ensuring a consistent admin-tier pairing.
    • src/agents/subagent-spawn.test.ts: Added test asserting every gateway call from spawnSubagentDirect carries scopes: ["operator.admin"].

  • What did NOT change (scope boundary):

    • message-handler.ts — the scope-upgrade silent: false security guard is untouched.
    • handshake-auth-helpers.ts — shouldAllowSilentLocalPairing logic is untouched.
    • server.silent-scope-upgrade-reconnect.poc.test.ts — all existing security tests pass as-is.
    • call.ts and method-scopes.ts — the least-privilege resolution logic is untouched.
    • No gateway auth flow, bootstrap token, or device pairing logic is modified.

Reproduction

  1. Install openclaw v2026.4.1 with device pairing enabled
  2. Start a conversation and trigger sessions_spawn (e.g. ask the agent to run a long research task)
  3. Observe gateway-client log: reason=scope-upgrade scopesFrom=operator.read scopesTo=operator.admin
  4. Connection closes with code 1008 "pairing required"
  5. Sub-agent never starts; main agent reports spawn failure

Risk / Mitigation

  • Risk: Subagent gateway calls now always request operator.admin instead of least-privilege per method. A compromised subagent process could theoretically invoke admin-only methods it previously could not reach in a single connection.
  • Mitigation: (1) Subagent gateway-client connections are local loopback only — they never traverse the network. (2) The gateway still enforces authorizeOperatorScopesForMethod per-request, so method-level authorization is unchanged. (3) The callSubagentGateway wrapper respects params.scopes if explicitly provided, preserving the ability to narrow scope for future callers. (4) Test added to verify the scope pinning behavior.

Change Type (select all)

  • Bug fix

Scope (select all touched areas)

  • Agents
  • Subagent Spawn

Linked Issue/PR

Fixes #59428

Changed files

  • CHANGELOG.md (modified, +1/-0)
  • src/agents/subagent-spawn.test.ts (modified, +46/-0)
  • src/agents/subagent-spawn.ts (modified, +16/-1)

Code Example

Gateway log output (redacted):
[gateway] security audit: device access upgrade requested reason=scope-upgrade device=<REDACTED> ip=unknown-ip auth=token roleFrom=operator roleTo=operator scopesFrom=operator.read scopesTo=operator.admin client=gateway-client conn=<REDACTED>
gateway connect failed: GatewayClientRequestError: pairing required
[ws] closed before connect ... code=1008 reason=pairing required
Gateway target: ws://127.0.0.1:18789
Source: local loopback
Config: ~/.openclaw/openclaw.json
Bind: auto
Sessions API response: {"ok":false,"error":"GatewayClientRequestError: pairing required","code":1008}
RAW_BUFFERClick to expand / collapse

Bug type

Regression (worked before, now fails)

Beta release blocker

No

Summary

sessions_spawn with runtime=subagent fails 100% of the time with WebSocket 1008 "pairing required" after upgrading to v2026.4.1.

Steps to reproduce

  1. Have OpenClaw v2026.4.1 running with a local gateway (systemd user service)
  2. From the main agent session, call sessions_spawn with runtime="subagent" and any task
  3. Observe immediate failure with error: "gateway closed (1008): pairing required"
  4. Gateway logs show: "security audit: device access upgrade requested" → "gateway connect failed: GatewayClientRequestError: pairing required"
  5. Pattern: gateway-client requests scope-upgrade from operator.read to operator.admin, gateway responds with "pairing required"

Expected behavior

Sub-agent spawns successfully and begins processing the assigned task in a background session.

Actual behavior

Sub-agent spawn fails immediately with WebSocket code 1008 "pairing required". No sub-agent session is created. Gateway logs show the gateway-client fails to connect because the scope upgrade from operator.read to operator.admin is denied with "pairing required".

OpenClaw version

2026.4.1 (213a704)

Operating system

Linux Debian 13 (Trixie)

Install method

npm global

Model

minimax-m2.7:cloud

Provider / routing chain

Ollama (cloud) — model served via Ollama Cloud using minimax-m2.7

Additional provider/model setup details

No response

Logs, screenshots, and evidence

Gateway log output (redacted):
[gateway] security audit: device access upgrade requested reason=scope-upgrade device=<REDACTED> ip=unknown-ip auth=token roleFrom=operator roleTo=operator scopesFrom=operator.read scopesTo=operator.admin client=gateway-client conn=<REDACTED>
gateway connect failed: GatewayClientRequestError: pairing required
[ws] closed before connect ... code=1008 reason=pairing required
Gateway target: ws://127.0.0.1:18789
Source: local loopback
Config: ~/.openclaw/openclaw.json
Bind: auto
Sessions API response: {"ok":false,"error":"GatewayClientRequestError: pairing required","code":1008}

Impact and severity

  • Affected: OpenClaw users relying on sub-agent spawning for background tasks
  • Severity: High — blocks all sub-agent workflows (long-running tasks, research, code generation)
  • Frequency: 100% reproducible on every spawn attempt
  • Consequence: Sub-agents cannot be spawned. All multi-step tasks must run inline in the main session, increasing memory pressure and blocking the main agent during long operations.

Additional information

Regression: broken since approximately v2026.3.28 or earlier. Issue #58085 shows sub-agents were already failing in v2026.3.28 with a different error (agentId is not allowed for sessions_spawn). The v2026.4.1 changelog mentions fix #59092 which addresses pairing-required errors for exec/node clients, but the sub-agent code path (gateway-client escalating to operator.admin) remains broken.

Attempted fixes (none resolved the issue):

  • Gateway restart via 'gateway restart' tool
  • Gateway restart via 'systemctl --user restart openclaw-gateway'
  • Full update from v2026.3.31 to v2026.4.1 via 'openclaw update'
  • Multiple restart cycles after update

A related issue #59393 "Subagent tool calls never execute" is also open as a regression. The root cause may be shared (both involve sub-agent session management failing).

Workaround: None reliable. Long-running tasks must run in the main session.

extent analysis

TL;DR

The most likely fix involves addressing the "pairing required" error for sub-agent sessions by re-examining the scope upgrade from operator.read to operator.admin in the gateway-client requests.

Guidance

  1. Review the changelog and related issues: Examine the changes made in fix #59092 for exec/node clients and determine if similar adjustments are needed for the sub-agent code path to handle the "pairing required" error.
  2. Investigate gateway-client scope upgrade: Analyze why the gateway-client requests a scope upgrade from operator.read to operator.admin and if this is necessary for sub-agent spawning. Consider if there's an alternative approach that doesn't require this upgrade.
  3. Check OpenClaw configuration: Verify the configuration in ~/.openclaw/openclaw.json to ensure there are no settings that could be causing or exacerbating the issue, particularly those related to authentication, authorization, or gateway settings.
  4. Compare with related issue #59393: Since both issues involve sub-agent session management failures, comparing the symptoms and potential fixes might provide insights into a common root cause.

Example

No specific code example can be provided without more details on the implementation, but reviewing the code changes in fix #59092 and comparing them with the sub-agent spawning code might offer clues on how to proceed.

Notes

The issue seems to be related to changes introduced around version 2026.3.28, and the fix for exec/node clients in version 2026.4.1 does not appear to have resolved the issue for sub-agents. The fact that a reliable workaround is not available suggests that a code or configuration change is necessary to address the root cause.

Recommendation

Apply a workaround by temporarily modifying the sub-agent spawning process to not require the scope upgrade to operator.admin, if possible, while awaiting a more permanent fix. This could involve adjusting the roles or scopes assigned to the sub-agent or modifying the gateway-client to handle the pairing requirement differently.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

FAQ

Expected behavior

Sub-agent spawns successfully and begins processing the assigned task in a background session.

#api#permission error#memory optimization#batch processing#GPU compatibility

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix [Bug]: sessions_spawn sub-agent fails with "pairing required" (1008) on v2026.4.1 [2 pull requests, 3 comments, 3 participants]