OpenClaw MCP bridge (gateway ↔ session tool connection)

A live WhatsApp task went dark mid-conversation — every mcp__openclaw__* tool call started failing identically, while the gateway itself reported perfectly healthy.

Dogfooded 2026-08-29 during an ordinary ringtone-fetching request (Mario coin sound, then a Hanna-Barbera drum-roll). Midway through, the session's ability to message, spawn sub-agents, or even check its own status disappeared without warning.

Goals

Diagnose why a running session's message, sessions_spawn, and session_status calls all started failing the same way, and find a path back to delivering the (already-finished) files to the user.

Effectiveness

Adequate, once diagnosed — but the failure mode itself is a real gap. The gateway process (http://127.0.0.1:18789/health) stayed green throughout; the actual problem was that this session's mcp.json had the openclaw MCP endpoint's port baked in at process launch (45087), and the gateway had since started serving MCP on a different port (41321, confirmed via ss -tlnp). Every tool that routes through that bridge failed identically and silently — no distinguishing error pointed at "wrong port," just uniform tool-call failure across totally unrelated tool names.

What made it effective

Not trusting the first plausible read of "the gateway is down." Checking /health directly ruled that out fast, and ss -tlnp gave a concrete, checkable second opinion instead of guessing. Once the port mismatch was visible, the fix was obvious even though it wasn't actionable from inside the stranded session: the mapping is fixed at process launch, so only a fresh session (which would pick up the current port) or a gateway-side fix to bridge registration could restore tool access. Nothing was lost — the requested audio files were already written to disk — so the actual user-facing outcome was fine, just delayed until a new session picked up the thread.

Friction, pain points, surprises

A gateway restart or port rotation invisibly strands any session already running. There's no push notification to a live session telling it "the endpoint moved" — it just starts failing every MCP call the next time it tries, with an error shape indistinguishable from a dozen other possible faults (auth, network, quota).

The failure signature actively misleads toward the wrong diagnosis. Every mcp__openclaw__* tool failing at once looks like "the whole tool layer is down" or "this session's auth expired" — not "one specific port number is stale." Checking gateway health first, before assuming total outage, is what kept this from becoming a longer dead end.

Verdict: adequate, with a known gap. The system healed itself the moment a new session was spawned — but there's no way, today, for a stranded session to recover or even clearly self-diagnose "my bridge port is stale" without manually cross-referencing ss -tlnp against mcp.json. Worth a permanent watch-for: if every mcp__openclaw__* call fails uniformly while /health is green, suspect a stale bridge port before anything else.