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

• Repository: openclaw/openclaw
• Author: openperf
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59503

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)