openclaw - 💡(How to fix) Fix sessions_spawn fails: Context engine "legacy" is not registered. Available engines: (none) [1 comments, 2 participants]

Summary

Every sessions_spawn (runtime=subagent, mode=run) call fails with:

Context engine subagent preparation failed: Context engine "legacy" is not registered. Available engines: (none)

Reproducible across 2026.4.23 → 2026.4.29 (npm openclaw@latest), surviving multiple gateway restarts and a fresh openclaw models auth login --provider anthropic --method cli --set-default. No third-party context-engine plugin is installed; this is the bare core path failing to register the built-in legacy engine on the spawn code path.

Reproduction

# From a Discord/Telegram/etc. agent, or any client that can call sessions_spawn:
mcp__openclaw__sessions_spawn({
  task: "echo ok",
  runtime: "subagent",
  mode: "run",
  lightContext: true,
  runTimeoutSeconds: 60
})

Returns:

{
  "status": "error",
  "error": "Context engine subagent preparation failed: Context engine \"legacy\" is not registered. Available engines: (none)",
  "childSessionKey": "agent:main:subagent:<uuid>"
}

Environment

• OpenClaw 2026.4.29 (a448042) — also reproduced on 2026.4.23 (a979721)
• Linux 6.17.0-23-generic, Node 22.22.2
• Service: systemd-managed openclaw-gateway (port 18790)
• agents.list has one agent (main, claude-cli/claude-opus-4-6)
• Default model resolves: claude-cli/claude-opus-4-7 (auth-profile OK after openclaw doctor)
• acpx runtime registered cleanly at boot (embedded acpx runtime backend registered)
• 71/117 stock plugins enabled; no plugin registers a context engine (legacy is core-owned)

What I ruled out

• Stale state: restarted gateway multiple times. No change.
• Auth profile drift: ~/.openclaw/agents/main/agent/auth-profiles.json rebuilt; openclaw doctor reports profile OK.
• 2026.4.27 alias-bridge fix (registerContextEngine root export, fixes #53497): upgrade to 2026.4.29 did not change the symptom.
• Plugin engine registration race: no plugin registers a context engine here; the failure is on the core legacy registration path.

What I traced in the dist (2026.4.29)

• subagent-spawn-*.js: prepareContextEngineSubagentSpawn calls subagentSpawnDeps.resolveContextEngine(params.cfg) — wired to the bare resolveContextEngine from registry-*.js, NOT through resolveSubagentRegistryContextEngine (the wrapper that calls ensureContextEnginesInitialized() first).
• subagent-registry-*.js does have a path (resolveSubagentRegistryContextEngine) that calls ensureContextEnginesInitialized() before resolving — but the spawn-prep code doesn't use that path.
• pi-embedded-*.js calls ensureContextEnginesInitialized() at lines ~79 and ~1569 — but our agent runs through the ACPX runtime backend (embedded acpx runtime backend registered), not pi-embedded. So the init is not fired on this agent's boot path.

Net: on a non-pi agent, ensureContextEnginesInitialized() is never called before the first subagent spawn, so the registry is empty, and the bare resolveContextEngine correctly throws.

Suggested fix

Option A (smallest): in subagent-spawn-*.ts prepareContextEngineSubagentSpawn, call ensureContextEnginesInitialized() (or use resolveSubagentRegistryContextEngine) before the bare resolve.

Option B: ensure the gateway/agent boot path calls ensureContextEnginesInitialized() for every runtime backend, not just pi-embedded.

Happy to PR if helpful — let me know which path you'd prefer.

Workaround for affected users

We've been doing all subagent-style work directly from the parent session for now. No real blocker for our use case, just a missed parallelization opportunity.