Como resolver automaticamente CAPTCHAs com NanoClaw e CapSolver

Quando seu assistente de IA navega pela web dentro de um container seguro, os CAPTCHAs ainda são o principal obstáculo. Páginas protegidas bloqueiam o agente, formulários não podem ser enviados e tarefas ficam travadas esperando intervenção humana — mesmo quando o agente está em sandbox.

NanoClaw é um framework leve para assistentes de IA que executa agentes Claude em contêineres Linux isolados. Cada agente recebe seu próprio sistema de arquivos, seu próprio navegador e suas próprias ferramentas — completamente separado do host e dos outros agentes. Mas como qualquer automação de navegador, os CAPTCHAs o param imediatamente.

CapSolver muda isso completamente. Ao carregar a extensão CapSolver no navegador Chromium do container, os CAPTCHAs são resolvidos automaticamente e invisivelmente em segundo plano. Nenhum código. Nenhuma chamada de API do seu lado. Nenhuma alteração em como você se comunica com seu assistente de IA.

A melhor parte? Você nem precisa mencionar CAPTCHAs ao IA. Basta dizer a ele para esperar um momento antes de enviar — e quando ele clicar em Enviar, o CAPTCHA já estará resolvido.

E como o NanoClaw executa cada agente em seu próprio container, cada agente recebe seu próprio navegador isolado com sua própria instância do CapSolver — sem conflitos, sem estado compartilhado, sem interferência entre agentes.

O que é NanoClaw?

NanoClaw é um framework leve para assistentes de IA projetado para segurança e simplicidade. Ele executa agentes Claude em contêineres Linux isolados — dando a cada agente isolação de nível de sistema operacional, em vez de verificações de permissão de nível de aplicativo.

Principais Funcionalidades

• Isolamento de contêineres: Cada agente roda em um sandbox Docker ou Apple Container com sistema de arquivos isolado
• Mensagens multi-canal: Comunique-se com seu IA por WhatsApp, Telegram, Discord, Slack e Gmail
• Navegador integrado: Cada contêiner inclui o Chromium e a ferramenta agent-browser para automação web
• Customização baseada em habilidades: Adicione capacidades por meio de habilidades do Claude Code — sem espalhamento de configuração
• Código mínimo: Um processo, poucos arquivos, fácil de entender e personalizar
• Tarefas agendadas: Configure tarefas recorrentes que executam o Claude e lhe enviam os resultados

O Navegador dentro do Contêiner

Cada contêiner NanoClaw vem com o Chromium Debian e a ferramenta de linha de comando agent-browser. O agente pode:

• Abrir e navegar até qualquer URL
• Ler conteúdo da página e fazer capturas de tela
• Clicar em botões, preencher formulários, selecionar listas suspensas
• Fazer capturas de tela
• Gerenciar sessões de navegador

Pense nisso como dar a cada agente de IA uma janela de navegador isolada dentro de um sandbox restrito.

O que é CapSolver?

CapSolver é um serviço líder de resolução de CAPTCHA que fornece soluções com inteligência artificial para contornar diversos desafios de CAPTCHA. Com suporte para vários tipos de CAPTCHA e tempos de resposta rápidos, o CapSolver se integra sem problemas a fluxos 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 Essa Integração é Diferente

A maioria das integrações de resolução de CAPTCHA exige que você escreva código — criar chamadas de API, polpar resultados, injetar tokens em campos ocultos de formulários. É assim que funciona com ferramentas como Crawlee, Puppeteer ou Playwright.

NanoClaw + CapSolver é fundamentalmente diferente:

A principal descoberta: A extensão CapSolver roda dentro do navegador Chromium do container. Quando o agente navega até uma página com um CAPTCHA, a extensão o detecta, o resolve em segundo plano e injeta o token — tudo antes mesmo que o agente tente enviar o formulário.

Você só precisa dar tempo. Em vez de dizer ao IA "resolva o CAPTCHA", você simplesmente diz:

"Vá para essa página, espere 70 segundos, depois clique em Enviar."

Isso é tudo. O IA não precisa saber nada sobre o CapSolver.

A Vantagem do Container

Como o NanoClaw executa cada agente em seu próprio container, você obtém um benefício único: cada agente tem sua própria instância do Chromium com sua própria extensão CapSolver. Isso significa:

• Múltiplos agentes podem resolver CAPTCHAs simultaneamente sem conflitos
• O estado do navegador de cada agente é completamente isolado
• Nenhum cookie, cache ou estado de extensão compartilhado entre agentes
• Se o navegador de um agente travar, os outros não são afetados

Pré-Requisitos

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

1. NanoClaw instalado e em execução (guia de instalação)
2. Uma conta no CapSolver com chave de API (cadastre-se aqui)

Nenhum Chrome para Testes é Necessário

Boa notícia: Os containers NanoClaw usam o Chromium Debian (via apt-get install chromium), que é não marcado e totalmente suporta a opção --load-extension. Ao contrário do Chrome da Google 137+, que removeu silenciosamente o suporte para carregar extensões no meio de 2025, o Chromium Debian funciona de forma nativa.

Você não precisa instalar o Chrome para testes, o Chromium embutido no Playwright ou nenhum navegador alternativo. O Chromium já presente no seu container é o suficiente.

Configuração Passo a Passo

Passo 1: Baixe a Extensão do CapSolver para o Chrome

Baixe a extensão do CapSolver para o diretório do seu projeto NanoClaw:

1. Vá para as versões da extensão CapSolver no GitHub
2. Baixe a versão mais recente CapSolver.Browser.Extension-chrome-vX.X.X.zip
3. Extraia o zip:

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

4. Verifique se a extração funcionou:

ls assets/capsolver-extension/manifest.json

Você deve ver manifest.json — isso confirma que a extensão está no local correto.

Passo 2: Defina a Chave de API do CapSolver

Abra o arquivo de configuração da extensão em assets/capsolver-extension/assets/config.js e substitua o valor apiKey pelo seu próprio:

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',  // ← sua chave aqui
  useCapsolver: true,
  // ... resto da configuração
};

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

Passo 3: Monte a Extensão no Container

O NanoClaw executa agentes em contêineres Docker. O diretório da extensão precisa estar disponível dentro do container em /opt/capsolver-extension.

Opção A: Auto-mount via container runner (recomendado)

Coloque a extensão no diretório assets/capsolver-extension/ do seu projeto NanoClaw. Em seguida, adicione um volume de montagem em src/container-runner.ts:

// Montar extensão do CapSolver se presente
const capsolverPath = path.join(process.cwd(), 'assets', 'capsolver-extension');
if (fs.existsSync(capsolverPath)) {
  mounts.push({
    hostPath: capsolverPath,
    containerPath: '/opt/capsolver-extension',
    readonly: true,
  });
}

Opção B: Incluir na imagem do container

Adicione ao seu container/Dockerfile:

# Adicionar extensão do CapSolver
COPY ../assets/capsolver-extension/ /opt/capsolver-extension/

Em seguida, reconstrua a imagem do container.

Passo 4: Configure o agent-browser para Carregar a Extensão

O NanoClaw usa a ferramenta de linha de comando agent-browser para automação de navegador dentro dos contêineres. Ele suporta carregar extensões do Chrome por meio de variáveis de ambiente.

Adicione essas variáveis de ambiente ao container em src/container-runner.ts:

if (fs.existsSync(capsolverPath)) {
  args.push('-e', 'AGENT_BROWSER_EXTENSIONS=/opt/capsolver-extension');
  args.push('-e', 'DISPLAY=:99');
  args.push('-e', 'AGENT_BROWSER_ARGS=--no-sandbox,--disable-gpu,--disable-blink-features=AutomationControlled,--disable-background-timer-throttling');
  args.push('-e', 'AGENT_BROWSER_HEADED=true');
}

Passo 5: Configure o Xvfb no Container

Extensões do Chrome exigem um display, mesmo em contêineres. Adicione o xvfb ao seu container/Dockerfile e inicie-o automaticamente no entrypoint:

# Adicionar xvfb à lista de instalação do apt-get
RUN apt-get update && apt-get install -y \
    chromium \
    xvfb \
    # ... outros dependências
    && rm -rf /var/lib/apt/lists/*

# Permitir que o Xvfb seja executado por usuário não root
RUN chmod u+s /usr/bin/Xvfb

# Criar diretório de sessão (o agent-browser precisa disso)
RUN mkdir -p /home/node/.claude/session-env && chown -R node:node /home/node/.claude

Atualize o entrypoint para iniciar o Xvfb automaticamente:

#!/bin/bash
set -e
# Iniciar Xvfb para extensões de navegador
if [ -n "$DISPLAY" ]; then
  Xvfb $DISPLAY -screen 0 1280x720x24 &
  sleep 0.5
fi
# ... resto do entrypoint

Passo 6: Reinicie o NanoClaw

# Reinicie o NanoClaw para aplicar as mudanças
npm run dev
# ou se estiver rodando como serviço:
pm2 restart nanoclaw

Passo 7: Verifique a Configuração

Envie uma mensagem de teste para seu agente NanoClaw por qualquer canal conectado (Discord, WhatsApp, Telegram):

Vá para https://www.google.com/recaptcha/api2/demo, espere 70 segundos,
depois clique em Enviar e me diga qual texto aparece na página.

Se o CapSolver estiver funcionando, o agente deve relatar: "Verificação bem-sucedida... Hooray!"

Como Usar

Esta é a seção mais importante. Após a configuração, usar o CapSolver com o NanoClaw é extremamente simples.

A Regra Dourada

Não mencione CAPTCHAs ou CapSolver ao IA. Apenas dê tempo antes de enviar formulários.

O agente de IA não precisa saber sobre CAPTCHAs. A extensão cuida de tudo em segundo plano. Tudo o que você precisa fazer é incluir um tempo de espera em suas instruções para que a extensão tenha tempo de resolver o desafio antes do formulário ser enviado.

Exemplo 1: Demo de reCAPTCHA

Envie isso para seu agente NanoClaw (via Discord, WhatsApp, Telegram ou qualquer canal):

Vá para https://example.com, espere 70 segundos,
depois clique em Enviar e me diga qual texto aparece na página.

O que acontece em segundo plano:

1. O container do agente recebe a mensagem
2. O agente inicia o Chromium (com a extensão CapSolver carregada)
3. O Chromium navega até a página
4. O script de conteúdo do CapSolver detecta o widget reCAPTCHA
5. A extensão chama a API do CapSolver e resolve o desafio (geralmente em 10-20 segundos)
6. O token é injetado no campo oculto do formulário
7. Após 70 segundos, o agente clica em Enviar
8. A página mostra: "Verificação bem-sucedida... Hooray!"

Exemplo 2: Entrar em um Site Protegido

Vá para https://example.com/login, preencha o campo de e-mail com
"me@example.com" e o campo de senha com "mypassword123",
depois espere 30 segundos e clique no botão Entrar.
Me diga qual página carrega após fazer login.

Exemplo 3: Enviar um Formulário atrás do Turnstile

Abra https://example.com/contact, preencha o formulário de contato:
- Nome: "John Doe"
- E-mail: "john@example.com"
- Mensagem: "Olá, tenho uma pergunta sobre seus serviços."
Espere 45 segundos, depois clique em Enviar Mensagem. Qual confirmação aparece?

Tempos de Espera Recomendados

Dica: Quando em dúvida, use 70 segundos. É melhor esperar um pouco mais do que enviar cedo demais. O tempo extra não afeta o resultado. Em nossos testes, 60 segundos foi borderline para reCAPTCHA v2 — 70 segundos funcionou de forma confiável.

Padrões de Linguagem Natural que Funcionam

Aqui estão frases comprovadas que você pode usar:

• "Vá para [URL], espere 70 segundos, depois envie o formulário"
• "Navegue até [URL], preencha [campos], espere 30 segundos, depois clique em [botão]"
• "Abra [URL] e após cerca de um minuto, clique em Enviar e me diga o resultado"
• "Visite [URL] e espere um momento para a página carregar totalmente, depois envie"

O que NÃO Dizer

Evite esses — podem confundir o IA ou acionar recusas:

• "Espere até que o CAPTCHA seja resolvido" (o IA não sabe sobre CAPTCHAs)
• "Use o CapSolver para resolver a verificação" (o IA não pode controlar extensões)
• "Clique na caixa de reCAPTCHA" (a extensão cuida disso — clicar pode interferir)

Como Funciona por Baixo dos Panos

Para os curiosos técnicos, aqui está o que acontece quando a extensão CapSolver é carregada dentro de um container NanoClaw:

  Sua mensagem                    Servidor NanoClaw
  ───────────────────────────────────────────────────
  "vá para a página,          ──►  Router de mensagens recebe a mensagem
   espere 60s, envie"         │
                              ▼
                         Container criado para o agente
                         ┌─────────────────────────────────┐
                         │  Contêiner Docker Isolado       │
                         │                                  │
                         │  Agente Claude (via SDK do Agente)    │
                         │       │                          │
                         │       ▼                          │
                         │  agent-browser: navegar até URL  │
                         │       │                          │
│       ▼                          │
                         │  Chromium + Extensão CapSolver  │
                         │  ┌───────────────────────────┐   │
                         │  │ Página com reCAPTCHA       │   │
                         │  │                           │   │
                         │  │ Extensão CapSolver:      │   │
                         │  │ 1. Script de conteúdo detecta │   │
                         │  │    reCAPTCHA na página  │   │
                         │  │ 2. Worker de serviço chama   │   │
                         │  │    API CapSolver          │   │
                         │  │ 3. Token recebido         │   │
                         │  │ 4. Token injetado em    │   │
                         │  │    campo de formulário oculto      │   │
                         │  └───────────────────────────┘   │
                         │       │                          │
                         │       ▼                          │
                         │  Agente aguarda 70 segundos...       │
                         │       │                          │
                         │       ▼                          │
                         │  agent-browser: clique em Enviar     │
                         │       │                          │
                         │       ▼                          │
                         │  "Verificação bem-sucedida!"         │
                         └─────────────────────────────────┘
                              │
                              ▼
                         Resposta enviada de volta via Discord/WhatsApp/etc.

Como a Extensão Carrega

NanoClaw usa a ferramenta de linha de comando agent-browser, que suporta o carregamento de extensões do Chrome via a variável de ambiente AGENT_BROWSER_EXTENSIONS. Quando essa variável é definida, o agent-browser passa automaticamente --load-extension para o Chromium.

1. Container inicia com AGENT_BROWSER_EXTENSIONS=/opt/capsolver-extension definido
2. Agente chama agent-browser open <url> — o Chromium inicia com a extensão carregada
3. A extensão ativa — seu worker de serviço começa e os scripts de conteúdo são injetados em cada página
4. Em páginas com CAPTCHAs — o script de conteúdo detecta o widget, chama a API CapSolver e injeta o token de solução na página

Como o NanoClaw usa o Chromium Debian (não o Chrome da Google), o sinalizador --load-extension funciona de forma confiável sem nenhuma solução alternativa. E como o agent-browser lida com o sinalizador internamente, você não precisa gerenciar os argumentos de inicialização do Chrome por conta própria.

Solução de Problemas

Extensão Não Carregando

Sintoma: O agente navega e envia, mas os CAPTCHAs não são resolvidos.

Possíveis causas:

1. Extensão não montada — Verifique o montagem de volume: ls /opt/capsolver-extension/manifest.json dentro do container
2. AGENT_BROWSER_EXTENSIONS não definido — Certifique-se de que a variável de ambiente AGENT_BROWSER_EXTENSIONS esteja definida como /opt/capsolver-extension no container
3. Exibição ausente — Extensões do Chrome precisam de um contexto de exibição. Certifique-se de que o Xvfb esteja rodando com DISPLAY=:99

Erro de Permissão no Navegador (session-env)

Sintoma: O agente relata "não é possível criar diretório de sessão em /home/node/.claude/session-env"

Causa: A ferramenta agent-browser precisa de um diretório de sessão gravável. Se o diretório .claude montado não contém isso, a ferramenta falha.

Solução: Certifique-se de que o diretório exista no Dockerfile e no host:

# No Dockerfile:
RUN mkdir -p /home/node/.claude/session-env && chown -R node:node /home/node/.claude

# No host (para o volume montado):
mkdir -p data/sessions/main/.claude/session-env
chmod -R 777 data/sessions/main/.claude

CAPTCHA Não Resolvido (Formulário Falha)

Possíveis causas:

1. Tempo de espera insuficiente — Aumente para 70 segundos
2. Chave de API inválida — Verifique seu painel do CapSolver
3. Saldo insuficiente — Recarregue sua conta do CapSolver
4. Extensão não carregada — Veja "Extensão Não Carregando" acima

Problemas de Exibição em Containers

Sintoma: O Chromium trava ou as extensões não funcionam dentro do container.

Solução: Certifique-se de que o Xvfb esteja rodando antes de iniciar o Chromium:

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

Adicione esses comandos ao script de entrada do container para que sejam executados automaticamente.

Alternativa: Habilidades do CapSolver (Solução Baseada em API)

Além do método da extensão do Chrome, o NanoClaw suporta um segundo método de integração usando CapSolver Skills — uma ferramenta CLI do Python que resolve CAPTCHAs via API do CapSolver diretamente.

Como Funciona

Em vez da extensão resolver os CAPTCHAs invisivelmente no plano de fundo, o agente explicitamente:

1. Extrai a chave do site CAPTCHA da página
2. Chama a API CapSolver via python3 /opt/capsolver-skills/scripts/solver.py
3. Recebe um token de solução
4. Injeta o token no campo de formulário oculto da página
5. Submete o formulário

Configuração

Clone o repositório capsolver-skills no seu projeto NanoClaw:

git clone https://github.com/capsolver/capsolver-skills.git assets/capsolver-skills

Adicione python3 e dependências ao seu container/Dockerfile:

RUN apt-get update && apt-get install -y python3 python3-pip \
    && pip3 install --break-system-packages requests python-dotenv

Monte o diretório de habilidades e passe a chave de API em src/container-runner.ts:

// Montar capsolver-skills
const capsolverSkillsPath = path.join(process.cwd(), 'assets', 'capsolver-skills');
if (fs.existsSync(capsolverSkillsPath)) {
  mounts.push({
    hostPath: capsolverSkillsPath,
    containerPath: '/opt/capsolver-skills',
    readonly: true,
  });
}

// Passar chave de API
args.push('-e', `API_KEY=${capsolverApiKey}`);

Defina CAPSOLVER_API_KEY no seu arquivo .env:

CAPSOLVER_API_KEY=CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Exemplo de Uso

@OpenCrawl Vá para https://www.google.com/recaptcha/api2/demo,
use a habilidade do capsolver para resolver o reCAPTCHA,
depois clique em Enviar e me diga o resultado.

Tipos de CAPTCHA Suportados

O solucionador de Habilidades do CapSolver suporta todos os principais tipos de CAPTCHA via CLI:

Extensão vs Habilidades: Quando Usar Cada Uma

Dica: Você pode usar os dois métodos simultaneamente. A extensão resolve os CAPTCHAs automaticamente no plano de fundo, enquanto o solucionador de Habilidades dá ao agente controle explícito quando necessário.

Boas Práticas

1. Sempre Use Tempos de Espera Generosos

Mais tempo de espera é sempre mais seguro. O CAPTCHA geralmente é resolvido em 10-30 segundos, mas latência de rede, desafios complexos ou tentativas podem adicionar tempo. 60-70 segundos é o ponto ideal.

2. Mantenha suas Mensagens Naturais

Em vez de:

"Navegue até a URL, espere pelo solucionador de CAPTCHA, depois envie"

Use:

"Vá até a URL, espere cerca de um minuto, depois envie o formulário"

Frase natural funciona melhor com a IA e evita recusas de segurança.

3. Monitore seu Saldo do CapSolver

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

4. Use o Método de Montagem de Volume

Montar o volume da extensão (em vez de embalá-la na imagem) torna fácil atualizar a extensão sem reconstruir a imagem do container. Basta baixar a nova versão e reiniciar o NanoClaw.

Conclusão

A integração NanoClaw + CapSolver traz resolução de CAPTCHA para agentes de IA containerizados — duas formas:

1. Extensão do Chrome (sem código): Monte a extensão, defina sua chave de API e os CAPTCHAs são resolvidos invisivelmente no plano de fundo. Apenas diga ao seu IA para esperar antes de enviar.
2. Habilidades do CapSolver (baseado em API): O agente chama explicitamente a API do CapSolver para gerar tokens e injetá-los na página. Mais controle, sem necessidade de esperar.

Ambos os métodos são verificados e funcionam. Use a extensão para fluxos de trabalho simples de "navegar e enviar", e as Habilidades do CapSolver quando você precisar de controle detalhado.

E graças à arquitetura de container do NanoClaw, cada agente tem seu próprio navegador e instância do CapSolver isolados — sem conflitos, sem estado compartilhado, resolução de CAPTCHA com múltiplos agentes.

Essa é a aparência da resolução de CAPTCHA quando você tem um assistente de IA containerizado: invisível, automático, isolado e sem código.

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

Perguntas Frequentes

Eu preciso dizer ao IA sobre o CapSolver?

Não. Na verdade, você deve evitar mencionar CAPTCHAs ou CapSolver em suas mensagens. A extensão funciona invisivelmente no plano de fundo. Apenas inclua um tempo de espera em suas instruções (ex.: "espere 70 segundos, depois envie") para dar à extensão tempo para resolver qualquer CAPTCHA na página.

Por que o NanoClaw não precisa do Chrome para testes?

Os containers NanoClaw usam o Chromium Debian instalado via apt-get, que é não marcado. Ao contrário do Chrome da Google 137+ (que removeu silenciosamente o suporte a --load-extension no meio de 2025), o Chromium Debian suporta totalmente o carregamento de extensões. Nenhuma solução alternativa é necessária.

Quais tipos de CAPTCHA o CapSolver suporta?

O CapSolver suporta reCAPTCHA v2 (caixa e invisível), reCAPTCHA v3, Cloudflare Turnstile, CAPTCHA AWS WAF e mais. A extensão do Chrome detecta automaticamente o tipo de CAPTCHA e o resolve de acordo.

Quanto custa o CapSolver?

O CapSolver oferece preços competitivos com base no tipo de CAPTCHA e volume. Visite capsolver.com para os preços atuais. Use o código promocional NANOCLAW para obter 6% a mais em seu primeiro recarregamento.

O NanoClaw é gratuito?

O NanoClaw é de código aberto (licença MIT) e gratuito para executar em seus próprios hardware. Você precisará de uma chave de API para o modelo de IA — seja uma chave de API da Anthropic diretamente, ou uma chave de API do OpenRouter (que lhe dá acesso a Claude e outros modelos por meio de uma única conta). Para resolução de CAPTCHA, você precisará de uma conta do CapSolver com créditos.

Quanto tempo devo dizer ao IA para esperar?

Para a maioria dos CAPTCHAs, 60-70 segundos é suficiente. O tempo real de resolução geralmente é 10-30 segundos, mas adicionar um buffer extra garante confiabilidade. Quando em dúvida, use 70 segundos — em nossos testes, 60 segundos foi borderline para reCAPTCHA v2.

Como a isolamento de container ajuda na resolução de CAPTCHA?

Cada agente NanoClaw roda em seu próprio container Docker com seu próprio navegador Chromium e instância de extensão do CapSolver. Isso significa que múltiplos agentes podem resolver CAPTCHAs simultaneamente sem conflitos — nenhum cookie compartilhado, nenhum estado de navegador compartilhado, nenhuma interferência. Se uma sessão de navegador de um agente tiver problemas, isso não afeta nenhum outro agente.

Posso usar isso em um servidor sem tela?

Sim. Você precisará do Xvfb (X Virtual Framebuffer) para a exibição, já que extensões do Chrome exigem um contexto de exibição. Defina DISPLAY=:99 e execute Xvfb :99 em segundo plano dentro do container.