Cómo resolver CAPTCHA en OpenBrowser usando CapSolver (Guía de automatización de Agente de IA)

Los agentes de navegación web impulsados por IA están transformando la forma en que interactuamos con Internet. Pueden navegar por páginas, completar formularios, extraer datos y completar flujos de trabajo de múltiples pasos, todo desde una instrucción de texto simple. Pero hay un obstáculo que detiene a cada agente en seco: CAPTCHAs.

OpenBrowser es un marco de navegación web autónomo que da a modelos de IA como GPT-4o, Claude y Gemini el control directo de un navegador real. Es poderoso, pero en el momento en que se encuentra con una página protegida por CAPTCHA, el agente se detiene.

CapSolver elimina este problema por completo. Al cargar la extensión CapSolver de Chrome en el perfil de inicio de OpenBrowser, los CAPTCHAs se detectan y resuelven automáticamente en segundo plano — sin necesidad de código de API, inyección de tokens o cambios en la lógica de su agente.

Lo mejor de todo es que nunca necesita que su agente sepa que los CAPTCHAs existen. La extensión se encarga de la detección, resolución e inyección de tokens a nivel de navegador. Para cuando el agente hace clic en Enviar, el CAPTCHA ya está resuelto.

¿Qué es OpenBrowser?

OpenBrowser es un marco de navegación web autónomo para IA construido en TypeScript y Playwright. Proporciona a los modelos de lenguaje grandes el control directo de un navegador Chromium real — convirtiendo cualquier modelo de lenguaje en un agente con capacidad web.

Características clave

• Compatibilidad con múltiples modelos: Funciona con OpenAI GPT-4o, Anthropic Claude y Google Gemini de forma predeterminada
• REPL interactivo: Chatea con tu agente de navegador en tiempo real desde la terminal
• Ejecución aislada: Cada sesión de navegación se ejecuta en un contexto aislado de Playwright para garantizar la seguridad
• Seguimiento de costos: Monitoreo integrado de tokens y costos para conocer exactamente el costo de cada tarea
• Constructor de LaunchProfile: API fluida para configurar opciones de inicio del navegador, extensiones, modo de stealth y más
• Modo de stealth: Evitación de huellas digitales integrada para reducir la detección de bots

La brecha del navegador

OpenBrowser da a los modelos de IA ojos y manos en la web. Pero los CAPTCHAs siguen siendo un punto ciego. El agente puede ver la página, leer los campos de formulario y hacer clic en botones, pero no puede resolver un desafío reCAPTCHA o un widget Turnstile. Es ahí donde entra CapSolver.

¿Qué es CapSolver?

CapSolver es un servicio líder de resolución de CAPTCHAs que proporciona soluciones impulsadas por IA para superar diversos desafíos de CAPTCHA. Con soporte para múltiples tipos de CAPTCHA y tiempos de respuesta rápidos, CapSolver se integra sin problemas en flujos de trabajo automatizados.

Tipos de CAPTCHA compatibles

• reCAPTCHA v2 (basado en imágenes e invisible)
• reCAPTCHA v3 & v3 Enterprise
• Cloudflare Turnstile
• Cloudflare 5-second Challenge
• AWS WAF CAPTCHA
• Otros mecanismos de seguridad y anti-bots ampliamente utilizados

¿Por qué esta integración es diferente?

La mayoría de las integraciones de resolución de CAPTCHA requieren que escriba código: crear llamadas a API, consultar resultados, inyectar tokens en campos ocultos. Así funciona con herramientas como Crawlee, Puppeteer o Playwright.

OpenBrowser + CapSolver es fundamentalmente diferente:

La clave del insight: La extensión de Chrome de CapSolver se ejecuta dentro del contexto de navegador de Playwright de OpenBrowser. Cuando el agente navega a una página con un CAPTCHA, la extensión lo detecta, lo resuelve en segundo plano y inyecta el token — todo antes de que el agente intente enviar el formulario.

Solo necesita darle tiempo. En lugar de escribir código para manejar CAPTCHAs, agregue un breve retraso a su flujo de agente:

// El agente espera, luego envía — CapSolver se encarga del resto
await page.waitForTimeout(30_000);
await page.click('button[type="submit"]');

Eso es todo. Sin lógica de CAPTCHA. Sin llamadas a API. Sin inyección de tokens.

Requisitos previos

Antes de configurar la integración, asegúrese de tener:

1. OpenBrowser instalado (npm install openbrowser o clonado desde GitHub)
2. Una cuenta de CapSolver con clave de API (regístrese aquí)
3. Node.js 18+ y TypeScript configurados
4. Chromium o Chrome para pruebas (consulte la nota importante a continuación)

Importante: Necesita Chromium, no Google Chrome

Google Chrome 137+ (lanzado a mediados de 2025) eliminó silenciosamente el soporte para --load-extension en las versiones comerciales. Esto significa que las extensiones de Chrome no se pueden cargar en sesiones automatizadas usando Google Chrome estándar. No hay error — la bandera simplemente se ignora.

Esto afecta a Google Chrome y Microsoft Edge. Debe usar uno de estos alternativos:

Cómo instalar Chrome para pruebas:

# Opción 1: A través de Playwright (recomendado — OpenBrowser ya usa Playwright)
npx playwright install chromium

# La ubicación del binario será algo como:
# ~/.cache/ms-playwright/chromium-XXXX/chrome-linux64/chrome  (Linux)
# ~/Library/Caches/ms-playwright/chromium-XXXX/chrome-mac/Chromium.app/Contents/MacOS/Chromium  (macOS)

# Opción 2: A través de descarga directa de Chrome para pruebas
# Visite: https://googlechromelabs.github.io/chrome-for-testing/
# Descargue la versión que coincida con su sistema operativo

Después de la instalación, anote la ruta completa al binario — la necesitará para el perfil de inicio.

Configuración paso a paso

Paso 1: Instalar OpenBrowser

Si aún no lo ha hecho, instale OpenBrowser:

npm install openbrowser

O clone el repositorio para obtener las últimas características:

git clone https://github.com/ntegrals/openbrowser.git
cd openbrowser
npm install

Paso 2: Descargar la extensión de CapSolver para Chrome

Descargue la extensión de CapSolver para Chrome y extráigala a un directorio conocido:

1. Vaya a las versiones de la extensión de CapSolver en GitHub
2. Descargue la última CapSolver.Browser.Extension-chrome-vX.X.X.zip
3. Extraiga la carpeta:

mkdir -p ~/.openbrowser/capsolver-extension
unzip CapSolver.Browser.Extension-chrome-v*.zip -d ~/.openbrowser/capsolver-extension/

4. Verifique que la extracción funcionó:

ls ~/.openbrowser/capsolver-extension/manifest.json

Debería ver manifest.json — esto confirma que la extensión está en el lugar correcto.

Paso 3: Establecer su clave de API de CapSolver

Abra el archivo de configuración de la extensión en ~/.openbrowser/capsolver-extension/assets/config.js y reemplace el valor de apiKey con el suyo:

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',  // su clave aquí
  useCapsolver: true,
  // ... resto de la configuración
};

Puede obtener su clave de API desde su panel de CapSolver.

Paso 4: Configurar su LaunchProfile

Aquí es donde OpenBrowser brilla. Use el constructor de LaunchProfile para cargar la extensión de CapSolver en el navegador:

import { LaunchProfile, OpenBrowser } from 'openbrowser';

const profile = new LaunchProfile()
  .addExtension('/home/user/.openbrowser/capsolver-extension')
  .extraArgs('--disable-extensions-except=/home/user/.openbrowser/capsolver-extension')
  .headless(false)    // Requerido — las extensiones MV3 necesitan un navegador con interfaz gráfica
  .stealthMode();     // Reduce las huellas de detección de bots

¿Por qué headless(false)? Las extensiones MV3 (Manifest V3) de Chrome, incluida CapSolver, requieren un contexto de navegador con interfaz gráfica. El servicio worker que impulsa la extensión no se carga en modo headless. En servidores sin pantalla, use Xvfb (vea el Paso 7).

Importante: Si pasa banderas de Chrome personalizadas en cualquier otro lugar de su configuración, no incluya --disable-background-networking. El servicio worker de la extensión de CapSolver necesita acceso de red saliente.

Paso 5: Iniciar el navegador y ejecutar su agente

import { LaunchProfile, OpenBrowser } from 'openbrowser';

const profile = new LaunchProfile()
  .addExtension('/home/user/.openbrowser/capsolver-extension')
  .extraArgs('--disable-extensions-except=/home/user/.openbrowser/capsolver-extension')
  .headless(false)
  .stealthMode();

const browser = await OpenBrowser.launch(profile);

// Navegue a una página protegida por CAPTCHA
await browser.goto('https://example.com/protected-form');

// Espere a que CapSolver detecte y resuelva el CAPTCHA
await browser.page.waitForTimeout(30_000);

// Envíe el formulario — el token del CAPTCHA ya está inyectado
await browser.page.click('button[type="submit"]');

// Lea la página de destino o el elemento de confirmación
const result = await browser.page.textContent('body');
console.log(result); // por ejemplo, el texto de confirmación que devuelve el sitio

await browser.close();

Paso 6: Usar con agentes de IA

La verdadera potencia de OpenBrowser es permitir que un modelo de IA controle el navegador. Así es como lo conecta con CapSolver:

import { LaunchProfile, OpenBrowser, Agent } from 'openbrowser';

const profile = new LaunchProfile()
  .addExtension('/home/user/.openbrowser/capsolver-extension')
  .extraArgs('--disable-extensions-except=/home/user/.openbrowser/capsolver-extension')
  .headless(false)
  .stealthMode();

const browser = await OpenBrowser.launch(profile);

// Cree un agente con su modelo preferido
const agent = new Agent({
  browser,
  model: 'gpt-4o',  // o 'claude-sonnet-4-20250514', 'gemini-pro', etc.
});

// Dé al agente una tarea — no es necesario mencionar CAPTCHAs
await agent.run(`
  Vaya a https://example.com/contact,
  complete el formulario de contacto con:
    Nombre: "Jane Smith"
    Correo electrónico: "[email protected]"
    Mensaje: "Me gustaría saber más sobre su plan empresarial."
  Espere 30 segundos para que la página se cargue completamente,
  luego haga clic en Enviar.
  Dígame qué mensaje de confirmación aparece.
`);

await browser.close();

Observe que las instrucciones del agente dicen "espere 30 segundos para que la página se cargue completamente" — una frase natural que da tiempo a CapSolver para resolver cualquier CAPTCHA en la página sin que la IA sepa nada al respecto.

Paso 7: Configurar Xvfb para servidores sin interfaz gráfica

Como las extensiones MV3 requieren un navegador con interfaz gráfica, necesita una pantalla virtual en servidores sin monitor:

# Instalar Xvfb
sudo apt-get install -y xvfb

# Iniciar una pantalla virtual
Xvfb :99 -screen 0 1280x720x24 &

# Establecer DISPLAY antes de ejecutar su script
export DISPLAY=:99

Luego ejecute su script de OpenBrowser normalmente. El navegador renderizará en la pantalla virtual y las extensiones se cargarán correctamente.

¿Cómo funciona en segundo plano?

Para los curiosos técnicos, aquí está el flujo completo cuando CapSolver se carga en OpenBrowser:

  Su Script / Agente de IA
  ──────────────────────────────────────────────────
  LaunchProfile                   OpenBrowser
    .addExtension(path)   ──►  Añade la bandera --load-extension
    .extraArgs(...)             Añade --disable-extensions-except
    .headless(false)            a los argumentos de lanzamiento de Playwright
    .stealthMode()               │
                                 ▼
                            Playwright lanza Chromium
                            ┌───────────────────────────────┐
                            │  Proceso de Chromium           │
                            │                                │
                            │  1. Servicio de extensión     │
                            │     activa (background.js)     │
                            │                                │
                            │  2. Scripts de contenido inyectados │
                            │     en cada página             │
                            └───────────────────────────────┘
                                 │
                                 ▼
                            El agente navega a la URL objetivo
                            ┌───────────────────────────────┐
                            │  Página con widget CAPTCHA     │
                            │                                │
                            │  Extensión CapSolver:          │
                            │  1. Script de contenido detecta │
                            │     CAPTCHA en la página       │
                            │  2. Servicio de trabajo llama  │
                            │     a la API de CapSolver      │
                            │  3. Token recibido             │
                            │  4. Token inyectado en campo   │
                            │     oculto                     │
                            └───────────────────────────────┘
                                 │
                                 ▼
                            El agente espera (30-60 segundos)...
                                 │
                                 ▼
                            El agente hace clic en Enviar
                                 │
                                 ▼
                            El formulario se envía con token válido
                                 │
                                 ▼
                            Página de confirmación específica del sitio

Cómo funciona .addExtension()

.addExtension(path) genera --load-extension=/path/to/extension. Para esta integración, también necesita permitir explícitamente la extensión desempaquetada con .extraArgs('--disable-extensions-except=/path/to/extension'). Este es el mismo mecanismo de extensión para desarrolladores de Chrome que OpenBrowser expone a través de su perfil de lanzamiento.
2. Tus argumentos adicionales permiten esa extensión con --disable-extensions-except=/ruta/a/capsolver-extensión
3. La extensión se activa — su trabajador de servicio MV3 comienza y los scripts de contenido se registran para inyección
4. En cada carga de página — los scripts de contenido escanean el DOM en busca de widgets de CAPTCHA conocidos (reCAPTCHA, Turnstile, etc.)
5. Cuando se encuentra un CAPTCHA — el script de contenido envía un mensaje al trabajador de servicio, que llama a la API de CapSolver, recibe un token de solución y lo inyecta en los campos ocultos del formulario de la página

Alternativa: Enfoque de la API de CapSolver

Si hay problemas al cargar la extensión de Chrome — o si desea control explícito sobre el flujo de resolución de CAPTCHA — puede usar directamente la API REST de CapSolver con la instancia de OpenBrowser de Playwright.

Ejemplo completo

import { LaunchProfile, OpenBrowser } from 'openbrowser';

const CAPSOLVER_API_KEY = process.env.CAPSOLVER_API_KEY!;

async function solveCaptchaViaAPI(
  pageUrl: string,
  siteKey: string
): Promise<string> {
  const createRes = await fetch("https://api.capsolver.com/createTask", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      clientKey: CAPSOLVER_API_KEY,
      task: {
        type: "ReCaptchaV2TaskProxyLess",
        websiteURL: pageUrl,
        websiteKey: siteKey,
      },
    }),
  });
  const { taskId, errorDescription } = await createRes.json();
  if (!taskId) throw new Error(`createTask falló: ${errorDescription}`);

  for (let i = 0; i < 40; i++) {
    await new Promise((r) => setTimeout(r, 3000));
    const resultRes = await fetch("https://api.capsolver.com/getTaskResult", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ clientKey: CAPSOLVER_API_KEY, taskId }),
    });
    const result = await resultRes.json();
    if (result.status === "ready") {
      return result.solution.gRecaptchaResponse;
    }
  }
  throw new Error("Tiempo de resolución agotado");
}

// Iniciar sin extensión — no se necesitan banderas especiales de Chrome
const profile = new LaunchProfile()
  .headless(false)
  .stealthMode();

const browser = await OpenBrowser.launch(profile);
const page = browser.page;

await page.goto("https://example.com/página-protegida");

// Detectar sitekey
const siteKey = await page.evaluate(() => {
  const el = document.querySelector(".g-recaptcha[data-sitekey]");
  return el?.getAttribute("data-sitekey") ?? "";
});
console.log("Sitekey:", siteKey);

// Resolver mediante API
const token = await solveCaptchaViaAPI(page.url(), siteKey);
console.log("Token recibido, longitud:", token.length);

// Inyectar token
await page.evaluate((t) => {
  const textarea = document.querySelector(
    'textarea[name="g-recaptcha-response"]'
  ) as HTMLTextAreaElement;
  if (textarea) textarea.value = t;
}, token);

// Enviar
await page.click("#recaptcha-demo-submit");
await page.waitForLoadState("networkidle");

const body = await page.textContent("body");
console.log(
  body?.includes("Verificación Exitosa")
    ? "CAPTCHA resuelto mediante API!"
    : body?.slice(0, 200)
);

await browser.close();

Cuándo usar API vs extensión

Solución de problemas

Extensión no carga

Síntoma: El navegador se inicia pero los CAPTCHAS no se resuelven. No aparecen entradas relacionadas con la extensión en chrome://extensions.

Causa: Está usando Chrome de Google 137+ que ignora silenciosamente --load-extension.

Solución: Cambie a Chrome para pruebas o al Chromium empaquetado por Playwright. Si necesita especificar un ejecutable personalizado:

const profile = new LaunchProfile()
  .addExtension('/ruta/a/capsolver-extensión')
  .extraArgs('--disable-extensions-except=/ruta/a/capsolver-extensión')
  .executablePath('/ruta/a/chrome-para-pruebas/chrome')
  .headless(false)
  .stealthMode();

Verifique su versión de Chrome:

/ruta/a/chrome --version
# Chrome para pruebas: "Chromium 143.0.7499.4"
# Chrome de Google: "Google Chrome 143.0.7499.109"

Extensión no funciona en modo sin cabeza

Síntoma: La extensión carga en modo con interfaz pero no en modo sin cabeza.

Causa: Las extensiones de Chrome MV3 (Manifest V3) requieren un contexto de navegador con interfaz. El trabajador de servicio no se inicializa en los modos --headless o --headless=new.

Solución: Siempre use .headless(false) en su LaunchProfile. En servidores, use Xvfb para proporcionar una pantalla virtual:

Xvfb :99 -screen 0 1280x720x24 &
export DISPLAY=:99

CAPTCHA no resuelto (formulario falla)

Posibles causas:

1. Tiempo de espera insuficiente — Aumente a 60 segundos
2. Clave de API inválida — Verifique assets/config.js en su directorio de extensión
3. Saldo insuficiente — Recargue su cuenta de CapSolver en capsolver.com
4. Extensión no cargada — Vea "Extensión no cargando" anteriormente
5. Red de fondo bloqueada — Si ha agregado --disable-background-networking a los argumentos de Chrome, elimínelo. La extensión necesita acceso a la red para llamar a la API de CapSolver.

Conflictos con modo stealth

Síntoma: Las páginas detectan el navegador como automatizado incluso con .stealthMode() activado.

Solución: Asegúrese de usar el Chromium empaquetado por Playwright o Chrome para pruebas. Algunas parches de stealth son específicos de la versión de Chromium. También asegúrese de no pasar banderas de Chrome que contradigan la configuración de stealth.

Mejores prácticas

1. Siempre usar tiempos de espera generosos

Más tiempo de espera siempre es más seguro. El CAPTCHA normalmente se resuelve en 5-20 segundos, pero la latencia de red, desafíos complejos o reintentos pueden agregar tiempo. 30-60 segundos es el punto óptimo.

2. Usar lenguaje natural con agentes de IA

Al dar instrucciones a agentes de IA mediante OpenBrowser, mantenga su lenguaje natural y evite mencionar CAPTCHAs:

Bueno:

"Vaya a la página, espere aproximadamente un minuto para que todo se cargue, luego envíe el formulario."

Evite:

"Espere a que el CAPTCHA se resuelva, luego envíe."

Un lenguaje natural funciona mejor con LLMs y evita rechazos de seguridad. El agente no necesita saber sobre CAPTCHAs — la extensión maneja todo de forma invisible.

3. Configurar modo token para CAPTCHAs invisibles

Para sitios que usan reCAPTCHA v3 o reCAPTCHA v2 invisible, asegúrese de que el modo token esté activado en la configuración de la extensión (assets/config.js). El modo token garantiza que la extensión resuelva el desafío e inyecte el token sin requerir ninguna interacción visible.

4. Monitorear su saldo de CapSolver

Cada resolución de CAPTCHA cuesta créditos. Revise su saldo en capsolver.com/dashboard regularmente para evitar interrupciones.

5. Usar stealthMode() para producción

Siempre active .stealthMode() en su LaunchProfile para uso en producción. Esto aplica técnicas de evasión de huellas dactilares que reducen la probabilidad de que el navegador sea marcado como automatizado — lo que a su vez reduce la probabilidad de encontrarse con CAPTCHAs agresivos.

const profile = new LaunchProfile()
  .addExtension('/ruta/a/capsolver-extensión')
  .extraArgs('--disable-extensions-except=/ruta/a/capsolver-extensión')
  .headless(false)
  .stealthMode();  // Actívelo siempre en producción

6. Establecer DISPLAY en servidores sin cabeza

Las extensiones de Chrome requieren una pantalla, incluso en servidores sin cabeza. Use Xvfb para crear una pantalla virtual:

# Instalar Xvfb
sudo apt-get install -y xvfb

# Iniciar una pantalla virtual
Xvfb :99 -screen 0 1280x720x24 &

# Establecer DISPLAY para su script de OpenBrowser
export DISPLAY=:99

Conclusión

La integración de OpenBrowser + CapSolver representa el enfoque más limpio posible para resolver CAPTCHAs en automatización de navegadores de IA. En lugar de escribir lógica de detección de CAPTCHA, manejar llamadas a API, sondear resultados y inyectar tokens — simplemente:

1. Descargue la extensión de CapSolver y cómprela a un directorio
2. Agregue la extensión y permítala: .addExtension('/ruta/a/capsolver-extensión') más .extraArgs('--disable-extensions-except=/ruta/a/capsolver-extensión')
3. Establezca headless(false) y use Xvfb en servidores
4. Elimine cualquier sobrescritura de --disable-background-networking
5. Agregue un tiempo de espera antes de enviar formularios para darle tiempo a la extensión de resolver

Sin cambios en su lógica de agente. Sin código específico de CAPTCHA. Sin acoplamiento entre su modelo de IA y el servicio de resolución. La extensión opera a nivel de navegador, completamente invisible para el agente.

Este es el aspecto que tiene la resolución de CAPTCHA cuando es verdaderamente automatizada: invisible, sin código y sin dependencia del modelo.

¿Listo para comenzar? Regístrese en CapSolver y use el código de bonificación OPENBROWSER para obtener un 6% adicional en su primera recarga!

Preguntas frecuentes

¿Necesito modificar mis instrucciones para agentes de IA para manejar CAPTCHAs?

No. La extensión de CapSolver funciona completamente a nivel de navegador — su agente de IA (GPT-4o, Claude, Gemini, etc.) nunca necesita saber sobre CAPTCHAs. Solo incluya un tiempo de espera razonable en sus instrucciones para el agente (por ejemplo, "espere 30 segundos para que la página se cargue completamente") para darle tiempo a la extensión de resolver cualquier desafío.

¿Por qué no puedo usar Chrome de Google regular?

Chrome 137+ (lanzado a mediados de 2025) eliminó el soporte para la bandera de línea de comandos --load-extension en construcciones de marca. Esto significa que no se pueden cargar extensiones de Chrome en sesiones automatizadas. Necesita Chrome para pruebas o Chromium independiente, que aún soportan esta bandera. Dado que OpenBrowser usa Playwright en segundo plano, la opción más sencilla es npx playwright install chromium.

¿Funciona esto en modo sin cabeza?

No directamente. Las extensiones de Chrome MV3 (Manifest V3) requieren un contexto de navegador con interfaz — el trabajador de servicio no se inicializa en modo sin cabeza. En servidores sin pantalla, use Xvfb para crear una pantalla virtual (Xvfb :99 & y export DISPLAY=:99). El navegador renderiza en la pantalla virtual y las extensiones se cargan normalmente.

¿Qué tipos de CAPTCHA soporta CapSolver?

CapSolver soporta reCAPTCHA v2 (casilla e invisible), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, Cloudflare 5-second Challenge, AWS WAF CAPTCHA y más. La extensión de Chrome detecta automáticamente el tipo de CAPTCHA y lo resuelve en consecuencia.

¿Cuánto cuesta CapSolver?

CapSolver ofrece precios competitivos basados en el tipo de CAPTCHA y el volumen. Visite capsolver.com para ver los precios actuales. Use el código de bonificación OPENBROWSER para obtener un 6% adicional en su primera recarga.

¿Funciona esto con todos los modelos de IA soportados por OpenBrowser?

Sí. Dado que CapSolver opera a nivel de navegador mediante una extensión de Chrome, funciona de manera idéntica sin importar qué modelo de IA impulsa a su agente de OpenBrowser — GPT-4o, Claude, Gemini o cualquier otro modelo soportado. El modelo nunca interactúa con el proceso de resolución de CAPTCHA.