Solución de problemas del Browser en Linux

Intentas ejecutar tu automatización y el navegador simplemente no arranca. Es un problema común en Linux: las capas de seguridad y los gestores de paquetes a veces bloquean la comunicación entre tus herramientas y el browser. Terminas perdiendo tiempo configurando permisos en lugar de avanzar en tu proyecto.

Este error suele ocurrir porque el sistema operativo restringe cómo los procesos externos controlan las ventanas del navegador, especialmente cuando usas paquetes preinstalados que vienen con limitaciones de seguridad estrictas.

Requisitos previos

• Ubuntu o una distribución Linux basada en Debian.
• Acceso a la terminal con permisos de sudo.
• OpenClaw instalado y configurado.

Inicio rápido

La mejor opción es instalar la versión oficial de Google Chrome. Esto evita las restricciones de los paquetes snap que suelen causar fallos en la conexión CDP.

1. Instala el paquete .deb oficial:

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt --fix-broken install -y  # por si faltan dependencias

2. Actualiza tu archivo ~/.openclaw/openclaw.json:

{
  "browser": {
    "enabled": true,
    "executablePath": "/usr/bin/google-chrome-stable",
    "headless": true,
    "noSandbox": true
  }
}

Solución de problemas

Error: “Failed to start Chrome CDP on port 18800”

Si ves este error, es probable que estés usando la versión snap de Chromium. Snap usa AppArmor para confinar el navegador, lo que impide que OpenClaw lo controle correctamente.

Solución: Usa el modo Attach-Only

Si no puedes desinstalar snap, configura OpenClaw para que se conecte a un navegador que tú inicies manualmente.

1. Modifica tu configuración:

{
  "browser": {
    "enabled": true,
    "attachOnly": true,
    "headless": true,
    "noSandbox": true
  }
}

2. Inicia Chromium de forma manual:

chromium-browser --headless --no-sandbox --disable-gpu \
  --remote-debugging-port=18800 \
  --user-data-dir=$HOME/.openclaw/browser/openclaw/user-data \
  about:blank &

3. Crea un servicio de systemd (opcional):

Si quieres que el browser se inicie solo, crea este archivo en ~/.config/systemd/user/openclaw-browser.service:

[Unit]
Description=OpenClaw Browser (Chrome CDP)
After=network.target

[Service]
ExecStart=/snap/bin/chromium --headless --no-sandbox --disable-gpu --remote-debugging-port=18800 --user-data-dir=%h/.openclaw/browser/openclaw/user-data about:blank
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

Actívalo con: systemctl --user enable --now openclaw-browser.service.

Error: “Chrome extension relay is running, but no tab is connected”

Este problema ocurre cuando usas el perfil de chrome (extension relay) y el sistema no detecta una pestaña activa con la extensión.

Cómo arreglarlo:

• Usa el navegador gestionado: Ejecuta openclaw browser start --browser-profile openclaw o cambia browser.defaultProfile a "openclaw" en tu JSON.
• Conecta la extensión: Abre el navegador manualmente, ve a una pestaña y haz clic en el icono de la extensión de OpenClaw para activarla.

Verificación del funcionamiento

Para comprobar que todo está en orden, usa estos comandos:

# Revisa el estado del servidor
curl -s http://127.0.0.1:18791/ | jq '{running, pid, chosenBrowser}'

# Prueba a iniciar el browser y listar pestañas
curl -s -X POST http://127.0.0.1:18791/start
curl -s http://127.0.0.1:18791/tabs

Config Reference

Opción	Descripción	Por defecto
browser.enabled	Activa el control del navegador	true
browser.executablePath	Ruta al binario (Chrome/Brave/Edge/Chromium)	auto-detectado
browser.headless	Ejecuta sin interfaz gráfica	false
browser.noSandbox	Añade el flag --no-sandbox	false
browser.attachOnly	No lanza el browser, solo se conecta a uno activo	false
browser.cdpPort	Puerto del Chrome DevTools Protocol	18800

¿Necesitas ayuda con una configuración específica? Prueba el AI Setup Assistant.

Próximos pasos

• Configuración avanzada de API
• Uso de perfiles de usuario