openclaw browser

Gestiona la superficie de control del navegador de OpenClaw y ejecuta acciones del navegador (ciclo de vida, perfiles, pestañas, instantáneas, capturas de pantalla, navegación, entrada, emulación de estado y depuración).

Relacionado:

• Herramienta de navegador + API: Herramienta de navegador

Indicadores comunes

• --url <gatewayWsUrl>: URL de WebSocket de Gateway (usa la configuración de forma predeterminada).
• --token <token>: token de Gateway (si es necesario).
• --timeout <ms>: tiempo de espera de la solicitud (ms).
• --expect-final: esperar una respuesta final de Gateway.
• --browser-profile <name>: elegir un perfil de navegador (predeterminado de la configuración).
• --json: salida legible por máquina (cuando se admite).

Inicio rápido (local)

openclaw browser profilesopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

Los agentes pueden ejecutar la misma comprobación de disponibilidad con browser({ action: "doctor" }).

Solución rápida de problemas

Si start falla con not reachable after start, primero soluciona la disponibilidad de CDP. Si start y tabs funcionan, pero open o navigate falla, el plano de control del navegador está en buen estado y el fallo suele deberse a la política SSRF de navegación.

Secuencia mínima:

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw tabsopenclaw browser --browser-profile openclaw open https://example.com

Guía detallada: Solución de problemas del navegador

Ciclo de vida

openclaw browser statusopenclaw browser doctoropenclaw browser doctor --deepopenclaw browser startopenclaw browser start --headlessopenclaw browser stopopenclaw browser --browser-profile openclaw reset-profile

Notas:

• doctor --deep añade una prueba de instantánea en vivo. Es útil cuando la disponibilidad básica de CDP está en verde, pero quieres una prueba de que se puede inspeccionar la pestaña actual.
• Para perfiles attachOnly y CDP remotos, openclaw browser stop cierra la sesión de control activa y borra las anulaciones temporales de emulación incluso cuando OpenClaw no inició el proceso del navegador por sí mismo.
• Para perfiles locales gestionados, openclaw browser stop detiene el proceso del navegador iniciado.
• openclaw browser start --headless se aplica solo a esa solicitud de inicio y solo cuando OpenClaw inicia un navegador local gestionado. No reescribe browser.headless ni la configuración del perfil, y no tiene efecto para un navegador que ya está en ejecución.
• En hosts Linux sin DISPLAY ni WAYLAND_DISPLAY, los perfiles locales gestionados se ejecutan automáticamente en modo sin interfaz, salvo que OPENCLAW_BROWSER_HEADLESS=0, browser.headless=false o browser.profiles.<name>.headless=false solicite explícitamente un navegador visible.

Si falta el comando

Si openclaw browser es un comando desconocido, revisa plugins.allow en ~/.openclaw/openclaw.json.

Cuando plugins.allow está presente, enumera explícitamente el Plugin de navegador incluido, salvo que la configuración ya tenga un bloque raíz browser:

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

Un bloque raíz browser explícito, por ejemplo browser.enabled=true o browser.profiles.<name>, también activa el Plugin de navegador incluido bajo una lista restrictiva de Plugins permitidos.

Relacionado: Herramienta de navegador

Perfiles

Los perfiles son configuraciones con nombre de enrutamiento del navegador. En la práctica:

• openclaw: inicia o se adjunta a una instancia dedicada de Chrome gestionada por OpenClaw (directorio de datos de usuario aislado).
• user: controla tu sesión existente de Chrome con sesión iniciada mediante Chrome DevTools MCP.
• perfiles CDP personalizados: apuntan a un endpoint CDP local o remoto.

openclaw browser profilesopenclaw browser create-profile --name work --color "#FF5A36"openclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name remote --cdp-url https://browser-host.example.comopenclaw browser delete-profile --name work

Usa un perfil específico:

openclaw browser --browser-profile work tabs

Pestañas

openclaw browser tabsopenclaw browser tab new --label docsopenclaw browser tab label t1 docsopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://docs.openclaw.ai --label docsopenclaw browser focus docsopenclaw browser close t1

tabs devuelve primero suggestedTargetId, luego el tabId estable, como t1, la etiqueta opcional y el targetId sin procesar. Los agentes deben pasar suggestedTargetId de vuelta a focus, close, instantáneas y acciones. Puedes asignar una etiqueta con open --label, tab new --label o tab label; se aceptan etiquetas, ids de pestaña, ids de destino sin procesar y prefijos únicos de ids de destino. El campo de solicitud sigue llamándose targetId por compatibilidad, pero acepta estas referencias de pestaña. Trata los ids de destino sin procesar como identificadores de diagnóstico, no como memoria duradera del agente. Cuando Chromium reemplaza el destino sin procesar subyacente durante una navegación o el envío de un formulario, OpenClaw conserva el tabId/la etiqueta estable adjunta a la pestaña de reemplazo cuando puede demostrar la coincidencia. Los ids de destino sin procesar siguen siendo volátiles; prefiere suggestedTargetId.

Instantánea / captura de pantalla / acciones

Instantánea:

openclaw browser snapshotopenclaw browser snapshot --urls

Captura de pantalla:

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref e12openclaw browser screenshot --labels

Notas:

• --full-page es solo para capturas de página; no puede combinarse con --ref ni --element.
• Los perfiles existing-session / user admiten capturas de pantalla de página y capturas --ref desde la salida de la instantánea, pero no capturas de pantalla CSS --element.
• --labels superpone las referencias de la instantánea actual en la captura de pantalla. En perfiles respaldados por Playwright, funciona con --full-page (superposición de etiquetas de página completa), --ref (superposición de etiquetas de recorte de elemento por referencia ARIA) y --element (superposición de etiquetas de recorte de elemento por selector CSS); en modos de recorte de elemento, las etiquetas se proyectan en relación con el elemento. La respuesta también incluye un arreglo annotations con el cuadro delimitador de cada referencia. Cada elemento tiene ref, number, role, name opcional y box: {x, y, width, height}; las coordenadas están en el espacio de la imagen capturada (viewport / página completa / relativo al elemento). El campo se omite cuando está vacío. Los perfiles existing-session renderizan una superposición chrome-mcp en las capturas de pantalla de página, pero no usan el helper de proyección de Playwright ni incluyen annotations; las capturas de pantalla CSS --element no se admiten allí. Sin Playwright ni chrome-mcp, las capturas de pantalla con etiquetas no están disponibles. Versiones anteriores ignoraban --full-page, --ref y --element en capturas de pantalla con etiquetas de Playwright y siempre devolvían una captura del viewport; ahora las capturas de pantalla con etiquetas respetan esos ámbitos.
• snapshot --urls agrega destinos de enlaces descubiertos a las instantáneas de IA para que los agentes puedan elegir destinos de navegación directos en lugar de adivinar solo a partir del texto del enlace.

Navegar/hacer clic/escribir (automatización de IU basada en referencias):

openclaw browser navigate https://example.comopenclaw browser click <ref>openclaw browser click-coords 120 340openclaw browser type <ref> "hello"openclaw browser press Enteropenclaw browser hover <ref>openclaw browser scrollintoview <ref>openclaw browser drag <startRef> <endRef>openclaw browser select <ref> OptionA OptionBopenclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'openclaw browser wait --text "Done"openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>openclaw browser evaluate --fn 'const title = document.title; return title;'openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'

evaluate --fn acepta el código fuente de una función, una expresión o el cuerpo de una sentencia. Los cuerpos de sentencia se envuelven como funciones asíncronas, así que usa return para el valor que quieres recibir. Usa evaluate --timeout-ms <ms> cuando la función del lado de la página pueda necesitar más tiempo que el tiempo de espera predeterminado de evaluate.

Las respuestas de acciones devuelven el targetId sin procesar actual después de un reemplazo de página activado por la acción cuando OpenClaw puede demostrar la pestaña de reemplazo. Los scripts deben seguir almacenando y pasando suggestedTargetId/etiquetas para flujos de trabajo duraderos.

Helpers de archivos y diálogos:

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>openclaw browser upload media://inbound/file.pdf --ref <ref>openclaw browser waitfordownloadopenclaw browser download <ref> report.pdfopenclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1

Los perfiles gestionados de Chrome guardan las descargas ordinarias activadas por clic en el directorio de descargas de OpenClaw (/tmp/openclaw/downloads de forma predeterminada, o la raíz temporal configurada). Usa waitfordownload o download cuando el agente necesite esperar un archivo específico y devolver su ruta; esos esperadores explícitos son dueños de la siguiente descarga. Las cargas aceptan archivos desde la raíz temporal de cargas de OpenClaw y medios entrantes gestionados por OpenClaw, incluidas referencias media://inbound/<id> y media/inbound/<id> relativas al sandbox. Las referencias de medios anidadas, el recorrido de rutas y las rutas locales arbitrarias siguen rechazándose. Cuando una acción abre un diálogo modal, la respuesta de la acción devuelve blockedByDialog con browserState.dialogs.pending; pasa --dialog-id para responderlo directamente. Los diálogos gestionados fuera de OpenClaw aparecen en browserState.dialogs.recent.

Estado y almacenamiento

Viewport + emulación:

openclaw browser resize 1280 720openclaw browser set viewport 1280 720openclaw browser set offline onopenclaw browser set media darkopenclaw browser set timezone Europe/Londonopenclaw browser set locale en-GBopenclaw browser set geo 51.5074 -0.1278 --accuracy 25openclaw browser set device "iPhone 14"openclaw browser set headers '{"x-test":"1"}'openclaw browser set credentials myuser mypass

Cookies + almacenamiento:

openclaw browser cookiesopenclaw browser cookies set session abc123 --url https://example.comopenclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set token abc123openclaw browser storage session clear

Depuración

openclaw browser console --level erroropenclaw browser pdfopenclaw browser responsebody "**/api"openclaw browser highlight <ref>openclaw browser errors --clearopenclaw browser requests --filter apiopenclaw browser trace startopenclaw browser trace stop --out trace.zip

Chrome existente mediante MCP

Usa el perfil user integrado, o crea tu propio perfil existing-session:

openclaw browser --browser-profile user tabsopenclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"openclaw browser create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222openclaw browser --browser-profile chrome-live tabs

La ruta predeterminada de existing-session es la conexión automática de Chrome MCP solo del host. Si el navegador ya se está ejecutando con un endpoint de DevTools, pasa --cdp-url para que Chrome MCP se adjunte a ese endpoint en su lugar. Para Docker, Browserless u otras configuraciones remotas donde no se necesitan las semánticas de Chrome MCP, usa un perfil CDP.

Límites actuales de existing-session:

• las acciones basadas en instantáneas usan refs, no selectores CSS
• browser.actionTimeoutMs aplica de forma predeterminada 60000 ms a las solicitudes act compatibles cuando los llamadores omiten timeoutMs; el timeoutMs por llamada sigue teniendo prioridad.
• click solo hace clic izquierdo
• type no admite slowly=true
• press no admite delayMs
• hover, scrollintoview, drag, select, fill y evaluate rechazan las anulaciones de tiempo de espera por llamada
• select admite un solo valor
• wait --load networkidle no se admite en perfiles de sesión existente (funciona en CDP administrado y sin procesar/remoto)
• las cargas de archivos requieren --ref / --input-ref, no admiten --element CSS y actualmente admiten un archivo a la vez
• los hooks de diálogo no admiten --timeout
• las capturas de pantalla admiten capturas de página y --ref, pero no --element CSS
• responsebody, la interceptación de descargas, la exportación a PDF y las acciones por lotes aún requieren un navegador administrado o un perfil CDP sin procesar

Control remoto del navegador (proxy de host de Node)

Si el Gateway se ejecuta en una máquina distinta de la del navegador, ejecuta un host de Node en la máquina que tiene Chrome/Brave/Edge/Chromium. El Gateway enviará las acciones del navegador a ese nodo mediante proxy (no se requiere un servidor de control de navegador separado).

Usa gateway.nodes.browser.mode para controlar el enrutamiento automático y gateway.nodes.browser.node para fijar un nodo específico si hay varios conectados.

Seguridad + configuración remota: Herramienta de navegador, Acceso remoto, Tailscale, Seguridad

Relacionado

• Referencia de CLI
• Navegador