Automatización del navegador

Esta guía cubre la configuración de las capacidades de automatización de navegadores en ZeroClaw, incluyendo tanto la automatización sin interfaz gráfica (headless) como el acceso a la interfaz gráfica de usuario (GUI) a través de VNC.

Descripción general

ZeroClaw admite múltiples métodos de acceso al navegador:

Inicio rápido: Automatización sin interfaz

1. Instalar agent-browser

# Instalar CLI
npm install -g agent-browser

# Descargar Chrome for Testing (incluye dependencias del sistema)
agent-browser install --with-deps

# Instalar CLI
npm install -g agent-browser

# Descargar Chrome para Testing
agent-browser install

2. Verificar la configuración de ZeroClaw

La herramienta del navegador está habilitada de forma predeterminada con allowed_domains = ["*"]. Restringe los dominios o desactívala mediante zeroclaw config set:

zeroclaw config set browser.allowed_domains '["example.com", "docs.example.com"]'
zeroclaw config set browser.enabled false

Política de esquema de URL. browser_open acepta tanto URLs http:// como https:// (igual que web_fetch, http_request y la herramienta browser, que ya aceptan HTTP en texto plano). El bloqueo de hosts locales/privados y la lista de अनुमति allowed_domains se aplican a http:// exactamente igual que a https://. Como allowed_domains tiene por defecto ["*"], la configuración predeterminada incluida permite abrir cualquier host público mediante HTTP en texto plano. Para reducir la exposición a HTTP en texto plano, sustituye la lista de अनुमति comodín por los hosts públicos específicos en los que confías. Ten en cuenta que esto no impone HTTPS para esos hosts: la lista de अनुमति controla orígenes, no esquemas; el comportamiento exclusivo de HTTPS para un host permitido requiere que ese host redirija/rechace por sí mismo el HTTP en texto plano (HSTS, 308 del lado del servidor), o una futura política de navegador consciente del esquema.

Para el backend agent_browser, establece browser.headed = true para iniciar el navegador en modo con interfaz (headed) para depuración o configuración inicial de inicio de sesión, o browser.headed = false para forzar el modo sin interfaz (headless). Cuando browser.headed no está establecido, Zeroclaw conserva el comportamiento heredado del entorno AGENT_BROWSER_HEADED. El backend nativo de rust sigue usando browser.native_headless.

Consulta la referencia de configuración para obtener todos los campos y valores predeterminados del navegador.

3. Prueba

echo Abre https://example.com y dime qué dice | zeroclaw agent -a assistant

Configuración de VNC (Acceso a la GUI)

Para depurar o cuando necesites acceso visual al navegador:

Instalar dependencias

apt-get install -y xvfb x11vnc fluxbox novnc websockify

# Opcional: Entorno de escritorio para Chrome Remote Desktop
apt-get install -y xfce4 xfce4-goodies

Iniciar el servidor VNC

#!/bin/bash
# Start virtual display with VNC access

DISPLAY_NUM=99
VNC_PORT=5900
NOVNC_PORT=6080
RESOLUTION=1920x1080x24

# Iniciar Xvfb
Xvfb :$DISPLAY_NUM -screen 0 $RESOLUTION -ac &
sleep 1

# Iniciar el administrador de ventanas
fluxbox -display :$DISPLAY_NUM &
sleep 1

# Iniciar x11vnc
x11vnc -display :$DISPLAY_NUM -rfbport $VNC_PORT -forever -shared -nopw -bg
sleep 1

# Iniciar noVNC (VNC basado en web)
websockify --web=/usr/share/novnc $NOVNC_PORT localhost:$VNC_PORT &

echo "VNC disponible en:"
echo "  Cliente VNC: localhost:$VNC_PORT"
echo "  Navegador web: http://localhost:$NOVNC_PORT/vnc.html"

Acceso VNC

• Cliente VNC: Conéctate a localhost:5900
• Navegador web: Abre http://localhost:6080/vnc.html

Iniciar el navegador en la pantalla VNC

DISPLAY=:99 google-chrome --no-sandbox https://example.com &

Escritorio remoto de Chrome

Instalar

# Descargar e instalar
wget https://dl.google.com/linux/direct/chrome-remote-desktop_current_amd64.deb
apt-get install -y ./chrome-remote-desktop_current_amd64.deb

# Configurar sesión
echo "xfce4-session" > ~/.chrome-remote-desktop-session
chmod +x ~/.chrome-remote-desktop-session

Configuración

1. Visita https://remotedesktop.google.com/headless
2. Copia el comando de configuración de “Debian Linux”
3. Ejecútalo en tu servidor
4. Inicia el servicio: systemctl --user start chrome-remote-desktop

Acceso remoto

Ve a https://remotedesktop.google.com/access desde cualquier dispositivo.

Pruebas

Pruebas de CLI

# Apertura y cierre básicos
agent-browser open https://example.com
agent-browser get title
agent-browser close

# Captura con referencias
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser close

# Captura de pantalla
agent-browser open https://example.com
agent-browser screenshot /tmp/test.png
agent-browser close

Pruebas de integración de ZeroClaw

# Extracción de contenido
echo Abre https://example.com y resúmelo | zeroclaw agent -a assistant

# Navegación
echo Ve a https://github.com/trending y lista los 3 repositorios principales | zeroclaw agent -a assistant

# Interacción con formularios
echo Ir a Wikipedia, buscar «lenguaje de programación Rust» y resumir | zeroclaw agent -a assistant

Solución de problemas

“Elemento no encontrado”

La página puede no estar completamente cargada. Agrega una espera:

agent-browser open https://slow-site.com
agent-browser wait --load networkidle
agent-browser snapshot -i

Diálogos de cookies que bloquean el acceso

Maneja el consentimiento de cookies primero:

agent-browser open https://site-with-cookies.com
agent-browser snapshot -i
agent-browser click @accept_cookies  # Haz clic en el botón de aceptar
agent-browser snapshot -i  # Ahora obtén el contenido real

Restricciones de red del entorno de contenedores de Docker

Si web_fetch falla dentro del entorno de Docker, utiliza agent-browser en su lugar:

# En lugar de web_fetch, usa:
agent-browser open https://example.com
agent-browser get text body

Notas de seguridad

• agent-browser ejecuta Chrome en modo headless con sandboxing
• Para sitios sensibles, utiliza --session-name para persistir el estado de autenticación.
• La configuración --allowed-domains restringe la navegación a dominios específicos.
• Los puertos VNC (5900, 6080) deben estar detrás de un firewall o de Tailscale.

Relacionado

• Documentación de agent-browser
• Referencia de configuración