​

Dépannage WSL2 + Windows + CDP Chrome distant

• OpenClaw Gateway s’exécute dans WSL2
• Chrome s’exécute sur Windows
• le contrôle du navigateur doit traverser la frontière WSL2/Windows

​

Choisissez d’abord le bon mode de navigateur

​

Option 1 : CDP distant brut de WSL2 vers Windows

• la Gateway reste dans WSL2
• Chrome s’exécute sur Windows
• vous avez besoin que le contrôle du navigateur traverse la frontière WSL2/Windows

​

Option 2 : Chrome MCP local à l’hôte

• OpenClaw et Chrome s’exécutent sur la même machine
• vous voulez l’état local du navigateur déjà connecté
• vous n’avez pas besoin d’un transport de navigateur inter-hôte
• vous n’avez pas besoin de routes avancées gérées ou réservées au CDP brut comme responsebody, l’export PDF, l’interception de téléchargements ou les actions par lot

​

Architecture fonctionnelle

• WSL2 exécute la Gateway sur 127.0.0.1:18789
• Windows ouvre l’interface de contrôle dans un navigateur normal sur http://127.0.0.1:18789/
• Chrome sous Windows expose un point de terminaison CDP sur le port 9222
• WSL2 peut atteindre ce point de terminaison CDP Windows
• OpenClaw pointe un profil de navigateur vers l’adresse joignable depuis WSL2

​

Pourquoi cette configuration prête à confusion

• WSL2 ne peut pas atteindre le point de terminaison CDP Windows
• l’interface de contrôle est ouverte depuis une origine non sécurisée
• gateway.controlUi.allowedOrigins ne correspond pas à l’origine de la page
• le token ou l’appairage manque
• le profil de navigateur pointe vers la mauvaise adresse

​

Règle critique pour l’interface de contrôle

​

Validez par couches

​

Couche 1 : Vérifier que Chrome sert bien le CDP sur Windows

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

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

​

Couche 2 : Vérifier que WSL2 peut atteindre ce point de terminaison Windows

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

• /json/version renvoie du JSON avec les métadonnées Browser / Protocol-Version
• /json/list renvoie du JSON (un tableau vide convient s’il n’y a aucune page ouverte)

• Windows n’expose pas encore le port à WSL2
• l’adresse est incorrecte du point de vue de WSL2
• le pare-feu / la redirection de port / le proxy local manque encore

​

Couche 3 : Configurer le bon profil de navigateur

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

• utilisez l’adresse joignable depuis WSL2, pas celle qui fonctionne uniquement sous Windows
• conservez attachOnly: true pour les navigateurs gérés de manière externe
• cdpUrl peut être http://, https://, ws:// ou wss://
• utilisez HTTP(S) quand vous voulez qu’OpenClaw découvre /json/version
• utilisez WS(S) uniquement quand le fournisseur du navigateur vous donne une URL de socket DevTools directe
• testez la même URL avec curl avant de vous attendre à ce qu’OpenClaw fonctionne

​

Couche 4 : Vérifier séparément la couche de l’interface de contrôle

• que l’origine de la page correspond à ce qu’attend gateway.controlUi.allowedOrigins
• que l’authentification par token ou l’appairage est correctement configuré
• que vous n’êtes pas en train de déboguer un problème d’authentification de l’interface de contrôle comme s’il s’agissait d’un problème de navigateur

• Interface de contrôle

​

Couche 5 : Vérifier le contrôle de navigateur de bout en bout

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

• l’onglet s’ouvre dans Chrome sous Windows
• openclaw browser tabs renvoie la cible
• les actions suivantes (snapshot, screenshot, navigate) fonctionnent depuis le même profil

​

Erreurs trompeuses fréquentes

• control-ui-insecure-auth
  • problème d’origine d’interface / de contexte sécurisé, pas un problème de transport CDP
• token_missing
  • problème de configuration de l’authentification
• pairing required
  • problème d’approbation de l’appareil
• Remote CDP for profile "remote" is not reachable
  • WSL2 ne peut pas atteindre le cdpUrl configuré
• Browser attachOnly is enabled and CDP websocket for profile "remote" is not reachable
  • le point de terminaison HTTP a répondu, mais le WebSocket DevTools n’a toujours pas pu être ouvert
• remplacements persistants de viewport / mode sombre / paramètres régionaux / mode hors ligne après une session distante
  • exécutez openclaw browser stop --browser-profile remote
  • cela ferme la session de contrôle active et libère l’état d’émulation Playwright/CDP sans redémarrer la Gateway ni le navigateur externe
• gateway timeout after 1500ms
  • il s’agit souvent encore d’un problème de joignabilité CDP ou d’un point de terminaison distant lent ou inaccessible
• No Chrome tabs found for profile="user"
  • profil Chrome MCP local à l’hôte sélectionné alors qu’aucun onglet local à cet hôte n’est disponible

​

Checklist de triage rapide

1. Windows : est-ce que curl http://127.0.0.1:9222/json/version fonctionne ?
2. WSL2 : est-ce que curl http://WINDOWS_HOST_OR_IP:9222/json/version fonctionne ?
3. Configuration OpenClaw : est-ce que browser.profiles.<name>.cdpUrl utilise exactement cette adresse joignable depuis WSL2 ?
4. Interface de contrôle : ouvrez-vous http://127.0.0.1:18789/ au lieu d’une IP LAN ?
5. Essayez-vous d’utiliser existing-session entre WSL2 et Windows au lieu du CDP distant brut ?

​

Conclusion pratique

• vérifiez d’abord localement le point de terminaison Chrome Windows
• vérifiez ensuite ce même point de terminaison depuis WSL2
• ne déboguez la configuration OpenClaw ou l’authentification de l’interface de contrôle qu’après cela