PicoClaw Automation: Una Guía para Integrar CapSolver API

Cuando tu asistente de IA automatiza tareas web, los CAPTCHAs son el principal obstáculo. Las páginas protegidas se niegan a enviar, los flujos de inicio de sesión se detienen y todo el pipeline de automatización se detiene esperando a que un humano haga clic en un cuadro de verificación o identifique semáforos.

PicoClaw es un asistente de IA personal ultraligero escrito en Go que funciona en hardware de $10 con menos de 10 MB de RAM. Se conecta a las plataformas de mensajería que ya usas y incluye una herramienta exec integrada que permite al agente escribir y ejecutar scripts de forma autónoma.

CapSolver proporciona una API de resolución de CAPTCHA impulsada por IA. Al combinar las capacidades de ejecución de scripts de PicoClaw con la API REST de CapSolver, tu agente puede detectar CAPTCHAs, resolverlos, inyectar tokens y enviar formularios sin intervención humana.

Lo mejor de todo es que solo le dices al agente lo que quieres hacer en lenguaje claro. Escribirá un script de Playwright, extraerá el sitekey, llamará a CapSolver, inyectará el token y enviará el formulario de forma autónoma. Y como PicoClaw está compilado en Go, toda la capa de orquestación cabe dentro de 10 MB de RAM en una placa RISC-V de $10.

¿Qué es PicoClaw?

PicoClaw es un asistente de IA personal ultraligero construido en Go 1.25.7 a través de un proceso de autoarranque sorprendente: el agente de IA condujo toda la migración arquitectónica desde Python, produciendo el 95% del código principal de forma autónoma con refinamiento humano.

Los números

El lema de PicoClaw lo dice todo: Hardware de $10. 10 MB de RAM. 1 segundo de arranque.

Características clave

• Ultraligero: Menos de 10 MB de uso de memoria — 99% más pequeño que agentes de TypeScript comparables
• Verdadera portabilidad: Binario autónomo único en arquitecturas RISC-V, ARM64 y x86_64
• Herramientas integradas: El agente puede leer/escribir archivos, ejecutar comandos de shell, buscar en la web, obtener páginas, enviar mensajes a través de canales, programar tareas cron y hasta interactuar con periféricos de hardware I2C/SPI
• Proveedor-agnostic: Funciona con OpenAI, Anthropic, DeepSeek, Gemini, Qwen, Moonshot, Groq, vLLM, Ollama, Cerebras, Mistral, NVIDIA y proveedores de pasarela como OpenRouter
• Sistema de habilidades: Amplía las capacidades con archivos SKILL.md usando metadatos JSON o YAML
• Sistema de memoria: Notas diarias y memoria a largo plazo persistente entre conversaciones
• Herramientas de hardware: Herramientas I2C y SPI para interactuar directamente con dispositivos embebidos — único de PicoClaw

La herramienta ExecTool

La ExecTool de PicoClaw (definida en pkg/tools/shell.go) es lo que hace posible la automatización del navegador. Es un entorno de ejecución de shell cuidadosamente aislado con 27+ patrones de denegación de seguridad compilados como regexps de Go, un tiempo de espera predeterminado de 60 segundos, restricción de ruta de trabajo y detección de intentos de navegación de ruta.

Cuando le pides al agente que interactúe con una página web, hace lo siguiente:

1. Escribe un script de Playwright mediante la herramienta write_file
2. Lo ejecuta mediante la herramienta exec (que llama a sh -c en Linux)
3. Lee la salida (stdout + stderr, truncada a 10 KB)
4. Informa los resultados de vuelta a través de tu canal de chat

El método guardCommand() de la herramienta comprueba cada comando contra los patrones de denegación compilados antes de la ejecución, aplica restricciones de ruta de trabajo y detecta intentos de navegación de ruta. Piénsalo como un acceso al terminal con aislamiento — el agente puede ejecutar scripts de Node.js y instalaciones locales de paquetes, pero no puede hacer rm -rf, sudo o docker run.

El bucle del agente

La lógica principal vive en pkg/tools/toolloop.go — un ciclo estrecho: Llamada a LLM -> Extraer llamadas a herramientas -> Ejecutar herramientas -> Añadir resultados -> repetir hasta que se obtenga una respuesta de texto final (o MaxIterations, predeterminado a 20). Este bucle se comparte entre el agente principal (pkg/agent/loop.go) y subagentes en segundo plano mediante spawn.

¿Qué es CapSolver?

CapSolver es un servicio líder de resolución de CAPTCHA que proporciona soluciones impulsadas por IA para evitar diversos desafíos de CAPTCHA. Con soporte para varios 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

¿Por qué el enfoque de PicoClaw es diferente?

La mayoría de las integraciones de resolución de CAPTCHA se dividen en dos categorías: integración a nivel de código donde escribes una clase de servicio dedicada, o extensión de navegador donde una extensión de Chrome maneja todo de forma invisible. PicoClaw toma un tercer enfoque: integración de API impulsada por agente en hardware de borde.

El propio agente de IA orquesta todo el proceso de resolución de forma autónoma — escribiendo un script de Playwright, extrayendo el sitekey, llamando a la API de CapSolver y inyectando el token de solución — todo a través de scripts que escribe y ejecuta en tiempo real. Y críticamente, el orquestador basado en Go que hace todo este coordinación consume menos de 10 MB de RAM.

La ventaja del dispositivo de borde

Puedes ejecutar automatización de resolución de CAPTCHA en hardware que cuesta menos que un café. Un LicheeRV-Nano de $9.90 que ejecuta PicoClaw puede recibir un mensaje de Telegram, coordinarse con la API en la nube de CapSolver, inyectar el token y enviar el formulario — todo mientras usa una fracción de los 64 MB de RAM de la placa. El trabajo pesado (reconocimiento de CAPTCHA) ocurre en los servidores de CapSolver; PicoClaw solo orquesta. Siempre en funcionamiento, 24/7, en un dispositivo del tamaño de un sello.

La clave principal: El binario de Go de PicoClaw es tan ligero que funciona en hardware que la mayoría de los marcos ni siquiera pueden arrancar — pero puede orquestar todo el pipeline de resolución de CAPTCHA a través de scripts de Playwright y la API REST de CapSolver.

Requisitos previos

Nota: Los ejemplos a continuación se probaron en Ubuntu 22.04 / 24.04. Los comandos usan apt y bash — ajusta según tu distribución si es necesario. Para dispositivos de borde (RISC-V, ARM), compila en cruz PicoClaw en tu máquina de construcción o descarga un binario preconstruido desde la página de lanzamientos.

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

1. Ubuntu 22.04+ (o cualquier distribución de Linux — el binario único de PicoClaw funciona en cualquier lugar)
2. Go 1.25.7+ instalado (solo necesario para construir desde el código fuente)
3. PicoClaw instalado y en ejecución (binario preconstruido o make build)
4. Una cuenta de CapSolver con clave de API (regístrate aquí)
5. Node.js 18+ instalado (para ejecutar scripts de Playwright mediante la herramienta exec)
6. Playwright instalado en tu espacio de trabajo

Configuración paso a paso

Paso 1: Instalar PicoClaw

Opción A: Binario preconstruido (más rápido)

# Descargar la última versión para tu plataforma
# Reemplaza v0.1.1 con la última versión de la página de lanzamientos
wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-amd64
chmod +x picoclaw-linux-amd64
sudo mv picoclaw-linux-amd64 /usr/local/bin/picoclaw

# Ejecutar el asistente de configuración interactivo
picoclaw onboard

Opción B: Construir desde el código fuente

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
make build
make install

# Inicializar configuración y espacio de trabajo
picoclaw onboard

Esto crea ~/.picoclaw/config.json, ~/.picoclaw/workspace/ (scripts, habilidades y memoria).

Paso 2: Establecer tu clave de API de CapSolver

Agrega tu clave de API de CapSolver como variable de entorno:

export CAPSOLVER_API_KEY="CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Puedes obtener tu clave de API desde tu panel de CapSolver.

Para una configuración persistente, agrégala a ~/.bashrc o ~/.zshrc.

Paso 3: Instalar herramientas de automatización de navegador

Instala Playwright y sus dependencias del sistema en Ubuntu:

# Instalar dependencias del navegador de Playwright (Ubuntu)
sudo apt install -y libnss3 libatk-bridge2.0-0 libdrm2 libxcomposite1 \
  libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libasound2t64

# Instalar Playwright en tu espacio de trabajo de PicoClaw
cd ~/.picoclaw/workspace
npm init -y
npm install playwright
npx playwright install chromium

Nota de dispositivo de borde: En placas con recursos limitados, es posible que desees instalar Chromium en una máquina más potente y apuntar a un navegador remoto mediante browserType.connect() de Playwright. El agente de PicoClaw solo necesita ~10 MB de RAM; el navegador es la parte pesada.

Paso 4: Configurar ExecTool para automatización de navegador

La herramienta ExecTool de PicoClaw tiene patrones de denegación integrados para seguridad. Los predeterminados funcionan bien para la automatización de CAPTCHA: node, npx y npm install locales están permitidos. Solo se bloquean comandos peligrosos como npm install -g, sudo, docker run, etc. No se necesitan cambios de configuración para el flujo estándar.

Paso 5: Iniciar el gateway

# Iniciar servicios de canal (Telegram, Discord, etc.)
picoclaw gateway

# O para pruebas interactivas
picoclaw agent

Paso 6: Verificar la configuración

Envía un mensaje de prueba al agente a través de cualquier canal conectado:

¿Qué herramientas tienes disponibles?

El agente debe listar exec entre sus herramientas — esta es la que usa para ejecutar scripts de automatización de navegador. También puedes verificar el acceso a Node.js:

Ejecutar: node --version

El agente debe ejecutar esto mediante la herramienta exec y devolver la versión de Node.js.

La habilidad integrada de CapSolver

PicoClaw utiliza un sistema de habilidades basado en archivos SKILL.md con metadatos frontmatter. Las habilidades se cargan desde tres ubicaciones en orden de prioridad (definido en pkg/skills/loader.go):

1. Habilidades del espacio de trabajo: ~/.picoclaw/workspace/skills/{name}/SKILL.md (nivel de proyecto, mayor prioridad)
2. Habilidades globales: ~/.picoclaw/skills/{name}/SKILL.md (nivel de usuario)
3. Habilidades integradas: skills/{name}/SKILL.md (incluidas con el binario)

Las habilidades del espacio de trabajo anulan a las globales, que a su vez anulan a las integradas. El cargador lee el frontmatter como JSON o YAML y construye un resumen en XML para el prompt del sistema.

El archivo de habilidad (~/.picoclaw/workspace/skills/capsolver/SKILL.md)

---
nombre: capsolver
descripción: "Resolver CAPTCHAs usando la API REST de CapSolver con Playwright. Soporta reCAPTCHA v2, reCAPTCHA v3 y Cloudflare Turnstile. Úsalo cuando automatices envíos de formularios o interacciones en páginas que encuentren desafíos CAPTCHA."
metadata: {"picoclaw":{"emoji":"🔓","siempre":true,"requiere":{"bins":["node"],"env":["CAPSOLVER_API_KEY"]}}}
---

# CapSolver

## NOTA IMPORTANTE: Ejecución requerida

Cuando un usuario te pide resolver un CAPTCHA, DEBES llamar inmediatamente a una herramienta. NO respondas con texto como "Ejecutando..." o "Comenzaré..." o "He iniciado la automatización...".

Tu primera acción DEBE ser una de:
1. Llamar a `write_file` para guardar un script de Node.js, luego llamar a `exec` para ejecutarlo
2. Llamar a `spawn` con una descripción detallada de la tarea para ejecución en segundo plano

Si respondes solo con texto y sin llamada a herramienta, el usuario no verá nada. Siempre ejecuta.

## Puntos de entrada de API

- **Crear tarea**: `POST https://api.capsolver.com/createTask`
- **Obtener resultado**: `POST https://api.capsolver.com/getTaskResult`

## Tipos de tarea

| CAPTCHA | Tipo de tarea | Ubicación del sitekey |
|---|---|---|
| reCAPTCHA v2 | `ReCaptchaV2TaskProxyLess` | atributo `data-sitekey` |
| reCAPTCHA v3 | `ReCaptchaV3TaskProxyLess` | llamada `grecaptcha.execute` o fuente de página |
| Cloudflare Turnstile | `AntiTurnstileTaskProxyLess` | `data-sitekey` en div de Turnstile |

Variantes empresariales: `ReCaptchaV2EnterpriseTaskProxyLess`, `ReCaptchaV3EnterpriseTaskProxyLess`.

## Flujo de trabajo

1. Navegar a la página con Playwright (Chromium sin cabeza)
2. Extraer el sitekey del DOM (`[data-sitekey]` atributo)
3. Llamar a `createTask` con el sitekey y la URL de la página
4. Consultar `getTaskResult` cada 2 segundos hasta que `estado: "listo"`
5. Inyectar el token en la página (campo oculto del formulario)
6. Enviar el formulario

## Patrón de código principal

```javascript
const CAPSOLVER_API_KEY = process.env.CAPSOLVER_API_KEY;

// Paso 1: Crear tarea
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',  // o ReCaptchaV3TaskProxyLess, AntiTurnstileTaskProxyLess
      websiteURL: pageUrl,
      websiteKey: siteKey
    }
  })
});
const { taskId } = await createRes.json();

// Paso 2: Consultar resultado
let token;
while (true) {
  await new Promise(r => setTimeout(r, 2000));
  const res = 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 res.json();
  if (result.status === 'ready') { token = result.solution.gRecaptchaResponse || result.solution.token; break; }
  if (result.status === 'failed') throw new Error('Resolución fallida');
}

// Paso 3: Inyectar token (reCAPTCHA)
await page.evaluate((t) => {
  document.querySelectorAll('textarea[name="g-recaptcha-response"]')
    .forEach(el => { el.value = t; el.innerHTML = t; });
}, token);
```

Para Turnstile, el campo del token suele ser `input[name="cf-turnstile-response"]` y la solución está en `result.solution.token`.

## Referencia de API

Todos los tipos de tarea requieren `type`, `websiteURL`, `websiteKey`. Los campos opcionales varían según el tipo:
- **reCAPTCHA v2**: `isInvisible`, `pageAction`, `enterprisePayload`, `apiDomain`
- **reCAPTCHA v3**: `pageAction` (de `grecaptcha.execute(key, {action: "..."})`)
- **Cloudflare Turnstile**: `metadata.action`, `metadata.cdata`

Puntos clave:

• El frontmatter usa JSON o YAML (pkg/skills/loader.go intenta primero JSON, luego YAML)
• metadata contiene configuración específica de PicoClaw: emoji para mostrar, always para cargar automáticamente, requires para comprobaciones de dependencias
• SkillsLoader.BuildSkillsSummary() genera resúmenes XML inyectados en el prompt del sistema
• La sección "Execution Required" obliga a llamar a herramientas en lugar de respuestas únicamente de texto

Después de crear la habilidad, verifica con picoclaw skills — deberías ver capsolver listado.

¿Cómo funciona

Cuando le pides a PicoClaw que interactúe con una página protegida por CAPTCHA, aquí está el flujo completo desde el mensaje hasta el resultado:

  Tu mensaje                     Agente de PicoClaw (Go, ~10MB de RAM)
  ─────────────────────────────────────────────────────────────
  "Ve a esa página,           ──► El Agente recibe a través de MessageBus
   completa el formulario,          │ (pkg/bus/bus.go)
   resuelve el captcha,             ▼
   y envíalo"                ContextBuilder inyecta habilidades
                                   │ (pkg/agent/context.go)
                                   ▼
                              RunToolLoop comienza
                                   │ (pkg/tools/toolloop.go)
                                   ▼
                              El Agente escribe un script en Node.js
                                   │ mediante la herramienta write_file
                                   ▼
                              ExecTool ejecuta el script
                              ┌────────────────────────────┐
                              │ pkg/tools/shell.go          │
                              │ guardCommand() → 27+ comprobaciones │
                              │ sh -c "node script.js"      │
                              │                             │
                              │  Chromium headless          │
                              │  1. Navegar a la página        │
                              │  2. Extraer sitekey         │
                              │  3. POST /createTask ────────── API de CapSolver
                              │  4. Consultar /getTaskResult ───── (en la nube)
                              │  5. Inyectar token            │
                              │  6. Enviar formulario         │
                              │  7. Captura de pantalla        │
                              └────────────────────────────┘
                                   │
                                   ▼ stdout devuelto (máximo 10KB)
                              El Agente lee la salida
                                   │
                                   ▼
                              "Formulario enviado con éxito!
                               Éxito en la verificación!"

El flujo de la API de CapSolver

El núcleo de la integración son dos llamadas a la API:

1. Crear una tarea — Envía la sitekey de CAPTCHA y la URL de la página a CapSolver:

const response = 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
    }
  })
});

2. Consultar el resultado — Verifica cada 2 segundos hasta que CapSolver devuelva el token resuelto:

const result = await fetch('https://api.capsolver.com/getTaskResult', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientKey: CAPSOLVER_API_KEY,
    taskId: taskId
  })
});
// result.solution.gRecaptchaResponse contiene el token

3. Inyectar el token — Establece el token en el campo oculto del formulario que espera reCAPTCHA:

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

Ejemplo de funcionamiento completo

Aquí está el script en Node.js real que genera y ejecuta el agente de PicoClaw para resolver reCAPTCHA en la página de demostración de Google. El agente lo escribe mediante write_file, luego lo ejecuta con exec — todo de forma autónoma a partir de un solo mensaje de Telegram:

const { chromium } = require('playwright');
const https = require('https');

const CAPSOLVER_API_KEY = process.env.CAPSOLVER_API_KEY;
const PAGE_URL = '';

function httpsPost(url, data) {
  return new Promise((resolve, reject) => {
    const req = https.request(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' }
    }, (res) => {
      let body = '';
      res.on('data', chunk => body += chunk);
      res.on('end', () => resolve(JSON.parse(body)));
    });
    req.on('error', reject);
    req.write(JSON.stringify(data));
    req.end();
  });
}

async function solveRecaptcha(siteKey, pageUrl) {
  console.log('Creando tarea de CapSolver...');

  const createRes = await httpsPost('https://api.capsolver.com/createTask', {
    clientKey: CAPSOLVER_API_KEY,
    task: {
      type: 'ReCaptchaV2TaskProxyLess',
      websiteURL: pageUrl,
      websiteKey: siteKey
    }
  });

  if (createRes.errorId) {
    throw new Error(`Error de CapSolver: ${createRes.errorDescription}`);
  }

  const { taskId } = createRes;
  console.log(`ID de tarea: ${taskId}`);

  let token;
  while (true) {
    await new Promise(r => setTimeout(r, 2000));

    const res = await httpsPost('https://api.capsolver.com/getTaskResult', {
      clientKey: CAPSOLVER_API_KEY,
      taskId
    });

    if (res.status === 'ready') {
      token = res.solution.gRecaptchaResponse;
      console.log(`Token recibido! Longitud: ${token.length}`);
      break;
    }
    if (res.status === 'failed') {
      throw new Error(`Tarea de CapSolver fallida: ${res.errorDescription}`);
    }

    console.log('Consultando... estado:', res.status);
  }

  if (!token) throw new Error('No se pudo obtener el token');
  return token;
}

async function main() {
  const browser = await chromium.launch({
    headless: true,
    args: ['--no-sandbox', '--disable-setuid-sandbox']
  });
  const page = await browser.newPage();

  try {
    await page.goto(PAGE_URL, { waitUntil: 'domcontentloaded', timeout: 30000 });
    const siteKey = await page.locator('[data-sitekey]').getAttribute('data-sitekey');
    console.log(`Sitekey: ${siteKey}`);

    const token = await solveRecaptcha(siteKey, PAGE_URL);

    await page.evaluate((t) => {
      document.querySelectorAll('textarea[name="g-recaptcha-response"]')
        .forEach(el => { el.value = t; el.innerHTML = t; });
    }, token);

    await page.locator('input[type="submit"]').click();
    await page.waitForTimeout(3000);

    const body = await page.textContent('body');
    console.log(body.includes('Success') ? 'ÉXITO!' : 'Resultado:', body.slice(0, 200));
    await page.screenshot({ path: 'recaptcha_result.png' });
  } finally {
    await browser.close();
  }
}

main().catch(err => {
  console.error('Error:', err.message);
  process.exit(1);
});

Ejécutalo directamente:

CAPSOLVER_API_KEY=CAP-XXX node solve_recaptcha.js

O deja que el agente de PicoClaw lo maneje — solo envía un mensaje en Telegram:

Resuelve el reCAPTCHA en https://example.com y envía el formulario.

El agente lee su habilidad capsolver, escribe el script, lo ejecuta mediante exec, lee la salida y reporta el resultado.

Cómo usarlo

Una vez que la configuración esté completa, usar CapSolver con PicoClaw es tan sencillo como enviar un mensaje en cualquier canal conectado.

Ejemplo 1: Resolver un demo de reCAPTCHA

Envía esto a tu agente mediante Telegram, Discord, WhatsApp o cualquier canal conectado:

Ve a https://example.com y resuelve
el reCAPTCHA usando la API de CapSolver, luego envía el formulario
y dime si tuvo éxito.

Lo que ocurre: El agente lee la habilidad capsolver, escribe un script de Playwright, lo ejecuta mediante exec (que pasa las comprobaciones de guardCommand() y se ejecuta con un límite de 60 segundos), y el script navega por la página, extrae la sitekey, llama a CapSolver, inyecta el token y envía el formulario. El resultado vuelve a ti a través del MessageBus.

Ejemplo 2: Iniciar sesión en un sitio protegido

Ve a https://example.com/login, completa el correo con
"[email protected]" y la contraseña con "mypassword", detecta y
resuelve cualquier CAPTCHA en la página, luego haz clic en Iniciar sesión y dime
qué ocurre.

Ejemplo 3: Enviar un formulario de contacto

Abre https://example.com/contact, completa los campos de nombre, correo electrónico y
mensaje, resuelve el CAPTCHA, envía el formulario y dime el mensaje de confirmación.

Ejemplo 4: Automatización en segundo plano mediante spawn

Para tareas que tardan más, usa la herramienta spawn (pkg/tools/spawn.go) para delegar a un subagente en segundo plano:

En segundo plano, ve a https://example.com/register, crea
una cuenta con mis datos, resuelve cualquier CAPTCHA que encuentres,
y avísame cuando esté listo.

Ejemplo 5: Monitoreo en dispositivos de borde (Telegram en una placa de $10)

Si PicoClaw está ejecutándose en una placa de borde como LicheeRV-Nano, combínalo con la herramienta cron:

Cada hora, revisa https://example.com/status — si hay un
CAPTCHA, resuélvelo y reporta el contenido de la página de estado.

¿Por qué funciona esto?

El agente de PicoClaw tiene todas las herramientas necesarias para resolver CAPTCHA de forma autónoma:

• exec (pkg/tools/shell.go) — ejecución de shell en un sandbox con 27+ patrones de denegación
• write_file / read_file (pkg/tools/filesystem.go) — gestión de scripts en el espacio de trabajo
• spawn (pkg/tools/spawn.go) — delegación a subagentes en segundo plano para tareas largas
• web_fetch (pkg/tools/web.go) — obtención de contenido de página para análisis del DOM
• Sistema de habilidades (pkg/skills/loader.go) — la habilidad capsolver proporciona documentación de la API en el contexto
• Memoria (pkg/agent/memory.go) — persiste los métodos exitosos entre sesiones

Resultados de rendimiento

Hemos probado la integración en la página de demostración de reCAPTCHA v2 de Google mediante un bot de Discord en Ubuntu 24.04. El agente de PicoClaw (usando glm-4.7 a través de z.ai) recibió un mensaje de Discord, escribió un script de Playwright de forma autónoma, resolvió el CAPTCHA y reportó el resultado — todo sin intervención humana:

Nota para dispositivos de borde: En placas con RAM limitada (por ejemplo, LicheeRV-Nano de $9,90 con 64MB), PicoClaw cabe fácilmente (~8MB), pero Chromium necesita 100-300MB. Usa connect() de Playwright para enviar el navegador a una máquina más potente mientras mantienes al agente ligero en el dispositivo de borde.

Solución de problemas

"No se puede encontrar el módulo 'playwright'"

Playwright no está instalado en el espacio de trabajo. Ejecuta:

cd ~/.picoclaw/workspace && npm install playwright && npx playwright install chromium

Librerías de navegador faltantes en Ubuntu

Si Chromium falla al iniciar con errores sobre librerías compartidas faltantes, instala las dependencias del sistema:

sudo apt install -y libnss3 libatk-bridge2.0-0 libdrm2 libxcomposite1 \
  libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libasound2t64

Patrones de denegación de ExecTool bloqueando npm install

Los patrones de denegación de PicoClaw bloquean npm install -g (instalaciones globales), sudo y apt install, pero permiten npm install local, node script.js y npx playwright install. Si ves "Comando bloqueado por el guardián de seguridad", puedes desactivar los patrones de denegación o proporcionar unos personalizados en ~/.picoclaw/config.json:

{ "tools": { "exec": { "enable_deny_patterns": false } } }

O usa una lista de permitidos personalizada que excluya solo los patrones que quieras bloquear.

Tiempo de espera para resolver CAPTCHA

• Verifica que tu clave de API de CapSolver sea válida
• Verifica tu saldo en tu cuenta de CapSolver en capsolver.com/dashboard
• El script consulta cada 2 segundos hasta que CapSolver devuelve ready o failed
• Si el límite de 60 segundos de la herramienta exec no es suficiente, el script se matará. Puedes aumentarlo programáticamente o usar la herramienta spawn para tareas más largas (los subagentes tienen su propio límite de tiempo)

Límite de tiempo de 60 segundos de ExecTool demasiado corto

El límite predeterminado en pkg/tools/shell.go es de 60 segundos. Para automatización de CAPTCHA, puede ser ajustado. Usa la herramienta spawn para tareas más largas (los subagentes se ejecutan de forma independiente), o modifica el límite en NewExecToolWithConfig() en el código fuente (timeout: 120 * time.Second).

No se encuentra la sitekey

El script extrae la sitekey del atributo data-sitekey. Si no se encuentra ningún elemento, el agente puede adaptarse y extraerla de las URLs de iframes o del código de la página.

El navegador se cierra en Docker/contenedores

Agrega --no-sandbox, --disable-setuid-sandbox y --disable-dev-shm-usage a los argumentos de lanzamiento de Playwright.

El agente no usa CapSolver

Verifica: (1) que la variable de entorno CAPSOLVER_API_KEY esté establecida antes de iniciar PicoClaw, (2) que el archivo de habilidad exista en ~/.picoclaw/workspace/skills/capsolver/SKILL.md, (3) que picoclaw skills lo muestre en la lista.

Buenas prácticas

1. Establece la clave de API como variable de entorno

No codifiques la clave en los scripts. Usa process.env.CAPSOLVER_API_KEY para que el agente la detecte automáticamente. PicoClaw pasa el entorno del proceso padre a todas las invocaciones de la herramienta exec.

2. Usa el modo headless en servidores

El enfoque basado en API de PicoClaw funciona en entornos completamente headless — no se necesita Xvfb ni pantalla virtual. Esta es una ventaja significativa frente a enfoques basados en extensiones, especialmente en dispositivos de borde donde no existe hardware de pantalla.

3. Supervisa tu saldo en CapSolver

Cada resolución de CAPTCHA cuesta créditos. Revisa tu saldo regularmente en capsolver.com/dashboard.

4. Mantén actualizado Playwright

Los proveedores de CAPTCHA evolucionan. Mantén actualizado Playwright y Chromium:

cd ~/.picoclaw/workspace && npm update playwright && npx playwright install chromium

5. Usa la herramienta spawn para tareas de larga duración

La automatización del navegador puede tardar 30-60 segundos. Usa spawn en lugar de depender del bucle principal del agente para evitar tiempos de espera y mantener al agente principal respondiendo a otros mensajes.

6. Aprovecha el sistema de memoria de PicoClaw

Después de una resolución exitosa de CAPTCHA, el agente guarda el método en ~/.picoclaw/workspace/memory/MEMORY.md. La próxima vez, recuerda el patrón exacto que funcionó.

7. Despliegue en dispositivos de borde: Delega el navegador

En placas de 10 dólares con RAM limitada, conéctese a una instancia remota de Chromium a través de chromium.connect('ws://server:9222'). Esto mantiene la huella de PicoClaw de ~8MB en el borde mientras el navegador se ejecuta en otro lugar.

8. Configure cuidadosamente la restricción del espacio de trabajo

La configuración restrict_to_workspace de PicoClaw limita las operaciones de archivo y ejecución al directorio del espacio de trabajo. Asegúrate de que tus scripts y la instalación de Playwright estén dentro de ~/.picoclaw/workspace/.

Conclusión

La integración de PicoClaw + CapSolver representa un enfoque fundamentalmente diferente para resolver CAPTCHAs. En lugar de extensiones de navegador pesadas en máquinas de escritorio, un agente compilado en Go que se ejecuta en hardware de 10 dólares coordina todo el flujo de resolución:

1. Navegar a la página objetivo con Playwright
2. Extraer la sitekey del atributo data-sitekey
3. Resolver llamando directamente a la API REST de CapSolver
4. Inyectar el token de solución en el campo de formulario oculto
5. Enviar el formulario y verificar el éxito

Esto le da a usted:

• Sin dependencia de extensión de Chrome — funciona con cualquier navegador headless
• Soporte de servidor headless — no se necesita pantalla o Xvfb
• Control en lenguaje natural — simplemente dígale al agente qué desea hacer a través de Telegram, Discord o cualquier otro canal entre 12+
• Despliegue en dispositivos de borde — se puede ejecutar 24/7 en una placa RISC-V de 10 dólares con menos de 10MB de RAM
• Seguridad por defecto — 27+ patrones de denegación en el ExecTool previenen comandos peligrosos

Bonus: Script de inicio rápido

Guarde el ejemplo funcional completo de arriba en ~/.picoclaw/workspace/solve_captcha.js y ejecute:

CAPSOLVER_API_KEY=CAP-XXX node ~/.picoclaw/workspace/solve_captcha.js

O simplemente envíe un mensaje de Telegram a su agente PicoClaw y deje que se encargue de todo de forma autónoma.

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

Preguntas frecuentes

¿Cómo resuelve PicoClaw los CAPTCHAs de manera diferente a las extensiones de navegador?

PicoClaw utiliza directamente la API REST de CapSolver. El agente escribe y ejecuta scripts de Node.js/Playwright que llaman a createTask y getTaskResult para obtener tokens de solución, luego los inyecta en el DOM de la página. No se necesita extensión de navegador. Toda la coordinación ocurre a través de ExecTool de PicoClaw (pkg/tools/shell.go), que ejecuta sh -c "node script.js" con 27+ patrones de denegación de seguridad, restricción de ruta del espacio de trabajo y un tiempo de espera configurable.

¿Necesito una versión especial de Chrome?

No. A diferencia de los enfoques basados en extensiones que requieren Chrome para Pruebas (ya que Chrome comercial 137+ deshabilitó la carga de extensiones), PicoClaw funciona con cualquier construcción de Chromium — incluyendo el Chromium empaquetado por Playwright, paquetes estándar de Chromium o Chrome headless. Esto es especialmente importante en dispositivos de borde donde quizás solo tenga acceso al Chromium empaquetado por el sistema.

¿Puede realmente ejecutarse PicoClaw en una placa de 10 dólares?

Sí. PicoClaw utiliza menos de 10MB de RAM y se inicia en menos de 1 segundo en un núcleo de 0,6GHz. Soporta RISC-V, ARM64 y x86_64. La API en la nube de CapSolver maneja el trabajo pesado; PicoClaw solo coordina. Nota: Chromium necesita 100-300MB de RAM, por lo tanto, placas con menos de 256MB deben conectarse a un navegador remoto.

¿Qué tipos de CAPTCHA soporta CapSolver?

CapSolver soporta reCAPTCHA v2 (casilla e invisible), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, AWS WAF CAPTCHA y más. La integración de PicoClaw usa ReCaptchaV2TaskProxyLess en el ejemplo, pero el archivo de habilidades documenta todos los tipos de tarea. El agente puede adaptarse a cualquier tipo de CAPTCHA soportado modificando el parámetro del tipo de tarea.

¿Puedo usar esto en un servidor headless?

Sí — y es donde el enfoque de PicoClaw brilla. Como no hay extensión de navegador involucrada, no necesita Xvfb ni una pantalla virtual. Playwright se ejecuta en modo headless completamente. Combinado con la pequeña huella de PicoClaw, esto lo hace ideal para despliegues de servidor siempre activos.

¿Cuánto cuesta CapSolver?

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

¿Es gratuito PicoClaw?

PicoClaw es de código abierto (licencia MIT) y gratuito para ejecutar en su propio hardware. Necesitará claves de API para el proveedor de modelo de inteligencia artificial de su elección y, para resolver CAPTCHAs, una cuenta de CapSolver con créditos. El binario de PicoClaw tiene costo cero en tiempo de ejecución.

¿Cuánto tiempo tarda en resolver CAPTCHAs?

En nuestra prueba de integración con un bot de Discord con reCAPTCHA v2, el script del agente de Playwright (incluyendo la consulta de la API de CapSolver) se ejecutó en 24,2 segundos. El tiempo total desde el mensaje de Discord hasta la respuesta fue de ~30 segundos, incluyendo 5 iteraciones de LLM para generación, ejecución y verificación visual del script.

¿Bloquearán los patrones de denegación de PicoClaw mis scripts de automatización?

No. Los patrones de denegación en pkg/tools/shell.go bloquean comandos peligrosos del sistema (rm -rf, sudo, docker run), no la ejecución regular de Node.js. Ejecutar node script.js y npm install local son totalmente permitidos. Solo se bloquean instalaciones globales (npm install -g) y comandos de gestión de paquetes.

¿Puedo ejecutar múltiples resoluciones de CAPTCHA en paralelo?

Sí. Use la herramienta spawn de PicoClaw para crear múltiples subagentes en segundo plano, cada uno manejando una tarea diferente de CAPTCHA. El SubagentManager (pkg/tools/subagent.go) ejecuta cada uno de forma independiente y reporta los resultados de vuelta a través del MessageBus.

¿Cómo se compara PicoClaw con Nanobot para resolver CAPTCHAs?

PicoClaw fue inspirado por Nanobot (Python), reescrito en Go para eficiencia extrema. Ambos usan resolución de CAPTCHA basada en agentes — la diferencia clave es en los recursos. Nanobot necesita 100MB+ de RAM y Python; PicoClaw necesita menos de 10MB y se entrega como un único binario. Para dispositivos de borde, PicoClaw es la elección clara.