Navegador (gestionado por OpenClaw)

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

Vista para principiantes:

Piensa en ello como un navegador separado, solo para el agente.
El perfil openclaw no toca tu perfil personal del navegador.
El agente puede abrir pestañas, leer páginas, hacer clic y escribir en un carril seguro.
El perfil por defecto chrome usa el navegador basado en Chromium por defecto del sistema vía el relay de extensión; cambia a openclaw para el navegador gestionado aislado.

Qué obtienes

Un perfil de navegador separado llamado openclaw (acento naranja por defecto).
Control determinístico de pestañas (listar/abrir/enfocar/cerrar).
Acciones del agente (clic/escribir/arrastrar/seleccionar), snapshots, capturas de pantalla, PDFs.
Soporte opcional multi-perfil (openclaw, work, remote, …).

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

Inicio rápido

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 obtienes “Browser disabled”, habilítalo en la configuración (ver abajo) y reinicia el Gateway.

Perfiles: `openclaw` vs `chrome`

openclaw: navegador gestionado y aislado (no requiere extensión).
chrome: relay de extensión a tu navegador del sistema (requiere que la extensión de OpenClaw esté adjunta a una pestaña).
existing-session: flujo oficial de adjunción de Chrome MCP para un perfil de Chrome en ejecución.

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

Configuración

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

{
  browser: {
    enabled: true, // por defecto: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // modo de red de confianza por defecto
      // allowPrivateNetwork: true, // alias legacy
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // sobrecarga legacy de perfil único
    remoteCdpTimeoutMs: 1500, // timeout HTTP de CDP remoto (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // timeout de handshake WebSocket de CDP remoto (ms)
    defaultProfile: "chrome",
    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" },
      chromeLive: {
        cdpPort: 18802,
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

Notas:

El servicio de control del navegador se vincula a loopback en un puerto derivado de gateway.port (por defecto: 18791, que es gateway + 2). El relay usa el siguiente puerto (18792).
Si sobrecargas el puerto del Gateway (gateway.port o OPENCLAW_GATEWAY_PORT), los puertos derivados del navegador se desplazan para mantenerse en la misma “familia”.
cdpUrl tiene como valor por defecto el puerto del relay cuando no se establece.
remoteCdpTimeoutMs aplica a verificaciones de accesibilidad CDP remoto (no-loopback).
remoteCdpHandshakeTimeoutMs aplica a verificaciones de accesibilidad WebSocket CDP remoto.
La navegación/apertura de pestañas del navegador está protegida contra SSRF antes de la navegación y se re-verifica con mejor esfuerzo en la URL final http(s) después de la navegación.
browser.ssrfPolicy.dangerouslyAllowPrivateNetwork tiene por defecto true (modelo de red de confianza). Establécelo a false para navegación estricta solo pública.
browser.ssrfPolicy.allowPrivateNetwork sigue soportado como alias legacy por compatibilidad.
attachOnly: true significa “nunca lanzar un navegador local; solo adjuntarse si ya está en ejecución.”
color + color por perfil tiñen la interfaz del navegador para que puedas ver qué perfil está activo.
El perfil por defecto es openclaw (navegador independiente gestionado por OpenClaw). Usa defaultProfile: "chrome" para optar por el relay de extensión de Chrome.
Orden de auto-detección: navegador por defecto del sistema si es basado en Chromium; de lo contrario Chrome -> Brave -> Edge -> Chromium -> Chrome Canary.
Los perfiles locales openclaw auto-asignan cdpPort/cdpUrl — establece esos solo para CDP remoto.
driver: "existing-session" usa Chrome DevTools MCP en lugar de CDP directo. No establezcas cdpUrl para ese driver.

Usar Brave (u otro navegador basado en Chromium)

Si tu navegador por defecto del sistema es basado en Chromium (Chrome/Brave/Edge/etc), OpenClaw lo usa automáticamente. Establece browser.executablePath para sobrecargar la auto-detección:

Ejemplo de CLI:

openclaw config set browser.executablePath "/usr/bin/google-chrome"

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

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

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

Control local vs remoto

Control local (por defecto): el Gateway inicia el servicio de control en loopback y puede lanzar un navegador local.
Control remoto (node host): ejecuta un node host en la máquina que tiene el navegador; el Gateway proxea las acciones del navegador hacia él.
CDP remoto: establece browser.profiles.<name>.cdpUrl (o browser.cdpUrl) para adjuntarse a un navegador remoto basado en Chromium. En este caso, OpenClaw no lanzará un navegador local.

Las URLs de CDP remoto pueden incluir autenticación:

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

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

Proxy de navegador del nodo (por defecto sin configuración)

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

Notas:

El node host expone su servidor de control de navegador local vía un comando proxy.
Los perfiles provienen de la propia configuración browser.profiles del nodo (igual que local).
Deshabilita si no lo quieres:
- En el nodo: nodeHost.browserProxy.enabled=false
- En el gateway: gateway.nodes.browser.mode="off"

Browserless (CDP remoto hospedado)

Browserless es un servicio hospedado de Chromium que expone endpoints CDP sobre HTTPS. Puedes apuntar un perfil de navegador de OpenClaw a un endpoint de región de Browserless y autenticarte con tu clave API.

Ejemplo:

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

Notas:

Reemplaza <BROWSERLESS_API_KEY> con tu token real de Browserless.
Elige el endpoint de región que coincida con tu cuenta de Browserless (consulta su documentación).

Proveedores de CDP por WebSocket directo

Algunos servicios de navegador hospedados exponen un endpoint de WebSocket directo en lugar del descubrimiento CDP estándar basado en HTTP (/json/version). OpenClaw soporta ambos:

Endpoints HTTP(S) (por ej. Browserless) — OpenClaw llama a /json/version para descubrir la URL del depurador WebSocket, luego se conecta.
Endpoints WebSocket (ws:// / wss://) — OpenClaw se conecta directamente, omitiendo /json/version. Usa esto para servicios como Browserbase o cualquier proveedor que te entregue una URL WebSocket.

Browserbase

Browserbase es una plataforma cloud para ejecutar navegadores headless con resolución de CAPTCHA integrada, modo stealth 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 Overview.
Reemplaza <BROWSERBASE_API_KEY> con tu clave API real de Browserbase.
Browserbase auto-crea una sesión de navegador al conectar el WebSocket, así que no se necesita un paso manual de creación de sesión.
El tier gratuito permite una sesión concurrente y una hora de navegador por mes. Consulta precios para los límites de planes de pago.
Consulta la documentación de Browserbase para 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 emparejamiento de nodos.
Si el control del navegador está habilitado y no hay autenticación configurada, OpenClaw auto-genera gateway.auth.token al inicio y lo persiste en la configuración.
Mantén el Gateway y cualquier node host en una red privada (Tailscale); evita la exposición pública.
Trata las URLs/tokens de CDP remoto como secretos; prefiere variables de entorno o un gestor de secretos.

Consejos para 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 (multi-navegador)

OpenClaw soporta múltiples perfiles con nombre (configuraciones de enrutamiento). Los perfiles pueden ser:

Gestionados 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)
Relay de extensión: tus pestañas existentes de Chrome vía el relay local + extensión de Chrome
Sesión existente: tu perfil existente de Chrome vía auto-conexión Chrome DevTools MCP

Valores por defecto:

El perfil openclaw se auto-crea si no existe.
El perfil chrome está integrado para el relay de extensión de Chrome (apunta a http://127.0.0.1:18792 por defecto).
Los perfiles de sesión existente son opt-in; créalos con --driver existing-session.
Los puertos CDP locales se asignan desde 18800-18899 por defecto.
Eliminar un perfil mueve su directorio de datos local a la Papelera.

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

Relay de extensión de Chrome (usa tu Chrome existente)

OpenClaw también puede controlar tus pestañas existentes de Chrome (sin una instancia separada de Chrome “openclaw”) vía un relay CDP local + una extensión de Chrome.

Guía completa: Extensión de Chrome

Flujo:

El Gateway se ejecuta localmente (misma máquina) o un node host se ejecuta en la máquina del navegador.
Un servidor relay local escucha en un cdpUrl de loopback (por defecto: http://127.0.0.1:18792).
Haces clic en el ícono de la extensión OpenClaw Browser Relay en una pestaña para adjuntar (no se auto-adjunta).
El agente controla esa pestaña vía la herramienta normal browser, seleccionando el perfil correcto.

Si el Gateway se ejecuta en otro lugar, ejecuta un node host en la máquina del navegador para que el Gateway pueda proxear las acciones del navegador.

Sesiones en sandbox

Si la sesión del agente está en sandbox, la herramienta browser puede usar por defecto target="sandbox" (navegador del sandbox). La toma de control del relay de extensión de Chrome requiere control del navegador host, así que:

ejecuta la sesión sin sandbox, o
establece agents.defaults.sandbox.browser.allowHostControl: true y usa target="host" al llamar la herramienta.

Configuración

Carga la extensión (dev/sin empaquetar):

openclaw browser extension install

Chrome -> chrome://extensions -> habilita “Modo desarrollador”
“Cargar descomprimida” -> selecciona el directorio impreso por openclaw browser extension path
Fija la extensión, luego haz clic en ella en la pestaña que quieres controlar (la insignia muestra ON).

Úsala:

CLI: openclaw browser --browser-profile chrome tabs
Herramienta del agente: browser con profile="chrome"

Opcional: si quieres un nombre diferente o puerto de relay, crea tu propio perfil:

openclaw browser create-profile \
  --name my-chrome \
  --driver extension \
  --cdp-url http://127.0.0.1:18792 \
  --color "#00AA00"

Notas:

Este modo depende de Playwright-on-CDP para la mayoría de las operaciones (capturas de pantalla/snapshots/acciones).
Desadjunta haciendo clic en el ícono de la extensión de nuevo.

Sesión existente de Chrome vía MCP

OpenClaw también puede adjuntarse a un perfil de Chrome en ejecución a través del servidor oficial Chrome DevTools MCP. Esto reutiliza las pestañas y el estado de inicio de sesión ya abiertos en ese perfil de Chrome.

Referencias oficiales de contexto y configuración:

Crea un perfil:

openclaw browser create-profile \
  --name chrome-live \
  --driver existing-session \
  --color "#00AA00"

Luego en Chrome:

Abre chrome://inspect/#remote-debugging
Habilita la depuración remota
Mantén Chrome en ejecución y aprueba el prompt de conexión cuando OpenClaw se adjunte

Prueba de adjunción en vivo:

openclaw browser --browser-profile chrome-live start
openclaw browser --browser-profile chrome-live status
openclaw browser --browser-profile chrome-live tabs
openclaw browser --browser-profile chrome-live snapshot --format ai

Cómo se ve el éxito:

status muestra driver: existing-session
status muestra running: true
tabs lista tus pestañas de Chrome ya abiertas
snapshot devuelve refs de la pestaña en vivo seleccionada

Qué verificar si la adjunción no funciona:

Chrome es versión 144+
La depuración remota está habilitada en chrome://inspect/#remote-debugging
Chrome mostró y aceptaste el prompt de consentimiento de adjunción
El Gateway o node host puede ejecutar npx chrome-devtools-mcp@latest --autoConnect

Notas:

Esta ruta es de mayor riesgo que el perfil aislado openclaw porque puede actuar dentro de tu sesión de navegador con sesión iniciada.
OpenClaw no lanza Chrome para este driver; se adjunta solo a una sesión existente.
OpenClaw usa el flujo oficial --autoConnect de Chrome DevTools MCP aquí, no el flujo legacy de puerto de depuración remota del perfil por defecto.
Las capturas de pantalla de sesión existente soportan capturas de página y capturas de elemento con --ref desde snapshots, pero no selectores CSS --element.
wait --url de sesión existente soporta patrones exactos, de subcadena y glob como otros drivers de navegador. wait --load networkidle aún no está soportado.
Algunas funciones aún requieren el relay de extensión o la ruta del navegador gestionado, como exportación de PDF e interceptación de descargas.
Deja el relay en loopback por defecto. Si el relay debe ser accesible desde un espacio de nombres de red diferente (por ejemplo Gateway en WSL2, Chrome en Windows), establece browser.relayBindHost a una dirección de vinculación explícita como 0.0.0.0, mientras mantienes la red circundante privada y autenticada.

Ejemplo WSL2 / entre espacios de nombres:

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

Garantías de aislamiento

Directorio de datos de usuario dedicado: nunca toca tu perfil personal del navegador.
Puertos dedicados: evita 9222 para prevenir colisiones con flujos de desarrollo.
Control determinístico de pestañas: apunta a pestañas por targetId, no “última pestaña”.

Selección de navegador

Al lanzar localmente, OpenClaw elige el primero disponible:

Chrome
Brave
Edge
Chromium
Chrome Canary

Puedes sobrecargar con browser.executablePath.

Plataformas:

macOS: busca en /Applications y ~/Applications.
Linux: busca google-chrome, brave, microsoft-edge, chromium, etc.
Windows: busca en ubicaciones de instalación comunes.

API de Control (opcional)

Solo para integraciones locales, el Gateway expone una pequeña API HTTP en loopback:

Estado/inicio/parada: GET /, POST /start, POST /stop
Pestañas: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
Snapshot/captura de pantalla: GET /snapshot, POST /screenshot
Acciones: POST /navigate, POST /act
Hooks: POST /hooks/file-chooser, POST /hooks/dialog
Descargas: POST /download, POST /wait/download
Depuración: GET /console, POST /pdf
Depuración: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
Red: POST /response/body
Estado: GET /cookies, POST /cookies/set, POST /cookies/clear
Estado: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
Configuración: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

Todos los endpoints aceptan ?profile=<name>.

Si la autenticación del gateway está configurada, las rutas HTTP del navegador también requieren autenticación:

Authorization: Bearer <gateway token>
x-openclaw-password: <gateway password> o autenticación HTTP Basic con esa contraseña

Requisito de Playwright

Algunas funciones (navigate/act/AI snapshot/role snapshot, capturas de pantalla de elemento, PDF) requieren Playwright. Si Playwright no está instalado, esos endpoints devuelven un error 501 claro. Los snapshots ARIA y las capturas de pantalla básicas siguen funcionando para Chrome gestionado por openclaw. Para el driver de relay de extensión de Chrome, los snapshots ARIA y las capturas de pantalla requieren Playwright.

Si ves Playwright is not available in this gateway build, instala el paquete completo de Playwright (no playwright-core) y reinicia el gateway, o reinstala OpenClaw con soporte de navegador.

Instalación de Playwright en Docker

Si tu Gateway se ejecuta en Docker, evita npx playwright (conflictos de sobrecargas de npm). Usa el CLI empaquetado en su lugar:

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

Para persistir las descargas del navegador, establece PLAYWRIGHT_BROWSERS_PATH (por ejemplo, /home/node/.cache/ms-playwright) y asegúrate de que /home/node se persista vía OPENCLAW_HOME_VOLUME o un bind mount. Consulta Docker.

Cómo funciona (interno)

Flujo de alto nivel:

Un pequeño servidor de control acepta solicitudes HTTP.
Se conecta a navegadores basados en Chromium (Chrome/Brave/Edge/Chromium) vía CDP.
Para acciones avanzadas (clic/escribir/snapshot/PDF), usa Playwright encima de CDP.
Cuando Playwright no está disponible, solo están disponibles las operaciones que no requieren Playwright.

Este diseño mantiene al agente en una interfaz estable y determinística mientras te permite intercambiar navegadores y perfiles locales/remotos.

Referencia rápida del CLI

Todos los comandos aceptan --browser-profile <name> para apuntar a un perfil específico. Todos los comandos también aceptan --json para salida legible por máquina (cargas útiles estables).

Básicos:

openclaw browser status
openclaw browser start
openclaw browser stop
openclaw browser tabs
openclaw browser tab
openclaw browser tab new
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://example.com
openclaw browser focus abcd1234
openclaw browser close abcd1234

Inspección:

openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12
openclaw browser screenshot --ref e12
openclaw browser snapshot
openclaw browser snapshot --format aria --limit 200
openclaw browser snapshot --interactive --compact --depth 6
openclaw browser snapshot --efficient
openclaw browser snapshot --labels
openclaw browser snapshot --selector "#main" --interactive
openclaw browser snapshot --frame "iframe#main" --interactive
openclaw browser console --level error
openclaw browser errors --clear
openclaw browser requests --filter api --clear
openclaw browser pdf
openclaw browser responsebody "**/api" --max-chars 5000

Acciones:

openclaw browser navigate https://example.com
openclaw browser resize 1280 720
openclaw browser click 12 --double
openclaw browser click e12 --double
openclaw browser type 23 "hello" --submit
openclaw browser press Enter
openclaw browser hover 44
openclaw browser scrollintoview e12
openclaw browser drag 10 11
openclaw browser select 9 OptionA OptionB
openclaw browser download e12 report.pdf
openclaw browser waitfordownload report.pdf
openclaw browser upload /tmp/openclaw/uploads/file.pdf
openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
openclaw browser dialog --accept
openclaw browser wait --text "Done"
openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
openclaw browser highlight e12
openclaw browser trace start
openclaw browser trace stop

Estado:

openclaw browser cookies
openclaw browser cookies set session abc123 --url "https://example.com"
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set theme dark
openclaw browser storage session clear
openclaw browser set offline on
openclaw browser set headers --headers-json '{"X-Debug":"1"}'
openclaw browser set credentials user pass
openclaw browser set credentials --clear
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
openclaw browser set geo --clear
openclaw browser set media dark
openclaw browser set timezone America/New_York
openclaw browser set locale en-US
openclaw browser set device "iPhone 14"

Notas:

upload y dialog son llamadas de preparación; ejecútalas antes del clic/pulsación que desencadena el selector/diálogo.
Las rutas de salida de descarga y trace están restringidas a las raíces temporales de OpenClaw:
- traces: /tmp/openclaw (respaldo: ${os.tmpdir()}/openclaw)
- descargas: /tmp/openclaw/downloads (respaldo: ${os.tmpdir()}/openclaw/downloads)
Las rutas de subida están restringidas a una raíz temporal de subidas de OpenClaw:
- subidas: /tmp/openclaw/uploads (respaldo: ${os.tmpdir()}/openclaw/uploads)
upload también puede establecer inputs de archivo directamente vía --input-ref o --element.
snapshot:
- --format ai (por defecto cuando Playwright está instalado): devuelve un snapshot AI con refs numéricos (aria-ref="<n>").
- --format aria: devuelve el árbol de accesibilidad (sin refs; solo inspección).
- --efficient (o --mode efficient): preset compacto de role snapshot (interactive + compact + depth + maxChars menor).
- Valor por defecto de configuración (solo herramienta/CLI): establece browser.snapshotDefaults.mode: "efficient" para usar snapshots eficientes cuando el llamador no pasa un modo (consulta Configuración del Gateway).
- Las opciones de role snapshot (--interactive, --compact, --depth, --selector) fuerzan un snapshot basado en roles con refs como ref=e12.
- --frame "<iframe selector>" limita los role snapshots a un iframe (se combina con role refs como e12).
- --interactive produce una lista plana y fácil de seleccionar de elementos interactivos (ideal para impulsar acciones).
- --labels agrega una captura de pantalla solo del viewport con etiquetas de ref superpuestas (imprime MEDIA:<path>).
click/type/etc requieren un ref de snapshot (ya sea numérico 12 o role ref e12). Los selectores CSS intencionalmente no están soportados para acciones.

Snapshots y refs

OpenClaw soporta dos estilos de “snapshot”:

AI snapshot (refs numéricos): openclaw browser snapshot (por defecto; --format ai)
- Salida: un snapshot de texto que incluye refs numéricos.
- Acciones: openclaw browser click 12, openclaw browser type 23 "hello".
- Internamente, el ref se resuelve vía aria-ref de Playwright.
Role snapshot (role refs como e12): openclaw browser snapshot --interactive (o --compact, --depth, --selector, --frame)
- Salida: una lista/árbol basada en roles con [ref=e12] (y opcional [nth=1]).
- Acciones: openclaw browser click e12, openclaw browser highlight e12.
- Internamente, el ref se resuelve vía getByRole(...) (más nth() para duplicados).
- Agrega --labels para incluir una captura de pantalla del viewport con etiquetas e12 superpuestas.

Comportamiento de los refs:

Los refs no son estables entre navegaciones; si algo falla, vuelve a ejecutar snapshot y usa un ref fresco.
Si el role snapshot se tomó con --frame, los role refs tienen alcance a ese iframe hasta el siguiente role snapshot.

Potenciadores de wait

Puedes esperar más que solo tiempo/texto:

Esperar por URL (globs soportados por Playwright):
- openclaw browser wait --url "**/dash"
Esperar por estado de carga:
- openclaw browser wait --load networkidle
Esperar por un predicado JS:
- openclaw browser wait --fn "window.ready===true"
Esperar a que un selector sea visible:
- openclaw browser wait "#main"

Se pueden combinar:

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

Flujos de depuración

Cuando una acción falla (por ej. “not visible”, “strict mode violation”, “covered”):

openclaw browser snapshot --interactive
Usa click <ref> / type <ref> (prefiere role refs en modo interactivo)
Si sigue fallando: openclaw browser highlight <ref> para ver qué está apuntando Playwright
Si la página se comporta de forma extraña:
- openclaw browser errors --clear
- openclaw browser requests --filter api --clear
Para depuración profunda: graba un trace:
- openclaw browser trace start
- reproduce el problema
- openclaw browser trace stop (imprime TRACE:<path>)

Salida JSON

--json es para scripting y herramientas estructuradas.

Ejemplos:

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

Los role snapshots en JSON incluyen refs más un pequeño bloque stats (lines/chars/refs/interactive) para que las herramientas puedan razonar sobre el tamaño y densidad de la carga útil.

Estado y controles de entorno

Son útiles para flujos de “hacer que el sitio se comporte como X”:

Cookies: cookies, cookies set, cookies clear
Almacenamiento: storage local|session get|set|clear
Sin conexión: set offline on|off
Headers: set headers --headers-json '{"X-Debug":"1"}' (el legacy set headers --json '{"X-Debug":"1"}' sigue soportado)
Autenticación HTTP basic: set credentials user pass (o --clear)
Geolocalización: set geo <lat> <lon> --origin "https://example.com" (o --clear)
Media: set media dark|light|no-preference|none
Zona horaria / locale: set timezone ..., set locale ...
Dispositivo / viewport:
- set device "iPhone 14" (presets de dispositivo de Playwright)
- set viewport 1280 720

Seguridad y privacidad

El perfil del navegador de openclaw puede contener sesiones con inicio de sesión; trátalo como sensible.
browser act kind=evaluate / openclaw browser evaluate y wait --fn ejecutan JavaScript arbitrario en el contexto de la página. La inyección de prompts puede dirigir esto. Deshabilítalo con browser.evaluateEnabled=false si no lo necesitas.
Para notas sobre inicios de sesión y anti-bot (X/Twitter, etc.), consulta Inicio de sesión en el navegador + publicación en X/Twitter.
Mantén el Gateway/node host privado (solo loopback o tailnet).
Los endpoints de CDP remoto son poderosos; túneles y protégelos.

Ejemplo de modo estricto (bloquear destinos privados/internos por defecto):

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // permitidos exactos opcionales
    },
  },
}

Solución de problemas

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

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

Herramientas del agente + cómo funciona el control

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

browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

Cómo se mapea:

browser snapshot devuelve un árbol de UI estable (AI o ARIA).
browser act usa los IDs ref del snapshot para hacer clic/escribir/arrastrar/seleccionar.
browser screenshot captura píxeles (página completa o elemento).
browser acepta:
- profile para elegir un perfil de navegador con nombre (openclaw, chrome o CDP remoto).
- target (sandbox | host | node) para seleccionar dónde vive el navegador.
- En sesiones en sandbox, target: "host" requiere agents.defaults.sandbox.browser.allowHostControl=true.
- Si se omite target: las sesiones en sandbox usan por defecto sandbox, las sesiones sin sandbox usan por defecto host.
- Si un nodo con capacidad de navegador está conectado, la herramienta puede auto-enrutar a él a menos que fijes target="host" o target="node".

Esto mantiene al agente determinístico y evita selectores frágiles.

Navegador (gestionado por OpenClaw)

Qué obtienes

Inicio rápido

Perfiles: openclaw vs chrome

Configuración

Usar Brave (u otro navegador basado en Chromium)

Control local vs remoto

Proxy de navegador del nodo (por defecto sin configuración)

Browserless (CDP remoto hospedado)

Proveedores de CDP por WebSocket directo

Browserbase

Seguridad

Perfiles (multi-navegador)

Relay de extensión de Chrome (usa tu Chrome existente)

Sesiones en sandbox

Configuración

Sesión existente de Chrome vía MCP

Garantías de aislamiento

Selección de navegador

API de Control (opcional)

Requisito de Playwright

Instalación de Playwright en Docker

Cómo funciona (interno)

Referencia rápida del CLI

Snapshots y refs

Potenciadores de wait

Flujos de depuración

Salida JSON

Estado y controles de entorno

Seguridad y privacidad

Solución de problemas

Herramientas del agente + cómo funciona el control

Perfiles: `openclaw` vs `chrome`