OmeniaClaw browser

Administra la superficie de control del navegador de OmeniaClaw 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 del navegador + API: Herramienta del navegador

Marcas comunes

• --url <gatewayWsUrl>: URL WebSocket del Gateway (usa la configuración por defecto).
• --token <token>: token del Gateway (si se requiere).
• --timeout <ms>: tiempo de espera de la solicitud (ms).
• --expect-final: espera una respuesta final del Gateway.
• --browser-profile <name>: elige un perfil de navegador (por defecto desde la configuración).
• --json: salida legible por máquinas (donde sea compatible).

Inicio rápido (local)

OmeniaClaw browser profilesOmeniaClaw browser --browser-profile OmeniaClaw startOmeniaClaw browser --browser-profile OmeniaClaw open https://example.comOmeniaClaw browser --browser-profile OmeniaClaw snapshot

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

Solución rápida de problemas

Si start falla con not reachable after start, primero soluciona la preparación 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 ser la política SSRF de navegación.

Secuencia mínima:

OmeniaClaw browser --browser-profile OmeniaClaw doctorOmeniaClaw browser --browser-profile OmeniaClaw startOmeniaClaw browser --browser-profile OmeniaClaw tabsOmeniaClaw browser --browser-profile OmeniaClaw open https://example.com

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

Ciclo de vida

OmeniaClaw browser statusOmeniaClaw browser doctorOmeniaClaw browser doctor --deepOmeniaClaw browser startOmeniaClaw browser start --headlessOmeniaClaw browser stopOmeniaClaw browser --browser-profile OmeniaClaw reset-profile

Notas:

• doctor --deep agrega una prueba de instantánea en vivo. Es útil cuando la preparación básica de CDP está en verde, pero quieres una prueba de que la pestaña actual se puede inspeccionar.
• Para perfiles attachOnly y CDP remotos, OmeniaClaw browser stop cierra la sesión de control activa y borra las anulaciones temporales de emulación incluso cuando OmeniaClaw no inició el proceso del navegador.
• Para perfiles locales administrados, OmeniaClaw browser stop detiene el proceso de navegador generado.
• OmeniaClaw browser start --headless se aplica solo a esa solicitud de inicio y solo cuando OmeniaClaw inicia un navegador local administrado. No reescribe browser.headless ni la configuración del perfil, y no tiene efecto en un navegador que ya está en ejecución.
• En hosts Linux sin DISPLAY ni WAYLAND_DISPLAY, los perfiles locales administrados se ejecutan automáticamente sin interfaz gráfica a menos que OmeniaClaw_BROWSER_HEADLESS=0, browser.headless=false o browser.profiles.<name>.headless=false soliciten explícitamente un navegador visible.

Si falta el comando

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

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

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

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

Relacionado: Herramienta del navegador

Perfiles

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

• OmeniaClaw: inicia o se adjunta a una instancia dedicada de Chrome administrada por OmeniaClaw (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.

OmeniaClaw browser profilesOmeniaClaw browser create-profile --name work --color "#FF5A36"OmeniaClaw browser create-profile --name chrome-live --driver existing-sessionOmeniaClaw browser create-profile --name remote --cdp-url https://browser-host.example.comOmeniaClaw browser delete-profile --name work

Usa un perfil específico:

OmeniaClaw browser --browser-profile work tabs

Pestañas

OmeniaClaw browser tabsOmeniaClaw browser tab new --label docsOmeniaClaw browser tab label t1 docsOmeniaClaw browser tab select 2OmeniaClaw browser tab close 2OmeniaClaw browser open https://omeniaclaw.com --label docsOmeniaClaw browser focus docsOmeniaClaw 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 id de destino. Cuando Chromium reemplaza el destino sin procesar subyacente durante una navegación o envío de formulario, OmeniaClaw mantiene el tabId/la etiqueta estable asociado 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:

OmeniaClaw browser snapshotOmeniaClaw browser snapshot --urls

Captura de pantalla:

OmeniaClaw browser screenshotOmeniaClaw browser screenshot --full-pageOmeniaClaw browser screenshot --ref e12OmeniaClaw browser screenshot --labels

Notas:

• --full-page es solo para capturas de página; no se puede combinar con --ref ni --element.
• Los perfiles existing-session / user admiten capturas de pantalla de página y capturas --ref desde la salida de instantánea, pero no capturas CSS --element.
• --labels superpone las referencias de instantánea actuales sobre la captura de pantalla.
• snapshot --urls agrega los 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 UI basada en referencias):

OmeniaClaw browser navigate https://example.comOmeniaClaw browser click <ref>OmeniaClaw browser click-coords 120 340OmeniaClaw browser type <ref> "hello"OmeniaClaw browser press EnterOmeniaClaw browser hover <ref>OmeniaClaw browser scrollintoview <ref>OmeniaClaw browser drag <startRef> <endRef>OmeniaClaw browser select <ref> OptionA OptionBOmeniaClaw browser fill --fields '[{"ref":"1","value":"Ada"}]'OmeniaClaw browser wait --text "Done"OmeniaClaw browser evaluate --fn '(el) => el.textContent' --ref <ref>

Las respuestas de acciones devuelven el targetId sin procesar actual después de un reemplazo de página activado por la acción cuando OmeniaClaw puede demostrar la pestaña de reemplazo. Aun así, los scripts deben almacenar y pasar suggestedTargetId/etiquetas para flujos de trabajo de larga duración.

Ayudantes de archivos + diálogos:

OmeniaClaw browser upload /tmp/OmeniaClaw/uploads/file.pdf --ref <ref>OmeniaClaw browser waitfordownloadOmeniaClaw browser download <ref> report.pdfOmeniaClaw browser dialog --accept

Los perfiles de Chrome administrados guardan las descargas ordinarias activadas por clic en el directorio de descargas de OmeniaClaw (/tmp/OmeniaClaw/downloads por defecto, 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.

Estado y almacenamiento

Vista + emulación:

OmeniaClaw browser resize 1280 720OmeniaClaw browser set viewport 1280 720OmeniaClaw browser set offline onOmeniaClaw browser set media darkOmeniaClaw browser set timezone Europe/LondonOmeniaClaw browser set locale en-GBOmeniaClaw browser set geo 51.5074 -0.1278 --accuracy 25OmeniaClaw browser set device "iPhone 14"OmeniaClaw browser set headers '{"x-test":"1"}'OmeniaClaw browser set credentials myuser mypass

Cookies + almacenamiento:

OmeniaClaw browser cookiesOmeniaClaw browser cookies set session abc123 --url https://example.comOmeniaClaw browser cookies clearOmeniaClaw browser storage local getOmeniaClaw browser storage local set token abc123OmeniaClaw browser storage session clear

Depuración

OmeniaClaw browser console --level errorOmeniaClaw browser pdfOmeniaClaw browser responsebody "**/api"OmeniaClaw browser highlight <ref>OmeniaClaw browser errors --clearOmeniaClaw browser requests --filter apiOmeniaClaw browser trace startOmeniaClaw browser trace stop --out trace.zip

Chrome existente mediante MCP

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

OmeniaClaw browser --browser-profile user tabsOmeniaClaw browser create-profile --name chrome-live --driver existing-sessionOmeniaClaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"OmeniaClaw browser --browser-profile chrome-live tabs

Esta ruta es solo para host. Para Docker, servidores sin interfaz gráfica, Browserless u otras configuraciones remotas, usa un perfil CDP en su lugar.

Límites actuales de existing-session:

• las acciones impulsadas por instantáneas usan referencias, no selectores CSS
• browser.actionTimeoutMs establece por defecto las solicitudes act compatibles en 60000 ms cuando los llamadores omiten timeoutMs; timeoutMs por llamada sigue prevaleciendo.
• click es solo clic izquierdo
• type no admite slowly=true
• press no admite delayMs
• hover, scrollintoview, drag, select, fill y evaluate rechazan anulaciones de tiempo de espera por llamada
• select admite solo un valor
• wait --load networkidle no es compatible
• las cargas de archivos requieren --ref / --input-ref, no admiten CSS --element 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 CSS --element
• responsebody, la intercepción de descargas, la exportación PDF y las acciones por lotes todavía requieren un navegador administrado o un perfil CDP sin procesar

Control remoto del navegador (proxy de host de nodo)

Si el Gateway se ejecuta en una máquina distinta a la del navegador, ejecuta un host de nodo en la máquina que tiene Chrome/Brave/Edge/Chromium. El Gateway enviará por proxy las acciones del navegador a ese nodo (no se requiere un servidor de control del 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 del navegador, Acceso remoto, Tailscale, Seguridad

Relacionado

• Referencia de CLI
• Navegador