Problem

Switching between sessions in the OpenClaw TUI/agent runtime takes 5-8 seconds due to synchronous MCP tool materialization in createRuntime. Every session switch spawns a new stdio MCP subprocess, fetches the full tool catalog, and registers all tools before the session becomes usable.

Environment

• OpenClaw 2026.5.28 (e932160)
• Windows 11 x64, Node v24.16.0
• MCP: vibe-trading stdio server (70+ tools)

Root Cause (Source Analysis)

The session switch path in sessions-htxRTdBr.js:

switchSession(path)
-> teardownCurrent() (dispose old session, serial)
-> createRuntime() (rebuilds entire runtime)
-> materializeMcpToolsForAgent()
-> getOrCreateSessionMcpRuntime()
-> getCatalog() (SYNCHRONOUS blocking call)
-> spawn stdio child process (~1-3s)
-> connectWithTimeout(30s) (~0.5-1s)
-> listAllTools() (~1-2s, 70+ tool definitions)
-> register 70+ tools to registry (~0.5-1s)
-> finishSessionReplacement()

Key source evidence:

1. getCatalog() is synchronous (agent-bundle-mcp-runtime--qlnxWNy.js:625-695): iterates all MCP servers, spawns stdio processes, connects, and lists tools - all awaited in series. Default connection timeout: 30s per server.

2. Tool materialization blocks createRuntime (agent-bundle-mcp-materialize-DAJQADAM.js:81): catalog = await params.runtime.getCatalog() blocks until all tools fetched.

3. No cross-session connection pooling (agent-bundle-mcp-runtime--qlnxWNy.js:789-830): runtimesBySessionId.get(params.sessionId) - each session gets its own key, so switching sessions always creates a new runtime with a new Python process.

4. sweepIdleRuntimes() runs on every getOrCreate call - unnecessary overhead.

Performance Breakdown (Estimated)

Suggested Fixes

P0: Cross-session MCP connection pool

Share a single stdio server connection across sessions instead of spawning per-session. The tool catalog for a given server config is identical across all sessions. Key change: use runtimesByConfigHash instead of runtimesBySessionId. Expected: 5-8s to less than 1s.

P1: Lazy tool materialization

Move getCatalog() out of the synchronous createRuntime path. Start catalog fetch in background, allow session to become usable with partial tool list. Expected: 5-8s to 1-2s.

P2: Tool definition cache

Cache resolved tool definitions to disk per server config hash. Avoid re-fetching identical 70+ tool definitions on every cold start. Expected: cold start 3-5s to 1-2s.

Related Issues

• Dashboard: slow session switching (8-10s) — no virtual scrolling, full re-render on every switch #87345 - Dashboard UI session switching (different layer: frontend rendering)
• observability: emit per-MCP-server sub-spans inside bundle-tools so cold-start cost is attributable #81595 - Observability for per-MCP-server cold-start cost (confirms known concern)
• Gateway lazy-spawns duplicate stdio MCP children with identical ppid+config (memory + CPU leak) #75621 - Gateway lazy-spawns duplicate stdio MCP children (redundant process spawning)
• MCP/plugin failures should degrade fast instead of blocking main reply path #64411 - MCP/plugin failures should degrade fast instead of blocking

Reproduction

1. Configure an MCP stdio server with many tools (e.g., vibe-trading with 70+ tools)
2. Start OpenClaw, enter a session
3. Switch to a different session
4. Observe 5-8 second delay before the new session is ready