What
When an operator opens an OpenClaw connection's web UI (or launches its session), TangleClaw serves the proxy against whatever tunnel currently exists — even a dead one — producing "tunnel connected" + a black screen. The fix: on open/launch, do a cheap end-to-end health check and force-rebuild the tunnel before serving if it isn't actually carrying traffic.
Why
Hit twice in 15 minutes (2026-06-01) on the 192.168.20.10 connections (TiLT Claw, RentalClaw). Their gateways get restarted by other work, which drops/wrong-targets the tunnel; the UI happily served the dead tunnel → black screen, and the only recovery was a human triggering POST .../tunnel by hand. The operator should never have to do that — it's the same API the UI already calls.
How (builds directly on #288)
detectTunnel is now end-to-end (active = real HTTP round-trip, not just a bound socket — landed in #288/#291, commit 7ecd491). So the open/launch path can:
- Before serving the proxy / starting the webui session, call
detectTunnel (or httpRoundTrip).
- If not
active, run ensureTunnel(..., { force: true }) (already idempotent + adaptive forward-target) and only then serve.
- Surface a brief "reconnecting tunnel…" state instead of a black screen.
Likely touch points: the /openclaw-direct/:id/* proxy entry (server.js), lib/sessions.js launch path, and the connection-open UI action.
Acceptance
- Opening a connection whose gateway was restarted auto-rebuilds the tunnel and serves a working UI (no black screen, no manual
POST).
- A healthy tunnel is served immediately (no needless rebuild — gate on the end-to-end check).
Related: #288, #291. Sibling background-loop version filed separately.
What
When an operator opens an OpenClaw connection's web UI (or launches its session), TangleClaw serves the proxy against whatever tunnel currently exists — even a dead one — producing "tunnel connected" + a black screen. The fix: on open/launch, do a cheap end-to-end health check and force-rebuild the tunnel before serving if it isn't actually carrying traffic.
Why
Hit twice in 15 minutes (2026-06-01) on the
192.168.20.10connections (TiLT Claw, RentalClaw). Their gateways get restarted by other work, which drops/wrong-targets the tunnel; the UI happily served the dead tunnel → black screen, and the only recovery was a human triggeringPOST .../tunnelby hand. The operator should never have to do that — it's the same API the UI already calls.How (builds directly on #288)
detectTunnelis now end-to-end (active= real HTTP round-trip, not just a bound socket — landed in #288/#291, commit 7ecd491). So the open/launch path can:detectTunnel(orhttpRoundTrip).active, runensureTunnel(..., { force: true })(already idempotent + adaptive forward-target) and only then serve.Likely touch points: the
/openclaw-direct/:id/*proxy entry (server.js),lib/sessions.jslaunch path, and the connection-open UI action.Acceptance
POST).Related: #288, #291. Sibling background-loop version filed separately.