> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# WSL2 + Windows + Problembehandlung für Remote-Chrome-CDP

Bei der üblichen Split-Host-Konfiguration läuft OpenClaw Gateway in WSL2, Chrome läuft unter Windows, und die Browsersteuerung muss die Grenze zwischen WSL2 und Windows überqueren. Das geschichtete Fehlermuster aus [Issue #39369](https://github.com/openclaw/openclaw/issues/39369) bedeutet, dass mehrere unabhängige Probleme gleichzeitig auftreten können, wodurch zunächst die falsche Schicht defekt wirkt.

## Wählen Sie zuerst den richtigen Browsermodus

Es gibt zwei gültige Muster:

### Option 1: Direktes Remote-CDP von WSL2 zu Windows

Verwenden Sie ein Remote-Browserprofil, das von WSL2 auf einen Windows-Chrome-CDP-Endpunkt zeigt.

Wählen Sie dies, wenn:

* der Gateway in WSL2 bleibt
* Chrome unter Windows läuft
* die Browsersteuerung die Grenze zwischen WSL2 und Windows überqueren muss

### Option 2: Host-lokales Chrome MCP

Verwenden Sie `existing-session` / `user` nur, wenn der Gateway selbst auf demselben Host wie Chrome läuft.

Wählen Sie dies, wenn:

* OpenClaw und Chrome auf derselben Maschine sind
* Sie den lokalen angemeldeten Browserzustand verwenden möchten
* Sie keinen hostübergreifenden Browsertransport benötigen
* Sie keine erweiterten verwalteten oder nur über direktes CDP verfügbaren Routen wie `responsebody`, PDF-
  Export, Download-Abfangen oder Batch-Aktionen benötigen

Für WSL2 Gateway + Windows Chrome bevorzugen Sie direktes Remote-CDP. Chrome MCP ist host-lokal, keine Brücke von WSL2 zu Windows.

## Funktionierende Architektur

Referenzform:

* WSL2 führt den 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 stellt einen CDP-Endpunkt auf Port `9222` bereit
* WSL2 kann diesen Windows-CDP-Endpunkt erreichen
* OpenClaw verweist mit einem Browserprofil auf die Adresse, die von WSL2 aus erreichbar ist

## Warum diese Konfiguration verwirrend ist

Mehrere Fehler können sich überlagern:

* WSL2 kann den Windows-CDP-Endpunkt nicht erreichen
* die Control UI wird von einem nicht sicheren Origin geöffnet
* `gateway.controlUi.allowedOrigins` passt nicht zum Seiten-Origin
* Token oder Pairing fehlt
* das Browserprofil zeigt auf die falsche Adresse

Deshalb kann nach dem Beheben einer Schicht weiterhin ein anderer Fehler sichtbar bleiben.

## Kritische Regel für die Control UI

Wenn die UI von Windows aus geöffnet wird, verwenden Sie Windows-localhost, sofern Sie keine absichtliche HTTPS-Konfiguration haben.

Verwenden Sie:

`http://127.0.0.1:18789/`

Verwenden Sie nicht standardmäßig eine LAN-IP für die Control UI. Reines HTTP auf einer LAN- oder tailnet-Adresse kann unsicheres Origin-/Geräteauthentifizierungsverhalten auslösen, das nichts mit CDP selbst zu tun hat. Siehe [Control UI](/de/web/control-ui).

## In Schichten validieren

Arbeiten Sie von oben nach unten. Überspringen Sie keine Schritte.

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

Starten Sie Chrome unter Windows mit aktivierter Remote-Debugging-Funktion:

```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
chrome.exe --remote-debugging-port=9222
```

Prüfen Sie von Windows aus zuerst Chrome selbst:

```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl http://127.0.0.1:9222/json/version
curl http://127.0.0.1:9222/json/list
```

Wenn dies unter Windows fehlschlägt, ist OpenClaw noch nicht das Problem.

### Schicht 2: Prüfen, ob WSL2 diesen Windows-Endpunkt erreichen kann

Testen Sie von WSL2 aus die exakte Adresse, die Sie in `cdpUrl` verwenden möchten:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 (ein leeres Array ist in Ordnung, wenn keine Seiten geöffnet sind)

Wenn dies fehlschlägt:

* Windows stellt den Port für WSL2 noch nicht bereit
* die Adresse ist für die WSL2-Seite falsch
* Firewall / Portweiterleitung / lokales Proxying fehlt noch

Beheben Sie das, bevor Sie die OpenClaw-Konfiguration anfassen.

### Schicht 3: Das richtige Browserprofil konfigurieren

Für direktes Remote-CDP verweisen Sie OpenClaw auf die Adresse, die von WSL2 aus erreichbar ist:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  browser: {
    enabled: true,
    defaultProfile: "remote",
    profiles: {
      remote: {
        cdpUrl: "http://WINDOWS_HOST_OR_IP:9222",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}
```

Hinweise:

* verwenden Sie die von WSL2 aus erreichbare Adresse, nicht das, was nur unter Windows funktioniert
* behalten Sie `attachOnly: true` für extern verwaltete Browser bei
* `cdpUrl` kann `http://`, `https://`, `ws://` oder `wss://` sein
* verwenden Sie HTTP(S), wenn OpenClaw `/json/version` erkennen soll
* verwenden Sie WS(S) nur, wenn der Browser-Provider Ihnen eine direkte DevTools-Socket-URL bereitstellt
* testen Sie dieselbe URL mit `curl`, bevor Sie erwarten, dass OpenClaw erfolgreich ist

### Schicht 4: Die Control-UI-Schicht separat prüfen

Öffnen Sie die UI von Windows aus:

`http://127.0.0.1:18789/`

Prüfen Sie dann:

* der Seiten-Origin entspricht dem, was `gateway.controlUi.allowedOrigins` erwartet
* Token-Authentifizierung oder Pairing ist korrekt konfiguriert
* Sie debuggen kein Control-UI-Authentifizierungsproblem, als wäre es ein Browserproblem

Hilfreiche Seite:

* [Control UI](/de/web/control-ui)

### Schicht 5: End-to-End-Browsersteuerung prüfen

Von WSL2 aus:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw browser open https://example.com --browser-profile remote
openclaw browser tabs --browser-profile remote
```

Gutes Ergebnis:

* der Tab wird in Windows Chrome geöffnet
* `openclaw browser tabs` gibt das Ziel zurück
* spätere Aktionen (`snapshot`, `screenshot`, `navigate`) funktionieren mit demselben Profil

## Häufige irreführende Fehler

Behandeln Sie jede Meldung als schichtspezifischen Hinweis:

* `control-ui-insecure-auth`
  * UI-Origin-/Secure-Context-Problem, kein CDP-Transportproblem
* `token_missing`
  * Problem mit der Authentifizierungskonfiguration
* `pairing required`
  * Problem mit der Gerätefreigabe
* `Remote CDP for profile "remote" is not reachable`
  * WSL2 kann die konfigurierte `cdpUrl` nicht erreichen
* `Browser attachOnly is enabled and CDP websocket for profile "remote" is not reachable`
  * der HTTP-Endpunkt hat geantwortet, aber der DevTools-WebSocket konnte trotzdem nicht geöffnet werden
* veraltete Viewport- / Dark-Mode- / Locale- / Offline-Overrides nach einer Remote-Sitzung
  * führen Sie `openclaw browser stop --browser-profile remote` aus
  * dies schließt die aktive Steuerungssitzung und gibt den Playwright-/CDP-Emulationszustand frei, ohne den Gateway oder den externen Browser neu zu starten
* `gateway timeout after 1500ms`
  * oft weiterhin CDP-Erreichbarkeit oder ein langsamer/nicht erreichbarer Remote-Endpunkt
* `No Chrome tabs found for profile="user"`
  * lokales Chrome-MCP-Profil ausgewählt, obwohl keine host-lokalen Tabs verfügbar sind

## 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 aus erreichbare Adresse?
4. Control UI: öffnen Sie `http://127.0.0.1:18789/` statt einer LAN-IP?
5. Versuchen Sie, `existing-session` über WSL2 und Windows hinweg zu verwenden, statt direktes Remote-CDP?

## Praktische Schlussfolgerung

Die Konfiguration ist in der Regel funktionsfähig. Die Schwierigkeit besteht darin, dass Browsertransport, Origin-Sicherheit der Control UI und Token/Pairing jeweils unabhängig fehlschlagen können, während sie aus Benutzersicht ähnlich aussehen.

Im Zweifel:

* prüfen Sie zuerst den Windows-Chrome-Endpunkt lokal
* prüfen Sie denselben Endpunkt anschließend von WSL2 aus
* debuggen Sie erst dann die OpenClaw-Konfiguration oder die Control-UI-Authentifizierung

## Verwandte Themen

* [Browser](/de/tools/browser)
* [Browser-Anmeldung](/de/tools/browser-login)
* [Browser-Linux-Fehlerbehebung](/de/tools/browser-linux-troubleshooting)