Automação PicoClaw: Um Guia para a Integração da API CapSolver

Quando seu assistente de IA automatiza tarefas na web, os CAPTCHAs são o principal obstáculo. Páginas protegidas recusam-se a submeter, fluxos de login travam e toda a pipeline de automação para aguardando um humano clicar em uma caixa de seleção ou identificar semáforos.

PicoClaw é um assistente de IA pessoal extremamente leve escrito em Go que funciona em hardware de $10 com menos de 10MB de RAM. Ele se conecta às plataformas de mensagens que você já usa e inclui uma ferramenta exec integrada que permite ao agente escrever e executar scripts de forma autônoma.

CapSolver fornece uma API de resolução de CAPTCHA com inteligência artificial. Combinando as capacidades de execução de scripts do PicoClaw com a API REST do CapSolver, seu agente pode detectar CAPTCHAs, resolvê-los, injetar tokens e submeter formulários — tudo sem intervenção humana.

O melhor de tudo? Você apenas diz ao agente o que deseja fazer em linguagem simples. Ele escreve um script Playwright, extrai o sitekey, chama o CapSolver, injeta o token e submete o formulário — tudo de forma autônoma. E como o PicoClaw é compilado em Go, toda a camada de orquestração cabe dentro de 10MB de RAM em uma placa RISC-V de $10.

O que é PicoClaw?

PicoClaw é um assistente de IA pessoal extremamente leve construído em Go 1.25.7 por meio de um processo notável de auto-inicialização: o agente de IA conduziu toda a migração arquitetural do Python, produzindo 95% do código principal de forma autônoma com refinamento com humano no loop.

Os Números

O slogan do PicoClaw diz tudo: Hardware de $10. 10MB de RAM. 1 segundo de inicialização.

Principais Funcionalidades

• Extremamente leve: Menos de 10MB de uso de memória — 99% menor que agentes de TypeScript comparáveis
• Verdadeira portabilidade: Binário único em arquiteturas RISC-V, ARM64 e x86_64
• Ferramentas integradas: O agente pode ler/gravar arquivos, executar comandos de shell, pesquisar na web, buscar páginas, enviar mensagens entre canais, agendar tarefas cron e até interagir com periféricos de hardware I2C/SPI
• Independente de fornecedores: Funciona com OpenAI, Anthropic, DeepSeek, Gemini, Qwen, Moonshot, Groq, vLLM, Ollama, Cerebras, Mistral, NVIDIA e fornecedores de gateway como OpenRouter
• Sistema de habilidades: Amplie as capacidades com arquivos SKILL.md usando frontmatter JSON ou YAML
• Sistema de memória: Notas diárias e memória de longo prazo persistente entre conversas
• Ferramentas de hardware: Ferramentas I2C e SPI para interação direta com dispositivos embutidos — exclusivo do PicoClaw

O ExecTool

O ExecTool do PicoClaw (definido em pkg/tools/shell.go) é o que torna a automação do navegador possível. É um ambiente de execução de shell com sandbox cuidadosamente configurado com 27+ padrões de negação compilados como regexps do Go, timeout padrão de 60 segundos, restrição de caminho do workspace e detecção de tentativas de navegação de caminho.

Quando você pede ao agente para interagir com uma página da web, ele:

1. Escreve um script Playwright usando a ferramenta write_file
2. O executa usando a ferramenta exec (que chama sh -c no Linux)
3. Lê a saída (stdout + stderr, truncada para 10KB)
4. Relata os resultados de volta para você no canal de chat

O método guardCommand() do ferramenta verifica cada comando contra padrões de negação compilados antes da execução, aplica restrições de caminho do workspace e detecta tentativas de navegação de caminho. Pense nisso como acesso à linha de comando com sandbox — o agente pode executar scripts Node.js e instalações locais de pacotes, mas não pode fazer rm -rf, sudo ou docker run.

O Loop do Agente

A lógica central está em pkg/tools/toolloop.go — um ciclo apertado: Chamada de LLM -> Extração de Chamadas de Ferramentas -> Execução de Ferramentas -> Adição de Resultados -> repetir até uma resposta final de texto (ou MaxIterations, padrão 20). Este loop é compartilhado entre o agente principal (pkg/agent/loop.go) e subagentes de fundo via spawn.

O que é CapSolver?

CapSolver é um serviço líder de resolução de CAPTCHA que fornece soluções com inteligência artificial para contornar vários desafios de CAPTCHA. Com suporte para vários tipos de CAPTCHA e tempos de resposta rápidos, o CapSolver se integra perfeitamente em fluxos de trabalho automatizados.

Tipos de CAPTCHA Suportados

• reCAPTCHA v2 (baseado em imagem e invisível)
• reCAPTCHA v3 & v3 Enterprise
• Cloudflare Turnstile
• Cloudflare 5-second Challenge
• AWS WAF CAPTCHA

Por Que a Abordagem do PicoClaw é Diferente

A maioria das integrações de resolução de CAPTCHA cai em dois grupos: integração de API de nível de código onde você escreve uma classe de serviço dedicada, ou extensão do navegador onde uma extensão do Chrome lida com tudo invisivelmente. O PicoClaw adota uma terceira abordagem: integração de API guiada pelo agente em hardware de borda.

O próprio agente de IA orquestra todo o fluxo de resolução de forma autônoma — escrevendo um script Playwright, extraindo o sitekey, chamando a API do CapSolver e injetando o token de solução — tudo por meio de scripts que ele escreve e executa no momento. E, criticamente, o orquestrador baseado em Go que faz toda essa coordenação consome menos de 10MB de RAM.

A Vantagem dos Dispositivos de Borda

Você pode executar automação de quebra de CAPTCHA em hardware que custa menos que um café. Um LicheeRV-Nano de $9,90 executando o PicoClaw pode receber uma mensagem do Telegram, coordenar com a API da nuvem do CapSolver, injetar o token e submeter o formulário — tudo enquanto usa uma fração da memória de 64MB da placa. O trabalho pesado (reconhecimento de CAPTCHA) acontece nos servidores do CapSolver; o PicoClaw apenas orquestra. Sempre ligado, 24/7, em um dispositivo do tamanho de um selo.

A principal descoberta: O binário do Go do PicoClaw é tão leve que roda em hardware que a maioria dos frameworks nem consegue inicializar — mas pode orquestrar todo o pipeline de resolução de CAPTCHA por meio de scripts Playwright e da API REST do CapSolver.

Pré-requisitos

Nota: Os exemplos abaixo foram testados em Ubuntu 22.04 / 24.04. Os comandos usam apt e bash — ajuste conforme necessário para sua distribuição. Para dispositivos de borda (RISC-V, ARM), compile o PicoClaw em sua máquina de construção ou baixe um binário pré-construído na página de lançamentos.

Antes de configurar a integração, certifique-se de que você tem:

1. Ubuntu 22.04+ (ou qualquer distribuição Linux — o binário único do PicoClaw funciona em qualquer lugar)
2. Go 1.25.7+ instalado (necessário apenas para compilar a partir do código-fonte)
3. PicoClaw instalado e em execução (binário pré-construído ou make build)
4. Conta no CapSolver com chave de API (cadastre-se aqui)
5. Node.js 18+ instalado (para executar scripts Playwright via a ferramenta exec)
6. Playwright instalado no seu workspace

Configuração Passo a Passo

Passo 1: Instalar o PicoClaw

Opção A: Binário Pré-construído (Mais Rápido)

# Baixe a versão mais recente para sua plataforma
# Substitua v0.1.1 pela versão mais recente da página de Lançamentos
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

# Execute o assistente de onboarding interativo
picoclaw onboard

Opção B: Construir a partir do Código-fonte

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

# Inicialize a configuração e o workspace
picoclaw onboard

Isso cria ~/.picoclaw/config.json, ~/.picoclaw/workspace/ (scripts, habilidades e memória).

Passo 2: Definir a Chave de API do CapSolver

Adicione sua chave de API do CapSolver como variável de ambiente:

export CAPSOLVER_API_KEY="CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Você pode obter sua chave de API em seu painel do CapSolver.

Para configuração persistente, adicione-a ao ~/.bashrc ou ~/.zshrc.

Passo 3: Instalar Ferramentas de Automação de Navegador

Instale o Playwright e suas dependências do sistema no Ubuntu:

# Instale as dependências do navegador do Playwright (Ubuntu)
sudo apt install -y libnss3 libatk-bridge2.0-0 libdrm2 libxcomposite1 \
  libxdamage1 libxrandr2 libgbm1 libpango-1.0-0 libasound2t64

# Instale o Playwright no seu workspace do PicoClaw
cd ~/.picoclaw/workspace
npm init -y
npm install playwright
npx playwright install chromium

Nota sobre dispositivos de borda: Em placas com recursos limitados, você pode querer instalar o Chromium em uma máquina mais potente e apontar o PicoClaw para um navegador remoto via browserType.connect() do Playwright. O próprio agente do PicoClaw precisa apenas de ~10MB de RAM; o navegador é a parte pesada.

Passo 4: Configurar o ExecTool para Automação de Navegador

O ExecTool do PicoClaw tem padrões de negação integrados para segurança. Os padrões padrão funcionam bem para automação de CAPTCHA: node, npx e npm install locais são todos permitidos. Apenas comandos perigosos como npm install -g, sudo, docker run são bloqueados. Nenhuma alteração de configuração é necessária para o fluxo padrão.

Passo 5: Iniciar o Gateway

# Inicie os serviços de canal (Telegram, Discord, etc.)
picoclaw gateway

# Ou para teste interativo
picoclaw agent

Passo 6: Verificar a Configuração

Envie uma mensagem de teste ao seu agente por qualquer canal conectado:

Quais ferramentas você tem disponíveis?

O agente deve listar exec entre suas ferramentas — é com ela que ele executa scripts de automação do navegador. Você também pode verificar o acesso ao Node.js:

Execute: node --version

O agente deve executar isso via a ferramenta exec e retornar a versão do Node.js.

A Habilidade Integrada do CapSolver

O PicoClaw usa um sistema de habilidades baseado em arquivos SKILL.md com metadados de frontmatter. As habilidades são carregadas de três locais em ordem de prioridade (definida em pkg/skills/loader.go):

1. Habilidades do workspace: ~/.picoclaw/workspace/skills/{name}/SKILL.md (nível de projeto, maior prioridade)
2. Habilidades globais: ~/.picoclaw/skills/{name}/SKILL.md (nível de usuário)
3. Habilidades integradas: skills/{name}/SKILL.md (incluso no binário)

Habilidades do workspace substituem habilidades globais, que substituem habilidades integradas. O carregador lê o frontmatter como JSON ou YAML e constrói um resumo XML para o prompt do sistema.

O Arquivo de Habilidade (~/.picoclaw/workspace/skills/capsolver/SKILL.md)

---
name: capsolver
description: "Resolva CAPTCHAs usando a API REST do CapSolver com Playwright. Suporta reCAPTCHA v2, reCAPTCHA v3 e Cloudflare Turnstile. Use quando automatizar submissões de formulário ou interações de página que enfrentem desafios de CAPTCHA."
metadata: {"picoclaw":{"emoji":"🔓","always":true,"requires":{"bins":["node"],"env":["CAPSOLVER_API_KEY"]}}}
---

# CapSolver

## AVISO IMPORTANTE: EXECUÇÃO NECESSÁRIA

Quando um usuário pede que você resolva um CAPTCHA, você DEVE chamar uma ferramenta imediatamente. NÃO responda com texto como "Executando..." ou "Vou iniciar..." ou "Iniciei a automação...".

Sua primeira ação deve ser uma das seguintes:
1. Chame `write_file` para salvar um script Node.js, depois chame `exec` para executá-lo
2. Chame `spawn` com uma descrição detalhada da tarefa para execução em segundo plano

Se você responder apenas com texto e nenhuma chamada de ferramenta, o usuário verá que nada acontece. Sempre execute.

## Endpoints da API

- **Criar tarefa**: `POST https://api.capsolver.com/createTask`
- **Obter resultado**: `POST https://api.capsolver.com/getTaskResult`

## Tipos de Tarefa

| CAPTCHA | Tipo de Tarefa | Localização do Sitekey |
|---|---|---|
| reCAPTCHA v2 | `ReCaptchaV2TaskProxyLess` | atributo `data-sitekey` |
| reCAPTCHA v3 | `ReCaptchaV3TaskProxyLess` | chamada `grecaptcha.execute` ou fonte da página |
| Cloudflare Turnstile | `AntiTurnstileTaskProxyLess` | `data-sitekey` no div do Turnstile |

Variantes empresariais: `ReCaptchaV2EnterpriseTaskProxyLess`, `ReCaptchaV3EnterpriseTaskProxyLess`.

## Fluxo de Trabalho

1. Navegue até a página com Playwright (Chromium headless)
2. Extraia o sitekey do DOM (`[data-sitekey]` attribute)
3. Chame `createTask` com o sitekey e URL da página
4. Consulte `getTaskResult` a cada 2 segundos até `status: "ready"`
5. Injete o token na página (campo oculto do formulário)
6. Submeta o formulário

## Padrão de Código Principal

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

// Etapa 1: Criar tarefa
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',  // ou ReCaptchaV3TaskProxyLess, AntiTurnstileTaskProxyLess
      websiteURL: pageUrl,
      websiteKey: siteKey
    }
  })
});
const { taskId } = await createRes.json();

// Etapa 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('Solve failed');
}

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

Para Turnstile, o campo do token geralmente é `input[name="cf-turnstile-response"]` e a solução está em `result.solution.token`.

## Referência da API

Todos os tipos de tarefa exigem `type`, `websiteURL`, `websiteKey`. Os campos opcionais variam por tipo:
- **reCAPTCHA v2**: `isInvisible`, `pageAction`, `enterprisePayload`, `apiDomain`
- **reCAPTCHA v3**: `pageAction` (de `grecaptcha.execute(key, {action: "..."})`)
- **Cloudflare Turnstile**: `metadata.action`, `metadata.cdata`

Pontos-chave:

• Frontmatter usa JSON ou YAML (pkg/skills/loader.go tenta JSON primeiro, cai para YAML)
• metadata contém configuração específica do PicoClaw: emoji para exibição, always para carregar automaticamente, requires para verificações de dependência
• SkillsLoader.BuildSkillsSummary() gera resumos XML injetados no prompt do sistema
• A seção "Execution Required" força chamadas de ferramentas em vez de respostas apenas de texto

Após criar a habilidade, verifique com picoclaw skills — você deve ver capsolver listado.

Como Funciona

Quando você pede ao PicoClaw para interagir com uma página protegida por CAPTCHA, aqui está o fluxo completo da mensagem ao resultado:

  Sua mensagem                     Agente PicoClaw (Go, ~10MB de RAM)
  ─────────────────────────────────────────────────────────────
  "Vá para essa página,           ──► Agente recebe via MessageBus
   preencha o formulário,                │ (pkg/bus/bus.go)
   resolva o captcha,                ▼
   e envie-o"             ContextBuilder injeta habilidades
                                   │ (pkg/agent/context.go)
                                   ▼
                              RunToolLoop inicia
                                   │ (pkg/tools/toolloop.go)
                                   ▼
                              Agente escreve script Node.js
                                   │ via ferramenta write_file
                                   ▼
                              ExecTool executa o script
                              ┌────────────────────────────┐
                              │ pkg/tools/shell.go          │
                              │ guardCommand() → 27+ verificações │
                              │ sh -c "node script.js"      │
                              │                             │
                              │  Chromium em modo sem cabeça         │
                              │  1. Navegue até a página        │
                              │  2. Extraia o sitekey         │
                              │  3. POST /createTask ────────── API CapSolver
                              │  4. Poll /getTaskResult ─────── (nuvem)
                              │  5. Injete o token            │
                              │  6. Submeta o formulário      │
                              │  7. Captura de tela           │
                              └────────────────────────────┘
                                   │
                                   ▼ stdout retornado (máx. 10KB)
                              Agente lê o output
                                   │
                                   ▼
                              "Formulário enviado com sucesso!
                               Sucesso na verificação!"

Fluxo da API CapSolver

O núcleo da integração são duas chamadas de API:

1. Criar uma tarefa — Envie o sitekey e a URL da página para o 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. Verificar o resultado — Verifique a cada 2 segundos até o CapSolver retornar o token resolvido:

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 contém o token

3. Injetar o token — Defina-o no campo oculto do formulário que o reCAPTCHA espera:

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

Exemplo Completo Funcional

Aqui está o script Node.js real que o agente do PicoClaw gera e executa para resolver reCAPTCHA na página de demonstração do Google. O agente escreve isso via write_file, depois o executa com exec — tudo de forma autônoma a partir de uma única mensagem no 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('Criando tarefa no 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(`Erro no CapSolver: ${createRes.errorDescription}`);
  }

  const { taskId } = createRes;
  console.log(`ID da tarefa: ${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 recebido! Comprimento: ${token.length}`);
      break;
    }
    if (res.status === 'failed') {
      throw new Error(`Tarefa do CapSolver falhou: ${res.errorDescription}`);
    }

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

  if (!token) throw new Error('Falha ao obter 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') ? 'SUCESSO!' : 'Resultado:', body.slice(0, 200));
    await page.screenshot({ path: 'recaptcha_result.png' });
  } finally {
    await browser.close();
  }
}

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

Execute-o diretamente:

CAPSOLVER_API_KEY=CAP-XXX node solve_recaptcha.js

Ou deixe o agente do PicoClaw lidar com tudo — apenas envie uma mensagem no Telegram:

Resolva o reCAPTCHA em https://example.com e envie o formulário.

O agente lê sua habilidade capsolver, escreve o script, o executa via exec, lê o resultado e relata de volta.

Como Usar

Após a configuração, usar o CapSolver com o PicoClaw é tão simples quanto enviar uma mensagem em qualquer canal conectado.

Exemplo 1: Resolver um Demo de reCAPTCHA

Envie isso para seu agente via Telegram, Discord, WhatsApp ou qualquer canal conectado:

Vá para https://example.com e resolva o reCAPTCHA usando a API do CapSolver, depois envie o formulário e me diga se funcionou.

O que acontece: O agente lê a habilidade capsolver, escreve um script Playwright, o executa via exec (que passa pelas verificações guardCommand() e o executa com um timeout de 60s), e o script navega pela página, extrai o sitekey, chama o CapSolver, injeta o token e envia. O resultado volta para você através do MessageBus.

Exemplo 2: Fazer login em um site protegido

Vá para https://example.com/login, preencha o email com
"me@example.com" e a senha com "mypassword", detecte e
resolva qualquer CAPTCHA na página, depois clique em Entrar e me diga
o que acontece.

Exemplo 3: Enviar um formulário de contato

Abra https://example.com/contact, preencha os campos de nome, email e
mensagem, resolva o CAPTCHA, envie o formulário e me diga a mensagem de confirmação.

Exemplo 4: Automação em segundo plano via Spawn

Para tarefas mais longas, use a ferramenta spawn (pkg/tools/spawn.go) para delegar para um subagente em segundo plano:

Em segundo plano, vá para https://example.com/register, crie
uma conta com meus dados, resolva qualquer CAPTCHA que encontrar,
e me avise quando estiver pronto.

Exemplo 5: Monitoramento de dispositivos de borda (Telegram em uma placa de $10)

Se o PicoClaw estiver rodando em um dispositivo de borda como LicheeRV-Nano, combine com a ferramenta cron:

A cada hora, verifique https://example.com/status — se houver um
portão de CAPTCHA, resolva-o e relate o conteúdo da página de status.

Por que isso funciona

O agente do PicoClaw tem todas as ferramentas necessárias para resolver CAPTCHA de forma autônoma:

• exec (pkg/tools/shell.go) — execução de shell com 27+ padrões de segurança
• write_file / read_file (pkg/tools/filesystem.go) — gerenciamento de scripts no workspace
• spawn (pkg/tools/spawn.go) — delegação para subagentes em segundo plano para tarefas longas
• web_fetch (pkg/tools/web.go) — busca de conteúdo de página para análise do DOM
• Sistema de habilidades (pkg/skills/loader.go) — a habilidade capsolver fornece documentação da API no contexto
• Memória (pkg/agent/memory.go) — persiste abordagens bem-sucedidas entre sessões

Resultados de Desempenho

Testamos a integração na página de demonstração do reCAPTCHA v2 do Google via um bot do Discord no Ubuntu 24.04. O agente PicoClaw (usando glm-4.7 via z.ai) recebeu uma mensagem do Discord, escreveu um script Playwright, resolveu o CAPTCHA e relatou de volta — tudo sem intervenção humana:

Nota sobre dispositivos de borda: Em placas com RAM limitada (ex: LicheeRV-Nano de $9,90 com 64MB), o PicoClaw cabe facilmente (~8MB), mas o Chromium precisa de 100-300MB. Use connect() do Playwright para transferir o navegador para uma máquina mais capaz, mantendo o agente leve no dispositivo de borda.

Solução de Problemas

"Não foi possível encontrar o módulo 'playwright'"

O Playwright não está instalado no workspace. Execute:

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

Bibliotecas de navegador ausentes no Ubuntu

Se o Chromium falhar ao iniciar com erros sobre bibliotecas compartilhadas ausentes, instale as dependências do sistema:

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

Padrões de negação do ExecTool bloqueando o npm install

Os padrões de negação do PicoClaw bloqueiam npm install -g (instalações globais), sudo e apt install, mas permitem npm install local, node script.js e npx playwright install. Se você ver "Comando bloqueado pelo guardião de segurança", pode desativar os padrões de negação ou fornecer uma lista de permissões personalizada em ~/.picoclaw/config.json:

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

Ou use uma lista de permissões personalizada que exclua apenas os padrões que você deseja bloquear.

Tempo limite de resolução de CAPTCHA

• Verifique se sua chave da API do CapSolver é válida
• Verifique seu saldo na conta do CapSolver em capsolver.com/dashboard
• O script verifica a cada 2 segundos até o CapSolver retornar ready ou failed
• Se o timeout de 60 segundos do exec for insuficiente, o script será finalizado. Pode aumentá-lo programaticamente ou usar a ferramenta spawn para tarefas mais longas (subagentes têm seu próprio timeout)

Timeout de 60 segundos do ExecTool muito curto

O timeout padrão em pkg/tools/shell.go é de 60 segundos. Para automação de CAPTCHA, isso pode ser apertado. Use a ferramenta spawn para tarefas mais longas (subagentes rodam independentemente), ou modifique o timeout em NewExecToolWithConfig() no código-fonte (timeout: 120 * time.Second).

Sitekey não encontrado

O script extrai o sitekey do atributo data-sitekey. Se nenhum elemento for encontrado, o agente pode se adaptar e extrair do URL do iframe ou da fonte da página.

Falha no navegador em Docker/container

Adicione --no-sandbox, --disable-setuid-sandbox e --disable-dev-shm-usage aos argumentos de lançamento do Playwright.

O agente não usa o CapSolver

Verifique: (1) a variável de ambiente CAPSOLVER_API_KEY está definida antes de iniciar o PicoClaw, (2) o arquivo de habilidade existe em ~/.picoclaw/workspace/skills/capsolver/SKILL.md, (3) picoclaw skills mostra-o listado.

Boas Práticas

1. Defina a chave da API como variável de ambiente

Não deixe a chave codificada nos scripts. Use process.env.CAPSOLVER_API_KEY para que o agente a encontre automaticamente. O PicoClaw passa o ambiente do processo pai para todas as invocações da ferramenta exec.

2. Use o modo sem cabeça em servidores

O método baseado em API do PicoClaw funciona em ambientes completamente sem cabeça — nenhum Xvfb ou tela virtual é necessário. Isso é uma vantagem significativa em comparação com abordagens baseadas em extensões, especialmente em dispositivos de borda onde o hardware de tela não existe.

3. Monitore seu saldo no CapSolver

Cada resolução de CAPTCHA custa créditos. Verifique seu saldo regularmente em capsolver.com/dashboard.

4. Mantenha o Playwright atualizado

Os provedores de CAPTCHA evoluem. Mantenha o Playwright e o Chromium atualizados:

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

5. Use a ferramenta Spawn para tarefas longas

A automação do navegador pode demorar 30-60 segundos. Use spawn em vez de depender do loop principal do agente para evitar timeouts e manter o agente principal respondendo a outras mensagens.

6. Aproveite o sistema de memória do PicoClaw

Após uma resolução bem-sucedida de CAPTCHA, o agente salva a abordagem em ~/.picoclaw/workspace/memory/MEMORY.md. Na próxima vez, ele lembrará do padrão exato que funcionou.

7. Implantação em dispositivos de borda: Desligue o navegador

Em placas de $10 com RAM limitada, conecte-se a uma instância remota do Chromium via chromium.connect('ws://server:9222'). Isso mantém o footprint de ~8MB do PicoClaw na borda enquanto o navegador roda em outro lugar.

8. Configure com cuidado a restrição do espaço de trabalho

A configuração restrict_to_workspace do PicoClaw limita operações de arquivo e execução ao diretório do espaço de trabalho. Certifique-se de que seus scripts e instalação do Playwright estejam dentro de ~/.picoclaw/workspace/.

Conclusão

A integração PicoClaw + CapSolver representa uma abordagem fundamentalmente diferente para resolução de CAPTCHA. Em vez de extensões de navegador pesadas em máquinas desktop, um agente compilado em Go executando em hardware de $10 coordena todo o fluxo de resolução:

1. Navegue até a página de destino com Playwright
2. Extraia o sitekey da atributo data-sitekey
3. Resolva chamando diretamente a API REST do CapSolver
4. Injete o token de solução no campo de formulário oculto
5. Envie o formulário e verifique o sucesso

Isso oferece a você:

• Nenhuma dependência de extensão do Chrome — funciona com qualquer navegador headless
• Suporte a servidor headless — não é necessário display ou Xvfb
• Controle em linguagem natural — basta dizer ao agente o que deseja fazer via Telegram, Discord ou qualquer um dos 12 canais ou mais
• Implantação em dispositivos de borda — execute 24/7 em uma placa RISC-V de $10 com menos de 10MB de RAM
• Segurança por padrão — 27+ padrões de negação no ExecTool impedem comandos perigosos

Bônus: Script de Início Rápido

Salve o exemplo funcional completo acima em ~/.picoclaw/workspace/solve_captcha.js e execute:

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

Ou simplesmente envie uma mensagem do Telegram ao seu agente PicoClaw e deixe-o lidar com tudo de forma autônoma.

Pronto para começar? Registre-se no CapSolver e use o código promocional PICOCLAW para obter um bônus extra de 6% na primeira recarga!

Perguntas Frequentes

Como o PicoClaw resolve CAPTCHAs de forma diferente das extensões de navegador?

O PicoClaw usa diretamente a API REST do CapSolver. O agente escreve e executa scripts Node.js/Playwright que chamam createTask e getTaskResult para obter tokens de solução, depois os injeta no DOM da página. Nenhuma extensão de navegador é necessária. A toda a orquestração acontece através do ExecTool do PicoClaw (pkg/tools/shell.go), que executa sh -c "node script.js" com 27+ padrões de negação, restrição de caminho do espaço de trabalho e um tempo limite configurável.

Preciso de uma versão especial do Chrome?

Não. Ao contrário de abordagens baseadas em extensões que exigem Chrome para Testes (já que o Chrome com marca registrada 137+ desativou o carregamento de extensões), o PicoClaw funciona com qualquer build do Chromium — incluindo o Chromium embutido no Playwright, pacotes padrão do Chromium ou Chrome headless. Isso é especialmente importante em dispositivos de borda onde você pode ter acesso apenas ao Chromium pacotado pela distribuição.

O PicoClaw realmente pode rodar em uma placa de $10?

Sim. O PicoClaw usa menos de 10MB de RAM e inicia em menos de 1 segundo em um núcleo de 0,6GHz. Ele suporta RISC-V, ARM64 e x86_64. A API em nuvem do CapSolver lida com o trabalho pesado; o PicoClaw apenas coordena. Observação: o Chromium precisa de 100-300MB de RAM, então placas com menos de 256MB devem se conectar a um navegador remoto.

Quais tipos de CAPTCHA o CapSolver suporta?

O CapSolver suporta reCAPTCHA v2 (checkbox e invisível), reCAPTCHA v3, reCAPTCHA Enterprise, Cloudflare Turnstile, AWS WAF CAPTCHA e mais. A integração do PicoClaw usa ReCaptchaV2TaskProxyLess no exemplo, mas o arquivo de habilidades documenta todos os tipos de tarefa. O agente pode se adaptar a qualquer tipo de CAPTCHA suportado modificando o parâmetro de tipo de tarefa.

Posso usar isso em um servidor headless?

Sim — e é aí que a abordagem do PicoClaw brilha. Como não há extensão de navegador envolvida, você não precisa de Xvfb ou de uma tela virtual. O Playwright roda no modo totalmente headless por padrão. Combinado com o footprint mínimo do PicoClaw, isso o torna ideal para implantações sempre ligadas em servidores.

Quanto custa o CapSolver?

O CapSolver oferece preços competitivos com base no tipo de CAPTCHA e no volume. Visite capsolver.com para ver os preços atuais. Use o código promocional PICOCLAW para obter 6% extra na sua primeira recarga.

O PicoClaw é gratuito?

O PicoClaw é de código aberto (licença MIT) e gratuito para executar em seu próprio hardware. Você precisará de chaves de API para o provedor de modelo de IA de sua escolha e, para resolução de CAPTCHA, uma conta no CapSolver com créditos. O binário do PicoClaw não tem custo de execução.

Quanto tempo leva para resolver CAPTCHA?

Em nosso teste de integração com o bot do Discord com reCAPTCHA v2, o script do Playwright do agente (incluindo a verificação da API do CapSolver) foi executado em 24,2 segundos. O tempo total do início ao fim, desde a mensagem do Discord até a resposta, foi de ~30 segundos, incluindo 5 iterações da LLM para geração, execução e verificação visual do script.

Os padrões de negação do PicoClaw bloquearão meus scripts de automação?

Não. Os padrões de negação em pkg/tools/shell.go bloqueiam comandos perigosos do sistema (rm -rf, sudo, docker run), não a execução regular do Node.js. Executar node script.js e npm install local são totalmente permitidos. Apenas instalações globais (npm install -g) e comandos de gerenciamento de pacotes são bloqueados.

Posso executar várias resoluções de CAPTCHA em paralelo?

Sim. Use a ferramenta spawn do PicoClaw para criar múltiplos subagentes em segundo plano, cada um lidando com uma tarefa diferente de CAPTCHA. O SubagentManager (pkg/tools/subagent.go) executa cada um independentemente e relata os resultados de volta através do MessageBus.

Como o PicoClaw se compara ao Nanobot para resolução de CAPTCHA?

O PicoClaw foi inspirado no Nanobot (Python), reescrito em Go para eficiência extrema. Ambos usam resolução de CAPTCHA baseada em agentes — a principal diferença é os recursos. O Nanobot precisa de 100MB+ de RAM e Python; o PicoClaw precisa de menos de 10MB e vem como um único binário. Para dispositivos de borda, o PicoClaw é a escolha clara.