WSL2 + Windows + Remote Chrome CDP Fehlerbehebung

Dieser Leitfaden behandelt das gängige Split-Host-Setup, bei dem:

  • das OpenClaw-Gateway in WSL2 läuft
  • Chrome unter Windows läuft
  • die Browsersteuerung die WSL2/Windows-Grenze überschreiten muss

Er behandelt auch das schichtweise Fehlermuster aus Issue #39369: Mehrere unabhängige Probleme können gleichzeitig auftreten, was die falsche Schicht zuerst verdächtig aussehen lässt.

Wähle zuerst den richtigen Browser-Modus

Du hast zwei gültige Varianten:

Option 1: Raw Remote CDP

Ein Remote-Browserprofil verwenden, das von WSL2 auf einen Windows Chrome CDP-Endpunkt zeigt.

Wähle dies, wenn:

  • du nur Browsersteuerung brauchst
  • du damit einverstanden bist, Chrome Remote Debugging für WSL2 freizugeben
  • du das Chrome Extension Relay nicht brauchst

Option 2: Chrome Extension Relay

Das eingebaute chrome-Profil plus die OpenClaw Chrome-Extension verwenden.

Wähle dies, wenn:

  • du dich über den Toolbar-Button an einen bestehenden Windows Chrome-Tab anhängen möchtest
  • du Extension-basierte Steuerung statt rohem --remote-debugging-port möchtest
  • das Relay selbst über die WSL2/Windows-Grenze erreichbar sein muss

Wenn du das Extension Relay über Namespaces hinweg verwendest, ist browser.relayBindHost die wichtige Einstellung, die in Browser und Chrome Extension eingeführt wird.

Funktionierende Architektur

Referenzform:

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

Warum dieses Setup verwirrend ist

Mehrere Fehler können sich überlagern:

  • WSL2 kann den Windows CDP-Endpunkt nicht erreichen
  • die Control UI wird von einem unsicheren Origin geöffnet
  • gateway.controlUi.allowedOrigins stimmt nicht mit dem Seiten-Origin überein
  • Token oder Pairing fehlt
  • das Browserprofil zeigt auf die falsche Adresse
  • das Extension Relay ist noch Loopback-only, obwohl du Namespace-übergreifenden Zugriff brauchst

Deshalb kann die Behebung einer Schicht einen anderen Fehler sichtbar lassen.

Kritische Regel für die Control UI

Wenn die UI von Windows aus geöffnet wird, verwende Windows localhost, es sei denn, du hast ein bewusstes HTTPS-Setup.

Verwende:

http://127.0.0.1:18789/

Verwende standardmäßig keine LAN-IP für die Control UI. Plain HTTP auf einer LAN- oder Tailnet-Adresse kann Insecure-Origin-/Device-Auth-Verhalten auslösen, das nichts mit CDP selbst zu tun hat. Siehe Control UI.

Schichtweise validieren

Arbeite von oben nach unten. Überspringe keine Schritte.

Schicht 1: Überprüfen, dass Chrome CDP unter Windows bereitstellt

Chrome unter Windows mit aktiviertem Remote Debugging starten:

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

Von Windows aus zuerst Chrome selbst überprüfen:

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

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

Schicht 2: Überprüfen, dass WSL2 den Windows-Endpunkt erreichen kann

Aus WSL2 heraus die exakte Adresse testen, die du in cdpUrl verwenden willst:

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

Gutes Ergebnis:

  • /json/version gibt JSON mit Browser / Protocol-Version Metadaten zurück
  • /json/list gibt JSON zurück (leeres Array ist okay, wenn keine Seiten offen sind)

Wenn das fehlschlägt:

  • Windows gibt den Port noch nicht für WSL2 frei
  • die Adresse ist auf der WSL2-Seite falsch
  • Firewall / Port-Forwarding / lokales Proxying fehlt noch

Behebe das, bevor du an der OpenClaw-Konfiguration arbeitest.

Schicht 3: Das richtige Browserprofil konfigurieren

Für Raw Remote CDP OpenClaw auf die Adresse richten, 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:

  • Verwende die von WSL2 erreichbare Adresse, nicht die, die nur unter Windows funktioniert
  • Behalte attachOnly: true für extern verwaltete Browser
  • Teste dieselbe URL mit curl, bevor du erwartest, dass OpenClaw erfolgreich ist

Schicht 4: Wenn du stattdessen das Chrome Extension Relay verwendest

Wenn der Browser-Rechner und das Gateway durch eine Namespace-Grenze getrennt sind, braucht das Relay möglicherweise eine Nicht-Loopback-Bind-Adresse.

Beispiel:

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

Verwende dies nur, wenn nötig:

  • Standardverhalten ist sicherer, weil das Relay Loopback-only bleibt
  • 0.0.0.0 erweitert die Angriffsfläche
  • Gateway-Auth, Node-Pairing und das umgebende Netzwerk privat halten

Wenn du das Extension Relay nicht brauchst, bevorzuge das Raw Remote CDP-Profil oben.

Schicht 5: Die Control UI-Schicht separat überprüfen

Die UI von Windows öffnen:

http://127.0.0.1:18789/

Dann überprüfen:

  • der Seiten-Origin stimmt mit dem überein, was gateway.controlUi.allowedOrigins erwartet
  • Token-Auth oder Pairing ist korrekt konfiguriert
  • du debuggst nicht ein Control UI-Auth-Problem als wäre es ein Browser-Problem

Hilfreiche Seite:

Schicht 6: Ende-zu-Ende-Browsersteuerung überprüfen

Aus WSL2:

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 gibt das Ziel zurück
  • spätere Aktionen (snapshot, screenshot, navigate) funktionieren mit dem gleichen Profil

Häufig irreführende Fehlermeldungen

Behandle jede Meldung als schichtspezifischen Hinweis:

  • control-ui-insecure-auth
    • UI-Origin-/Secure-Context-Problem, kein CDP-Transport-Problem
  • token_missing
    • Auth-Konfigurationsproblem
  • pairing required
    • Geräte-Genehmigungsproblem
  • Remote CDP for profile "remote" is not reachable
    • WSL2 kann die konfigurierte cdpUrl nicht erreichen
  • gateway timeout after 1500ms
    • oft noch CDP-Erreichbarkeit oder ein langsamer/unerreichbarer Remote-Endpunkt
  • Chrome extension relay is running, but no tab is connected
    • Extension Relay-Profil ausgewählt, aber noch kein angehängter Tab vorhanden

Schnelle Triage-Checkliste

  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-Konfiguration: Verwendet browser.profiles.<name>.cdpUrl genau diese von WSL2 erreichbare Adresse?
  4. Control UI: Öffnest du http://127.0.0.1:18789/ statt einer LAN-IP?
  5. Nur Extension Relay: Brauchst du tatsächlich browser.relayBindHost, und wenn ja, ist er explizit gesetzt?

Praktisches Fazit

Das Setup ist normalerweise machbar. Die Schwierigkeit besteht darin, dass Browser-Transport, Control UI-Origin-Sicherheit, Token/Pairing und Extension-Relay-Topologie jeweils unabhängig fehlschlagen können, während sie von der Benutzerseite ähnlich aussehen.

Im Zweifelsfall:

  • Überprüfe zuerst den Windows Chrome-Endpunkt lokal
  • Überprüfe dann denselben Endpunkt von WSL2 aus
  • Debugge erst dann die OpenClaw-Konfiguration oder die Control UI-Auth
Weiter
Overview
arrow_forward