gateway-proxy-debug

name	gateway-proxy-debug
description	Gateway and proxy debugging for vercel-openclaw: /gateway routing, HTML injection, WebSocket rewrite, gateway-token handoff, waiting page, status heartbeat, sandbox port URL cache, and proxy auth. Use when the OpenClaw UI, WebSockets, gateway proxying, or waiting-page flow breaks.

Gateway Proxy Debug

Use this skill when the wrapper can reach a sandbox but /gateway, HTML injection, WebSockets, or token handoff is broken.

Evidence First

Collect:

• Browser URL and failing request path.
• GET /api/status.
• GET /api/admin/sandbox-diag.
• GET /api/admin/logs filtered for proxy., gateway., sandbox.port_, token..
• Network trace for /gateway/*, WebSocket upgrade, and POST /api/status heartbeat.

Keep app auth, deployment protection bypass, gateway token, and AI Gateway auth separate. Do not paste gateway tokens in artifacts.

Path Diagram

browser -> wrapper auth -> /gateway route -> ensure sandbox running
  -> fresh gateway token -> sandbox port URL -> OpenClaw gateway
  -> HTML injection -> WebSocket rewrite -> heartbeat POST /api/status

Mark each edge unknown, verified-good, or verified-bad.

Common Failure Splits

• Waiting page is correct because sandbox is not ready yet.
• Proxy auth failed before any sandbox request.
• Cached port URL is stale and needs invalidation.
• Gateway token is stale or not injected.
• HTML injection failed or produced a malformed script.
• WebSocket URL rewrite points at the wrong origin/path.
• Heartbeat is missing and sandbox times out.

Fix Boundaries

• Primary: src/app/gateway/[[...path]]/route.ts.
• Helpers: src/server/proxy/{proxy-route-utils,htmlInjection,waitingPage}.ts.
• Lifecycle dependencies: src/server/sandbox/lifecycle.ts, src/server/public-url.ts.
• Tests: proxy/html injection tests plus lifecycle tests for heartbeat interactions.
• Docs: lat.md/sandbox-lifecycle.md, docs/architecture.md, docs/deployment-protection.md.

Verification

Run focused tests when available, then:

node scripts/verify.mjs --steps=test,typecheck
lat check

For UI/WebSocket fixes, verify in a browser or with a smoke check that HTML contains the injected script and WebSocket traffic reaches the sandbox.