--- read_when: - Programar o depurar el navegador del agente mediante la API de control local - Buscando la referencia de CLI de `openclaw browser` - Agregar automatización personalizada del navegador con snapshots y refs summary: API de control del navegador de OpenClaw, referencia de CLI y acciones de scripting title: API de control del navegador x-i18n: generated_at: "2026-07-05T11:43:24Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 72412826cdf61f59fc9470be41834c9a35b0af2dff162fcc401e9d0f5790a2bb source_path: tools/browser-control.md workflow: 16 --- Para la configuración, los ajustes y la solución de problemas, consulta [Browser](/es/tools/browser). Esta página es la referencia para la API HTTP de control local, la CLI `openclaw browser` y los patrones de scripting (snapshots, refs, esperas, flujos de depuración). ## API de control (opcional) Solo para integraciones locales, el Gateway expone una pequeña API HTTP de loopback. Este servidor independiente es opcional: establece la variable de entorno `OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1` en el entorno del servicio gateway y reinicia el gateway antes de que los endpoints HTTP estén disponibles. Sin esta variable, el runtime de control del navegador sigue funcionando mediante la CLI y las herramientas del agente, pero nada escucha en el puerto de control de loopback. - Estado/iniciar/detener: `GET /`, `GET /doctor`, `POST /start`, `POST /stop`, `POST /reset-profile` - Perfiles: `GET /profiles`, `POST /profiles/create`, `DELETE /profiles/:name` - Pestañas: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId`, `POST /tabs/action` - 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` - Permisos: `POST /permissions/grant` - Depuración: `GET /console`, `POST /pdf` - Depuración: `GET /errors`, `GET /requests`, `GET /dialogs`, `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` `POST /tabs/action` es la forma por lotes que la CLI usa internamente para los subcomandos de `browser tab` (`{"action":"new"|"label"|"select"|"close"|"list", ...}`); prefiere las rutas de pestaña de propósito único anteriores al crear scripts directamente. Todos los endpoints aceptan `?profile=`. `POST /start?headless=true` solicita un lanzamiento headless de un solo uso para perfiles gestionados locales sin cambiar la configuración persistente del navegador; los perfiles de solo conexión, CDP remoto y sesión existente rechazan esa anulación porque OpenClaw no lanza esos procesos de navegador. Para endpoints de pestañas, `targetId` es el nombre del campo de compatibilidad. Prefiere pasar `suggestedTargetId` desde `GET /tabs` o `POST /tabs/open`; también se aceptan etiquetas y identificadores `tabId` como `t1`. Los ids de destino CDP sin procesar y los prefijos únicos de ids de destino sin procesar siguen funcionando, pero son identificadores de diagnóstico volátiles. Si la autenticación del gateway con secreto compartido está configurada, las rutas HTTP del navegador también requieren autenticación: - `Authorization: Bearer ` - `x-openclaw-password: ` o autenticación HTTP Basic con esa contraseña Notas: - Esta API de navegador de loopback independiente **no** consume encabezados de identidad de proxy de confianza ni de Tailscale Serve. - Si `gateway.auth.mode` es `none` o `trusted-proxy`, estas rutas de navegador de loopback no heredan esos modos portadores de identidad; mantenlas solo en loopback. ### Contrato de errores de `/act` `POST /act` usa una respuesta de error estructurada para validación a nivel de ruta y fallos de política: ```json { "error": "", "code": "ACT_*" } ``` Valores actuales de `code`: - `ACT_KIND_REQUIRED` (HTTP 400): falta `kind` o no se reconoce. - `ACT_INVALID_REQUEST` (HTTP 400): el payload de la acción no superó 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á deshabilitado por configuración. - `ACT_TARGET_ID_MISMATCH` (HTTP 403): el `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. Otros fallos de runtime pueden seguir devolviendo `{ "error": "" }` sin un campo `code`. ### Requisito de Playwright Algunas funciones (navigate/act/snapshot de IA/snapshot de rol, capturas de pantalla de elementos, PDF) requieren Playwright. Si Playwright no está instalado, esos endpoints devuelven un error 501 claro. Lo que sigue funcionando sin Playwright: - Snapshots ARIA - Snapshots de accesibilidad estilo rol (`--interactive`, `--compact`, `--depth`, `--efficient`) cuando hay disponible un WebSocket CDP por pestaña. Esto es una alternativa para inspección y descubrimiento de refs; Playwright sigue siendo el motor de acciones principal. - Capturas de pantalla de página para el navegador `openclaw` gestionado cuando hay disponible un WebSocket CDP por pestaña - Capturas de pantalla de página para perfiles `existing-session` / Chrome MCP - Capturas de pantalla basadas en refs de `existing-session` (`--ref`) desde la salida de snapshot Lo que aún necesita Playwright: - `navigate` - `act` - Snapshots de IA que dependen del formato nativo de snapshot de IA de Playwright - Capturas de pantalla de elementos con selector CSS (`--element`) - exportación completa del navegador a PDF Las capturas de pantalla de elementos también rechazan `--full-page`; la ruta devuelve `fullPage is not supported for element screenshots`. Si ves `Playwright is not available in this gateway build`, al Gateway empaquetado le falta la dependencia central de runtime del navegador. Reinstala o actualiza OpenClaw y luego reinicia el gateway. Para Docker, instala también los binarios del navegador Chromium como se muestra a continuación. #### Instalación de Playwright en Docker Si tu Gateway se ejecuta en Docker, evita `npx playwright` (conflictos de anulación de npm). Para imágenes personalizadas, integra Chromium en la imagen: ```bash OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh ``` Para una imagen existente, instala mediante la CLI incluida en su lugar: ```bash 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 mediante `OPENCLAW_HOME_VOLUME` o un bind mount. OpenClaw detecta automáticamente el Chromium persistido en Linux. Consulta [Docker](/es/install/docker). ## Cómo funciona (interno) Un pequeño servidor de control de loopback acepta solicitudes HTTP y se conecta a navegadores basados en Chromium mediante CDP. Las acciones avanzadas (click/type/snapshot/PDF) pasan por Playwright sobre CDP; cuando falta Playwright, solo están disponibles las operaciones que no usan Playwright. El agente ve una interfaz estable mientras los navegadores y perfiles locales/remotos se intercambian libremente por debajo. ## Referencia rápida de la CLI Todos los comandos aceptan `--browser-profile ` para apuntar a un perfil específico, y `--json` para salida legible por máquina. ```bash openclaw browser status openclaw browser doctor openclaw browser doctor --deep # add a live snapshot probe openclaw browser start openclaw browser start --headless # one-shot local managed headless launch openclaw browser stop # also clears emulation on attach-only/remote CDP openclaw browser reset-profile # moves the profile's browser data to Trash openclaw browser tabs openclaw browser tab # shortcut for current tab openclaw browser tab new openclaw browser tab new --label research openclaw browser tab label abcd1234 research openclaw browser tab select 2 openclaw browser tab close 2 openclaw browser open https://example.com openclaw browser focus abcd1234 openclaw browser close abcd1234 ``` ```bash openclaw browser profiles openclaw browser create-profile --name research --color "#0066CC" openclaw browser create-profile --name attach --driver existing-session --cdp-url http://127.0.0.1:9222 openclaw browser delete-profile --name research ``` ```bash openclaw browser screenshot openclaw browser screenshot --full-page openclaw browser screenshot --ref 12 # or --ref e12 openclaw browser screenshot --labels 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 --urls openclaw browser snapshot --selector "#main" --interactive openclaw browser snapshot --frame "iframe#main" --interactive openclaw browser snapshot --out snapshot.txt 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 ``` ```bash openclaw browser navigate https://example.com openclaw browser resize 1280 720 openclaw browser click 12 --double # or e12 for role refs openclaw browser click-coords 120 340 # viewport coordinates 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 upload media://inbound/file.pdf openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]' openclaw browser dialog --accept openclaw browser dialog --dismiss --dialog-id d1 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 evaluate --fn 'const title = document.title; return title;' openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }' openclaw browser highlight e12 openclaw browser trace start openclaw browser trace stop ``` ```bash 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 # --clear to remove openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com" 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 click/press que activa el selector/cuadro de diálogo. Si una acción abre un modal, la respuesta de la acción incluye `blockedByDialog` y `browserState.dialogs.pending`; pasa ese `dialogId` para responder directamente. Los cuadros de diálogo gestionados fuera de OpenClaw aparecen en `browserState.dialogs.recent`. - `click`/`type`/etc requieren una `ref` de `snapshot` (numérica `12`, ref de rol `e12` o ref ARIA accionable `ax12`). Los selectores CSS no son compatibles intencionalmente para acciones. Usa `click-coords` cuando la posición visible del viewport sea el único destino fiable. - Las rutas de descarga y traza están restringidas a las raíces temporales de OpenClaw: `/tmp/openclaw{,/downloads}` (alternativa: `${os.tmpdir()}/openclaw/...`). - `upload` acepta archivos desde la raíz temporal de subidas de OpenClaw y medios entrantes gestionados por OpenClaw. Los medios entrantes gestionados pueden referenciarse como `media://inbound/`, `media/inbound/` relativo al sandbox, o una ruta resuelta dentro del directorio de medios entrantes gestionados. Las refs de medios anidadas, traversal, symlinks, hardlinks y rutas locales arbitrarias se siguen rechazando. - `upload` también puede establecer entradas de archivo directamente mediante `--input-ref` o `--element`. Los ids y las etiquetas de pestaña estables sobreviven al reemplazo raw-target de Chromium cuando OpenClaw puede probar la pestaña de reemplazo, como la misma URL o una sola pestaña antigua que se convierte en una sola pestaña nueva después del envío de un formulario. Los ids de destino sin procesar siguen siendo volátiles; prefiere `suggestedTargetId` de `tabs` en los scripts. Indicadores de instantáneas de un vistazo: - `--format ai` (predeterminado con Playwright): instantánea de IA con referencias numéricas (`aria-ref=""`). - `--format aria`: árbol de accesibilidad con referencias `axN`. Cuando Playwright está disponible, OpenClaw vincula las referencias con ids DOM de backend a la página activa para que las acciones de seguimiento puedan usarlas; de lo contrario, trata la salida solo como inspección. - `--efficient` (o `--mode efficient`): preajuste compacto de instantánea de roles. Configura `browser.snapshotDefaults.mode: "efficient"` para que sea el valor predeterminado (consulta [Configuración del Gateway](/es/gateway/configuration-reference#browser)). - `--interactive`, `--compact`, `--depth`, `--selector` fuerzan una instantánea de roles con referencias `ref=e12`. `--frame "