Browser Relay · SSH tunnels · Gateway ports · six-step acceptance runbook
You run OpenClaw Gateway on a VPS or cloud Mac but want local Chrome with the official Browser Relay extension for web automation—not another headless Chromium container. Typical failures: the extension shows connected while CDP reports no tab is connected, or you see 401 and port-probe mismatches after an SSH tunnel. This playbook is for teams who need an auditable split between a remote control plane and a real desktop browser: a decision matrix against headless Docker, a symptom table for 18792 health and tunnel params, and a six-step runbook. Pair it with the headless browser checklist and Compose networking runbook.
In 2026 defaults, Gateway often listens on 127.0.0.1:18789 while Browser Relay on a dev laptop listens on 127.0.0.1:18792. Moving Gateway to a remote VPS splits control plane and browser into different network namespaces: the agent still says localhost, but the browser is on your notebook. Community reports (remote Gateway plus SSH tunnels) cluster around relay auth that only checks a local runtime map (401 through tunnels), EADDRINUSE probes on the wrong port, and extension ON without an attached tab. Treating channels reply as full acceptance wastes hours tuning model timeouts.
Extension green equals end-to-end pass: ON only means the relay process listens; without opening and attaching a tab on the target site, CDP will still report no tab.
Tunnel direction reversed: when the remote Gateway must reach local 18792, use remote forwarding -R; mapping remote 18789 to your laptop with -L alone does not fix the browser plane.
Token and port table drift: relay token, tunnel map, and extension options must be one set; changing one without the others yields 401 or empty ports.
Mixing with headless Docker: containers need shm_size; local Relay needs tunnels and attach—see the headless checklist.
Binding Gateway to 0.0.0.0 for convenience: widens control-plane exposure; keep loopback plus tunnel or private network per the networking article.
Encode the five items as tunnel must-haves and forbidden patterns in your change ticket. The next section gives a sign-off matrix between headless containers and local Relay before copy-paste acceptance steps.
Choose based on where the browser runs, who holds the user session, and compliance boundaries—not personal preference. Pick one runbook after the table; do not tune both stacks in one change window.
| Pattern | When it fits | Main cost and risk |
|---|---|---|
| Docker headless Chromium | Unattended VPS batches without laptop SSO | High shm/memory peaks; fingerprint may differ from a real profile |
| Local Chrome + Relay | Needs laptop cookies/SSO, human-in-the-loop debugging | SSH tunnels and extension attach; remote Gateway must not expose browser to the public internet |
| Dedicated 24/7 cloud Mac + Relay | Team shared capacity in one region | Higher ops cost but defensible SLA and tunnel templates |
Relay stability is mostly who owns port 18792, which localhost the tunnel maps, and whether tokens are one set; other tuning is secondary.
Official 2026 guidance still recommends openclaw onboard --install-daemon plus openclaw gateway status and openclaw doctor for the control plane. Browser skills add relay health and tab attach as release gates equal to Gateway green.
This sequence continues the Gateway install troubleshooting checklist: prove control plane, then browser plane. Paste outputs into the ticket each step.
Accept Gateway: on the VPS run openclaw gateway status; confirm loopback bind on 18789 (or your documented port); reachability only via proxy or SSH.
Start local Relay: install the Chrome extension; run curl -sS http://127.0.0.1:18792/health on the laptop.
Attach a tab: open the target site and attach via the extension; without attach, no tab is connected is expected.
Create the tunnel: from the laptop, e.g. ssh -N -R 18793:127.0.0.1:18792 user@vps and point Gateway relay URL to 127.0.0.1:18793 on the VPS.
Align tokens: match Gateway relay/gateway token with extension or env injection; on 401 through tunnels, verify gateway token headers instead of local-only runtime maps.
End-to-end skill: run a minimal browser skill while tailing openclaw logs --follow; on failure use the symptom table one knob at a time.
curl -sS http://127.0.0.1:18792/health openclaw gateway status ssh -N -R 18793:127.0.0.1:18792 user@your-vps.example curl -sS http://127.0.0.1:18793/health
Tip: if you switch to in-container headless browsers, use the headless skill checklist instead of stacking shm tweaks on this runbook.
Index by symptom first. Change one variable per experiment and archive curl plus log snippets.
| Symptom | Check first | Typical cause and move |
|---|---|---|
| Extension ON, skill says no tab connected | Tab opened and attached on target URL | Operational gate; document in runbook |
| curl mapped-port /health fails after tunnel | ssh -R alive, remote listener | Tunnel died or port taken; use ss -lntp |
| Relay 401 / unauthorized | Token headers and configs | Remote tunnel not using gateway token; align configs |
| EADDRINUSE but browser still unavailable | Probe port vs real Relay port | Unify port table; see community tunnel cases |
| Gateway CLI timeout | 18789 reachability, SSH -L | Read networking article before blaming Relay |
Warning: do not rotate API keys, reverse-proxy certs, and tunnel ports in one change; triple moves are not bisectable.
Local Relay fits interactive debugging and laptop identity; move topology when you need 24/7 unattended runs or cannot maintain personal notebook tunnels.
| Signal | Suggested action | Notes |
|---|---|---|
| Many users depend on one developer laptop tunnel | Move to headless Docker or dedicated cloud Mac | Removes bus factor |
| Tunnel drops weekly on sleep | Use regional 24/7 node plus standardized ssh/systemd | Track tunnel uptime in SLO |
| Requirement for public internet browser | Do not; use headless or compliant remote desktop | Relay assumes loopback trust |
Ad-hoc VPS plus manual SSH is flexible early, yet production OpenClaw needs sign-off capacity and ticketed changes personal tunnels rarely provide. Placing Gateway and browser workloads on a predictable 24/7 cloud Mac footprint with fixed runbooks beats endless port edits. For teams needing dedicated, region-stable Mac capacity, VpsMesh Mac Mini cloud rental is usually the better fit for co-locating control plane with Relay or headless profiles. See pricing and help center.
Use -L 18789:127.0.0.1:18789 to pull remote Gateway control plane to your laptop for debugging. Use -R so the VPS reaches local 18792, matching the Gateway relay URL. More on control-plane timeouts in the Compose networking article.
Open and attach a tab on the target site first. If attach still fails, check tunnel health and tokens using the install troubleshooting checklist log sequence.
Not recommended. Keep loopback plus SSH or private network, or switch to headless Docker skills or a dedicated node.