Recetas CLI para automatización del navegador: ejemplos prácticos de comandos

Introducción

Los flags CLI de BotBrowser proporcionan un control detallado sobre los perfiles de huella digital, el enrutamiento de proxy, la configuración de idioma, la configuración de renderizado y el comportamiento de automatización. Con docenas de flags disponibles, saber cuáles combinar para escenarios específicos ahorra un tiempo de configuración significativo.

Este artículo recopila recetas listas para usar en casos de uso comunes. Cada receta incluye el comando exacto, una explicación de por qué se incluye cada flag y notas sobre cuándo usarlo o modificarlo. Todas las recetas asumen que tienes un binario de BotBrowser y archivos de perfil .enc de las publicaciones de GitHub.

Por qué importan las recetas CLI

El sistema de configuración de BotBrowser es flexible por diseño. Puedes anular casi cualquier configuración de perfil en tiempo de ejecución, enrutar el tráfico a través de proxies con credenciales integradas, controlar el comportamiento de renderizado y gestionar múltiples instancias desde la línea de comandos. Esta flexibilidad significa que hay muchas configuraciones válidas, y encontrar la combinación correcta para tu escenario puede implicar revisar toda la Referencia de Flags CLI.

Las recetas cubren la brecha entre entender los flags individuales y combinarlos de manera efectiva. Codifican configuraciones probadas que manejan casos extremos comunes, como asegurar que cada instancia concurrente tenga su propio directorio de datos de usuario, o emparejar la configuración de proxy con las anulaciones de idioma correctas.

El sistema de prioridad de configuración hace que las recetas CLI sean especialmente potentes. Los flags CLI --bot-config-* tienen la prioridad más alta, anulando la configuración del perfil sin modificar el archivo de perfil cifrado. Esto significa que puedes mantener un conjunto pequeño de perfiles base y personalizarlos en el momento del lanzamiento para diferentes escenarios.

Contexto técnico

Categorías de flags

Los flags de BotBrowser se dividen en varias categorías:

Flags principales (--bot-profile, --bot-profile-dir) controlan qué perfil de huella digital se carga. Cada sesión de BotBrowser comienza con uno de estos.

Flags de proxy (--proxy-server, --proxy-ip, --proxy-bypass-rgx) controlan el enrutamiento de red. BotBrowser extiende el flag de proxy estándar de Chromium para soportar credenciales integradas en la URL.

Flags de anulación de configuración (--bot-config-*) anulan valores específicos del perfil cargado. La zona horaria, el idioma, las preferencias de idioma, la marca del navegador, las dimensiones de pantalla y la configuración de renderizado son todos configurables.

Flags de comportamiento (--bot-disable-debugger, --bot-always-active, --bot-inject-random-history, etc.) controlan el comportamiento en tiempo de ejecución que no está vinculado a un valor específico del perfil.

Flags de personalización (--bot-title, --bot-cookies, --bot-bookmarks, --bot-script) añaden datos específicos de la sesión o scripts de automatización.

Detección automática

BotBrowser deriva automáticamente la zona horaria, el idioma y las preferencias de idioma a partir de la IP de tu proxy. En la mayoría de las recetas, no necesitas especificar estos valores manualmente. Solo anúlalos cuando necesites una configuración diferente a la que sugiere la IP.

Flags estándar de Chromium

BotBrowser también soporta todos los flags estándar de Chromium. Los más comunes incluyen --headless, --user-data-dir, --remote-debugging-port y --window-size. Estos están documentados en la referencia de línea de comandos de Chromium.

Recetas

Receta 1: Lanzamiento mínimo

La configuración más simple posible de BotBrowser:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --headless

Esto carga el perfil y se ejecuta en modo headless. La zona horaria, el idioma y las preferencias de idioma se detectan automáticamente a partir de la IP de tu máquina. Úsalo para pruebas locales y desarrollo.

Receta 2: Lanzamiento de producción con proxy

chromium-browser \
  --bot-profile="/opt/profiles/windows-chrome-131.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --user-data-dir="/tmp/bb-session-$(date +%s)" \
  --remote-debugging-port=9222 \
  --headless

El proxy maneja el enrutamiento geográfico mientras BotBrowser deriva automáticamente la zona horaria y el idioma a partir de la IP de salida del proxy. Un --user-data-dir único previene conflictos con otras instancias. El puerto de depuración habilita el control programático vía CDP.

Receta 3: Idioma y zona horaria explícitos

Cuando necesitas configuraciones regionales específicas independientemente de la ubicación de tu proxy:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-config-timezone="Europe/Berlin" \
  --bot-config-locale="de-DE" \
  --bot-config-languages="de-DE,de,en-US" \
  --bot-config-location="52.5200,13.4050" \
  --headless

Esto anula los valores detectados automáticamente con una configuración alemana explícita. Útil cuando la IP de tu proxy no refleja con precisión la región deseada.

Receta 4: Despliegue multi-instancia

#!/bin/bash
PROFILES_DIR="/opt/profiles/windows-chrome"
BASE_PORT=9222

for i in $(seq 1 5); do
  chromium-browser \
    --bot-profile-dir="${PROFILES_DIR}" \
    --bot-title="Worker ${i}" \
    --user-data-dir="/tmp/bb-worker-${i}" \
    --remote-debugging-port=$((BASE_PORT + i)) \
    --proxy-server=socks5://user:pass@proxy.example.com:1080 \
    --headless &
done

Cada instancia obtiene un perfil aleatorio del directorio, su propio directorio de datos de usuario, un puerto de depuración único y un título descriptivo para identificación. El --bot-title aparece en el título de la ventana y la barra de tareas, facilitando la identificación de instancias específicas.

Receta 5: Cambio de marca del navegador

Presentarse como Microsoft Edge en lugar de Chrome:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-config-browser-brand="edge" \
  --headless

Valores de marca disponibles: chrome, chromium, edge, brave, opera, webview. BotBrowser ajusta el User-Agent, los encabezados Client Hints y los valores de API relacionados para coincidir con la marca seleccionada.

Receta 6: Sesión con cookies e historial

Pre-cargar el navegador con datos de sesión:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-cookies='[{"name":"session_id","value":"abc123","domain":".example.com"},{"name":"pref","value":"dark","domain":".example.com"}]' \
  --bot-bookmarks='[{"title":"Dashboard","type":"url","url":"https://example.com/dashboard"}]' \
  --bot-inject-random-history \
  --bot-always-active \
  --user-data-dir="/data/persistent-session" \
  --headless

--bot-cookies establece cookies iniciales. --bot-bookmarks añade entradas de marcadores. --bot-inject-random-history crea un historial de navegación sintético para la autenticidad de la sesión. --bot-always-active mantiene las ventanas activas incluso cuando no están enfocadas.

Receta 7: Carga de cookies desde archivo

Para conjuntos grandes de cookies, carga desde un archivo JSON:

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-cookies="@/opt/data/cookies.json" \
  --headless

El prefijo @ indica a BotBrowser que lea las cookies desde la ruta de archivo especificada en lugar de analizar el valor como JSON en línea.

Receta 8: Ruido determinista para reproducibilidad

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-noise-seed=42 \
  --bot-time-seed=42 \
  --bot-time-scale=0.92 \
  --headless

--bot-noise-seed hace que el ruido de Canvas, WebGL, audio, métricas de texto y ClientRect sea determinista. La misma semilla produce el mismo hash de huella digital cada vez. --bot-time-seed proporciona diversidad determinista en los tiempos de ejecución entre operaciones del navegador. --bot-time-scale comprime los intervalos de performance.now() para reducir las señales de rastreo basadas en temporización.

Receta 9: Grabación de Canvas para análisis

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-canvas-record-file="/tmp/canvas-capture.jsonl" \
  --bot-noise-seed=12345 \
  --headless

Registra todas las llamadas API de Canvas 2D, WebGL y WebGL2 en un archivo JSONL. La semilla de ruido está fijada para que la salida grabada sea reproducible. Úsalo para análisis forense y depuración del comportamiento de huella digital de Canvas.

Receta 10: Automatización sin framework

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-script="/opt/scripts/automation.js" \
  --bot-disable-debugger \
  --bot-disable-console-message \
  --headless

Ejecuta un archivo JavaScript con acceso directo a CDP a través de chrome.debugger. No se requiere Node.js ni npm. --bot-disable-debugger evita que las páginas detengan la ejecución con sentencias debugger. --bot-disable-console-message suprime la salida de consola para que no se exponga a través de CDP.

Receta 11: Headless con tamaño de ventana específico

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-config-window="1920x1080" \
  --bot-config-screen="2560x1440" \
  --window-size=1920,1080 \
  --headless

Establece tanto las dimensiones de ventana/pantalla a nivel de perfil como el tamaño de ventana de Chromium. Los flags --bot-config-window y --bot-config-screen controlan lo que reportan las APIs de JavaScript, mientras que --window-size establece el viewport real.

Receta 12: Privacidad WebRTC con STUN personalizado

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-webrtc-ice="google" \
  --bot-local-dns \
  --headless

--bot-webrtc-ice controla qué endpoints STUN/TURN se exponen a través de WebRTC, previniendo la filtración de IP local. --bot-local-dns mantiene la resolución DNS local en lugar de depender del DNS del proveedor de proxy.

Receta 13: Encabezados HTTP personalizados

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-custom-headers='{"X-Requested-With":"com.example.app","X-Custom-Auth":"token123"}' \
  --headless

Inyecta encabezados personalizados en todas las solicitudes HTTP salientes. Útil para autenticación de API y enrutamiento de solicitudes.

Receta 14: Protección de puertos

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-port-protection \
  --headless

Evita que páginas remotas detecten qué servicios se ejecutan en localhost bloqueando el escaneo de puertos en puertos comunes de desarrollo y acceso remoto.

Receta 15: Depuración y solución de problemas

chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --bot-internal --v=1 \
  --enable-logging=stderr \
  --headless

Habilita el registro interno de BotBrowser (--bot-internal --v=1) y el registro stderr de Chromium para una salida de diagnóstico detallada. Úsalo para solucionar problemas de configuración.

Verificación

Después de aplicar cualquier receta, verifica el resultado navegando a una herramienta de prueba de huella digital:

# Verificación rápida con una URL de prueba
chromium-browser \
  --bot-profile="/opt/profiles/profile.enc" \
  --proxy-server=socks5://user:pass@proxy.example.com:1080 \
  --bot-noise-seed=42 \
  --remote-debugging-port=9222 \
  --headless

Luego conéctate vía CDP y navega a CreepJS o BrowserLeaks para confirmar que tu configuración produce una huella digital consistente y realista. Consulta Cómo verificar la protección de tu huella digital del navegador para una metodología de prueba detallada.

Mejores prácticas

Comienza con lo mínimo, añade flags según sea necesario. Comienza con la Receta 1 y añade flags solo cuando tengas un requisito específico. Los flags innecesarios añaden complejidad sin beneficio.

Deja que la detección automática funcione. Si estás usando un proxy, BotBrowser maneja la zona horaria, el idioma y las preferencias de idioma automáticamente. Solo anúlalos cuando los valores detectados automáticamente no coincidan con tus necesidades.

Usa --user-data-dir para cada instancia concurrente. Sin directorios de datos separados, las instancias comparten cookies, caché y datos de perfil, causando un comportamiento impredecible.

Usa --bot-title para identificación. Al ejecutar múltiples instancias, el título facilita identificar cuál es cuál en los registros y listados de procesos.

Prefiere --bot-config-* sobre la edición de perfiles. Los flags CLI tienen la prioridad más alta y no requieren modificar archivos cifrados.

Registra todo en desarrollo. Usa --bot-internal --v=1 durante el desarrollo y las pruebas. Desactiva el registro detallado en producción para mejorar el rendimiento.

Preguntas frecuentes

¿Puedo combinar --bot-profile y --bot-profile-dir?

No. Si se especifican ambos, --bot-profile-dir tiene prioridad. Usa --bot-profile para identidades persistentes y --bot-profile-dir para rotación aleatoria.

¿Qué pasa si especifico flags en conflicto?

Los flags CLI tienen la prioridad más alta. Si un flag contradice un valor del perfil, el flag gana. Si dos flags entran en conflicto entre sí, el último especificado generalmente tiene efecto.

¿Cómo sé qué flags soporta mi nivel de licencia?

Los flags que requieren un nivel específico se indican en la Referencia de Flags CLI con etiquetas como (PRO), (ENT Tier1), (ENT Tier2), etc. Usar un flag sin el nivel requerido no tiene efecto.

¿Puedo guardar combinaciones de flags en un archivo?

Sí. Crea un script de shell o archivo de configuración con tus combinaciones de flags. Para Playwright/Puppeteer, define tu array de argumentos en un módulo de configuración compartido.

¿Cuál es el número máximo de flags que puedo usar?

No hay un límite práctico en el número de flags. Sin embargo, mantén tu configuración lo más simple posible. Cada flag innecesario es un punto potencial de confusión durante la depuración.

¿Cómo restablezco al comportamiento predeterminado?

Lanza sin ningún flag --bot-config-* para usar los valores predeterminados del perfil. Lanza sin --bot-profile para ejecutar como Chromium estándar.

¿Son estas recetas multiplataforma?

Sí. Los mismos flags funcionan en Windows, macOS y Linux. Ajusta el nombre del binario (chromium-browser, chrome, chrome.exe) y el formato de ruta para tu plataforma.

Resumen

Estas recetas cubren las configuraciones de BotBrowser más comunes, desde lanzamientos mínimos de desarrollo hasta despliegues de producción con múltiples instancias. Comienza con la receta más simple que satisfaga tus necesidades y añade flags de forma incremental a medida que crecen los requisitos.

Para profundizar en temas específicos, consulta Gestión de perfiles para organizar perfiles, Configuración de servidor headless para la configuración de servidores Ubuntu, Guía de despliegue con Docker para despliegues en contenedores, y Automatización con Bot Script para automatización sin framework.