Dépannage de WSL2 + Windows + Chrome CDP distant

Dans la configuration courante avec hôtes séparés, le Gateway OpenClaw s’exécute dans WSL2, Chrome s’exécute sous Windows, et le contrôle du navigateur doit franchir la frontière WSL2/Windows. Plusieurs problèmes indépendants peuvent survenir simultanément (voir le problème nº 39369) : le transport CDP, la sécurité de l’origine de la Control UI et le jeton/l’appairage peuvent chacun échouer indépendamment tout en produisant des erreurs d’apparence similaire. Parcourez les couches ci-dessous dans l’ordre au lieu de tenter de deviner laquelle est défaillante.

Choisir d’abord le bon mode de navigateur

Option 1 : CDP distant brut de WSL2 vers Windows

Utilisez un profil de navigateur distant pointant depuis WSL2 vers un point de terminaison CDP de Chrome sous Windows. Choisissez cette option lorsque le Gateway reste dans WSL2, que Chrome s’exécute sous Windows et que le contrôle du navigateur doit franchir la frontière WSL2/Windows.

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

Utilisez le pilote existing-session (profil user) uniquement lorsque le Gateway s’exécute sur le même hôte que Chrome, que vous souhaitez utiliser l’état local du navigateur connecté, que vous n’avez pas besoin d’un transport du navigateur entre plusieurs hôtes et que vous n’avez pas besoin de responsebody, de l’exportation PDF, de l’interception des téléchargements ni d’actions par lots (les profils MCP Chrome ne les prennent pas en charge). Pour un Gateway sous WSL2 avec Chrome sous Windows, utilisez le CDP distant brut. MCP Chrome est local à l’hôte et ne constitue pas un pont entre WSL2 et Windows.

Architecture opérationnelle

WSL2 exécute le Gateway sur 127.0.0.1:18789
Windows ouvre la Control UI dans un navigateur normal à l’adresse 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 sous Windows
OpenClaw fait pointer un profil de navigateur vers l’adresse accessible depuis WSL2

Règle essentielle pour la Control UI

Lorsque l’interface est ouverte depuis Windows, utilisez l’hôte local Windows, sauf si vous disposez d’une configuration HTTPS intentionnelle :

http://127.0.0.1:18789/

N’utilisez pas par défaut une adresse IP du réseau local. Le protocole HTTP non chiffré sur une adresse de réseau local ou de tailnet peut déclencher un comportement d’origine non sécurisée ou d’authentification de l’appareil sans rapport avec CDP lui-même. Consultez Control UI.

Valider couche par couche

Procédez de haut en bas ; ne sautez aucune étape. Corriger une couche peut tout de même laisser visible une autre erreur provenant d’une couche inférieure.

Couche 1 : vérifier que Chrome fournit CDP sous Windows

chrome.exe --remote-debugging-port=9222 --user-data-dir="$env:LOCALAPPDATA\OpenClaw\ChromeCDP"

Chrome 136 et les versions ultérieures ignorent les options de ligne de commande de débogage distant pour le répertoire de données Chrome par défaut. Utilisez un répertoire de données distinct et non défini par défaut, comme illustré ci-dessus. Consultez la modification de sécurité du débogage distant de Chrome. Cela ne rend pas le profil Chrome normal connecté contrôlable à distance. Depuis Windows, vérifiez d’abord Chrome lui-même :

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

Si cette vérification échoue, diagnostiquez les écouteurs Windows ci-dessous. OpenClaw n’est pas encore en cause.

Diagnostiquer IPv4 et IPv6 avant de modifier portproxy

Chromium tente d’abord de lier le débogage distant à 127.0.0.1 et ne se rabat sur [::1] que si la liaison IPv4 échoue. Une règle v4tov4 persistante qui écoute sur 127.0.0.1:9222 peut occuper ce point de terminaison avant le démarrage de Chrome. Chrome se rabat alors sur [::1]:9222, tandis que l’ancienne règle redirige le trafic IPv4 vers son propre écouteur et renvoie une réponse vide. Vérifiez les écouteurs et les règles de proxy réels depuis Windows au lieu de les déduire de la version de Chrome :

netstat -ano | findstr :9222
netsh interface portproxy show all
curl.exe http://127.0.0.1:9222/json/version
curl.exe http://[::1]:9222/json/version

Utilisez tasklist /fi "PID eq <PID>" pour chaque PID indiqué par netstat.

Si chrome.exe répond sur 127.0.0.1, supprimez toute règle portproxy qui écoute également sur 127.0.0.1:9222. Redirigez uniquement l’adresse de l’adaptateur Windows accessible depuis WSL2 vers 127.0.0.1.
Si chrome.exe répond uniquement sur [::1], faites pointer l’écouteur accessible depuis WSL2 vers ::1 avec v4tov6 au lieu de rediriger vers une adresse IPv4 inutilisée :
netsh interface portproxy add v4tov6 listenaddress=WINDOWS_HOST_OR_IP listenport=9222 connectaddress=::1 connectport=9222

Liez l’écouteur à l’adresse de l’adaptateur dont WSL2 a besoin. N’exposez pas le port CDP sur 0.0.0.0, une adresse du réseau local ou une adresse de tailnet : CDP accorde le contrôle de la session du navigateur.

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

Depuis WSL2, testez l’adresse exacte que vous prévoyez d’utiliser dans cdpUrl :

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

Résultat attendu :

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

Si cette vérification échoue, Windows n’expose pas encore le port à WSL2, l’adresse est incorrecte du côté de WSL2, ou le pare-feu, la redirection de port ou le proxy fait défaut. Corrigez cela avant de modifier la configuration d’OpenClaw.

Couche 3 : configurer le bon profil de navigateur

Faites pointer OpenClaw vers l’adresse accessible depuis WSL2 :

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

Remarques :

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

Couche 4 : vérifier séparément la couche de la Control UI

Ouvrez http://127.0.0.1:18789/ depuis Windows, puis vérifiez :

que l’origine de la page correspond à ce qu’attend gateway.controlUi.allowedOrigins
que l’authentification par jeton ou l’appairage est correctement configuré
que vous ne diagnostiquez pas un problème d’authentification de la Control UI comme s’il s’agissait d’un problème de navigateur

Page utile : Control UI.

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

Depuis WSL2 :

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

Résultat attendu :

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

Erreurs courantes susceptibles d’induire en erreur

Message	Signification
`control-ui-insecure-auth`	problème d’origine ou de contexte sécurisé de l’interface, et non 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é
réponse CDP vide / `other side closed` via un portproxy	incompatibilité entre les écouteurs Windows ou boucle sur soi-même ; inspectez les deux familles d’adresses de bouclage et `netsh interface portproxy show all`
`Browser attachOnly is enabled and CDP websocket for profile "remote" is not reachable`	le point de terminaison HTTP a répondu, mais la WebSocket DevTools n’a pas pu être ouverte
paramètres obsolètes de fenêtre d’affichage, de mode sombre, de langue ou de mode hors ligne après une session distante	exécutez `openclaw browser --browser-profile remote stop` pour fermer la session et libérer la connexion Playwright/CDP mise en cache sans redémarrer le Gateway ni le navigateur externe
délai d’attente autour de `remoteCdpTimeoutMs` (1500 ms par défaut)	il s’agit généralement toujours d’un problème d’accessibilité de CDP ou d’un point de terminaison distant lent ou inaccessible
`Playwright page enumeration timed out after 3000ms`	la connexion au CDP distant a réussi, mais la lecture persistante de ses onglets s’est bloquée ; le délai est la valeur la plus élevée entre `remoteCdpTimeoutMs` et `remoteCdpHandshakeTimeoutMs`
`No Chrome tabs found for profile="user"`	le profil MCP Chrome local est sélectionné alors qu’aucun onglet local à l’hôte n’est disponible

Liste de contrôle pour un diagnostic rapide

Windows : laquelle des adresses 127.0.0.1 ou [::1] répond sur /json/version, et cet écouteur appartient-il à chrome.exe ?
WSL2 : curl http://WINDOWS_HOST_OR_IP:9222/json/version fonctionne-t-il ?
Configuration d’OpenClaw : browser.profiles.<name>.cdpUrl utilise-t-il exactement cette adresse accessible depuis WSL2 ?
Control UI : ouvrez-vous http://127.0.0.1:18789/ plutôt qu’une adresse IP du réseau local ?
Essayez-vous d’utiliser existing-session entre WSL2 et Windows au lieu du CDP distant brut ?

Vérifiez d’abord localement le point de terminaison de Chrome sous Windows, puis vérifiez le même point de terminaison depuis WSL2, et seulement ensuite diagnostiquez la configuration d’OpenClaw ou l’authentification de la Control UI.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

Dépannage de WSL2 + Windows + Chrome CDP distant

Choisir d’abord le bon mode de navigateur

Option 1 : CDP distant brut de WSL2 vers Windows

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

Architecture opérationnelle

Règle essentielle pour la Control UI

Valider couche par couche

Couche 1 : vérifier que Chrome fournit CDP sous Windows

Diagnostiquer IPv4 et IPv6 avant de modifier portproxy

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

Couche 3 : configurer le bon profil de navigateur

Couche 4 : vérifier séparément la couche de la Control UI

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

Erreurs courantes susceptibles d’induire en erreur

Liste de contrôle pour un diagnostic rapide

Voir aussi

​Choisir d’abord le bon mode de navigateur

​Option 1 : CDP distant brut de WSL2 vers Windows

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

​Architecture opérationnelle

​Règle essentielle pour la Control UI

​Valider couche par couche

​Couche 1 : vérifier que Chrome fournit CDP sous Windows

​Diagnostiquer IPv4 et IPv6 avant de modifier portproxy

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

​Couche 3 : configurer le bon profil de navigateur

​Couche 4 : vérifier séparément la couche de la Control UI

​Couche 5 : vérifier le contrôle du navigateur de bout en bout

​Erreurs courantes susceptibles d’induire en erreur

​Liste de contrôle pour un diagnostic rapide

​Voir aussi

Choisir d’abord le bon mode de navigateur

Option 1 : CDP distant brut de WSL2 vers Windows

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

Architecture opérationnelle

Règle essentielle pour la Control UI

Valider couche par couche

Couche 1 : vérifier que Chrome fournit CDP sous Windows

Diagnostiquer IPv4 et IPv6 avant de modifier portproxy

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

Couche 3 : configurer le bon profil de navigateur

Couche 4 : vérifier séparément la couche de la Control UI

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

Erreurs courantes susceptibles d’induire en erreur

Liste de contrôle pour un diagnostic rapide

Voir aussi