Como resolver Captcha no Nanobot com CapSolver

Quando seu assistente de IA automatiza tarefas na web, os CAPTCHAs são o principal obstáculo. Páginas protegidas não submetem, fluxos de login travam e todo o loop de automação para de funcionar esperando por um humano.

Nanobot é um framework de assistente de IA pessoal ultra-leve que você pode executar em seu próprio hardware. Ele se conecta aos canais que você já usa — WhatsApp, Telegram, Discord, Slack, Email, entre outros — e vem com 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 baseada em IA. Ao combinar as capacidades de execução de scripts do Nanobot com a API REST do CapSolver, seu agente pode detectar CAPTCHAs, resolvê-los, injetar tokens e submeter formulários — sem intervenção humana.

A melhor parte? Você apenas diz ao agente o que deseja fazer em linguagem comum. Ele escreve um script Playwright, extrai o sitekey, chama o CapSolver, injeta o token e submete o formulário — tudo de forma autônoma.

O que é o Nanobot?

Nanobot é um framework de assistente de IA pessoal em ~3.500 linhas de código Python principal. Foi projetado para ser leve, extensível e auto-hospedado.

Principais Funcionalidades

• Caixa de entrada multicanal: Converse com seu AI por WhatsApp, Discord, Telegram, Slack, Email, QQ e mais
• Ferramentas integradas: O agente pode ler/gravar arquivos, executar comandos de shell, pesquisar na web, buscar páginas, enviar mensagens entre canais e criar tarefas em segundo plano
• Independente de provedor: Funciona com Anthropic, OpenAI, DeepSeek, Gemini, Qwen, Moonshot, Zhipu, Groq, vLLM e provedores de gateway como OpenRouter
• Primeiro local: Roda em seu próprio hardware — seus dados ficam com você
• Sistema de memória: Notas diárias e memória de longo prazo que persiste entre conversas
• Sistema de habilidades: Estenda com habilidades embaladas ou personalizadas para tarefas especializadas

A Ferramenta exec

A ferramenta exec do Nanobot é o que torna a automação do navegador possível. O agente pode executar qualquer comando de shell, incluindo scripts Node.js que controlam um navegador headless. Quando você pede ao agente para interagir com uma página da web, ele:

1. Escreve um script Playwright
2. Executa-o via a ferramenta exec
3. Lê a saída e as capturas de tela
4. Relata os resultados de volta para você no seu canal de chat

Pense nisso como dar acesso total ao terminal para seu assistente de IA — ele pode instalar ferramentas, escrever scripts e executá-los, tudo a partir de uma instrução em linguagem natural.

O que é o CapSolver?

CapSolver é um serviço líder de resolução de CAPTCHA que fornece soluções baseadas em IA para contornar diversos desafios de CAPTCHA. Com suporte a 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 e v3 Enterprise
• Cloudflare Turnstile
• Cloudflare 5-second Challenge
• AWS WAF CAPTCHA
• Outros mecanismos de anti-bot amplamente utilizados

Por Que a Abordagem do Nanobot é Diferente

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

O agente de IA coordena todo o fluxo de resolução de forma autônoma — escrevendo um script Playwright, extraíndo o sitekey, chamando a API do CapSolver e injetando o token de solução — tudo por meio de scripts que ele escreve e executa em tempo real.

A principal descoberta: O agente do Nanobot não precisa de uma extensão de navegador porque pode chamar programaticamente a API do CapSolver, extrair o sitekey do DOM da página e injetar o token de solução — tudo por meio de scripts Playwright que ele executa via ferramenta exec. Isso funciona em ambientes totalmente headless sem nenhuma configuração de tela.

Pré-requisitos

Nota: Os exemplos abaixo foram testados em Ubuntu 22.04 / 24.04. Os comandos usam apt e bash — ajuste conforme sua distro, se necessário.

Antes de configurar a integração, certifique-se de ter:

1. Ubuntu 22.04+ (ou qualquer Linux baseado em Debian — outras distros funcionam com pacotes equivalentes)
2. Python 3.11+ instalado (sudo apt install python3 python3-pip python3-venv)
3. Nanobot instalado e em execução (pip install nanobot-ai ou pip install -e ".[dev]")
4. Uma conta no CapSolver com chave de API (inscreva-se aqui)
5. Node.js 18+ instalado (para executar scripts Playwright)
6. Playwright instalado no seu ambiente de trabalho

Configuração Passo a Passo

Passo 1: Instalar o Nanobot

# Instalar do PyPI
pip install nanobot-ai

# Ou instalar do código-fonte para desenvolvimento
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e ".[dev]"

# Inicializar configuração e ambiente de trabalho
nanobot onboard

Passo 2: Definir sua Chave de API do CapSolver

Adicione sua chave de API do CapSolver como uma 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 seu perfil de shell (~/.bashrc ou ~/.zshrc).

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

Instale o Playwright e suas dependências no Ubuntu:

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

# Instalar o Playwright no seu ambiente de trabalho do nanobot
cd ~/.nanobot/workspace
npm init -y
npm install playwright
npx playwright install chromium

Passo 4: Iniciar o Gateway

# Iniciar os serviços de canal (Telegram, Discord, etc.)
nanobot gateway

# Ou para testes interativos
nanobot agent

Passo 5: Verificar a Configuração

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

Quais ferramentas você tem disponíveis?

O agente deve listar exec entre suas ferramentas — é essa que ele usa para executar scripts de automação do navegador.

A Habilidade Integrada do CapSolver

O Nanobot inclui uma habilidade integrada do capsolver que é sempre carregada no prompt do sistema do agente. Isso significa que, em cada mensagem, o agente já tem os documentos corretos da API do CapSolver, tipos de tarefa, padrões de código e instruções de execução em seu contexto — ele nunca precisa adivinhar ou procurar.

Como Funcionam as Habilidades no Nanobot

Habilidades são arquivos markdown em nanobot/skills/{name}/SKILL.md com frontmatter YAML. Quando always: true é definido nos metadados, o conteúdo completo da habilidade é injetado automaticamente no prompt do sistema do agente. O agente não precisa chamar read_file — ele simplesmente sabe.

O Arquivo de Habilidade (nanobot/skills/capsolver/SKILL.md)

Para instalar a habilidade, crie o arquivo nanobot/skills/capsolver/SKILL.md com este conteúdo:

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

# CapSolver

## IMPORTANTE: Execução Necessária

Quando um usuário pede que você resolva um CAPTCHA, você DEVE chamar imediatamente uma ferramenta. 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. Chamar `write_file` para salvar um script Node.js, depois chamar `exec` para executá-lo
2. Chamar `spawn` com uma descrição detalhada da tarefa para execução em segundo plano

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

## Pontos de 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 Turnstile |

Variantes empresariais: `ReCaptchaV2EnterpriseTaskProxyLess`, `ReCaptchaV3EnterpriseTaskProxyLess`.

## Fluxo de Trabalho

1. Navegue até a página com o Playwright (Chromium headless)
2. Extraia o sitekey do DOM (`[data-sitekey]`)
3. Chame `createTask` com o sitekey e a URL da página
4. Consulte `getTaskResult` a cada 2 segundos até que o status seja "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;

// Passo 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();

// Passo 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('Resolução falhou');
}

// Passo 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 Completa da API

Veja `{baseDir}/references/api.md` para documentação completa dos parâmetros, campos opcionais e exemplos de respostas para todos os tipos de tarefa.

Pontos-chave:

• A flag always: true garante que essa habilidade seja carregada em cada conversa — o agente sempre tem os documentos da API na memória
• O campo requires verifica se o node está instalado e se a CAPSOLVER_API_KEY está definida
• A seção "Execução Necessária" impede que o agente apenas descreva o que faria — força chamadas reais às ferramentas

Referência da API (references/api.md)

A habilidade também inclui uma referência completa da API que o agente pode ler sob demanda para obter detalhes sobre os parâmetros. Aqui está o que ela abrange:

reCAPTCHA v2

Parâmetros obrigatórios: type, websiteURL, websiteKey

Parâmetros opcionais: isInvisible (Booleano), pageAction (String), recaptchaDataSValue (String), enterprisePayload (Objeto), apiDomain (String)

{
  "clientKey": "SUA_CHAVE_DE_API",
  "task": {
    "type": "ReCaptchaV2TaskProxyLess",
    "websiteURL": "https://www.google.com/recaptcha/api2/demo",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-",
    "isInvisible": false
  }
}

Token de resposta: solution.gRecaptchaResponse → injete em textarea[name="g-recaptcha-response"]

reCAPTCHA v3

Parâmetros obrigatórios: type, websiteURL, websiteKey

Parâmetros opcionais: pageAction (String — de grecaptcha.execute(key, {action: "..."}), valores comuns: login, submit, homepage), enterprisePayload (Objeto), apiDomain (String)

{
  "clientKey": "SUA_CHAVE_DE_API",
  "task": {
    "type": "ReCaptchaV3TaskProxyLess",
    "websiteURL": "https://www.example.com",
    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_kl-",
    "pageAction": "login"
  }
}

Token de resposta: solution.gRecaptchaResponse → injete em textarea[name="g-recaptcha-response"]

Cloudflare Turnstile

Parâmetros obrigatórios: type (AntiTurnstileTaskProxyLess), websiteURL, websiteKey

Parâmetros opcionais: metadata.action (String — de data-action), metadata.cdata (String — de data-cdata)

{
  "clientKey": "SUA_CHAVE_DE_API",
  "task": {
    "type": "AntiTurnstileTaskProxyLess",
    "websiteURL": "https://www.example.com",
    "websiteKey": "0x4XXXXXXXXXXXXXXXXX",
    "metadata": {
      "action": "login",
      "cdata": "0000-1111-2222-3333-exemplo-cdata"
    }
  }
}

Token de resposta: solution.token → injete em input[name="cf-turnstile-response"]

Tempos Típicos de Resolução

                         │  3. Chamar a API REST do CapSolver:     │
                         │     POST /createTask             │
                         │     POST /getTaskResult (poll)   │
                         │                                  │
                         │  4. Injetar o token em campos      │
                         │     de texto/entrada ocultos     │
                         │                                  │
                         │  5. Clicar em Enviar             │
                         │  6. Verificar sucesso             │
                         │  7. Tirar capturas de tela        │
                         └─────────────────────────────────┘
                              │
                              ▼
                         O agente lê a saída e as capturas de tela
                              │
                              ▼
                         "Formulário enviado com sucesso!
                          A página mostra: Verificação
                          Sucesso... Hooray!"

O Fluxo da API do CapSolver

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

1. Criar uma tarefa — Envie a chave do site CAPTCHA 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é que o CapSolver retorne 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 real que o agente Nanobot gerou e executou para resolver o reCAPTCHA na página de demonstração do Google. O agente escreveu este script via write_file, depois o executou com exec — tudo de forma autônoma a partir de uma única mensagem no Discord:

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

const CAPSOLVER_API_KEY = process.env.CAPSOLVER_API_KEY;
const PAGE_URL = 'https://www.google.com/recaptcha/api2/demo';

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
    }
  });

  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');
    }
  }

  if (!token) throw new Error('Falha em obter o token');
  return token;
}

async function main() {
  const browser = await chromium.launch({ headless: true });
  const page = await browser.newPage();

  console.log('Navegando para a página...');
  await page.goto(PAGE_URL, { waitUntil: 'domcontentloaded', timeout: 30000 });

  console.log('Extraindo sitekey...');
  const siteKey = await page.locator('[data-sitekey]').getAttribute('data-sitekey');
  console.log(`Sitekey: ${siteKey}`);

  console.log('Resolvendo reCAPTCHA com o Capsolver...');
  const token = await solveRecaptcha(siteKey, PAGE_URL);

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

  console.log('Submetendo o formulário...');
  await page.locator('input[type="submit"]').click();

  console.log('Aguardando o resultado...');
  await page.waitForTimeout(3000);

  const successText = await page.textContent('body');
  if (successText.includes('Success') || successText.includes('Verification')) {
    console.log('\n✅ SUCESSO! reCAPTCHA resolvido e formulário enviado com sucesso!');
    console.log('Mensagem de sucesso:', successText.slice(0, 200));
  } else {
    console.log('\n❌ Resultado ambíguo. Conteúdo da página:', successText.slice(0, 300));
  }

  await page.screenshot({ path: 'recaptcha_result.png' });
  console.log('Captura de tela salva em recaptcha_result.png');

  await browser.close();
}

main().catch(console.error);

Execute-o:

CAPSOLVER_API_KEY=CAP-XXX node solve_recaptcha.js

Como Usar com o Nanobot

Após a configuração, usar o CapSolver com o Nanobot é tão simples quanto enviar uma mensagem.

Exemplo 1: Resolver um reCAPTCHA de Demonstração

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

Vá para https://www.google.com/recaptcha/api2/demo e resolva
o reCAPTCHA usando a API do CapSolver, depois submeta o formulário
e me diga se funcionou.

O que acontece:

1. O agente escreve um script Playwright
2. O script navega até a página e extrai a chave do reCAPTCHA do DOM
3. Ele chama a API createTask do CapSolver com a chave
4. Ele verifica a getTaskResult a cada 2 segundos até que o token esteja pronto (~18 segundos)
5. Ele injeta o token no campo oculto g-recaptcha-response
6. Ele clica em Enviar e verifica o sucesso
7. O agente relata de volta: "Formulário enviado com sucesso! A página mostra: Verificação Sucesso... Hooray!"

Exemplo 2: Entrar em um site protegido

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

Exemplo 3: Submeter um formulário de contato

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

Por que isso funciona

Porque o agente do Nanobot possui:

• Ferramenta exec — executa qualquer comando de shell, incluindo scripts Node.js
• Ferramenta web_fetch — busca conteúdo da página para entender a estrutura da página
• Ferramentas de arquivo — pode escrever, editar e ler scripts de automação
• Memória — lembra abordagens funcionais para tarefas futuras
• Habilidade integrada capsolver — sempre carregada no contexto do agente (veja A Habilidade Integrada do CapSolver acima), inclui tipos de tarefa, padrões de código, referência da API e instruções de execução que garantem que o agente escreva e execute scripts, em vez de apenas descrever o que faria

Recompensar Erros de Hallucinação: Garantindo que o Agente Atue

Um desafio com agentes baseados em LLM é que alguns modelos respondem com textos como "Executando a automação agora..." sem chamar nenhuma ferramenta. O usuário vê uma mensagem que parece progresso, mas nada acontece no fundo.

O Nanobot resolve isso com um mecanismo de retry de alucinação integrado ao loop do agente. Quando o LLM responde com texto na primeira iteração e esse texto contém frases de ação como "executando agora", "comecei", ou "executando agora" — mas não fez nenhuma chamada de ferramenta — o Nanobot detecta isso e envia automaticamente um prompt de correção:

"Você descreveu iniciar uma tarefa, mas não chamou nenhuma ferramenta. O usuário não pode ver seu progresso a menos que você use ferramentas como exec, write_file ou spawn. Por favor, chame a ferramenta apropriada agora."

O LLM tenta novamente e chama a ferramenta real (ex: spawn para iniciar uma tarefa de automação em segundo plano). Isso acontece de forma transparente — o usuário apenas vê os resultados chegarem alguns segundos depois.

Isso é um recursos geral do nanobot que melhora a confiabilidade para todas as tarefas que usam ferramentas, não apenas para resolver CAPTCHAs.

Alterações Recomendadas no Código

Para habilitar o retry de alucinação e outras melhorias de confiabilidade, aplique estas três mudanças na sua instalação do Nanobot:

1. Retry de Alucinação (nanobot/agent/loop.py)

No método _process_message, substitua a ramificação else que lida com respostas sem chamadas de ferramentas:

            else:
                # Nenhuma chamada de ferramenta — mas verifique se o LLM teve alucinação
                if iteration == 1 and self._seems_like_hallucinated_action(response.content):
                    logger.warning("LLM descreveu ação sem chamadas de ferramentas — retrying com correção")
                    messages.append({"role": "assistant", "content": response.content})
                    messages.append({
                        "role": "user",
                        "content": (
                            "[System: Você descreveu iniciar uma tarefa, mas não chamou nenhuma ferramenta. "
                            "O usuário não pode ver seu progresso a menos que você use ferramentas como exec, "
                            "write_file ou spawn. Por favor, chame a ferramenta apropriada agora para "
                            "realmente executar a tarefa.]"
                        ),
                    })
                    continue
                final_content = response.content
                break

E adicione este método de detecção à classe AgentLoop:

    @staticmethod
    def _seems_like_hallucinated_action(content: str | None) -> bool:
        """Detecta se o LLM descreveu uma ação sem chamar ferramentas."""
        if not content:
            return False
        lower = content.lower()
        phrases = [
            "executando agora", "eu comecei", "vou começar", "iniciando a",
            "eu comecei", "vou iniciar", "executando agora", "estou trabalhando em",
            "deixe-me executar", "executando a", "eu iniciei", "lançando a",
            "eu iniciei", "trabalhando nisso",
        ]
        return any(phrase in lower for phrase in phrases)

2. Habilidades em Subagentes (nanobot/agent/subagent.py)

Sem essa alteração, subagentes iniciados via ferramenta spawn não têm a habilidade do capsolver em seu contexto. Adicione a importação e injete habilidades sempre carregadas no prompt do subagente:

# Adicione a importação
from nanobot.agent.skills import SkillsLoader

# No __init__, adicione:
self._skills = SkillsLoader(workspace)

# No final do _build_subagent_prompt(), antes de return:
        always_skills = self._skills.get_always_skills()
        if always_skills:
            skills_content = self._skills.load_skills_for_context(always_skills)
            if skills_content:
                prompt += f"\n\n## Documentação de Referência\n\n{skills_content}"
        return prompt

3. Timeout do Exec (nanobot/config/schema.py)

Scripts de automação de navegador precisam de mais do que os 60 segundos padrão — o polling do CapSolver pode levar 20+ segundos. Aumente o timeout:

class ExecToolConfig(BaseModel):
    """Configuração da ferramenta de execução de shell."""
    timeout: int = 120  # era 60

Após aplicar essas mudanças, reinicie o Nanobot (pm2 restart nanobot ou reinicie o serviço).

Resultados de Desempenho

Testamos a integração na página de demonstração do reCAPTCHA v2 do Google. Aqui estão os resultados reais da nossa execução de demonstração:

O agente salvou uma captura de tela final (recaptcha_result.png) mostrando a página de sucesso após a submissão do formulário.

Solução de Problemas

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

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

cd ~/.nanobot/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

Tempo limite de resolução do 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é que o CapSolver retorne ready ou failed — se travar, verifique sua chave da API e saldo

Chave do site não encontrada

O script extrai a chave do site do atributo data-sitekey no elemento DOM do reCAPTCHA. Se nenhum elemento com data-sitekey for encontrado, a chave pode estar embutida de outra forma — o agente pode escrever um script modificado para extrair a chave de URLs de iframe ou fonte da página, se necessário.

O navegador trava em Docker/containeres

Adicione estas opções às opções de lançamento do Playwright:

chromium.launch({
  headless: true,
  args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage']
});

O agente não usa o CapSolver

Certifique-se de que a variável de ambiente CAPSOLVER_API_KEY esteja definida antes de iniciar o Nanobot. O agente verifica-a no momento da execução do script.

Boas Práticas

1. Defina a Chave da API como Variável de Ambiente

Não defina a chave no script. Use process.env.CAPSOLVER_API_KEY para que o agente a reconheça automaticamente.

2. Use o Modo Headless em Servidores

A abordagem baseada em API do Nanobot funciona em ambientes totalmente headless — nenhum Xvfb ou tela virtual é necessário. Isso é uma vantagem significativa em comparação com abordagens baseadas em extensões.

3. Monitore seu Saldo do CapSolver

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

4. Mantenha o Playwright Atualizado

Os provedores de CAPTCHA evoluem. Mantenha o Playwright e o Chromium atualizados para evitar problemas de detecção:

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

Conclusão

A integração Nanobot + CapSolver adota uma abordagem fundamentalmente diferente da resolução de CAPTCHA baseada em extensões. Em vez de carregar uma extensão do Chrome, o agente de IA coordena todo o fluxo de resolução:

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

Isso oferece:

• Nenhuma dependência de extensão do Chrome — funciona com qualquer navegador headless
• Suporte a servidor headless — não é necessário exibição ou Xvfb
• Controle por linguagem natural — basta dizer ao agente o que deseja fazer

Pronto para começar? Registre-se no CapSolver e use o código de bônus NANOBOT para obter mais 6% de bônus em seu primeiro recarregamento!

Perguntas Frequentes

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

O Nanobot usa diretamente a API REST do CapSolver. O agente escreve e executa scripts que chamam createTask e getTaskResult para obter tokens de solução, depois injeta-os no DOM da página. Nenhuma extensão do navegador é necessária.

Preciso de uma versão especial do Chrome?

Não. Ao contrário dos métodos baseados em extensões que exigem Chrome for Testing (já que o Chrome comercial 137+ desativou o carregamento de extensões), o Nanobot funciona com qualquer build do Chromium — incluindo o Chromium embutido no Playwright, pacotes padrão do Chromium ou até o Chrome headless.

Quais tipos de CAPTCHA o CapSolver suporta?

O CapSolver suporta reCAPTCHA v2 (caixa de seleção e invisível), reCAPTCHA v3, Cloudflare Turnstile, AWS WAF CAPTCHA e mais. Testamos a integração do Nanobot com a reCAPTCHA v2 usando o tipo de tarefa ReCaptchaV2TaskProxyLess. Para outros tipos de CAPTCHA, o agente pode escrever um script usando o tipo de tarefa apropriado do CapSolver — consulte a documentação do CapSolver para a lista completa.

Posso usar isso em um servidor headless?

Sim — e é exatamente onde o método do Nanobot brilha. Como não há extensão do navegador envolvida, você não precisa de Xvfb ou de uma tela virtual. O Playwright funciona em modo totalmente headless por padrão.

Quanto custa o CapSolver?

O CapSolver oferece preços competitivos com base no tipo de CAPTCHA e volume. Visite capsolver.com para ver os preços atuais.

O Nanobot é gratuito?

O Nanobot é de código aberto 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 resolver CAPTCHAs, uma conta no CapSolver com créditos.

Quanto tempo leva a resolução de CAPTCHA?

Em nossos testes com reCAPTCHA v2, a API do CapSolver devolveu a solução em ~20 segundos. O agente verifica a cada 2 segundos e continua assim que o token estiver pronto. O tempo total de execução do script (navegar + resolver + injetar + enviar) foi de ~34 segundos, e o tempo total do início ao fim, desde a mensagem até a resposta, foi de ~45 segundos, incluindo a escrita do script pelo agente.