Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw puede ejecutar un perfil dedicado de Chrome/Brave/Edge/Chromium que controla el agente. Está aislado de tu navegador personal y se gestiona mediante un pequeño servicio de control local dentro del Gateway (solo loopback). Vista para principiantes:
  • Piensa en él como un navegador separado, solo para el agente.
  • El perfil openclaw no toca tu perfil de navegador personal.
  • El agente puede abrir pestañas, leer páginas, hacer clic y escribir en un canal seguro.
  • El perfil integrado user se adjunta a tu sesión real iniciada en Chrome 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), instantáneas, capturas de pantalla, PDF.
  • Una skill browser-automation incluida que enseña a los agentes el bucle de recuperación de instantáneas, pestañas estables, referencias obsoletas y bloqueadores manuales cuando el plugin de navegador está habilitado.
  • Soporte opcional para múltiples perfiles (openclaw, work, remote, …).
Este navegador no es tu navegador de uso diario. Es una superficie segura y aislada para la automatización y verificación del agente.

​
Inicio rápido

openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
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
Si recibes “Browser disabled”, habilítalo en la configuración (consulta más abajo) y reinicia el Gateway. Si openclaw browser no existe en absoluto, o el agente dice que la herramienta de navegador no está disponible, ve a Falta el comando o la herramienta de navegador.

​
Control del Plugin

La herramienta browser predeterminada es un plugin incluido. Deshabilítalo para reemplazarlo por otro plugin que registre el mismo nombre de herramienta browser: 
{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}
Los valores predeterminados necesitan tanto plugins.entries.browser.enabled como browser.enabled=true. Deshabilitar solo el plugin elimina la CLI openclaw browser, el método de Gateway browser.request, la herramienta del agente y el servicio de control como una sola unidad; tu configuración browser.* permanece intacta para un reemplazo. Los cambios de configuración del navegador requieren reiniciar el Gateway para que el plugin pueda volver a registrar su servicio.

​
Guía para agentes

Nota sobre perfiles de herramientas: tools.profile: "coding" incluye web_search y web_fetch, pero no incluye la herramienta browser completa. Si el agente o un subagente generado debe usar automatización del navegador, añade browser en la etapa de perfil: 
{
  tools: {
    profile: "coding",
    alsoAllow: ["browser"],
  },
}
Para un solo agente, usa agents.list[].tools.alsoAllow: ["browser"]. tools.subagents.tools.allow: ["browser"] por sí solo no basta porque la política de subagente se aplica después del filtrado de perfiles. El plugin de navegador incluye dos niveles de guía para agentes:
  • La descripción de la herramienta browser lleva el contrato compacto siempre activo: elegir el perfil correcto, mantener las referencias en la misma pestaña, usar tabId/etiquetas para dirigir pestañas y cargar la skill de navegador para trabajo de varios pasos.
  • La skill browser-automation incluida lleva el bucle operativo más largo: comprobar primero estado/pestañas, etiquetar pestañas de tarea, tomar una instantánea antes de actuar, volver a tomarla después de cambios en la interfaz, recuperar referencias obsoletas una vez e informar inicios de sesión/2FA/captcha o bloqueadores de cámara/micrófono como acción manual en lugar de adivinar.
Las skills incluidas con plugins se listan entre las skills disponibles del agente cuando el plugin está habilitado. Las instrucciones completas de la skill se cargan bajo demanda, por lo que los turnos rutinarios no pagan el costo completo en tokens.

​
Falta el comando o la herramienta de navegador

Si openclaw browser es desconocido después de una actualización, falta browser.request, o el agente informa que la herramienta de navegador no está disponible, la causa habitual es una lista plugins.allow que omite browser y no existe ningún bloque raíz de configuración browser. Añádelo: 
{
  plugins: {
    allow: ["telegram", "browser"],
  },
}
Un bloque raíz explícito browser, por ejemplo browser.enabled=true o browser.profiles.<name>, activa el plugin de navegador incluido incluso bajo un plugins.allow restrictivo, coincidiendo con el comportamiento de configuración de canales. plugins.entries.browser.enabled=true y tools.alsoAllow: ["browser"] no sustituyen por sí solos la pertenencia a la lista permitida. Eliminar plugins.allow por completo también restaura el valor predeterminado.

​
Perfiles: openclaw frente a user

  • openclaw: navegador gestionado y aislado (no requiere extensión).
  • user: perfil integrado de adjunción de Chrome MCP para tu sesión real de Chrome con sesión iniciada.
Para llamadas del agente a la herramienta de navegador:
  • Predeterminado: usa el navegador aislado openclaw.
  • Prefiere profile="user" cuando importen las sesiones existentes con inicio de sesión y el usuario esté frente al ordenador para hacer clic/aprobar cualquier solicitud de adjunción.
  • profile es la anulación explícita cuando quieres un modo de navegador específico.
Establece browser.defaultProfile: "openclaw" si quieres el modo gestionado de forma predeterminada.

​
Configuración

La configuración del navegador vive en ~/.openclaw/openclaw.json. 
{
  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)
    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)
    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)
    actionTimeoutMs: 60000, // default browser act timeout (ms)
    tabCleanup: {
      enabled: true, // default: true
      idleMinutes: 120, // set 0 to disable idle cleanup
      maxTabsPerSession: 8, // set 0 to disable the per-session cap
      sweepMinutes: 5,
    },
    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",
        headless: true,
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      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 se enlaza a loopback en un puerto derivado de gateway.port (predeterminado 18791 = gateway + 2). Anular gateway.port o OPENCLAW_GATEWAY_PORT desplaza los puertos derivados dentro de la misma familia.
  • Los perfiles locales openclaw asignan automáticamente cdpPort/cdpUrl; establece esos valores solo para CDP remoto. cdpUrl usa de forma predeterminada el puerto CDP local gestionado cuando no se establece.
  • remoteCdpTimeoutMs se aplica a comprobaciones de accesibilidad HTTP de CDP remoto y attachOnly, y a solicitudes HTTP de apertura de pestañas; remoteCdpHandshakeTimeoutMs se aplica a sus handshakes WebSocket de CDP.
  • localLaunchTimeoutMs es el presupuesto para que un proceso local gestionado de Chrome exponga su endpoint HTTP de CDP. localCdpReadyTimeoutMs es el presupuesto posterior para la disponibilidad del websocket CDP después de descubrir el proceso. Auméntalos en Raspberry Pi, VPS de gama baja o hardware antiguo donde Chromium arranque lentamente. Los valores deben ser enteros positivos de hasta 120000 ms; los valores de configuración inválidos se rechazan.
  • Los fallos repetidos de lanzamiento/disponibilidad de Chrome gestionado abren un cortacircuitos por perfil. Después de varios fallos consecutivos, OpenClaw pausa brevemente nuevos intentos de lanzamiento en lugar de iniciar Chromium en cada llamada a la herramienta de navegador. Corrige el problema de inicio, deshabilita el navegador si no se necesita, o reinicia el Gateway después de la reparación.
  • actionTimeoutMs es el presupuesto predeterminado para solicitudes act del navegador cuando el llamador no pasa timeoutMs. El transporte del cliente añade una pequeña ventana de holgura para que esperas largas puedan terminar en lugar de agotar el tiempo en el límite HTTP.
  • tabCleanup es una limpieza de mejor esfuerzo para pestañas abiertas por sesiones de navegador del agente principal. La limpieza del ciclo de vida de subagente, cron y ACP sigue cerrando sus pestañas rastreadas explícitas al final de la sesión; las sesiones principales mantienen las pestañas activas reutilizables y luego cierran en segundo plano las pestañas rastreadas inactivas o excedentes.
  • 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 con mejor esfuerzo en la URL http(s) final después.
  • En modo SSRF estricto, también se comprueban la detección de endpoints CDP remotos y las sondas /json/version (cdpUrl).
  • Las variables de entorno HTTP_PROXY, HTTPS_PROXY, ALL_PROXY y NO_PROXY de Gateway/proveedor no proxy automáticamente el navegador gestionado por OpenClaw. Chrome gestionado se inicia de forma directa de manera predeterminada para que la configuración de proxy del proveedor no debilite las comprobaciones SSRF del navegador.
  • Para proxy el navegador gestionado en sí, pasa flags explícitos de proxy de Chrome mediante browser.extraArgs, como --proxy-server=... o --proxy-pac-url=.... El modo SSRF estricto bloquea el enrutamiento explícito de proxy del navegador salvo que el acceso del navegador a redes privadas esté habilitado intencionalmente.
  • browser.ssrfPolicy.dangerouslyAllowPrivateNetwork está desactivado de forma predeterminada; habilítalo solo cuando el acceso del navegador a redes privadas sea de confianza de forma intencional.
  • browser.ssrfPolicy.allowPrivateNetwork sigue siendo compatible como alias heredado.
  • attachOnly: true significa no iniciar nunca un navegador local; solo adjuntarse si ya hay uno en ejecución.
  • headless se puede establecer globalmente o por perfil administrado local. Los valores por perfil anulan browser.headless, de modo que un perfil iniciado localmente puede permanecer sin interfaz mientras otro sigue visible.
  • POST /start?headless=true y openclaw browser start --headless solicitan un inicio sin interfaz de una sola vez para perfiles administrados locales sin reescribir browser.headless ni la configuración del perfil. Los perfiles de sesión existente, solo adjuntar y CDP remoto rechazan la anulación porque OpenClaw no inicia esos procesos de navegador.
  • En hosts Linux sin DISPLAY ni WAYLAND_DISPLAY, los perfiles administrados locales pasan automáticamente al modo sin interfaz cuando ni el entorno ni la configuración del perfil/global eligen explícitamente el modo con interfaz. openclaw browser status --json informa headlessSource como env, profile, config, request, linux-display-fallback o default.
  • OPENCLAW_BROWSER_HEADLESS=1 fuerza inicios administrados locales sin interfaz para el proceso actual. OPENCLAW_BROWSER_HEADLESS=0 fuerza el modo con interfaz para los inicios ordinarios y devuelve un error accionable en hosts Linux sin servidor de pantalla; una solicitud explícita start --headless sigue teniendo prioridad para ese inicio.
  • executablePath se puede establecer globalmente o por perfil administrado local. Los valores por perfil anulan browser.executablePath, de modo que distintos perfiles administrados pueden iniciar distintos navegadores basados en Chromium. Ambas formas aceptan ~ para el directorio de inicio de tu SO.
  • color (de nivel superior y por perfil) tiñe la interfaz del navegador para que puedas ver qué perfil está activo.
  • El perfil predeterminado es openclaw (independiente administrado). Usa defaultProfile: "user" para optar por el navegador de usuario con sesión iniciada.
  • Orden de detección automática: navegador predeterminado del sistema si está basado en Chromium; de lo contrario, Chrome → Brave → Edge → Chromium → Chrome Canary.
  • driver: "existing-session" usa Chrome DevTools MCP en lugar de CDP sin procesar. No establezcas cdpUrl para ese driver.
  • Establece browser.profiles.<name>.userDataDir cuando un perfil de sesión existente deba adjuntarse a un perfil de usuario de Chromium no predeterminado (Brave, Edge, etc.). Esta ruta también acepta ~ para el directorio de inicio de tu SO.

​
Usar Brave u otro navegador basado en Chromium

Si tu navegador predeterminado del sistema está basado en Chromium (Chrome/Brave/Edge/etc), OpenClaw lo usa automáticamente. Establece browser.executablePath para anular la detección automática. Los valores executablePath de nivel superior y por perfil aceptan ~ para el directorio de inicio de tu SO: 
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
O establécelo en la configuración, por plataforma: 
{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
  },
}
executablePath por perfil solo afecta a los perfiles administrados locales que OpenClaw inicia. Los perfiles existing-session se adjuntan a un navegador que ya está en ejecución, y los perfiles CDP remotos usan el navegador detrás de cdpUrl.

​
Control local frente a remoto

  • Control local (predeterminado): el Gateway inicia el servicio de control 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; el Gateway reenvía las acciones del navegador a él.
  • CDP remoto: establece browser.profiles.<name>.cdpUrl (o browser.cdpUrl) para adjuntarte a un navegador remoto basado en Chromium. En este caso, OpenClaw no iniciará un navegador local.
  • Para servicios CDP administrados externamente en loopback (por ejemplo, Browserless en Docker publicado en 127.0.0.1), establece también attachOnly: true. El CDP en loopback sin attachOnly se trata como un perfil de navegador local administrado por OpenClaw.
  • headless solo afecta a los perfiles administrados locales que OpenClaw inicia. No reinicia ni cambia navegadores de sesión existente o CDP remotos.
  • executablePath sigue la misma regla de perfil administrado local. Cambiarlo en un perfil administrado local en ejecución marca ese perfil para reinicio/reconciliación, de modo que el siguiente inicio use el nuevo binario.
El comportamiento al detener difiere según el modo del perfil:
  • perfiles administrados locales: openclaw browser stop detiene el proceso de navegador que OpenClaw inició
  • perfiles solo adjuntar y CDP remotos: openclaw browser stop cierra la sesión de control activa y libera las anulaciones de emulación de Playwright/CDP (viewport, esquema de color, locale, zona horaria, modo sin conexión y estado similar), aunque OpenClaw no haya iniciado ningún proceso de navegador
Las URL de CDP remotas pueden incluir autenticación:
  • Tokens de consulta (p. ej., https://provider.example?token=<token>)
  • Autenticación HTTP Basic (p. ej., https://user:pass@provider.example)
OpenClaw conserva la autenticación al llamar a endpoints /json/* y al conectarse al WebSocket de CDP. Prefiere variables de entorno o gestores de secretos para tokens en lugar de confirmarlos en archivos de configuración.

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

Si ejecutas un host de Node en la máquina que tiene tu navegador, OpenClaw puede enrutar automáticamente las llamadas a herramientas de navegador a ese Node sin ninguna configuración de navegador adicional. Esta es la ruta predeterminada para Gateways remotos. Notas:
  • El host de Node expone su servidor local de control del navegador mediante un comando de proxy.
  • Los perfiles provienen de la propia configuración browser.profiles del Node (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 estableces nodeHost.browserProxy.allowProfiles, OpenClaw lo trata como un límite de privilegio mínimo: solo se pueden seleccionar 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 Node: nodeHost.browserProxy.enabled=false
    • En el Gateway: gateway.nodes.browser.mode="off"

​
Browserless (CDP remoto alojado)

Browserless es un servicio de Chromium alojado que expone URL de conexión CDP mediante HTTPS y WebSocket. OpenClaw puede usar cualquiera de las dos formas, pero para un perfil de navegador remoto la opción más sencilla es la URL directa de WebSocket de la documentación de conexión de Browserless. Ejemplo: 
{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}
Notas:
  • Sustituye <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.

​
Browserless Docker en el mismo host

Cuando Browserless está autoalojado en Docker y OpenClaw se ejecuta en el host, trata Browserless como un servicio CDP administrado externamente: 
{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    profiles: {
      browserless: {
        cdpUrl: "ws://127.0.0.1:3000",
        attachOnly: true,
        color: "#00AA00",
      },
    },
  },
}
La dirección en browser.profiles.browserless.cdpUrl debe ser accesible desde el proceso de OpenClaw. Browserless también debe anunciar un endpoint accesible coincidente; establece EXTERNAL de Browserless en esa misma base WebSocket pública para OpenClaw, como ws://127.0.0.1:3000, ws://browserless:3000 o una dirección estable de red privada de Docker. Si /json/version devuelve webSocketDebuggerUrl que apunta a una dirección que OpenClaw no puede alcanzar, el HTTP de CDP puede parecer correcto mientras la conexión WebSocket sigue fallando. No dejes attachOnly sin establecer para un perfil Browserless en loopback. Sin attachOnly, OpenClaw trata el puerto loopback como un perfil de navegador administrado local y puede informar de que el puerto está en uso pero no pertenece a OpenClaw.

​
Proveedores CDP WebSocket directos

Algunos servicios de navegador alojados exponen un endpoint WebSocket directo en lugar del descubrimiento CDP estándar basado en HTTP (/json/version). OpenClaw acepta tres formas de URL CDP y elige automáticamente la estrategia de conexión adecuada:
  • Descubrimiento 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 alternativa 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 /json/version por completo.
  • Raíces WebSocket sin ruta - ws://host[:port] o wss://host[:port] sin ruta /devtools/... (p. ej., Browserless, Browserbase). OpenClaw intenta primero el descubrimiento HTTP /json/version (normalizando el esquema a http/https); si el descubrimiento devuelve un webSocketDebuggerUrl, se usa; de lo contrario, OpenClaw recurre a un handshake WebSocket directo en la raíz sin ruta. Si el endpoint WebSocket anunciado rechaza el handshake de CDP pero la raíz sin ruta configurada lo acepta, OpenClaw también recurre a esa raíz. Esto permite que un ws:// sin ruta apuntando a un Chrome local aún se conecte, ya que Chrome solo acepta actualizaciones WebSocket en la ruta específica por destino de /json/version, mientras que los proveedores alojados todavía pueden usar su endpoint WebSocket raíz cuando su endpoint de descubrimiento anuncia una URL de vida corta que no es adecuada para CDP de Playwright.

​
Browserbase

Browserbase es una plataforma en la nube para ejecutar navegadores sin interfaz con resolución de CAPTCHA integrada, modo sigiloso y proxies residenciales. 
{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}
Notas:
  • Regístrate y copia tu API Key desde el panel de resumen.
  • Sustituye <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 se necesita ningún paso manual de creación de sesión.
  • El nivel gratuito permite una sesión simultánea y una hora de navegador al mes. Consulta precios para ver los límites de los planes de pago.
  • Consulta la documentación de Browserbase para la referencia completa de la API, guías de SDK y ejemplos de integración.

​
Seguridad

Ideas clave:
  • El control del navegador es solo de loopback; los flujos de acceso pasan por la autenticación del Gateway o el emparejamiento de nodos.
  • La API HTTP independiente del navegador de loopback usa solo autenticación con secreto compartido: autenticación bearer con token del 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 independiente del navegador de loopback.
  • Si el control del navegador está habilitado y no se configura autenticación con secreto compartido, OpenClaw genera un token de gateway solo en tiempo de ejecución para ese arranque. Configura gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN o OPENCLAW_GATEWAY_PASSWORD explícitamente si los clientes necesitan un secreto estable entre reinicios.
  • OpenClaw no genera automáticamente ese token cuando gateway.auth.mode ya es password, none o trusted-proxy.
  • Mantén el Gateway y cualquier host de nodo en una red privada (Tailscale); evita la exposición pública.
  • Trata las URL/tokens de CDP remoto como secretos; prefiere variables de entorno o un gestor de secretos.
Consejos para CDP remoto:
  • 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 (multinavegador)

OpenClaw admite múltiples perfiles con nombre (configuraciones de enrutamiento). Los perfiles pueden ser:
  • gestionado 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
Valores predeterminados:
  • El perfil openclaw se crea automáticamente si falta.
  • El perfil user viene integrado para adjuntar una sesión existente de Chrome MCP.
  • Los perfiles de sesión existente son opcionales más allá de user; créalos con --driver existing-session.
  • Los puertos CDP locales se asignan desde 18800-18899 de forma predeterminada.
  • Al eliminar un perfil, su directorio de datos local se mueve a la papelera.
Todos los endpoints de control aceptan ?profile=<name>; la CLI usa --browser-profile.

​
Sesión existente mediante Chrome DevTools MCP

OpenClaw también puede adjuntarse a un perfil de navegador basado en Chromium en ejecución mediante el servidor oficial de Chrome DevTools MCP. Esto reutiliza las pestañas y el estado de inicio de sesión ya abiertos en ese perfil del navegador. Referencias oficiales de contexto y configuración: Perfil integrado:
  • user
Opcional: crea tu propio perfil personalizado de sesión existente si quieres un nombre, color o directorio de datos del navegador diferente. Comportamiento predeterminado:
  • El perfil integrado user usa la conexión automática de Chrome MCP, que apunta al perfil local predeterminado de Google Chrome.
Usa userDataDir para Brave, Edge, Chromium o un perfil de Chrome no predeterminado. ~ se expande al directorio personal de tu sistema operativo: 
{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}
Luego, en el navegador correspondiente:
  1. Abre la página de inspección de ese navegador para depuración remota.
  2. Habilita la depuración remota.
  3. Mantén el navegador en ejecución y aprueba el aviso de conexión cuando OpenClaw se adjunte.
Páginas de inspección comunes:
  • Chrome: chrome://inspect/#remote-debugging
  • Brave: brave://inspect/#remote-debugging
  • Edge: edge://inspect/#remote-debugging
Prueba rápida de adjunción en vivo: 
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
Cómo se ve el éxito:
  • 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
Qué comprobar si la adjunción no funciona:
  • el navegador basado en Chromium de destino tiene la versión 144+
  • la depuración remota está habilitada en la página de inspección de ese navegador
  • el navegador mostró el aviso de consentimiento de adjunción y lo aceptaste
  • openclaw doctor migra la configuración antigua de navegador basada en plugins y comprueba que Chrome esté instalado localmente para los perfiles predeterminados de conexión automática, pero no puede habilitar la depuración remota del lado del navegador por ti
Uso por agentes:
  • Usa profile="user" cuando necesites el estado de navegador con sesión iniciada del usuario.
  • Si usas un perfil personalizado de sesión existente, pasa ese nombre de perfil explícito.
  • Elige este modo solo cuando el usuario esté frente al equipo para aprobar el aviso de adjunción.
  • el Gateway o el host de nodo puede iniciar npx chrome-devtools-mcp@latest --autoConnect
Notas:
  • Esta ruta tiene mayor riesgo que el perfil aislado openclaw porque puede actuar dentro de tu sesión de navegador iniciada.
  • OpenClaw no inicia el navegador para este controlador; solo se adjunta.
  • OpenClaw usa aquí el flujo oficial --autoConnect de Chrome DevTools MCP. Si userDataDir está definido, se pasa para apuntar a ese directorio de datos de usuario.
  • La sesión existente puede adjuntarse en el host seleccionado o mediante un nodo de navegador conectado. Si Chrome vive en otro lugar y no hay ningún nodo de navegador conectado, usa CDP remoto o un host de nodo en su lugar.

​
Inicio personalizado de Chrome MCP

Sobrescribe el servidor Chrome DevTools MCP iniciado por perfil cuando el flujo predeterminado npx chrome-devtools-mcp@latest no es lo que quieres (hosts sin conexión, versiones fijadas, binarios incorporados):
CampoQué hace
mcpCommandEjecutable que se inicia en lugar de npx. Se resuelve tal cual; se respetan las rutas absolutas.
mcpArgsArreglo de argumentos pasado literalmente a mcpCommand. Reemplaza los argumentos predeterminados chrome-devtools-mcp@latest --autoConnect.
Cuando cdpUrl está definido en un perfil de sesión existente, OpenClaw omite --autoConnect y reenvía el endpoint a Chrome MCP automáticamente:
  • http(s)://... → --browserUrl <url> (endpoint de descubrimiento HTTP de DevTools).
  • ws(s)://... → --wsEndpoint <url> (WebSocket CDP directo).
Las banderas de endpoint y userDataDir no se pueden combinar: cuando cdpUrl está definido, userDataDir se ignora para el inicio de Chrome MCP, ya que Chrome MCP se adjunta al navegador en ejecución detrás del endpoint en lugar de abrir un directorio de perfil.
En comparación con el perfil gestionado openclaw, los controladores de sesión existente están más restringidos:
  • Capturas de pantalla - funcionan las capturas de página y las capturas de elementos --ref; los selectores CSS --element no. --full-page no puede combinarse con --ref ni --element. Playwright no es necesario para capturas de página ni de elementos basadas en refs.
  • Acciones - click, type, hover, scrollIntoView, drag y select requieren refs de instantánea (sin selectores CSS). click-coords hace clic en coordenadas visibles del viewport y no requiere una ref de instantánea. click solo usa el botón izquierdo. type no admite slowly=true; usa fill o press. press no admite delayMs. type, hover, scrollIntoView, drag, select, fill y evaluate no admiten timeouts por llamada. select acepta un único valor.
  • Espera / carga / diálogo - wait --url admite patrones exactos, de subcadena y glob; wait --load networkidle no es compatible. Los hooks de carga requieren ref o inputRef, un archivo a la vez, sin element CSS. Los hooks de diálogo no admiten sobrescrituras de timeout.
  • Funcionalidades solo gestionadas - las acciones por lotes, la exportación a PDF, la interceptación de descargas y responsebody siguen requiriendo la ruta del navegador gestionado.

​
Garantías de aislamiento

  • Directorio dedicado de datos de usuario: nunca toca tu perfil personal del navegador.
  • Puertos dedicados: evita 9222 para prevenir colisiones con flujos de trabajo de desarrollo.
  • Control determinista de pestañas: tabs devuelve primero suggestedTargetId, luego identificadores tabId estables como t1, etiquetas opcionales y el targetId sin procesar. Los agentes deben reutilizar suggestedTargetId; los id sin procesar siguen disponibles para depuración y compatibilidad.

​
Selección de navegador

Al iniciar localmente, OpenClaw elige el primero disponible:
  1. Chrome
  2. Brave
  3. Edge
  4. Chromium
  5. Chrome Canary
Puedes sobrescribirlo con browser.executablePath. Plataformas:
  • macOS: comprueba /Applications y ~/Applications.
  • Linux: comprueba ubicaciones comunes de Chrome/Brave/Edge/Chromium bajo /usr/bin, /snap/bin, /opt/google, /opt/brave.com, /usr/lib/chromium y /usr/lib/chromium-browser, además de Chromium gestionado por Playwright bajo PLAYWRIGHT_BROWSERS_PATH o ~/.cache/ms-playwright.
  • Windows: comprueba ubicaciones de instalación comunes.

​
API de control (opcional)

Para scripts y depuración, el Gateway expone una pequeña API HTTP de control solo de loopback junto con una CLI openclaw browser correspondiente (instantáneas, refs, mejoras de espera, salida JSON, flujos de trabajo de depuración). Consulta API de control del navegador para obtener la referencia completa.

​
Solución de problemas

Para problemas específicos de Linux (especialmente snap Chromium), consulta Solución de problemas del navegador. Para configuraciones con Gateway en WSL2 + Chrome en Windows con hosts separados, consulta Solución de problemas de WSL2 + Windows + CDP remoto de Chrome.

​
Error de inicio de CDP frente a bloqueo SSRF de navegación

Estas son clases de error diferentes y apuntan a rutas de código distintas.
  • Error de inicio o preparación de CDP significa que OpenClaw no puede confirmar que el plano de control del navegador esté sano.
  • Bloqueo SSRF de navegación significa que el plano de control del navegador está sano, pero una página de destino de navegación se rechaza por política.
Ejemplos comunes:
  • Error 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>
    • Port <port> is in use for profile "<name>" but not by openclaw cuando un servicio CDP externo de loopback está configurado sin attachOnly: true
  • Bloqueo SSRF de navegación:
    • los flujos open, navigate, de instantánea o de apertura de pestañas fallan con un error de política de navegador/red mientras start y tabs aún funcionan
Usa esta secuencia mínima para separar ambas cosas: 
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com
Cómo leer los resultados:
  • 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 sano. Trátalo como un problema de alcanzabilidad de CDP, no como un problema de navegación de páginas.
  • Si start y tabs tienen éxito pero open o navigate falla, 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 gestionado está sana.
Detalles importantes de comportamiento:
  • La configuración del navegador usa de forma predeterminada un objeto de política SSRF de cierre seguro incluso cuando no configuras browser.ssrfPolicy.
  • Para el perfil gestionado local de loopback openclaw, las comprobaciones de salud de CDP omiten intencionadamente la aplicación de alcanzabilidad 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.
Guía de seguridad:
  • 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 deliberadamente confiables donde el acceso del navegador a redes privadas sea necesario y haya sido revisado.

​
Herramientas del agente + cómo funciona el control

El agente recibe una herramienta para la automatización del navegador:
  • browser - doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act
Cómo se asigna:
  • browser snapshot devuelve un árbol de interfaz de usuario estable (AI o ARIA).
  • browser act usa los ID ref de la instantánea para hacer clic/escribir/arrastrar/seleccionar.
  • browser screenshot captura píxeles (página completa, elemento o referencias etiquetadas).
  • browser doctor comprueba la preparación de Gateway, Plugin, perfil, navegador y pestaña.
  • browser acepta:
    • profile para elegir un perfil de navegador con nombre (openclaw, chrome o CDP remoto).
    • target (sandbox | host | node) para seleccionar dónde reside 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; las sesiones no aisladas usan host de forma predeterminada.
    • Si hay conectado un nodo con capacidad de navegador, la herramienta puede redirigir automáticamente a él, a menos que fijes target="host" o target="node".
Esto mantiene al agente determinista y evita selectores frágiles.

​
Relacionado