Soluciona problemas de OpenClaw en WSL2 y Windows

¿Alguna vez has sentido que configurar herramientas entre WSL2 y Windows es como intentar que dos personas que hablan idiomas distintos se entiendan a través de un muro? Es frustrante cuando algo debería funcionar por red local pero simplemente se queda cargando sin dar explicaciones claras.

Si estás intentando controlar Chrome desde tu entorno de Linux pero el navegador vive en Windows, seguramente te has topado con problemas de red, permisos o firewalls. Esta guía te ayudará a desenredar esa red de fallos solapados para que todo funcione como debe.

Solución de problemas: WSL2 + Windows + remote Chrome CDP

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

• OpenClaw Gateway se ejecuta dentro de WSL2
• Chrome se ejecuta en Windows
• El control del browser debe cruzar la frontera entre WSL2 y Windows

También cubre el patrón de fallos en capas del issue #39369: varios problemas independientes pueden aparecer a la vez, lo que hace que la capa equivocada parezca rota al principio.

Elige primero el modo de browser adecuado

Tienes dos patrones válidos:

Opción 1: Raw remote CDP

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

Elige esto cuando:

• Solo necesitas control del browser
• Te sientes cómodo exponiendo el remote debugging de Chrome a WSL2
• No necesitas el Chrome extension relay

Opción 2: Chrome extension relay

Usa el perfil chrome integrado junto con la OpenClaw Chrome extension.

Elige esto cuando:

• Quieres conectarte a una pestaña existente de Windows Chrome con el botón de la barra de herramientas
• Prefieres el control basado en extensiones en lugar de usar --remote-debugging-port directamente
• El relay mismo debe ser accesible a través de la frontera WSL2/Windows

Si usas el extension relay a través de namespaces, browser.relayBindHost es el ajuste importante introducido en Browser y Chrome extension.

Arquitectura de trabajo

Forma de referencia:

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

Por qué esta configuración es confusa

Varios fallos pueden solaparse:

• WSL2 no puede alcanzar el endpoint CDP de Windows
• La Control UI se abre desde un origen no seguro
• gateway.controlUi.allowedOrigins no coincide con el origen de la página
• Falta el token o el emparejamiento (pairing)
• El perfil de browser apunta a la dirección incorrecta
• El extension relay sigue configurado solo para loopback cuando realmente necesitas acceso entre namespaces

Debido a esto, arreglar una capa puede dejar a la vista un error diferente.

Regla crítica para la Control UI

Cuando abras la UI desde Windows, usa el 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 Control UI. El HTTP plano en una dirección de LAN o tailnet puede activar comportamientos de origen no seguro o de autenticación de dispositivo que no tienen relación con el CDP en sí. Consulta Control UI.

Valida por capas

Trabaja de arriba hacia abajo. No te saltes pasos.

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

Inicia Chrome en Windows con el remote debugging habilitado:

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

Desde Windows, verifica primero el propio Chrome:

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 pueda 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

Buen resultado:

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

Si esto falla:

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

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

Capa 3: Configura el perfil de browser correcto

Para un raw remote CDP, apunta OpenClaw a la dirección que sea 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 browsers gestionados externamente
• Prueba la misma URL con curl antes de esperar que OpenClaw funcione

Capa 4: Si usas el Chrome extension relay en su lugar

Si la máquina del browser y el Gateway están separados por un límite de namespace, es posible que el relay necesite una dirección de escucha (bind address) que no sea de 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 se mantiene solo en loopback
• 0.0.0.0 amplía la superficie de exposición
• Mantén la autenticación del Gateway, el emparejamiento de nodos y la red circundante como privados

Si no necesitas el extension relay, prefiere el perfil de raw remote CDP mencionado arriba.

Capa 5: Verifica la capa de la Control UI 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 el emparejamiento están configurados correctamente
• No estás intentando solucionar un problema de autenticación de la Control UI como si fuera un problema del browser

Página útil:

• Control UI

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

Desde WSL2:

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

Para el extension relay:

openclaw browser tabs --browser-profile chrome

Buen resultado:

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

Errores comunes que confunden

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

• control-ui-insecure-auth
  • Problema de origen de la UI o de contexto seguro (secure-context), no un problema de transporte CDP
• token_missing
  • Problema de configuración de autenticación
• pairing required
  • Problema de aprobación del dispositivo
• Remote CDP for profile "remote" is not reachable
  • WSL2 no puede alcanzar la cdpUrl configurada
• gateway timeout after 1500ms
  • A menudo sigue siendo un problema de alcance de CDP o un endpoint remoto lento/inalcanzable
• Chrome extension relay is running, but no tab is connected
  • Se seleccionó el perfil de extension relay, pero aún no existe ninguna pestaña conectada

Checklist de triaje rápido

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: ¿usa browser.profiles.<name>.cdpUrl esa dirección exacta accesible desde WSL2?
4. Control UI: ¿estás abriendo http://127.0.0.1:18789/ en lugar de una IP de LAN?
5. Solo para extension relay: ¿realmente necesitas browser.relayBindHost? Si es así, ¿está configurado explícitamente?

Conclusión práctica

La configuración suele ser viable. Lo difícil es que el transporte del browser, la seguridad de origen de la Control UI, el token/emparejamiento y la topología del extension-relay pueden fallar de forma independiente mientras parecen lo mismo desde el lado del usuario.

Cuando tengas dudas:

• Primero, verifica el endpoint de Chrome en Windows localmente
• Segundo, verifica el mismo endpoint desde WSL2
• Solo entonces depura la configuración de OpenClaw o la autenticación de la Control UI

AI Setup Assistant

Siguientes pasos

• Control UI
• Browser
• Chrome extension