Risoluzione dei problemi di WSL2 + Windows + Chrome CDP remoto

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Scegli prima la modalità browser corretta

​

Opzione 1: CDP remoto grezzo da WSL2 a Windows

• il Gateway rimane dentro WSL2
• Chrome viene eseguito su Windows
• hai bisogno che il controllo del browser attraversi il confine WSL2/Windows

​

Opzione 2: Chrome MCP locale all’host

• OpenClaw e Chrome sono sulla stessa macchina
• vuoi lo stato del browser locale con sessione avviata
• non hai bisogno del trasporto browser tra host
• non hai bisogno di percorsi avanzati gestiti/solo raw-CDP come responsebody, esportazione PDF, intercettazione dei download o azioni in batch

​

Architettura funzionante

• WSL2 esegue il Gateway su 127.0.0.1:18789
• Windows apre l’interfaccia di controllo in un browser normale su http://127.0.0.1:18789/
• Chrome su Windows espone un endpoint CDP sulla porta 9222
• WSL2 può raggiungere quell’endpoint CDP di Windows
• OpenClaw punta un profilo browser all’indirizzo raggiungibile da WSL2

​

Perché questa configurazione crea confusione

• WSL2 non riesce a raggiungere l’endpoint CDP di Windows
• l’interfaccia di controllo viene aperta da un’origine non sicura
• gateway.controlUi.allowedOrigins non corrisponde all’origine della pagina
• token o abbinamento mancanti
• il profilo browser punta all’indirizzo sbagliato

​

Regola critica per l’interfaccia di controllo

​

Convalida per livelli

​

Livello 1: Verifica che Chrome stia servendo CDP su 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

​

Livello 2: Verifica che WSL2 possa raggiungere quell’endpoint Windows

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

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

• Windows non sta ancora esponendo la porta a WSL2
• l’indirizzo è sbagliato dal lato WSL2
• firewall / port forwarding / proxy locale sono ancora mancanti

​

Livello 3: Configura il profilo browser corretto

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

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

​

Livello 4: Verifica separatamente il livello dell’interfaccia di controllo

• l’origine della pagina corrisponde a ciò che gateway.controlUi.allowedOrigins si aspetta
• l’autenticazione con token o l’abbinamento sono configurati correttamente
• non stai facendo debug di un problema di autenticazione dell’interfaccia di controllo come se fosse un problema del browser

• Interfaccia di controllo

​

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

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

• la scheda si apre in Chrome su Windows
• openclaw browser tabs restituisce il target
• le azioni successive (snapshot, screenshot, navigate) funzionano dallo stesso profilo

​

Errori fuorvianti comuni

• control-ui-insecure-auth
  • problema di origine UI / contesto sicuro, non un problema di 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 riesce a raggiungere il cdpUrl configurato
• Browser attachOnly is enabled and CDP websocket for profile "remote" is not reachable
  • l’endpoint HTTP ha risposto, ma il WebSocket DevTools non ha comunque potuto essere aperto
• override obsoleti di viewport / modalità scura / locale / offline dopo una sessione remota
  • esegui openclaw browser stop --browser-profile remote
  • questo chiude la sessione di controllo attiva e rilascia lo stato di emulazione Playwright/CDP senza riavviare il gateway o il browser esterno
• gateway timeout after 1500ms
  • spesso è ancora raggiungibilità CDP o un endpoint remoto lento/non raggiungibile
• No Chrome tabs found for profile="user"
  • profilo Chrome MCP locale selezionato quando non sono disponibili schede locali all’host

​

Checklist di triage rapida

1. Windows: curl http://127.0.0.1:9222/json/version funziona?
2. WSL2: curl http://WINDOWS_HOST_OR_IP:9222/json/version funziona?
3. Configurazione OpenClaw: browser.profiles.<name>.cdpUrl usa esattamente quell’indirizzo raggiungibile da WSL2?
4. Interfaccia di controllo: stai aprendo http://127.0.0.1:18789/ invece di un IP LAN?
5. Stai cercando di usare existing-session attraverso WSL2 e Windows invece di CDP remoto grezzo?

​

Indicazione pratica

• verifica prima localmente l’endpoint Chrome di Windows
• verifica poi lo stesso endpoint da WSL2
• solo dopo fai debug della configurazione OpenClaw o dell’autenticazione dell’interfaccia di controllo

​

Correlati

• Browser
• Login del browser
• Risoluzione dei problemi del browser su Linux