Risoluzione dei problemi di WSL2 + Windows + CDP remoto di Chrome

Nella comune configurazione con host separati, OpenClaw Gateway viene eseguito all'interno di WSL2, Chrome viene eseguito su Windows e il controllo del browser deve attraversare il confine tra WSL2 e Windows. Possono emergere contemporaneamente diversi problemi indipendenti (vedere issue #39369): il trasporto CDP, la sicurezza dell'origine della UI di controllo e il token/associazione possono non funzionare ciascuno autonomamente, producendo errori dall'aspetto simile. Esamina nell'ordine i livelli riportati di seguito anziché tentare di indovinare quale non funziona.

Scegli prima la modalità browser corretta

Opzione 1: CDP remoto diretto da WSL2 a Windows

Usa un profilo browser remoto che da WSL2 punti a un endpoint CDP di Chrome su Windows. Scegli questa opzione quando il Gateway rimane all'interno di WSL2, Chrome viene eseguito su Windows e il controllo del browser deve attraversare il confine tra WSL2 e Windows.

Opzione 2: Chrome MCP locale all'host

Usa il driver existing-session (profilo user) solo quando il Gateway viene eseguito sullo stesso host di Chrome, vuoi utilizzare lo stato locale del browser con accesso effettuato, non ti serve il trasporto del browser tra host e non ti servono responsebody, l'esportazione in PDF, l'intercettazione dei download o le azioni in batch (i profili Chrome MCP non supportano queste funzionalità).

Per Gateway WSL2 + Chrome su Windows, usa CDP remoto diretto. Chrome MCP è locale all'host, non è un ponte tra WSL2 e Windows.

Architettura funzionante

• WSL2 esegue il Gateway su 127.0.0.1:18789
• Windows apre la UI di controllo in un browser normale all'indirizzo http://127.0.0.1:18789/
• Chrome su Windows espone un endpoint CDP sulla porta 9222
• WSL2 può raggiungere tale endpoint CDP di Windows
• OpenClaw indirizza un profilo browser all'indirizzo raggiungibile da WSL2

Regola fondamentale per la UI di controllo

Quando la UI viene aperta da Windows, usa il localhost di Windows, a meno che tu non disponga di una configurazione HTTPS intenzionale:

http://127.0.0.1:18789/

Non usare per impostazione predefinita un indirizzo IP LAN. HTTP semplice su un indirizzo LAN o tailnet può attivare comportamenti relativi a un'origine non sicura o all'autenticazione del dispositivo, non correlati a CDP. Vedere UI di controllo.

Convalida per livelli

Procedi dall'alto verso il basso; non saltare passaggi. La correzione di un livello può comunque lasciare visibile un errore diverso proveniente da un livello successivo.

Livello 1: verifica che Chrome esponga CDP su Windows

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

Chrome 136 e versioni successive ignorano le opzioni della riga di comando per il debug remoto quando viene usata la directory dati predefinita di Chrome. Usa una directory dati separata e non predefinita, come mostrato sopra. Vedere la modifica alla sicurezza del debug remoto di Chrome. Ciò non rende controllabile da remoto il normale profilo Chrome con accesso effettuato.

Da Windows, verifica innanzitutto Chrome stesso:

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

Se l'operazione non riesce, diagnostica i listener di Windows riportati di seguito. OpenClaw non è ancora il problema.

Diagnostica IPv4 e IPv6 prima di modificare portproxy

Chromium tenta prima di associare il debug remoto a 127.0.0.1 e passa a [::1] solo se l'associazione IPv4 non riesce. Una regola v4tov4 persistente in ascolto su 127.0.0.1:9222 può occupare tale endpoint prima dell'avvio di Chrome. Chrome quindi passa a [::1]:9222, mentre la vecchia regola inoltra il traffico IPv4 nuovamente al proprio listener e restituisce una risposta vuota.

Controlla i listener e le regole proxy effettivi da Windows, anziché dedurli dalla versione di Chrome:

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

Usa tasklist /fi "PID eq <PID>" per ogni PID restituito da netstat.

• Se chrome.exe risponde su 127.0.0.1, rimuovi qualsiasi regola portproxy che sia anch'essa in ascolto su 127.0.0.1:9222. Inoltra soltanto l'indirizzo dell'adattatore Windows raggiungibile da WSL2 verso 127.0.0.1.

• Se chrome.exe risponde solo su [::1], indirizza il listener raggiungibile da WSL2 a ::1 con v4tov6, invece di inoltrarlo a un indirizzo IPv4 inutilizzato:

  netsh interface portproxy add v4tov6 listenaddress=WINDOWS_HOST_OR_IP listenport=9222 connectaddress=::1 connectport=9222

Associa il listener all'indirizzo dell'adattatore necessario a WSL2. Non esporre la porta CDP su 0.0.0.0, su un indirizzo LAN o su un indirizzo tailnet: CDP concede il controllo della sessione del browser.

Livello 2: verifica che WSL2 possa raggiungere tale endpoint di Windows

Da WSL2, verifica l'indirizzo esatto che intendi usare in cdpUrl:

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

Risultato corretto:

• /json/version restituisce JSON con i metadati Browser / Protocol-Version
• /json/list restituisce JSON (un array vuoto va bene se non ci sono pagine aperte)

Se l'operazione non riesce, Windows non sta ancora esponendo la porta a WSL2, l'indirizzo è errato per il lato WSL2 oppure manca il firewall, l'inoltro della porta o il proxy. Correggi il problema prima di modificare la configurazione di OpenClaw.

Livello 3: configura il profilo browser corretto

Indirizza OpenClaw all'indirizzo raggiungibile da WSL2:

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

Note:

• usa l'indirizzo raggiungibile da WSL2, non quello che funziona soltanto su Windows
• mantieni attachOnly: true per i browser gestiti esternamente
• cdpUrl può essere http://, https://, ws:// o wss://
• usa HTTP(S) quando vuoi che OpenClaw rilevi /json/version
• usa WS(S) solo quando il fornitore del browser ti fornisce un URL diretto per il socket DevTools
• verifica lo stesso URL con curl prima di aspettarti che OpenClaw funzioni

Livello 4: verifica separatamente il livello della UI di controllo

Apri http://127.0.0.1:18789/ da Windows, quindi verifica:

• che l'origine della pagina corrisponda a quanto previsto da gateway.controlUi.allowedOrigins
• che l'autenticazione tramite token o l'associazione sia configurata correttamente
• che tu non stia diagnosticando un problema di autenticazione della UI di controllo come se fosse un problema del browser

Pagina utile: UI di controllo.

Livello 5: verifica il controllo del browser end-to-end

Da WSL2:

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

Risultato corretto:

• la scheda si apre in Chrome su Windows
• browser tabs restituisce la destinazione
• le azioni successive (snapshot, screenshot, navigate) funzionano con lo stesso profilo

Errori fuorvianti comuni

Elenco di controllo per una diagnosi rapida

1. Windows: quale tra 127.0.0.1 e [::1] risponde su /json/version e tale listener appartiene a chrome.exe?
2. WSL2: curl http://WINDOWS_HOST_OR_IP:9222/json/version funziona?
3. Configurazione di OpenClaw: browser.profiles.<name>.cdpUrl usa esattamente tale indirizzo raggiungibile da WSL2?
4. UI di controllo: stai aprendo http://127.0.0.1:18789/ anziché un indirizzo IP LAN?
5. Stai tentando di usare existing-session tra WSL2 e Windows invece del CDP remoto diretto?

Verifica innanzitutto l'endpoint Chrome di Windows localmente, quindi verifica lo stesso endpoint da WSL2 e solo a quel punto diagnostica la configurazione di OpenClaw o l'autenticazione della UI di controllo.

Contenuti correlati

• Browser
• Accesso al browser
• Risoluzione dei problemi del browser su Linux