openclaw - 💡(How to fix) Fix sub-agent dispatch: in-process spawn hits gateway pairing gate (no in-process lane shortcut) [1 participants]

Summary

Native sub-agent dispatch via sessions_spawn({runtime: "subagent", ...}) opens a fresh WebSocket back to the local gateway from src/agents/subagent-spawn.ts:657 (callGateway({method: "agent", ...})). That connect goes through loadOrCreateDeviceIdentity() → presents a brand-new device fingerprint → hits the pairing gate at src/gateway/server/ws-connection/message-handler.ts:802 → connection closed with code=1008 reason=pairing required.

In a typical desktop install this is invisible because device pairing was set up by the CLI bootstrap. In a freshly-bootstrapped server-side install (gateway and agent runtime in the same process, no operator-driven pairing step), every sessions_spawn for a native sub-agent fails at the gate.

Documentation says one thing, code does another

docs/tools/subagents.md:277-282:

Sub-agents use a dedicated in-process queue lane — Lane name: subagent.

There is no in-process shortcut implemented today. Tracing the failing call:

1. src/agents/subagent-spawn.ts:657 — callGateway({method: "agent", params: {lane: AGENT_LANE_SUBAGENT, ...}}) opens a WebSocket.
2. src/gateway/server-methods/agent.ts:197 — agentHandlers.agent receives the request.
3. Same file, line 145: dispatchAgentRunFromGateway → agentCommandFromIngress(...) (now in-process).
4. src/agents/pi-embedded-runner/run.ts:217 → enqueueCommandInLane(globalLane, ...) where globalLane = CommandLane.Subagent.

The in-process queue lane (step 4) is reached only after the WebSocket handshake completes. So in-process dispatch happens, but only after passing through the gateway's full WebSocket auth gate that was designed for external CLI clients.

The pairing-gate failure

src/gateway/server/ws-connection/handshake-auth-helpers.ts:63-86 — shouldSkipBackendSelfPairing would bypass the pairing gate, but it requires sharedAuthOk = true (token or password auth passed). In a server install where gateway.auth.mode = "token" with an empty gateway.auth.token (a common config when the operator hasn't seeded a token), sharedAuthOk = false, so backend-self-pairing-skip never fires and the spawn fails.

shouldAllowSilentLocalPairing at :49-61 returns true for local clients with reason = "not-paired", but the silent pairing request flag does not auto-approve reason = "scope-upgrade" paths in our observed traces.

Live worker log at the moment of failure:

[gateway] security audit: device access upgrade requested
  reason=scope-upgrade
  device=6d3e97b4e247e137a7e07fc97dc07d62a9b5756f8ee04983bbf074a87bcd10f9
  ip=unknown-ip auth=token roleFrom=operator roleTo=operator
  scopesFrom=operator.read scopesTo=operator.admin
  client=cli  conn=e4e33139-c42e-4d6c-917a-cb3c47910da2
gateway connect failed: GatewayClientRequestError: pairing required
[ws] closed before connect conn=e4e33139-... peer=127.0.0.1:59136->127.0.0.1:18789
  code=1008 reason=pairing required

(client=cli is misleading — it's the agent runtime's spawn call, not an external CLI session.)

Reproduction (rough — need an openclaw maintainer to confirm minimal repro)

1. Run openclaw gateway in a fresh container (STATE_DIR=/tmp/openclaw-fresh, no prior pairing).
2. Configure gateway.auth.mode = "token" with gateway.auth.token = "" (or mode = "none" — both reportedly fail the same way for the spawn-time pairing gate).
3. Concierge agent calls sessions_spawn({runtime: "subagent", agentId: "<some-native-agent>", mode: "run", task: "..."}).
4. Observe pairing required (1008) in worker logs and the spawn tool returns an error.

Suggested fix directions (in priority order)

1. In-process dispatch shortcut. When subagent-spawn.ts detects the gateway is running in the same process (e.g. a singleton handle injected at boot), call agentCommandFromIngress(...) directly and skip callGateway entirely. This honors the docs (in-process queue lane) and eliminates the WebSocket handshake for the same-process case.
2. Auto-approve self-pairing for backend clients on local connections. Loosen shouldSkipBackendSelfPairing to also accept auth.mode = "none" (without requiring sharedAuthOk to be true), since "none" mode by design means the deployment trusts the network boundary.
3. Document a config flag (e.g. gateway.subagentAuth.disable: true, mirroring the existing gateway.controlUi.dangerouslyDisableDeviceAuth) so operators of single-process server deployments can opt out of the pairing gate for the subagent dispatch surface specifically.

(1) is the cleanest because it makes the docs accurate and removes WebSocket overhead for in-process spawns. (2) is the smallest patch. (3) is the least invasive but requires operators to know about the flag.

Workaround (currently in use downstream)

Plugins that need autonomous delivery of long-running results spawn an in-plugin setInterval poller inside the tool's execute() and deliver to the user's channel directly, sidestepping sessions_spawn entirely. See the sidekyk-video and sidekyk-hf-video-generator plugins in sidekyk-verticals for the recipe.

Severity

Medium — blocks autonomous-delivery patterns built around sessions_spawn for any server-side openclaw install where the operator hasn't seeded a paired device. Workaround exists (in-plugin polling) but it's per-plugin boilerplate that shouldn't be necessary for what the docs say is a first-class queue-lane primitive.

Related downstream work

• sidekykai/sidekyk-verticals#46 — the original sub-agent flow that hit this.
• sidekykai/sidekyk-verticals#52 — the pivot to in-plugin polling (workaround).
• sidekykai/openclawmtsaas#352 — the symptom report (silent delivery).
• Diagnosis writeup: https://github.com/sidekykai/sidekyk-verticals/pull/46#issuecomment-4292533712