Navegador (gestionado por OpenClaw)

OpenClaw puede ejecutar un perfil dedicado de Chrome/Brave/Edge/Chromium que controla el agente. Está aislado de tu navegador personal y se gestiona mediante un pequeño servicio local de control dentro del Gateway (solo loopback).

Vista para principiantes:

• Piensa en él como un navegador separado, solo para el agente.
• El perfil openclaw no toca tu perfil de navegador personal.
• El agente puede abrir pestañas, leer páginas, hacer clic y escribir en una vía segura.
• El perfil integrado user se conecta a tu sesión real de Chrome con sesión iniciada mediante Chrome MCP.

# Lo que obtienes

• Un perfil de navegador separado llamado openclaw (acento naranja por defecto).
• Control determinista de pestañas (listar/abrir/enfocar/cerrar).
• Acciones del agente (clic/escribir/arrastrar/seleccionar), instantáneas, capturas de pantalla, PDF.
• Una skill browser-automation incluida que enseña a los agentes el bucle de recuperación de instantáneas, pestañas estables, referencias obsoletas y bloqueadores manuales cuando el plugin de navegador está habilitado.
• Soporte opcional para varios perfiles (openclaw, work, remote, ...).

Este navegador no es tu navegador diario. Es una superficie segura y aislada para la automatización y verificación del agente.

# Inicio rápido

openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

Si recibes "Browser disabled", habilítalo en la configuración (consulta abajo) y reinicia el Gateway.

Si openclaw browser no existe en absoluto, o el agente dice que la herramienta de navegador no está disponible, ve a Comando o herramienta de navegador faltante.

# Control del plugin

La herramienta browser predeterminada es un plugin incluido. Deshabilítala para reemplazarla por otro plugin que registre el mismo nombre de herramienta browser:

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

Los valores predeterminados necesitan tanto plugins.entries.browser.enabled como browser.enabled=true. Deshabilitar solo el plugin elimina la CLI openclaw browser, el método de gateway browser.request, la herramienta del agente y el servicio de control como una sola unidad; tu configuración browser.* permanece intacta para un reemplazo.

Los cambios de configuración del navegador requieren reiniciar el Gateway para que el plugin pueda volver a registrar su servicio.

# Guía para agentes

Nota sobre el perfil de herramientas: tools.profile: "coding" incluye web_search y web_fetch, pero no incluye la herramienta browser completa. Si el agente o un subagente generado debe usar automatización de navegador, añade browser en la etapa de perfil:

{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}

Para un único agente, usa agents.list[].tools.alsoAllow: ["browser"]. tools.subagents.tools.allow: ["browser"] por sí solo no basta, porque la política de subagentes se aplica después del filtrado de perfil.

El plugin de navegador incluye dos niveles de guía para agentes:

• La descripción de la herramienta browser contiene el contrato compacto siempre activo: elegir el perfil correcto, mantener las referencias en la misma pestaña, usar tabId/etiquetas para dirigir pestañas y cargar la skill de navegador para trabajo de varios pasos.
• La skill browser-automation incluida contiene el bucle operativo más largo: comprobar estado/pestañas primero, etiquetar pestañas de tarea, tomar una instantánea antes de actuar, volver a tomar una instantánea después de cambios en la interfaz, recuperar referencias obsoletas una vez, e informar bloqueadores de inicio de sesión/2FA/captcha o cámara/micrófono como acción manual en lugar de adivinar.

Las Skills incluidas en plugins aparecen en las Skills disponibles del agente cuando el plugin está habilitado. Las instrucciones completas de la skill se cargan bajo demanda, así que los turnos rutinarios no pagan el coste completo de tokens.

# Comando o herramienta de navegador faltante

Si openclaw browser es desconocido después de una actualización, falta browser.request, o el agente informa que la herramienta de navegador no está disponible, la causa habitual es una lista plugins.allow que omite browser y no existe ningún bloque raíz de configuración browser. Añádelo:

{
  plugins: {
    allow: ["telegram", "browser"],
  },
}

Un bloque raíz explícito browser, por ejemplo browser.enabled=true o browser.profiles.<name>, activa el plugin de navegador incluido incluso con un plugins.allow restrictivo, coincidiendo con el comportamiento de configuración de canales. plugins.entries.browser.enabled=true y tools.alsoAllow: ["browser"] no sustituyen por sí solos la pertenencia a la lista de permitidos. Eliminar plugins.allow por completo también restaura el valor predeterminado.

# Perfiles: openclaw frente a user

• openclaw: navegador gestionado y aislado (no requiere extensión).
• user: perfil integrado de conexión Chrome MCP para tu sesión real de Chrome con sesión iniciada.

Para llamadas de herramientas de navegador del agente:

• Predeterminado: usar el navegador aislado openclaw.
• Prefiere profile="user" cuando importen las sesiones existentes con inicio de sesión y el usuario esté frente al ordenador para hacer clic/aprobar cualquier aviso de conexión.
• profile es la anulación explícita cuando quieres un modo de navegador específico.

Establece browser.defaultProfile: "openclaw" si quieres el modo gestionado por defecto.

# Configuración

La configuración del navegador reside en ~/.openclaw/openclaw.json.

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)
    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)
    actionTimeoutMs: 60000, // default browser act timeout (ms)
    tabCleanup: {
      enabled: true, // default: true
      idleMinutes: 120, // set 0 to disable idle cleanup
      maxTabsPerSession: 8, // set 0 to disable the per-session cap
      sweepMinutes: 5,
    },
    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

# Usar Brave u otro navegador basado en Chromium

Si tu navegador predeterminado del sistema está basado en Chromium (Chrome/Brave/Edge/etc), OpenClaw lo usa automáticamente. Configura browser.executablePath para anular la autodetección. Los valores executablePath de nivel superior y por perfil aceptan ~ para el directorio de inicio de tu sistema operativo:

openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

O configúralo en la configuración, por plataforma:

{
browser: {
executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
},
}

{
browser: {
executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
},
}

{
browser: {
executablePath: "/usr/bin/brave-browser",
},
}

executablePath por perfil solo afecta a los perfiles gestionados locales que OpenClaw inicia. Los perfiles existing-session se adjuntan en cambio a un navegador ya en ejecución, y los perfiles CDP remotos usan el navegador detrás de cdpUrl.

# Control local frente a remoto

• Control local (predeterminado): el Gateway inicia el servicio de control de loopback y puede iniciar un navegador local.
• Control remoto (host de nodo): ejecuta un host de nodo en la máquina que tiene el navegador; el Gateway redirige las acciones del navegador hacia él.
• CDP remoto: configura browser.profiles.<name>.cdpUrl (o browser.cdpUrl) para adjuntarte a un navegador remoto basado en Chromium. En este caso, OpenClaw no iniciará un navegador local.
• Para servicios CDP gestionados externamente en loopback (por ejemplo, Browserless en Docker publicado en 127.0.0.1), configura también attachOnly: true. El CDP en loopback sin attachOnly se trata como un perfil de navegador gestionado localmente por OpenClaw.
• headless solo afecta a los perfiles gestionados locales que OpenClaw inicia. No reinicia ni cambia navegadores de sesión existente o CDP remotos.
• executablePath sigue la misma regla de perfil gestionado local. Cambiarlo en un perfil gestionado local en ejecución marca ese perfil para reinicio/reconciliación, de modo que el siguiente inicio use el nuevo binario.

El comportamiento de detención difiere según el modo de perfil:

• perfiles gestionados locales: openclaw browser stop detiene el proceso del navegador que OpenClaw inició
• perfiles solo adjuntar y CDP remotos: openclaw browser stop cierra la sesión de control activa y libera las anulaciones de emulación de Playwright/CDP (viewport, esquema de color, configuración regional, zona horaria, modo sin conexión y estado similar), aunque OpenClaw no haya iniciado ningún proceso de navegador

Las URL de CDP remoto pueden incluir autenticación:

• Tokens de consulta (p. ej., https://provider.example?token=<token>)
• Autenticación HTTP Basic (p. ej., https://user:[email protected])

OpenClaw conserva la autenticación al llamar a los endpoints /json/* y al conectarse al WebSocket de CDP. Prefiere variables de entorno o gestores de secretos para los tokens en lugar de confirmarlos en archivos de configuración.

# Proxy de navegador de Node (predeterminado sin configuración)

Si ejecutas un host de nodo en la máquina que tiene tu navegador, OpenClaw puede enrutar automáticamente las llamadas a herramientas del navegador a ese nodo sin configuración adicional del navegador. Esta es la ruta predeterminada para gateways remotos.

Notas:

• El host de nodo expone su servidor local de control del navegador mediante un comando proxy.
• Los perfiles provienen de la propia configuración browser.profiles del nodo (igual que en local).
• nodeHost.browserProxy.allowProfiles es opcional. Déjalo vacío para el comportamiento heredado/predeterminado: todos los perfiles configurados siguen estando accesibles a través del proxy, incluidas las rutas de creación/eliminación de perfiles.
• Si configuras nodeHost.browserProxy.allowProfiles, OpenClaw lo trata como un límite de privilegio mínimo: solo se pueden dirigir perfiles permitidos y las rutas persistentes de creación/eliminación de perfiles quedan bloqueadas en la superficie del proxy.
• Desactívalo si no lo quieres:
  • En el nodo: nodeHost.browserProxy.enabled=false
  • En el gateway: gateway.nodes.browser.mode="off"

# Browserless (CDP remoto alojado)

Browserless es un servicio Chromium alojado que expone URL de conexión CDP mediante HTTPS y WebSocket. OpenClaw puede usar cualquiera de las dos formas, pero para un perfil de navegador remoto la opción más simple es la URL directa de WebSocket de la documentación de conexión de Browserless.

Ejemplo:

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

Notas:

• Sustituye <BROWSERLESS_API_KEY> por tu token real de Browserless.
• Elige el endpoint de región que coincida con tu cuenta de Browserless (consulta su documentación).
• Si Browserless te da una URL base HTTPS, puedes convertirla a wss:// para una conexión CDP directa o conservar la URL HTTPS y dejar que OpenClaw descubra /json/version.

# Browserless Docker en el mismo host

Cuando Browserless se autoaloja en Docker y OpenClaw se ejecuta en el host, trata Browserless como un servicio CDP gestionado externamente:

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}

La dirección en browser.profiles.browserless.cdpUrl debe ser accesible desde el proceso de OpenClaw. Browserless también debe anunciar un endpoint accesible coincidente; configura EXTERNAL de Browserless con esa misma base WebSocket pública hacia OpenClaw, como ws://127.0.0.1:3000, ws://browserless:3000 o una dirección estable de red privada Docker. Si /json/version devuelve webSocketDebuggerUrl apuntando a una dirección que OpenClaw no puede alcanzar, CDP HTTP puede parecer saludable mientras el adjunto WebSocket sigue fallando.

No dejes attachOnly sin configurar para un perfil Browserless en loopback. Sin attachOnly, OpenClaw trata el puerto de loopback como un perfil de navegador gestionado localmente e informa que el puerto está en uso pero no pertenece a OpenClaw.

# Proveedores CDP de WebSocket directo

Algunos servicios de navegador alojados exponen un endpoint WebSocket directo en lugar de la detección CDP estándar basada en HTTP (/json/version). OpenClaw acepta tres formas de URL CDP y elige automáticamente la estrategia de conexión correcta:

• Detección HTTP(S) - http://host[:port] o https://host[:port]. OpenClaw llama a /json/version para descubrir la URL del depurador WebSocket y luego se conecta. Sin alternativa WebSocket.
• Endpoints WebSocket directos - ws://host[:port]/devtools/<kind>/<id> o wss://... con una ruta /devtools/browser|page|worker|shared_worker|service_worker/<id>. OpenClaw se conecta directamente mediante un handshake WebSocket y omite /json/version por completo.
• Raíces WebSocket simples - ws://host[:port] o wss://host[:port] sin ruta /devtools/... (p. ej. Browserless, Browserbase). OpenClaw intenta primero la detección HTTP /json/version (normalizando el esquema a http/https); si la detección devuelve un webSocketDebuggerUrl, se usa; de lo contrario, OpenClaw recurre a un handshake WebSocket directo en la raíz simple. Si el endpoint WebSocket anunciado rechaza el handshake CDP pero la raíz simple configurada lo acepta, OpenClaw también recurre a esa raíz. Esto permite que un ws:// simple apuntado a un Chrome local todavía conecte, ya que Chrome solo acepta actualizaciones WebSocket en la ruta específica por destino de /json/version, mientras que los proveedores alojados pueden seguir usando su endpoint WebSocket raíz cuando su endpoint de detección anuncia una URL de corta duración que no es adecuada para CDP de Playwright.

# Browserbase

Browserbase es una plataforma en la nube para ejecutar navegadores headless con resolución de CAPTCHA integrada, modo sigiloso y proxies residenciales.

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

Notas:

• Regístrate y copia tu API Key desde el panel de resumen.
• Sustituye <BROWSERBASE_API_KEY> por tu clave de API real de Browserbase.
• Browserbase crea automáticamente una sesión de navegador al conectar por WebSocket, por lo que no se necesita ningún paso manual de creación de sesión.
• El nivel gratuito permite una sesión concurrente y una hora de navegador al mes. Consulta precios para conocer los límites de los planes de pago.
• Consulta la documentación de Browserbase para obtener la referencia completa de la API, guías de SDK y ejemplos de integración.

# Seguridad

Ideas clave:

• El control del navegador es solo loopback; el acceso fluye a través de la autenticación del Gateway o el emparejamiento de nodos.
• La API HTTP de navegador loopback independiente usa solo autenticación con secreto compartido: autenticación bearer con token de Gateway, x-openclaw-password o autenticación HTTP Basic con la contraseña de Gateway configurada.
• Los encabezados de identidad de Tailscale Serve y gateway.auth.mode: "trusted-proxy" no autentican esta API de navegador loopback independiente.
• Si el control del navegador está habilitado y no hay autenticación con secreto compartido configurada, OpenClaw genera un token de Gateway solo de tiempo de ejecución para ese inicio. Configura gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN o OPENCLAW_GATEWAY_PASSWORD explícitamente si los clientes necesitan un secreto estable entre reinicios.
• OpenClaw no genera automáticamente ese token cuando gateway.auth.mode ya es password, none o trusted-proxy.
• Mantén el Gateway y cualquier host de nodo en una red privada (Tailscale); evita la exposición pública.
• Trata las URL/tokens de CDP remoto como secretos; prefiere variables de entorno o un gestor de secretos.

Consejos de CDP remoto:

• Prefiere endpoints cifrados (HTTPS o WSS) y tokens de corta duración cuando sea posible.
• Evita incrustar tokens de larga duración directamente en archivos de configuración.

# Perfiles (varios navegadores)

OpenClaw admite varios perfiles con nombre (configuraciones de enrutamiento). Los perfiles pueden ser:

• gestionado por openclaw: una instancia dedicada de navegador basado en Chromium con su propio directorio de datos de usuario + puerto CDP
• remoto: una URL CDP explícita (navegador basado en Chromium ejecutándose en otro lugar)
• sesión existente: tu perfil de Chrome existente mediante conexión automática de Chrome DevTools MCP

Valores predeterminados:

• El perfil openclaw se crea automáticamente si falta.
• El perfil user está integrado para la conexión de sesión existente de Chrome MCP.
• Los perfiles de sesión existente son opcionales más allá de user; créalos con --driver existing-session.
• Los puertos CDP locales se asignan desde 18800-18899 de forma predeterminada.
• Eliminar un perfil mueve su directorio de datos local a la Papelera.

Todos los endpoints de control aceptan ?profile=<name>; la CLI usa --browser-profile.

# Sesión existente mediante Chrome DevTools MCP

OpenClaw también puede conectarse a un perfil de navegador basado en Chromium en ejecución mediante el servidor oficial Chrome DevTools MCP. Esto reutiliza las pestañas y el estado de inicio de sesión ya abiertos en ese perfil de navegador.

Referencias oficiales de contexto y configuración:

• Chrome para desarrolladores: usa Chrome DevTools MCP con tu sesión de navegador
• README de Chrome DevTools MCP

Perfil integrado:

• user

Opcional: crea tu propio perfil personalizado de sesión existente si quieres un nombre, color o directorio de datos de navegador diferente.

Comportamiento predeterminado:

• El perfil integrado user usa la conexión automática de Chrome MCP, que apunta al perfil local predeterminado de Google Chrome.

Usa userDataDir para Brave, Edge, Chromium o un perfil de Chrome no predeterminado. ~ se expande al directorio personal de tu sistema operativo:

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

Luego, en el navegador correspondiente:

1. Abre la página de inspección de ese navegador para depuración remota.
2. Habilita la depuración remota.
3. Mantén el navegador en ejecución y aprueba la solicitud de conexión cuando OpenClaw se conecte.

Páginas de inspección comunes:

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

Prueba rápida de conexión en vivo:

openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

Cómo se ve el éxito:

• status muestra driver: existing-session
• status muestra transport: chrome-mcp
• status muestra running: true
• tabs enumera tus pestañas de navegador ya abiertas
• snapshot devuelve refs desde la pestaña activa seleccionada

Qué comprobar si la conexión no funciona:

• el navegador de destino basado en Chromium es versión 144+
• la depuración remota está habilitada en la página de inspección de ese navegador
• el navegador mostró la solicitud de consentimiento de conexión y la aceptaste
• openclaw doctor migra la configuración de navegador antigua basada en Plugin y comprueba que Chrome esté instalado localmente para perfiles predeterminados de conexión automática, pero no puede habilitar la depuración remota del lado del navegador por ti

Uso por agentes:

• Usa profile="user" cuando necesites el estado de navegador con sesión iniciada del usuario.
• Si usas un perfil personalizado de sesión existente, pasa ese nombre de perfil explícito.
• Elige este modo solo cuando el usuario esté en la computadora para aprobar la solicitud de conexión.
• el Gateway o host de nodo puede iniciar npx chrome-devtools-mcp@latest --autoConnect

Notas:

• Esta ruta tiene más riesgo que el perfil aislado openclaw porque puede actuar dentro de tu sesión de navegador iniciada.
• OpenClaw no inicia el navegador para este driver; solo se conecta.
• OpenClaw usa aquí el flujo oficial --autoConnect de Chrome DevTools MCP. Si userDataDir está configurado, se pasa para apuntar a ese directorio de datos de usuario.
• La sesión existente puede conectarse en el host seleccionado o mediante un nodo de navegador conectado. Si Chrome vive en otro lugar y no hay ningún nodo de navegador conectado, usa CDP remoto o un host de nodo en su lugar.

# Inicio personalizado de Chrome MCP

Anula el servidor Chrome DevTools MCP iniciado por perfil cuando el flujo predeterminado npx chrome-devtools-mcp@latest no sea lo que quieres (hosts sin conexión, versiones fijadas, binarios incluidos por el proveedor):

Cuando cdpUrl está configurado en un perfil de sesión existente, OpenClaw omite --autoConnect y reenvía automáticamente el endpoint a Chrome MCP:

• http(s)://... → --browserUrl <url> (endpoint de descubrimiento HTTP de DevTools).
• ws(s)://... → --wsEndpoint <url> (WebSocket CDP directo).

Las flags de endpoint y userDataDir no se pueden combinar: cuando cdpUrl está configurado, userDataDir se ignora para el inicio de Chrome MCP, ya que Chrome MCP se conecta al navegador en ejecución detrás del endpoint en lugar de abrir un directorio de perfil.

# Garantías de aislamiento

• Directorio de datos de usuario dedicado: nunca toca tu perfil de navegador personal.
• Puertos dedicados: evita 9222 para prevenir colisiones con flujos de trabajo de desarrollo.
• Control determinista de pestañas: tabs devuelve suggestedTargetId primero, luego handles tabId estables como t1, etiquetas opcionales y el targetId sin procesar. Los agentes deberían reutilizar suggestedTargetId; los ids sin procesar siguen disponibles para depuración y compatibilidad.

# Selección de navegador

Al iniciar localmente, OpenClaw elige el primero disponible:

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

Puedes anularlo con browser.executablePath.

Plataformas:

• macOS: comprueba /Applications y ~/Applications.
• Linux: comprueba ubicaciones comunes de Chrome/Brave/Edge/Chromium bajo /usr/bin, /snap/bin, /opt/google, /opt/brave.com, /usr/lib/chromium y /usr/lib/chromium-browser.
• Windows: comprueba ubicaciones de instalación comunes.

# API de control (opcional)

Para scripting y depuración, el Gateway expone una pequeña API HTTP de control solo loopback más una CLI openclaw browser correspondiente (instantáneas, refs, mejoras de espera, salida JSON, flujos de trabajo de depuración). Consulta API de control de navegador para la referencia completa.

# Solución de problemas

Para problemas específicos de Linux (especialmente Chromium instalado por snap), consulta Solución de problemas de navegador.

Para configuraciones con Gateway en WSL2 + Chrome en Windows en hosts divididos, consulta Solución de problemas de WSL2 + Windows + CDP remoto de Chrome.

# Error de inicio CDP frente a bloqueo SSRF de navegación

Estas son clases de fallo diferentes y apuntan a rutas de código diferentes.

• Error de inicio o preparación de CDP significa que OpenClaw no puede confirmar que el plano de control del navegador esté sano.
• Bloqueo SSRF de navegación significa que el plano de control del navegador está sano, pero un destino de navegación de página es rechazado por la política.

Ejemplos comunes:

• Error de inicio o preparación de CDP:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
  • Port <port> is in use for profile "<name>" but not by openclaw cuando un servicio CDP externo de loopback está configurado sin attachOnly: true
• Bloqueo SSRF de navegación:
  • los flujos open, navigate, snapshot o de apertura de pestañas fallan con un error de política de navegador/red mientras start y tabs siguen funcionando

Usa esta secuencia mínima para separar ambos:

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

Cómo leer los resultados:

• Si start falla con not reachable after start, soluciona primero la preparación de CDP.
• Si start tiene éxito pero tabs falla, el plano de control aún no está sano. Trata esto como un problema de accesibilidad de CDP, no como un problema de navegación de página.
• Si start y tabs tienen éxito pero open o navigate falla, el plano de control del navegador está activo y el fallo está en la política de navegación o en la página de destino.
• Si start, tabs y open tienen éxito, la ruta básica de control de navegador gestionado está sana.

Detalles importantes de comportamiento:

• La configuración de navegador usa de forma predeterminada un objeto de política SSRF cerrado ante fallos incluso cuando no configuras browser.ssrfPolicy.
• Para el perfil gestionado local de loopback openclaw, las comprobaciones de salud de CDP omiten intencionadamente la aplicación de accesibilidad SSRF del navegador para el propio plano de control local de OpenClaw.
• La protección de navegación es independiente. Un resultado correcto de start o tabs no significa que un destino posterior de open o navigate esté permitido.

Guía de seguridad:

• No relajes la política SSRF del navegador de forma predeterminada.
• Prefiere excepciones de host restringidas como hostnameAllowlist o allowedHostnames frente a acceso amplio a redes privadas.
• Usa dangerouslyAllowPrivateNetwork: true solo en entornos intencionalmente confiables donde el acceso de navegador a redes privadas sea necesario y revisado.

# Herramientas de agente + cómo funciona el control

El agente obtiene una herramienta para automatización del navegador:

• browser - doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

Cómo se corresponde:

• browser snapshot devuelve un árbol de interfaz de usuario estable (IA o ARIA).
• browser act usa los ID de ref de la instantánea para hacer clic/escribir/arrastrar/seleccionar.
• browser screenshot captura píxeles (página completa, elemento o referencias etiquetadas).
• browser doctor comprueba la preparación de Gateway, Plugin, perfil, navegador y pestaña.
• browser acepta:
  • profile para elegir un perfil de navegador con nombre (openclaw, chrome o CDP remoto).
  • target (sandbox | host | node) para seleccionar dónde reside el navegador.
  • En sesiones aisladas, target: "host" requiere agents.defaults.sandbox.browser.allowHostControl=true.
  • Si se omite target: las sesiones aisladas usan sandbox de forma predeterminada; las sesiones no aisladas usan host de forma predeterminada.
  • Si hay un Node compatible con navegador conectado, la herramienta puede redirigirse automáticamente a él salvo que fijes target="host" o target="node".

Esto mantiene al agente determinista y evita selectores frágiles.

# Relacionado

• Resumen de herramientas - todas las herramientas de agente disponibles
• Aislamiento - control del navegador en entornos aislados
• Seguridad - riesgos y endurecimiento del control del navegador