​

Navegador (administrado por openclaw)

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

​

Qué obtienes

• Un perfil de navegador separado llamado openclaw (acento naranja de forma predeterminada).
• Control determinista de pestañas (listar/abrir/enfocar/cerrar).
• Acciones del agente (clic/escribir/arrastrar/seleccionar), snapshots, capturas de pantalla, PDF.
• Compatibilidad opcional con varios perfiles (openclaw, work, remote, …).

​

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

​

Control del Plugin

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

• plugins.entries.browser.enabled no desactivado
• browser.enabled=true

​

Falta el comando o la herramienta del navegador

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

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

• browser.enabled=true no es suficiente por sí solo cuando plugins.allow está configurado.
• plugins.entries.browser.enabled=true tampoco es suficiente por sí solo cuando plugins.allow está configurado.
• tools.alsoAllow: ["browser"] no carga el Plugin de navegador incluido. Solo ajusta la política de herramientas después de que el plugin ya se haya cargado.
• Si no necesitas una lista restrictiva de plugins permitidos, quitar plugins.allow también restaura el comportamiento predeterminado del navegador incluido.

• openclaw browser es un comando desconocido.
• falta browser.request.
• El agente informa que la herramienta del navegador no está disponible o falta.

​

Perfiles: openclaw frente a user

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

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

​

Configuración

{
  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)
    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" },
      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" },
    },
  },
}

• El servicio de control del navegador se enlaza a loopback en un puerto derivado de gateway.port (predeterminado: 18791, que es gateway + 2).
• Si sobrescribes el puerto de Gateway (gateway.port o OPENCLAW_GATEWAY_PORT), los puertos derivados del navegador cambian para permanecer en la misma “familia”.
• cdpUrl usa de forma predeterminada el puerto CDP local administrado cuando no está configurado.
• remoteCdpTimeoutMs se aplica a las comprobaciones de accesibilidad de CDP remoto (no loopback).
• remoteCdpHandshakeTimeoutMs se aplica a las comprobaciones de accesibilidad del handshake WebSocket de CDP remoto.
• La navegación del navegador y la apertura de pestañas están protegidas contra SSRF antes de la navegación y se vuelven a comprobar en la medida de lo posible en la URL final http(s) después de la navegación.
• En el modo SSRF estricto, la detección y las sondas del endpoint CDP remoto (cdpUrl, incluidas las búsquedas de /json/version) también se comprueban.
• browser.ssrfPolicy.dangerouslyAllowPrivateNetwork está desactivado de forma predeterminada. Establécelo en true solo cuando confíes intencionalmente en el acceso del navegador a la red privada.
• browser.ssrfPolicy.allowPrivateNetwork sigue siendo compatible como alias heredado por compatibilidad.
• attachOnly: true significa “nunca iniciar un navegador local; solo conectarse si ya está en ejecución”.
• color + el color por perfil tiñen la IU del navegador para que puedas ver qué perfil está activo.
• El perfil predeterminado es openclaw (navegador independiente administrado por OpenClaw). Usa defaultProfile: "user" para optar por el navegador del usuario con inicio de sesión.
• Orden de detección automática: navegador predeterminado del sistema si está basado en Chromium; en caso contrario Chrome → Brave → Edge → Chromium → Chrome Canary.
• Los perfiles openclaw locales asignan cdpPort/cdpUrl automáticamente; configúralos solo para CDP remoto.
• driver: "existing-session" usa Chrome DevTools MCP en lugar de CDP sin formato. No configures cdpUrl para ese driver.
• Configura browser.profiles.<name>.userDataDir cuando un perfil existing-session deba conectarse a un perfil de usuario Chromium no predeterminado, como Brave o Edge.

​

Usar Brave (u otro navegador basado en Chromium)

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 frente a remoto

• Control local (predeterminado): Gateway inicia el servicio de control en loopback y puede iniciar un navegador local.
• Control remoto (host de Node): ejecuta un host de Node en la máquina que tiene el navegador; Gateway envía mediante proxy las acciones del navegador hacia él.
• CDP remoto: configura browser.profiles.<name>.cdpUrl (o browser.cdpUrl) para conectarte a un navegador remoto basado en Chromium. En este caso, OpenClaw no iniciará un navegador local.

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

• Tokens de consulta (por ejemplo, https://provider.example?token=<token>)
• Autenticación HTTP Basic (por ejemplo, https://user:pass@provider.example)

​

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

• El host de Node 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 siendo 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 usar los perfiles permitidos, y las rutas persistentes de creación/eliminación de perfiles se bloquean 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)

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

• Reemplaza <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.

​

Proveedores CDP directos por WebSocket

• 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 fallback a 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 por completo /json/version.
• Raíces WebSocket simples — ws://host[:port] o wss://host[:port] sin una ruta /devtools/... (por ejemplo, Browserless, Browserbase). OpenClaw intenta primero la detección HTTP de /json/version (normalizando el esquema a http/https); si la detección devuelve un webSocketDebuggerUrl, se usa; en caso contrario, OpenClaw recurre a un handshake WebSocket directo en la raíz simple. Esto cubre tanto puertos de depuración remota de estilo Chrome como proveedores solo WebSocket.

​

Browserbase

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

• Regístrate y copia tu API Key desde el panel Overview.
• Reemplaza <BROWSERBASE_API_KEY> por tu clave de API real de Browserbase.
• Browserbase crea automáticamente una sesión de navegador al conectarse por WebSocket, así que no hace falta 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 los precios para conocer los límites de los planes de pago.
• Consulta la documentación de Browserbase para ver la referencia completa de la API, guías del SDK y ejemplos de integración.

​

Seguridad

• El control del navegador es solo loopback; el acceso fluye a través de la autenticación de Gateway o del emparejamiento de nodos.
• La API HTTP independiente del navegador en loopback usa solo autenticación con secreto compartido: auth bearer con el token de gateway, x-openclaw-password o autenticación HTTP Basic con la contraseña configurada del gateway.
• Los encabezados de identidad de Tailscale Serve y gateway.auth.mode: "trusted-proxy" no autentican esta API HTTP independiente del navegador en loopback.
• Si el control del navegador está activado y no se configura ninguna autenticación con secreto compartido, OpenClaw genera automáticamente gateway.auth.token al iniciar y lo persiste en la configuración.
• OpenClaw no genera automáticamente ese token cuando gateway.auth.mode ya es password, none o trusted-proxy.
• Mantén Gateway y cualquier host de nodo en una red privada (Tailscale); evita la exposición pública.
• Trata las URL y los tokens de CDP remoto como secretos; prefiere variables de entorno o un gestor de secretos.

• 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)

• administrados 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

• 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 además de user; créalos con --driver existing-session.
• Los puertos CDP locales se asignan del rango 18800–18899 de forma predeterminada.
• Al eliminar un perfil, su directorio de datos local se mueve a la papelera.

​

Sesión existente mediante Chrome DevTools MCP

• Chrome for Developers: Use Chrome DevTools MCP with your browser session
• Chrome DevTools MCP README

• user

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

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

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

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

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

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

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

• Usa profile="user" cuando necesites el estado del navegador del usuario con sesión iniciada.
• 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 el aviso de conexión.
• Gateway o el host del nodo pueden ejecutar npx chrome-devtools-mcp@latest --autoConnect

• Esta ruta es de mayor riesgo que el perfil aislado openclaw porque puede actuar dentro de tu sesión de navegador con inicio de sesión.
• OpenClaw no inicia el navegador para este driver; solo se conecta a una sesión existente.
• OpenClaw usa aquí el flujo oficial --autoConnect de Chrome DevTools MCP. Si userDataDir está configurado, OpenClaw lo transmite para apuntar a ese directorio de datos de usuario de Chromium explícito.
• Las capturas de pantalla de sesión existente admiten capturas de página y capturas de elementos con --ref desde snapshots, pero no selectores CSS --element.
• Las capturas de pantalla de páginas de sesión existente funcionan sin Playwright mediante Chrome MCP. Las capturas de elementos basadas en refs (--ref) también funcionan allí, pero --full-page no se puede combinar con --ref ni con --element.
• Las acciones de sesión existente siguen siendo más limitadas que la ruta del navegador administrado:
  • click, type, hover, scrollIntoView, drag y select requieren refs de snapshot en lugar de selectores CSS
  • click es solo con el botón izquierdo (sin sobrescrituras de botón ni modificadores)
  • type no admite slowly=true; usa fill o press
  • press no admite delayMs
  • hover, scrollIntoView, drag, select, fill y evaluate no admiten sobrescrituras de timeout por llamada
  • select actualmente admite solo un único valor
• La sesión existente wait --url admite patrones exactos, de subcadena y glob como otros drivers de navegador. wait --load networkidle aún no es compatible.
• Los hooks de carga de sesión existente requieren ref o inputRef, admiten un archivo a la vez y no admiten direccionamiento CSS mediante element.
• Los hooks de diálogos de sesión existente no admiten sobrescrituras de timeout.
• Algunas funciones aún requieren la ruta del navegador administrado, incluidas acciones por lotes, exportación a PDF, interceptación de descargas y responsebody.
• La sesión existente puede conectarse en el host seleccionado o a través de un nodo de navegador conectado. Si Chrome está en otro lugar y no hay ningún nodo de navegador conectado, usa CDP remoto o un host de nodo en su lugar.

​

Garantías de aislamiento

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

​

Selección de navegador

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

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

​

API de control (opcional)

• Estado/inicio/detención: 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

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

• Esta API independiente del navegador en loopback no consume encabezados de identidad de trusted-proxy ni de Tailscale Serve.
• Si gateway.auth.mode es none o trusted-proxy, estas rutas de navegador en loopback no heredan esos modos con identidad; mantenlas solo en loopback.

​

Contrato de error de /act

{ "error": "<message>", "code": "ACT_*" }

• ACT_KIND_REQUIRED (HTTP 400): falta kind o no se reconoce.
• ACT_INVALID_REQUEST (HTTP 400): la carga útil de la acción falló en la normalización o validación.
• ACT_SELECTOR_UNSUPPORTED (HTTP 400): se usó selector con un tipo de acción no compatible.
• ACT_EVALUATE_DISABLED (HTTP 403): evaluate (o wait --fn) está desactivado por configuración.
• ACT_TARGET_ID_MISMATCH (HTTP 403): targetId de nivel superior o por lotes entra en conflicto con el destino de la solicitud.
• ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): la acción no es compatible con perfiles de sesión existente.

​

Requisito de Playwright

• Snapshots ARIA
• Capturas de pantalla de página para el navegador administrado openclaw cuando haya un WebSocket CDP por pestaña disponible
• Capturas de pantalla de página para perfiles existing-session / Chrome MCP
• Capturas de pantalla basadas en refs de existing-session (--ref) a partir de la salida de snapshot

• navigate
• act
• AI snapshots / role snapshots
• Capturas de pantalla de elementos con selector CSS (--element)
• Exportación completa de PDF del navegador

​

Instalación de Playwright en Docker

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

​

Cómo funciona (interno)

• Un pequeño servidor de control acepta solicitudes HTTP.
• Se conecta a navegadores basados en Chromium (Chrome/Brave/Edge/Chromium) mediante CDP.
• Para acciones avanzadas (click/type/snapshot/PDF), usa Playwright sobre CDP.
• Cuando falta Playwright, solo están disponibles las operaciones que no dependen de Playwright.

​

Referencia rápida de la CLI

• 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

• 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

• Para perfiles solo de conexión y de CDP remoto, openclaw browser stop sigue siendo el comando correcto de limpieza después de las pruebas. Cierra la sesión de control activa y borra las anulaciones temporales de emulación en lugar de finalizar el navegador subyacente.
• openclaw browser errors --clear
• openclaw browser requests --filter api --clear
• openclaw browser pdf
• openclaw browser responsebody "**/api" --max-chars 5000

• 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

• 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"

• upload y dialog son llamadas de preparación; ejecútalas antes del click/press que activa el selector de archivos o el diálogo.
• Las rutas de salida de descargas y trazas están restringidas a raíces temporales de OpenClaw:
  • trazas: /tmp/openclaw (fallback: ${os.tmpdir()}/openclaw)
  • descargas: /tmp/openclaw/downloads (fallback: ${os.tmpdir()}/openclaw/downloads)
• Las rutas de carga están restringidas a una raíz temporal de cargas de OpenClaw:
  • cargas: /tmp/openclaw/uploads (fallback: ${os.tmpdir()}/openclaw/uploads)
• upload también puede configurar directamente entradas de archivo mediante --input-ref o --element.
• snapshot:
  • --format ai (predeterminado cuando Playwright está instalado): devuelve un AI snapshot con refs numéricas (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).
  • Predeterminado de configuración (solo herramienta/CLI): configura browser.snapshotDefaults.mode: "efficient" para usar snapshots eficientes cuando quien llama no pasa un modo (consulta Configuración de 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 refs de rol como e12).
  • --interactive genera una lista plana y fácil de elegir de elementos interactivos (ideal para ejecutar acciones).
  • --labels agrega una captura de pantalla solo de la ventana visible con etiquetas de ref superpuestas (imprime MEDIA:<path>).
• click/type/etc. requieren una ref de snapshot (ya sea la numérica 12 o la ref de rol e12). Los selectores CSS no son compatibles intencionalmente para acciones.

​

Snapshots y refs

• AI snapshot (refs numéricas): openclaw browser snapshot (predeterminado; --format ai)
  • Salida: un snapshot de texto que incluye refs numéricas.
  • Acciones: openclaw browser click 12, openclaw browser type 23 "hello".
  • Internamente, la ref se resuelve mediante aria-ref de Playwright.
• Role snapshot (refs de rol como e12): openclaw browser snapshot --interactive (o --compact, --depth, --selector, --frame)
  • Salida: una lista o árbol basado en roles con [ref=e12] (y opcionalmente [nth=1]).
  • Acciones: openclaw browser click e12, openclaw browser highlight e12.
  • Internamente, la ref se resuelve mediante getByRole(...) (más nth() para duplicados).
  • Agrega --labels para incluir una captura de pantalla de la ventana visible con etiquetas e12 superpuestas.

• Las refs no son estables entre navegaciones; si algo falla, vuelve a ejecutar snapshot y usa una ref nueva.
• Si el role snapshot se tomó con --frame, las refs de rol quedan limitadas a ese iframe hasta el siguiente role snapshot.

​

Mejoras de wait

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

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

​

Flujos de depuración

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

​

Salida JSON

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

​

Controles de estado y entorno

• Cookies: cookies, cookies set, cookies clear
• Storage: storage local|session get|set|clear
• Sin conexión: set offline on|off
• Headers: set headers --headers-json '{"X-Debug":"1"}' (el heredado set headers --json '{"X-Debug":"1"}' sigue siendo compatible)
• Auth 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 / configuración regional: set timezone ..., set locale ...
• Dispositivo / viewport:
  • set device "iPhone 14" (presets de dispositivos de Playwright)
  • set viewport 1280 720

​

Seguridad y privacidad

• El perfil de navegador 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 guiar esto. Desactívalo con browser.evaluateEnabled=false si no lo necesitas.
• Para inicios de sesión y notas anti-bot (X/Twitter, etc.), consulta Inicio de sesión del navegador + publicación en X/Twitter.
• Mantén privado el gateway o host del nodo (solo loopback o tailnet).
• Los endpoints CDP remotos son potentes; canalízalos de forma segura y protégelos.

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optional exact allow
    },
  },
}

​

Solución de problemas

​

Fallo de inicio de CDP frente a bloqueo SSRF de navegación

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

• Fallo 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>
• Bloqueo SSRF de navegación:
  • los flujos open, navigate, snapshot o apertura de pestañas fallan con un error de política del navegador o de red mientras start y tabs siguen funcionando

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

• Si start falla con not reachable after start, primero soluciona la preparación de CDP.
• Si start tiene éxito pero tabs falla, el plano de control sigue sin estar en buen estado. Trátalo 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 fallan, 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 del navegador administrado está en buen estado.

• La configuración del navegador usa de forma predeterminada un objeto de política SSRF de cierre por defecto incluso cuando no configuras browser.ssrfPolicy.
• Para el perfil administrado local openclaw en loopback, las comprobaciones de estado de CDP omiten intencionalmente 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.

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

• start tiene éxito
• tabs tiene éxito
• open http://internal.example falla

• start falla con not reachable after start
• tabs también falla o no puede ejecutarse

​

Herramientas del agente + cómo funciona el control

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

• browser snapshot devuelve un árbol de IU estable (AI o ARIA).
• browser act usa los ID ref del snapshot para hacer clic, escribir, arrastrar o 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 aisladas, target: "host" requiere agents.defaults.sandbox.browser.allowHostControl=true.
  • Si se omite target: las sesiones aisladas usan sandbox de forma predeterminada y las no aisladas usan host.
  • Si hay un nodo con capacidad de navegador conectado, la herramienta puede enrutar automáticamente hacia él a menos que fijes target="host" o target="node".

​

Relacionado

• Descripción general de las herramientas — todas las herramientas de agente disponibles
• Aislamiento — control del navegador en entornos aislados
• Seguridad — riesgos y refuerzo del control del navegador