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/version
curl.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 :9222
netsh interface portproxy show all
curl.exe http://127.0.0.1:9222/json/version
curl.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/version
curl 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.com
openclaw 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

Messaggio	Significato
`control-ui-insecure-auth`	problema dell’origine o del contesto sicuro della UI, non un problema del trasporto CDP
`token_missing`	problema di configurazione dell’autenticazione
`pairing required`	problema di approvazione del dispositivo
`Remote CDP for profile "remote" is not reachable`	WSL2 non può raggiungere il `cdpUrl` configurato
risposta CDP vuota / `other side closed` attraverso un portproxy	mancata corrispondenza del listener di Windows o auto-loop; controlla entrambe le famiglie di loopback e `netsh interface portproxy show all`
`Browser attachOnly is enabled and CDP websocket for profile "remote" is not reachable`	l’endpoint HTTP ha risposto, ma non è stato possibile aprire il WebSocket DevTools
viewport / modalità scura / impostazioni locali / override offline obsoleti dopo una sessione remota	esegui `openclaw browser --browser-profile remote stop` per chiudere la sessione e rilasciare la connessione Playwright/CDP memorizzata nella cache senza riavviare il Gateway o il browser esterno
timeout relativo a `remoteCdpTimeoutMs` (valore predefinito 1500 ms)	in genere si tratta comunque della raggiungibilità CDP oppure di un endpoint remoto lento o irraggiungibile
`Playwright page enumeration timed out after 3000ms`	il CDP remoto si è connesso, ma la lettura persistente delle schede si è bloccata; la scadenza corrisponde al valore maggiore tra `remoteCdpTimeoutMs` e `remoteCdpHandshakeTimeoutMs`
`No Chrome tabs found for profile="user"`	è stato selezionato il profilo Chrome MCP locale, ma non sono disponibili schede locali all’host

Elenco di controllo per una diagnosi rapida

Windows: quale tra 127.0.0.1 e [::1] risponde su /json/version e tale listener appartiene a chrome.exe?
WSL2: curl http://WINDOWS_HOST_OR_IP:9222/json/version funziona?
Configurazione di OpenClaw: browser.profiles.<name>.cdpUrl usa esattamente tale indirizzo raggiungibile da WSL2?
UI di controllo: stai aprendo http://127.0.0.1:18789/ anziché un indirizzo IP LAN?
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.

Overview

Plugins

Plugin guides

Building plugins

Skills

Automation

Tools

Agent coordination

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

Scegli prima la modalità browser corretta

Opzione 1: CDP remoto diretto da WSL2 a Windows

Opzione 2: Chrome MCP locale all’host

Architettura funzionante

Regola fondamentale per la UI di controllo

Convalida per livelli

Livello 1: verifica che Chrome esponga CDP su Windows

Diagnostica IPv4 e IPv6 prima di modificare portproxy

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

Livello 3: configura il profilo browser corretto

Livello 4: verifica separatamente il livello della UI di controllo

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

Errori fuorvianti comuni

Elenco di controllo per una diagnosi rapida

Contenuti correlati

​Scegli prima la modalità browser corretta

​Opzione 1: CDP remoto diretto da WSL2 a Windows

​Opzione 2: Chrome MCP locale all’host

​Architettura funzionante

​Regola fondamentale per la UI di controllo

​Convalida per livelli

​Livello 1: verifica che Chrome esponga CDP su Windows

​Diagnostica IPv4 e IPv6 prima di modificare portproxy

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

​Livello 3: configura il profilo browser corretto

​Livello 4: verifica separatamente il livello della UI di controllo

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

​Errori fuorvianti comuni

​Elenco di controllo per una diagnosi rapida

​Contenuti correlati

Scegli prima la modalità browser corretta

Opzione 1: CDP remoto diretto da WSL2 a Windows

Opzione 2: Chrome MCP locale all’host

Architettura funzionante

Regola fondamentale per la UI di controllo

Convalida per livelli

Livello 1: verifica che Chrome esponga CDP su Windows

Diagnostica IPv4 e IPv6 prima di modificare portproxy

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

Livello 3: configura il profilo browser corretto

Livello 4: verifica separatamente il livello della UI di controllo

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

Errori fuorvianti comuni

Elenco di controllo per una diagnosi rapida

Contenuti correlati