Solución de problemas WSL2 + Windows + Chrome CDP remoto

Esta guía cubre la configuración común de host dividido donde:

  • El Gateway de OpenClaw se ejecuta dentro de WSL2
  • Chrome se ejecuta en Windows
  • El control del navegador debe cruzar la frontera WSL2/Windows

También cubre el patrón de falla por capas del issue #39369: varios problemas independientes pueden aparecer a la vez, lo que hace que la capa equivocada parezca estar rota primero.

Elige el modo de navegador correcto primero

Tienes dos patrones válidos:

Opción 1: CDP remoto directo

Usa un perfil de navegador remoto que apunte desde WSL2 a un endpoint CDP de Chrome en Windows.

Elige esto cuando:

  • solo necesitas control del navegador
  • te sientes cómodo exponiendo la depuración remota de Chrome a WSL2
  • no necesitas el relay de extensión de Chrome

Opción 2: Relay de extensión de Chrome

Usa el perfil integrado chrome más la extensión de Chrome de OpenClaw.

Elige esto cuando:

  • quieres adjuntarte a una pestaña existente de Chrome en Windows con el botón de la barra de herramientas
  • quieres control basado en extensión en lugar de --remote-debugging-port directo
  • el relay mismo debe ser accesible a través de la frontera WSL2/Windows

Si usas el relay de extensión entre espacios de nombres, browser.relayBindHost es la configuración importante introducida en Navegador y Extensión de Chrome.

Arquitectura funcional

Forma de referencia:

  • WSL2 ejecuta el Gateway en 127.0.0.1:18789
  • Windows abre la UI de Control en un navegador normal en http://127.0.0.1:18789/
  • Chrome en Windows expone un endpoint CDP en el puerto 9222
  • WSL2 puede alcanzar ese endpoint CDP de Windows
  • OpenClaw apunta un perfil de navegador a la dirección que es accesible desde WSL2

Por qué esta configuración es confusa

Varias fallas pueden superponerse:

  • WSL2 no puede alcanzar el endpoint CDP de Windows
  • La UI de Control se abrió desde un origen no seguro
  • gateway.controlUi.allowedOrigins no coincide con el origen de la página
  • Falta token o emparejamiento
  • El perfil de navegador apunta a la dirección equivocada
  • El relay de extensión sigue siendo solo loopback cuando realmente necesitas acceso entre espacios de nombres

Por eso, arreglar una capa puede dejar visible un error diferente.

Regla crítica para la UI de Control

Cuando la UI se abre desde Windows, usa localhost de Windows a menos que tengas una configuración HTTPS deliberada.

Usa:

http://127.0.0.1:18789/

No uses por defecto una IP de LAN para la UI de Control. HTTP plano en una dirección de LAN o tailnet puede activar comportamiento de origen-inseguro/autenticación-de-dispositivo que no tiene relación con CDP en sí. Consulta UI de Control.

Valida por capas

Trabaja de arriba a abajo. No te saltes pasos.

Capa 1: Verifica que Chrome está sirviendo CDP en Windows

Inicia Chrome en Windows con depuración remota habilitada:

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

Desde Windows, verifica Chrome primero:

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

Si esto falla en Windows, OpenClaw aún no es el problema.

Capa 2: Verifica que WSL2 puede alcanzar ese endpoint de Windows

Desde WSL2, prueba la dirección exacta que planeas usar en cdpUrl:

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

Resultado esperado:

  • /json/version devuelve JSON con metadatos de Browser / Protocol-Version
  • /json/list devuelve JSON (un array vacío está bien si no hay páginas abiertas)

Si esto falla:

  • Windows no está exponiendo el puerto a WSL2 aún
  • La dirección es incorrecta para el lado de WSL2
  • Falta firewall / reenvío de puertos / proxy local

Arregla eso antes de tocar la configuración de OpenClaw.

Capa 3: Configura el perfil de navegador correcto

Para CDP remoto directo, apunta OpenClaw a la dirección accesible desde WSL2:

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

Notas:

  • Usa la dirección accesible desde WSL2, no la que solo funciona en Windows
  • Mantén attachOnly: true para navegadores gestionados externamente
  • Prueba la misma URL con curl antes de esperar que OpenClaw tenga éxito

Capa 4: Si usas el relay de extensión de Chrome en su lugar

Si la máquina del navegador y el Gateway están separados por una frontera de espacio de nombres, el relay puede necesitar una dirección de vinculación no-loopback.

Ejemplo:

{
  browser: {
    enabled: true,
    defaultProfile: "chrome",
    relayBindHost: "0.0.0.0",
  },
}

Usa esto solo cuando sea necesario:

  • El comportamiento por defecto es más seguro porque el relay permanece solo en loopback
  • 0.0.0.0 expande la superficie de exposición
  • Mantén la autenticación del Gateway, el emparejamiento de nodos y la red circundante privados

Si no necesitas el relay de extensión, prefiere el perfil de CDP remoto directo de arriba.

Capa 5: Verifica la capa de la UI de Control por separado

Abre la UI desde Windows:

http://127.0.0.1:18789/

Luego verifica:

  • El origen de la página coincide con lo que gateway.controlUi.allowedOrigins espera
  • La autenticación por token o emparejamiento está configurada correctamente
  • No estás depurando un problema de autenticación de la UI de Control como si fuera un problema del navegador

Página útil:

Capa 6: Verifica el control del navegador de extremo a extremo

Desde WSL2:

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

Para el relay de extensión:

openclaw browser tabs --browser-profile chrome

Resultado esperado:

  • La pestaña se abre en Chrome de Windows
  • openclaw browser tabs devuelve el objetivo
  • Las acciones posteriores (snapshot, screenshot, navigate) funcionan desde el mismo perfil

Errores comunes engañosos

Trata cada mensaje como una pista específica de capa:

  • control-ui-insecure-auth
    • Problema de origen de UI / contexto seguro, no un problema de transporte CDP
  • token_missing
    • Problema de configuración de autenticación
  • pairing required
    • Problema de aprobación de dispositivo
  • Remote CDP for profile "remote" is not reachable
    • WSL2 no puede alcanzar el cdpUrl configurado
  • gateway timeout after 1500ms
    • A menudo sigue siendo accesibilidad CDP o un endpoint remoto lento/inalcanzable
  • Chrome extension relay is running, but no tab is connected
    • Perfil de relay de extensión seleccionado, pero aún no existe pestaña adjunta

Lista de verificación rápida

  1. Windows: ¿funciona curl http://127.0.0.1:9222/json/version?
  2. WSL2: ¿funciona curl http://WINDOWS_HOST_OR_IP:9222/json/version?
  3. Configuración de OpenClaw: ¿browser.profiles.<name>.cdpUrl usa esa dirección exacta accesible desde WSL2?
  4. UI de Control: ¿estás abriendo http://127.0.0.1:18789/ en lugar de una IP de LAN?
  5. Solo relay de extensión: ¿realmente necesitas browser.relayBindHost, y si es así está configurado explícitamente?

Conclusión práctica

La configuración generalmente es viable. La parte difícil es que el transporte del navegador, la seguridad de origen de la UI de Control, token/emparejamiento y la topología del relay de extensión pueden fallar independientemente mientras se ven similares desde el lado del usuario.

Ante la duda:

  • Verifica el endpoint de Chrome en Windows localmente primero
  • Verifica el mismo endpoint desde WSL2 segundo
  • Solo entonces depura la configuración de OpenClaw o la autenticación de la UI de Control
Siguiente
Overview
arrow_forward