Navegador (administrado por openclaw)
OpenClaw puede ejecutar un perfil dedicado de Chrome/Brave/Edge/Chromium que el agente controla. Está aislado de su navegador personal y se gestiona mediante un pequeño servicio de control local dentro del Gateway (solo loopback). Vista para principiantes:- Piense en ello como un navegador separado, solo para el agente.
- El perfil
openclawno toca su perfil personal del navegador. - El agente puede abrir pestañas, leer páginas, hacer clic y escribir en un entorno seguro.
- El perfil predeterminado
chromeusa el navegador Chromium predeterminado del sistema a través del relay de extensiones; cambie aopenclawpara el navegador administrado e aislado.
Qué obtiene
- 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), instantáneas, capturas de pantalla, PDFs.
- Soporte opcional para múltiples perfiles (
openclaw,work,remote, …).
Inicio rápido
Perfiles: openclaw vs chrome
openclaw: navegador administrado y aislado (no requiere extensión).chrome: relay de extensión hacia su navegador del sistema (requiere que la extensión de OpenClaw esté adjunta a una pestaña).
browser.defaultProfile: "openclaw" si desea el modo administrado de forma predeterminada.
Configuración
Los ajustes del navegador viven en~/.openclaw/openclaw.json.
- El servicio de control del navegador se vincula a loopback en un puerto derivado de
gateway.port(predeterminado:18791, que es gateway + 2). El relay usa el siguiente puerto (18792). - Si anula el puerto del Gateway (
gateway.portoOPENCLAW_GATEWAY_PORT), los puertos derivados del navegador se desplazan para mantenerse en la misma “familia”. cdpUrlusa por defecto el puerto del relay cuando no se establece.remoteCdpTimeoutMsse aplica a verificaciones de alcanzabilidad CDP remotas (no loopback).remoteCdpHandshakeTimeoutMsse aplica a verificaciones de alcanzabilidad del WebSocket CDP remoto.attachOnly: truesignifica “nunca lanzar un navegador local; solo adjuntarse si ya está en ejecución”.color+colorpor perfil tiñen la UI del navegador para que pueda ver qué perfil está activo.- El perfil predeterminado es
chrome(relay de extensión). UsedefaultProfile: "openclaw"para el navegador administrado. - Orden de autodetección: navegador predeterminado del sistema si es Chromium; de lo contrario Chrome → Brave → Edge → Chromium → Chrome Canary.
- Los perfiles locales
openclawasignan automáticamentecdpPort/cdpUrl— establezca esos solo para CDP remoto.
Usar Brave (u otro navegador basado en Chromium)
Si su navegador predeterminado del sistema es basado en Chromium (Chrome/Brave/Edge/etc), OpenClaw lo usa automáticamente. Establezcabrowser.executablePath para anular
la autodetección:
Ejemplo de CLI:
Control local vs remoto
- Control local (predeterminado): el Gateway inicia el servicio de control en loopback y puede lanzar un navegador local.
- Control remoto (host de nodo): ejecute un host de nodo en la máquina que tiene el navegador; el Gateway proxya las acciones del navegador hacia él.
- CDP remoto: establezca
browser.profiles.<name>.cdpUrl(obrowser.cdpUrl) para adjuntarse a un navegador basado en Chromium remoto. En este caso, OpenClaw no lanzará un navegador local.
- Tokens de consulta (p. ej.,
https://provider.example?token=<token>) - Autenticación HTTP Basic (p. ej.,
https://user:[email protected])
/json/* y al conectarse
al WebSocket CDP. Prefiera variables de entorno o gestores de secretos para
los tokens en lugar de confirmarlos en archivos de configuración.
Proxy de navegador del nodo (predeterminado sin configuración)
Si ejecuta un host de nodo en la máquina que tiene su navegador, OpenClaw puede redirigir automáticamente las llamadas de herramientas del navegador a ese nodo sin ninguna configuración adicional del navegador. Este es el camino predeterminado para gateways remotos. Notas:- El host del nodo expone su servidor local de control del navegador mediante un comando proxy.
- Los perfiles provienen de la propia configuración
browser.profilesdel nodo (igual que local). - Desactívelo si no lo desea:
- En el nodo:
nodeHost.browserProxy.enabled=false - En el gateway:
gateway.nodes.browser.mode="off"
- En el nodo:
Browserless (CDP remoto alojado)
Browserless es un servicio Chromium alojado que expone endpoints CDP sobre HTTPS. Puede apuntar un perfil de navegador de OpenClaw a un endpoint regional de Browserless y autenticarse con su clave de API. Ejemplo:- Reemplace
<BROWSERLESS_API_KEY>con su token real de Browserless. - Elija el endpoint regional que coincida con su cuenta de Browserless (consulte su documentació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 del nodo.
- Si el control del navegador está habilitado y no hay autenticación configurada, OpenClaw genera automáticamente
gateway.auth.tokenal iniciarse y lo guarda en la configuración. - Mantenga el Gateway y cualquier host de nodo en una red privada (Tailscale); evite la exposición pública.
- Trate las URLs/tokens de CDP remoto como secretos; prefiera variables de entorno o un gestor de secretos.
- Prefiera endpoints HTTPS y tokens de corta duración cuando sea posible.
- Evite incrustar tokens de larga duración directamente en archivos de configuración.
Perfiles (multi-navegador)
OpenClaw admite múltiples perfiles con nombre (configuraciones de enrutamiento). Los perfiles pueden ser:- openclaw-managed: una instancia dedicada de navegador basado en Chromium con su propio directorio de datos de usuario + puerto CDP
- remote: una URL CDP explícita (navegador basado en Chromium ejecutándose en otro lugar)
- extension relay: sus pestañas existentes de Chrome mediante el relay local + extensión de Chrome
- El perfil
openclawse crea automáticamente si falta. - El perfil
chromeestá integrado para el relay de la extensión de Chrome (apunta ahttp://127.0.0.1:18792de forma predeterminada). - Los puertos CDP locales se asignan desde 18800–18899 de forma predeterminada.
- Eliminar un perfil mueve su directorio de datos local a la Papelera.
?profile=<name>; la CLI usa --browser-profile.
Relay de extensión de Chrome (use su Chrome existente)
OpenClaw también puede controlar sus pestañas existentes de Chrome (sin una instancia separada de Chrome “openclaw”) mediante un relay CDP local + una extensión de Chrome. Guía completa: Chrome extension Flujo:- El Gateway se ejecuta localmente (misma máquina) o un host de nodo se ejecuta en la máquina del navegador.
- Un servidor de relay local escucha en un loopback
cdpUrl(predeterminado:http://127.0.0.1:18792). - Usted hace clic en el ícono de la extensión OpenClaw Browser Relay en una pestaña para adjuntarla (no se adjunta automáticamente).
- El agente controla esa pestaña mediante la herramienta normal
browser, seleccionando el perfil correcto.
Sesiones en sandbox
Si la sesión del agente está en sandbox, la herramientabrowser puede usar por defecto target="sandbox" (navegador de sandbox).
La toma de control del relay de la extensión de Chrome requiere control del navegador del host, por lo que debe:
- ejecutar la sesión sin sandbox, o
- establecer
agents.defaults.sandbox.browser.allowHostControl: truey usartarget="host"al llamar a la herramienta.
Configuración
- Cargue la extensión (dev/unpacked):
- Chrome →
chrome://extensions→ habilite “Developer mode” - “Load unpacked” → seleccione el directorio impreso por
openclaw browser extension path - Fije la extensión y luego haga clic en ella en la pestaña que desea controlar (la insignia muestra
ON).
- Utilícelo:
- CLI:
openclaw browser --browser-profile chrome tabs - Herramienta del agente:
browserconprofile="chrome"
- Este modo se basa en Playwright-on-CDP para la mayoría de las operaciones (capturas/snapshots/acciones).
- Desacople haciendo clic nuevamente en el ícono de la extensión.
Garantías de aislamiento
- Directorio de datos de usuario dedicado: nunca toca su perfil personal del navegador.
- Puertos dedicados: evita
9222para prevenir colisiones con flujos de trabajo de desarrollo. - Control determinista de pestañas: apunte a pestañas por
targetId, no por “última pestaña”.
Selección del navegador
Al lanzar localmente, OpenClaw elige el primero disponible:- Chrome
- Brave
- Edge
- Chromium
- Chrome Canary
browser.executablePath.
Plataformas:
- macOS: verifica
/Applicationsy~/Applications. - Linux: busca
google-chrome,brave,microsoft-edge,chromium, etc. - Windows: verifica ubicaciones comunes de instalación.
API de control (opcional)
Solo para integraciones locales, el Gateway expone una pequeña API HTTP en loopback:- Estado/iniciar/detener:
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 - Ajustes:
POST /set/offline,POST /set/headers,POST /set/credentials,POST /set/geolocation,POST /set/media,POST /set/timezone,POST /set/locale,POST /set/device
?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 (navegar/actuar/snapshot de IA/snapshot por rol, capturas de elementos, PDF) requieren Playwright. Si Playwright no está instalado, esos endpoints devuelven un error 501 claro. Las instantáneas ARIA y las capturas básicas aún funcionan para Chrome administrado por openclaw. Para el controlador de relay de la extensión de Chrome, las instantáneas ARIA y las capturas requieren Playwright. Si vePlaywright is not available in this gateway build, instale el paquete completo de
Playwright (no playwright-core) y reinicie el gateway, o reinstale
OpenClaw con soporte de navegador.
Instalación de Playwright en Docker
Si su Gateway se ejecuta en Docker, evitenpx playwright (conflictos de override de npm).
Use la CLI incluida:
PLAYWRIGHT_BROWSERS_PATH (por ejemplo,
/home/node/.cache/ms-playwright) y asegúrese de que /home/node persista mediante
OPENCLAW_HOME_VOLUME o un bind mount. Consulte 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) mediante CDP.
- Para acciones avanzadas (clic/escribir/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
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áquinas (payloads estables).
Básicos:
openclaw browser statusopenclaw browser startopenclaw browser stopopenclaw browser tabsopenclaw browser tabopenclaw browser tab newopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://example.comopenclaw browser focus abcd1234openclaw browser close abcd1234
openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref 12openclaw browser screenshot --ref e12openclaw browser snapshotopenclaw browser snapshot --format aria --limit 200openclaw browser snapshot --interactive --compact --depth 6openclaw browser snapshot --efficientopenclaw browser snapshot --labelsopenclaw browser snapshot --selector "#main" --interactiveopenclaw browser snapshot --frame "iframe#main" --interactiveopenclaw browser console --level erroropenclaw browser errors --clearopenclaw browser requests --filter api --clearopenclaw browser pdfopenclaw browser responsebody "**/api" --max-chars 5000
openclaw browser navigate https://example.comopenclaw browser resize 1280 720openclaw browser click 12 --doubleopenclaw browser click e12 --doubleopenclaw browser type 23 "hello" --submitopenclaw browser press Enteropenclaw browser hover 44openclaw browser scrollintoview e12openclaw browser drag 10 11openclaw browser select 9 OptionA OptionBopenclaw browser download e12 /tmp/report.pdfopenclaw browser waitfordownload /tmp/report.pdfopenclaw browser upload /tmp/file.pdfopenclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'openclaw browser dialog --acceptopenclaw browser wait --text "Done"openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"openclaw browser evaluate --fn '(el) => el.textContent' --ref 7openclaw browser highlight e12openclaw browser trace startopenclaw browser trace stop
openclaw browser cookiesopenclaw browser cookies set session abc123 --url "https://example.com"openclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set theme darkopenclaw browser storage session clearopenclaw browser set offline onopenclaw browser set headers --json '{"X-Debug":"1"}'openclaw browser set credentials user passopenclaw browser set credentials --clearopenclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"openclaw browser set geo --clearopenclaw browser set media darkopenclaw browser set timezone America/New_Yorkopenclaw browser set locale en-USopenclaw browser set device "iPhone 14"
uploadydialogson llamadas de armado; ejecútelas antes del clic/pulsación que dispara el selector/diálogo.- Las rutas de descarga y de trazas están restringidas a los directorios temporales raíz de OpenClaw:
- traces:
/tmp/openclaw(alternativa:${os.tmpdir()}/openclaw) - downloads:
/tmp/openclaw/downloads(alternativa:${os.tmpdir()}/openclaw/downloads)
- traces:
- Las rutas de subida están restringidas a un directorio temporal raíz de subidas de OpenClaw:
- uploads:
/tmp/openclaw/uploads(alternativa:${os.tmpdir()}/openclaw/uploads)
- uploads:
uploadtambién puede establecer entradas de archivos directamente mediante--input-refo--element.snapshot:--format ai(predeterminado cuando Playwright está instalado): devuelve una instantánea de IA con referencias numéricas (aria-ref="<n>").--format aria: devuelve el árbol de accesibilidad (sin referencias; solo inspección).--efficient(o--mode efficient): preajuste compacto de snapshot por rol (interactivo + compacto + profundidad + maxChars menor).- Predeterminado de configuración (solo herramienta/CLI): establezca
browser.snapshotDefaults.mode: "efficient"para usar instantáneas eficientes cuando el llamador no pase un modo (ver Gateway configuration). - Opciones de snapshot por rol (
--interactive,--compact,--depth,--selector) fuerzan un snapshot basado en roles con referencias comoref=e12. --frame "<iframe selector>"delimita los snapshots por rol a un iframe (se combina con referencias de rol comoe12).--interactiveproduce una lista plana y fácil de seleccionar de elementos interactivos (mejor para dirigir acciones).--labelsagrega una captura solo del viewport con etiquetas de referencia superpuestas (imprimeMEDIA:<path>).
click/type/etc requieren unrefdesnapshot(ya sea12numérico o referencia de role12). Los selectores CSS no se admiten intencionalmente para acciones.
Snapshots y referencias
OpenClaw admite dos estilos de “snapshot”:-
Snapshot de IA (referencias numéricas):
openclaw browser snapshot(predeterminado;--format ai)- Salida: un snapshot de texto que incluye referencias numéricas.
- Acciones:
openclaw browser click 12,openclaw browser type 23 "hello". - Internamente, la referencia se resuelve mediante
aria-refde Playwright.
-
Snapshot por rol (referencias de rol como
e12):openclaw browser snapshot --interactive(o--compact,--depth,--selector,--frame)- Salida: una lista/árbol basado en roles con
[ref=e12](y[nth=1]opcional). - Acciones:
openclaw browser click e12,openclaw browser highlight e12. - Internamente, la referencia se resuelve mediante
getByRole(...)(másnth()para duplicados). - Agregue
--labelspara incluir una captura del viewport con etiquetase12superpuestas.
- Salida: una lista/árbol basado en roles con
- Las referencias no son estables entre navegaciones; si algo falla, vuelva a ejecutar
snapshoty use una referencia nueva. - Si el snapshot por rol se tomó con
--frame, las referencias de rol quedan delimitadas a ese iframe hasta el siguiente snapshot por rol.
Potenciadores de espera
Puede esperar más que solo tiempo/texto:- Esperar URL (globs compatibles con Playwright):
openclaw browser wait --url "**/dash"
- Esperar estado de carga:
openclaw browser wait --load networkidle
- Esperar un predicado JS:
openclaw browser wait --fn "window.ready===true"
- Esperar a que un selector se vuelva visible:
openclaw browser wait "#main"
Depurar workflows
Cuando una acción falla (p. ej., “not visible”, “strict mode violation”, “covered”):openclaw browser snapshot --interactive- Use
click <ref>/type <ref>(prefiera referencias de rol en modo interactivo) - Si aún falla:
openclaw browser highlight <ref>para ver qué está apuntando Playwright - Si la página se comporta de forma extraña:
openclaw browser errors --clearopenclaw browser requests --filter api --clear
- Para depuración profunda: registre un trace:
openclaw browser trace start- reproduzca el problema
openclaw browser trace stop(imprimeTRACE:<path>)
Salida JSON
--json es para scripting y herramientas estructuradas.
Ejemplos:
refs más un pequeño bloque stats (líneas/caracteres/referencias/interactivo) para que las herramientas puedan razonar sobre el tamaño y la densidad del payload.
Controles de estado y entorno
Son útiles para flujos de trabajo 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 - Encabezados:
set headers --json '{"X-Debug":"1"}'(o--clear) - Autenticación básica HTTP:
set credentials user pass(o--clear) - Geolocalización:
set geo <lat> <lon> --origin "https://example.com"(o--clear) - Medios:
set media dark|light|no-preference|none - Zona horaria / configuración regional:
set timezone ...,set locale ... - Dispositivo / viewport:
set device "iPhone 14"(preajustes de dispositivos de Playwright)set viewport 1280 720
Seguridad y privacidad
- El perfil del navegador openclaw puede contener sesiones con inicio de sesión; trátelo como sensible.
browser act kind=evaluate/openclaw browser evaluateywait --fnejecutan JavaScript arbitrario en el contexto de la página. La inyección de prompts puede dirigir esto. Desactívelo conbrowser.evaluateEnabled=falsesi no lo necesita.- Para inicios de sesión y notas anti-bot (X/Twitter, etc.), consulte Browser login + X/Twitter posting.
- Mantenga el Gateway/host de nodo privado (solo loopback o tailnet).
- Los endpoints CDP remotos son potentes; túnelos y protéjalos.
Solución de problemas
Para problemas específicos de Linux (especialmente Chromium snap), consulte Browser troubleshooting.Herramientas del agente + cómo funciona el control
El agente obtiene una herramienta para la automatización del navegador:browser— estado/iniciar/detener/pestañas/abrir/enfocar/cerrar/snapshot/captura/navegar/actuar
browser snapshotdevuelve un árbol de UI estable (IA o ARIA).browser actusa los IDsrefdel snapshot para hacer clic/escribir/arrastrar/seleccionar.browser screenshotcaptura píxeles (página completa o elemento).browseracepta:profilepara 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"requiereagents.defaults.sandbox.browser.allowHostControl=true. - Si se omite
target: las sesiones en sandbox usan por defectosandbox, las sesiones sin sandbox usan por defectohost. - Si hay un nodo con capacidad de navegador conectado, la herramienta puede auto-enrutarse a él a menos que fije
target="host"otarget="node".