OpenClaw unter WSL2: Chrome-Verbindung in 5 Minuten fixen

Wenn du versuchst, Tools in WSL2 mit Chrome auf Windows zu verbinden, landest du oft in einer Sackgasse. Das Problem bei diesem Split-Host-Setup ist meistens nicht ein einzelner Fehler, sondern mehrere kleine Hürden beim Netzwerk und bei den Berechtigungen, die sich gegenseitig verdecken.

Dieser Guide hilft dir, die Verbindung zwischen dem OpenClaw Gateway in WSL2 und Chrome auf Windows sauber zu konfigurieren. Wir gehen die typischen Fehlerbilder durch, die auch in Issue #39369 beschrieben wurden, damit du nicht an der falschen Stelle suchst.

Wähle zuerst den richtigen Browser-Modus

Du hast zwei sinnvolle Möglichkeiten für dein Setup:

Option 1: Raw remote CDP

Du nutzt ein Remote-Browser-Profil, das von WSL2 direkt auf einen Windows Chrome CDP Endpoint zeigt.

Wähle das, wenn:

• du nur die Browser-Steuerung brauchst
• es für dich okay ist, das Chrome Remote Debugging für WSL2 freizugeben
• du das Chrome Extension Relay nicht benötigst

Option 2: Chrome extension relay

Du nutzt das integrierte chrome Profil zusammen mit der OpenClaw Chrome Extension.

Wähle das, wenn:

• du dich mit dem Toolbar-Button an einen bestehenden Windows Chrome Tab hängen willst
• du die Steuerung über die Extension statt über --remote-debugging-port bevorzugst
• das Relay selbst über die WSL2/Windows-Grenze hinweg erreichbar sein muss

Wenn du das Extension Relay über verschiedene Namespaces hinweg nutzt, ist browser.relayBindHost die entscheidende Einstellung, die in Browser und Chrome extension eingeführt wurde.

Funktionsweise der Architektur

So sieht der Aufbau im Idealfall aus:

• WSL2 führt das Gateway auf 127.0.0.1:18789 aus
• Windows öffnet das Control UI in einem normalen Browser unter http://127.0.0.1:18789/
• Windows Chrome stellt einen CDP Endpoint auf Port 9222 bereit
• WSL2 kann diesen Windows CDP Endpoint erreichen
• OpenClaw zeigt mit einem Browser-Profil auf die Adresse, die von WSL2 aus erreichbar ist

Warum dieses Setup verwirrend ist

Oft überschneiden sich verschiedene Fehlerquellen:

• WSL2 kann den Windows CDP Endpoint nicht erreichen
• Das Control UI wird von einer unsicheren Origin aus geöffnet
• gateway.controlUi.allowedOrigins passt nicht zur Page Origin
• Token oder Pairing fehlen
• Das Browser-Profil zeigt auf die falsche Adresse
• Das Extension Relay ist noch auf Loopback-only eingestellt, obwohl du Zugriff über Namespaces hinweg brauchst

Deshalb kann es passieren, dass du ein Problem löst, aber immer noch eine Fehlermeldung siehst, weil eine andere Schicht noch blockiert.

Wichtige Regel für das Control UI

Wenn du das UI von Windows aus öffnest, verwende Windows Localhost, außer du hast explizit HTTPS konfiguriert.

Nutze:

http://127.0.0.1:18789/

Verwende für das Control UI standardmäßig keine LAN-IP. Normales HTTP auf einer LAN- oder Tailnet-Adresse kann Insecure-Origin-Probleme auslösen, die nichts mit CDP zu tun haben. Siehe Control UI.

Validierung in Schichten

Arbeite dich von oben nach unten durch. Überspringe keine Schritte.

Schicht 1: Prüfen, ob Chrome CDP auf Windows bereitstellt

Starte Chrome auf Windows mit aktiviertem Remote Debugging:

chrome.exe --remote-debugging-port=9222

Prüfe Chrome zuerst direkt unter Windows:

curl http://127.0.0.1:9222/json/version
curl http://127.0.0.1:9222/json/list

Wenn das schon unter Windows fehlschlägt, liegt das Problem noch nicht bei OpenClaw.

Schicht 2: Prüfen, ob WSL2 diesen Windows Endpoint erreicht

Teste von WSL2 aus genau die Adresse, die du in cdpUrl nutzen willst:

curl http://WINDOWS_HOST_OR_IP:9222/json/version
curl http://WINDOWS_HOST_OR_IP:9222/json/list

Gutes Ergebnis:

• /json/version liefert JSON mit Browser- und Protocol-Version-Metadaten
• /json/list liefert JSON (ein leeres Array ist okay, wenn keine Tabs offen sind)

Falls das fehlschlägt:

• Windows gibt den Port noch nicht für WSL2 frei
• Die Adresse ist für die WSL2-Seite falsch
• Firewall, Port-Forwarding oder lokale Proxies fehlen noch

Fixe das, bevor du die OpenClaw-Konfiguration anfasst.

Schicht 3: Das richtige Browser-Profil konfigurieren

Für Raw Remote CDP lässt du OpenClaw auf die Adresse zeigen, die von WSL2 aus erreichbar ist:

{
  browser: {
    enabled: true,
    defaultProfile: "remote",
    profiles: {
      remote: {
        cdpUrl: "http://WINDOWS_HOST_OR_IP:9222",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

Hinweise:

• Nutze die für WSL2 erreichbare Adresse, nicht die, die nur auf Windows funktioniert
• Setze attachOnly: true für extern verwaltete Browser
• Teste die URL mit curl, bevor du erwartest, dass OpenClaw sie schluckt

Schicht 4: Falls du stattdessen das Chrome Extension Relay nutzt

Wenn der Browser-Rechner und das Gateway durch eine Namespace-Grenze getrennt sind, braucht das Relay eventuell eine Bind-Adresse, die kein Loopback ist.

Beispiel:

{
  browser: {
    enabled: true,
    defaultProfile: "chrome",
    relayBindHost: "0.0.0.0",
  },
}

Nutze das nur, wenn nötig:

• Das Standardverhalten ist sicherer, da das Relay auf Loopback bleibt
• 0.0.0.0 macht den Dienst im Netzwerk sichtbarer
• Halte Gateway-Auth, Node-Pairing und das Netzwerk privat

Wenn du das Extension Relay nicht brauchst, ist das Raw Remote CDP Profil von oben die bessere Wahl.

Schicht 5: Die Control UI Schicht separat prüfen

Öffne das UI von Windows aus:

http://127.0.0.1:18789/

Prüfe dann:

• Die Page Origin passt zu dem, was gateway.controlUi.allowedOrigins erwartet
• Token-Auth oder Pairing sind korrekt konfiguriert
• Du suchst nicht nach einem Browser-Problem, obwohl es ein Auth-Problem im Control UI ist

Hilfreiche Seite:

• Control UI

Schicht 6: Browser-Steuerung End-to-End prüfen

Von WSL2 aus:

openclaw browser open https://example.com --browser-profile remote
openclaw browser tabs --browser-profile remote

Für das Extension Relay:

openclaw browser tabs --browser-profile chrome

Gutes Ergebnis:

• Der Tab öffnet sich in Windows Chrome
• openclaw browser tabs zeigt das Ziel an
• Weitere Aktionen (snapshot, screenshot, navigate) funktionieren mit demselben Profil

Häufige irreführende Fehlermeldungen

Betrachte jede Meldung als Hinweis auf eine bestimmte Schicht:

• control-ui-insecure-auth
  • Problem mit der UI Origin oder dem Secure-Context, kein CDP-Transportproblem
• token_missing
  • Problem mit der Auth-Konfiguration
• pairing required
  • Das Gerät muss noch freigegeben werden
• Remote CDP for profile "remote" is not reachable
  • WSL2 erreicht die konfigurierte cdpUrl nicht
• gateway timeout after 1500ms
  • Meistens immer noch ein Problem mit der CDP-Erreichbarkeit oder ein zu langsamer Endpoint
• Chrome extension relay is running, but no tab is connected
  • Das Relay-Profil ist aktiv, aber es ist noch kein Tab verbunden

Checkliste für schnelle Fehlerdiagnose

1. Windows: Funktioniert curl http://127.0.0.1:9222/json/version?
2. WSL2: Funktioniert curl http://WINDOWS_HOST_OR_IP:9222/json/version?
3. OpenClaw Config: Nutzt browser.profiles.<name>.cdpUrl exakt diese WSL2-Adresse?
4. Control UI: Öffnest du http://127.0.0.1:18789/ statt einer LAN-IP?
5. Nur bei Extension Relay: Brauchst du browser.relayBindHost wirklich und ist es explizit gesetzt?

Praktisches Fazit

Das Setup ist absolut machbar. Die Schwierigkeit liegt darin, dass Browser-Transport, Control UI Security, Token-Pairing und die Relay-Topologie unabhängig voneinander fehlschlagen können.

Wenn du unsicher bist:

1. Prüfe zuerst den Windows Chrome Endpoint lokal.
2. Teste denselben Endpoint danach von WSL2 aus.
3. Passe erst dann die OpenClaw-Config an.
4. Kontrolliere zum Schluss die Auth-Einstellungen im Control UI.

AI Setup Assistant

Nächste Schritte

• Control UI konfigurieren
• Browser-Profile im Detail
• Chrome Extension einrichten