Browser Relay · SSH-Tunnel · Gateway-Ports · sechsstufiges Abnahme-Runbook
Sie betreiben OpenClaw Gateway auf einem VPS oder Cloud-Mac, möchten aber lokales Chrome mit der offiziellen Browser-Relay-Extension für Web-Automatisierung — nicht noch einen Headless-Chromium-Container. Typische Fehler: Die Extension zeigt „verbunden“, während CDP no tab is connected meldet, oder Sie sehen 401 und Port-Probe-Mismatches nach einem SSH-Tunnel. Dieses Playbook richtet sich an Teams, die eine nachvollziehbare Trennung zwischen remote Steuerebene und echtem Desktop-Browser brauchen: eine Entscheidungsmatrix gegenüber Headless Docker, eine Symptomtabelle für 18792-Health und Tunnel-Parameter sowie ein sechsstufiges Runbook. Ergänzen Sie es mit der Headless-Browser-Checkliste und dem Compose-Netzwerk-Runbook. Aus DSGVO-Sicht dokumentieren Sie Zugriffspfade und Datenminimierung: Browser-Sitzungen bleiben auf dem Endgerät, der VPS sieht nur den Relay-Kanal — kein öffentliches Binden des Browsers ans Internet.
In den 2026-Standardeinstellungen lauscht Gateway oft auf 127.0.0.1:18789, während Browser Relay auf dem Entwicklungs-Laptop auf 127.0.0.1:18792 hört. Verlagern Sie Gateway auf einen remote VPS, teilen sich Steuerebene und Browser unterschiedliche Netzwerk-Namespaces: Der Agent spricht weiter von localhost, der Browser sitzt auf Ihrem Notebook. Community-Berichte (remote Gateway plus SSH-Tunnel) häufen sich um Relay-Auth, die nur eine lokale Runtime-Map prüft (401 durch Tunnel), EADDRINUSE-Probes auf dem falschen Port und Extension ON ohne angehängten Tab. Kanal-Antworten als vollständige Abnahme zu behandeln, kostet Stunden Modell-Timeout-Tuning. Für Compliance-Teams in der EU ist zusätzlich relevant: Wer welchen Tab sieht, welche Cookies im lokalen Profil liegen und ob der Zugriff über dokumentierte Tunnel läuft — das gehört ins Änderungsticket, nicht nur in Slack.
Extension grün gleich End-to-End bestanden: ON bedeutet nur, dass der Relay-Prozess lauscht; ohne geöffneten und angehängten Tab auf der Zielseite meldet CDP weiterhin no tab.
Tunnelrichtung vertauscht: Wenn das remote Gateway lokales 18792 erreichen muss, nutzen Sie Remote-Forwarding -R; allein -L für remote 18789 auf den Laptop repariert nicht die Browser-Ebene.
Token- und Porttabellen-Drift: Relay-Token, Tunnel-Map und Extension-Optionen müssen ein Satz sein; ändern Sie eines ohne die anderen, folgen 401 oder leere Ports.
Mischbetrieb mit Headless Docker: Container brauchen shm_size; lokales Relay braucht Tunnel und Attach — siehe die Headless-Checkliste.
Gateway an 0.0.0.0 binden: erweitert die Exposition der Steuerebene und widerspricht dem Prinzip der Datenminimierung; Loopback plus Tunnel oder Privatnetz laut Netzwerk-Artikel.
Kodieren Sie die fünf Punkte als Tunnel-Pflichten und verbotene Muster im Änderungsticket. Der nächste Abschnitt liefert eine Abnahme-Matrix zwischen Headless-Containern und lokalem Relay, bevor Sie Copy-Paste-Abnahmeschritte übernehmen.
Wählen Sie nach wo der Browser läuft, wer die Benutzersitzung hält und welche Compliance-Grenzen gelten — nicht nach persönlicher Präferenz. Nach der Tabelle ein Runbook; beide Stacks nicht in einem Änderungsfenster tunen.
| Muster | Wann es passt | Hauptkosten und Risiko |
|---|---|---|
| Docker Headless Chromium | Unbeaufsichtigte VPS-Batches ohne Laptop-SSO | Hohe shm/Speicher-Spitzen; Fingerabdruck kann vom echten Profil abweichen |
| Lokales Chrome + Relay | Laptop-Cookies/SSO, Debugging mit Mensch in der Schleife | SSH-Tunnel und Extension-Attach; remote Gateway darf Browser nicht ins öffentliche Internet stellen |
| Dedizierter 24/7 Cloud-Mac + Relay | Team-Kapazität in einer Region, auditierbare Zugriffe | Höhere Ops-Kosten, dafür SLA und Tunnel-Vorlagen für Datenschutz-Dokumentation |
Relay-Stabilität hängt vor allem davon ab, wer Port 18792 besitzt, welches localhost der Tunnel mappt und ob Tokens ein Satz sind; der Rest ist Feintuning.
Offizielle 2026-Empfehlung bleibt openclaw onboard --install-daemon plus openclaw gateway status und openclaw doctor für die Steuerebene. Browser-Skills ergänzen Relay-Health und Tab-Attach als Freigabe-Gates gleichwertig zu Gateway grün.
Diese Sequenz setzt die Gateway-Installations-Checkliste fort: Steuerebene beweisen, dann Browser-Ebene. Outputs pro Schritt ins Ticket einfügen.
Gateway abnehmen: auf dem VPS openclaw gateway status; Loopback-Bind auf 18789 (oder dokumentierter Port); Erreichbarkeit nur via Proxy oder SSH.
Lokales Relay starten: Chrome-Extension installieren; auf dem Laptop curl -sS http://127.0.0.1:18792/health.
Tab anbinden: Zielseite öffnen und per Extension attach; ohne Attach ist no tab is connected erwartbar.
Tunnel anlegen: vom Laptop z. B. ssh -N -R 18793:127.0.0.1:18792 user@vps und Gateway-Relay-URL auf 127.0.0.1:18793 auf dem VPS zeigen.
Tokens angleichen: Gateway-Relay-/Gateway-Token mit Extension oder Env-Injection abgleichen; bei 401 durch Tunnel Gateway-Token-Header prüfen statt nur lokaler Runtime-Maps.
End-to-End-Skill: minimalen Browser-Skill fahren bei openclaw logs --follow; bei Fehler Symptomtabelle, ein Knopf pro Experiment.
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
Tipp: Wechseln Sie zu Headless-Browsern im Container, nutzen Sie die Headless-Skill-Checkliste statt shm-Tweaks auf diesem Runbook zu stapeln.
Zuerst nach Symptom indexieren. Pro Experiment eine Variable ändern und curl- sowie Log-Snippets archivieren.
| Symptom | Zuerst prüfen | Typische Ursache und Schritt |
|---|---|---|
| Extension ON, Skill meldet no tab connected | Tab auf Ziel-URL geöffnet und attached | Operatives Gate; im Runbook dokumentieren |
| curl mapped-port /health schlägt nach Tunnel fehl | ssh -R aktiv, remote Listener | Tunnel tot oder Port belegt; ss -lntp |
| Relay 401 / unauthorized | Token-Header und Configs | Remote-Tunnel ohne Gateway-Token; Configs angleichen |
| EADDRINUSE, Browser trotzdem nicht erreichbar | Probe-Port vs. echter Relay-Port | Porttabelle vereinheitlichen |
| Gateway-CLI-Timeout | 18789-Erreichbarkeit, SSH -L | Netzwerk-Artikel lesen, bevor Relay beschuldigt wird |
Warnung: API-Keys, Reverse-Proxy-Zerts und Tunnel-Ports nicht in einem Change rotieren; Dreifach-Moves sind nicht bisectbar.
Lokales Relay passt zu interaktivem Debugging und Laptop-Identität; wechseln Sie die Topologie bei 24/7-Unbeaufsichtigung oder wenn persönliche Notebook-Tunnel nicht haltbar sind.
| Signal | Empfohlene Aktion | Hinweise |
|---|---|---|
| Viele Nutzer hängen an einem Entwickler-Laptop-Tunnel | Wechsel zu Headless Docker oder dediziertem Cloud-Mac | Entfernt Bus-Faktor |
| Tunnel bricht wöchentlich beim Sleep ab | Regionaler 24/7-Knoten plus standardisiertes ssh/systemd | Tunnel-Uptime im SLO tracken |
| Anforderung Browser im öffentlichen Internet | Nicht tun; Headless oder konformes Remote Desktop | Relay setzt Loopback-Vertrauen voraus |
Ad-hoc-VPS plus manuelles SSH ist früh flexibel, doch Produktions-OpenClaw braucht abnahmefähige Kapazität und ticketierte Changes, die persönliche Tunnel selten liefern. Gateway und Browser-Workloads auf einem planbaren 24/7-Cloud-Mac-Fußabdruck mit festen Runbooks schlagen endlose Port-Edits. Teams mit Bedarf an dedizierter, regional stabiler Mac-Kapazität finden in der VpsMesh Mac Mini Cloud-Miete meist die bessere Lösung, um Steuerebene mit Relay oder Headless-Profilen zu co-lokalisieren. Siehe Preise und Hilfezentrum.
Nutzen Sie -L 18789:127.0.0.1:18789, um die remote Gateway-Steuerebene zum Laptop zum Debuggen zu holen. Nutzen Sie -R, damit der VPS lokales 18792 erreicht und die Gateway-Relay-URL passt. Mehr zu Control-Plane-Timeouts im Compose-Netzwerk-Artikel.
Zuerst Tab auf der Ziel-URL öffnen und anbinden. Scheitert Attach weiterhin, Tunnel-Health und Tokens prüfen — Log-Sequenz in der Installations-Checkliste.
Nicht empfohlen. Loopback plus SSH oder Privatnetz beibehalten, oder zu Headless-Docker-Skills oder einem dedizierten Knoten wechseln.