Como resolver CAPTCHA em automação de navegadores com Hermes Agent e CapSolver

Quando seu agente de IA navega pela web para você, os CAPTCHAs são o principal obstáculo. Páginas protegidas bloqueiam o agente, formulários recusam-se a enviar e tarefas ficam travadas esperando intervenção humana.

Hermes Agent da Nous Research é um agente de IA auto-improving que funciona em qualquer lugar — de um VPS de $5 a um cluster de GPU — e chega até você em todos os canais que você já usa: Telegram, Discord, Slack, WhatsApp, Signal e e-mail. Ele também pode controlar um navegador para navegar por páginas, clicar em botões, preencher formulários e extrair dados em seu nome. Mas como qualquer agente que controla um navegador, ele fica travado em CAPTCHAs.

CapSolver muda isso completamente. Ao carregar a extensão do CapSolver no navegador ao qual o Hermes se conecta, os CAPTCHAs são resolvidos automaticamente e invisivelmente no fundo. Nenhum código. Nenhuma chamada de API do seu lado. Nenhuma engenharia de prompts.

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

O que é Hermes Agent?

Hermes Agent é um agente de IA autônomo de código aberto criado pela Nous Research. Ele é projetado em torno de três princípios: memória persistente (ele se lembra de você e dos seus projetos entre as sessões), criação autônoma de habilidades (ele aprende procedimentos a partir da experiência e os repete na próxima vez) e flexibilidade de infraestrutura (execute-o em um VPS pequeno, um contêiner Docker, um sandbox serverless ou sua própria GPU).

Recursos Principais

• Porta de múltiplos canais: Comunique-se com seu agente por meio do Telegram, Discord, Slack, WhatsApp, Signal, e-mail ou sua própria interface de terminal
• Modelo de sua escolha: OpenRouter (200+ modelos), Nous Portal, NVIDIA NIM, Z.AI, seu próprio endpoint — mude com hermes model
• Memória entre sessões: Pesquisa de sessão FTS5 + resumo por LLM significa que o agente se lembra do que você falou na semana passada
• Sistema de habilidades: Memória procedural que o agente constrói sozinho, compatível com o padrão agentskills.io
• Sete backends de terminal: Local, Docker, SSH, Singularity, Modal, Daytona, Vercel Sandbox
• Ferramenta de navegador integrada: Controla um Chromium real via Playwright + Protocolo de DevTools do Chrome

A Ferramenta de Navegador

O Hermes pode controlar um navegador Chromium para fazer trabalho real — navegar, ler DOM, clicar, digitar, capturar tela, raspar. A camada de ferramenta de navegador é incomum em um aspecto específico: em vez de forçá-lo a um único backend, o Hermes suporta cinco fornecedores de navegador intercambiáveis:

Os provedores em nuvem não podem carregar extensões — você não controla o navegador remoto. O Camoufox é baseado em Firefox e não executa uma extensão Chrome MV3. O ponto de integração limpo é o quinto: CDP attach, onde o Hermes se conecta a um Chromium você lançou separadamente. É aí que o CapSolver se encaixa.

Este é um modelo diferente de ferramentas como OpenClaw (que lança seu próprio Chromium e aceita um array browser.extensions) ou Crawlee (onde você controla as bandeiras de lançamento do Playwright). Com o Hermes, você traz seu próprio Chrome com a extensão carregada previamente, e o Hermes se conecta a ele pelo protocolo DevTools.

O que é CapSolver?

CapSolver é um serviço líder de resolução de CAPTCHA que fornece soluções com inteligência artificial para superar desafios modernos de CAPTCHA. Com suporte para todo tipo de CAPTCHA principal e tempos de resposta rápidos, o CapSolver se integra perfeitamente a fluxos de trabalho automatizados — seja você conduzindo um navegador via Playwright, chamando sua API diretamente ou, como neste guia, executando sua extensão do Chrome dentro da sessão do navegador do agente.

Por que essa integração é diferente

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

Hermes + CapSolver é fundamentalmente diferente:

A principal descoberta: A extensão do CapSolver roda no navegador anexado. O Hermes se conecta a esse navegador pelo CDP e o controla normalmente. Quando o agente navega para uma página com um CAPTCHA, a extensão — rodando no mesmo Chrome, completamente invisível ao agente — detecta o widget, chama a API do CapSolver e injeta o token de solução na página. Quando o agente clicar em Enviar, o formulário já carrega um token válido.

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

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

Isso é tudo. O agente não precisa saber que o CapSolver existe.

Requisitos Prévios

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

1. Hermes Agent instalado e o gateway em execução (instruções de instalação)
2. Conta no CapSolver com chave de API (cadastre-se aqui)
3. Chromium ou Chrome para testes (veja a nota importante abaixo)

Importante: Você Precisa do Chromium, Não do Google Chrome

Google Chrome 137+ (lançado no meio de 2025) removeu silenciosamente o suporte para --load-extension em builds de marca. Isso significa que extensões do Chrome não podem ser carregadas em sessões automatizadas usando o Google Chrome padrão. Não há erro — o sinalizador é simplesmente ignorado.

Isso afeta o Google Chrome e o Microsoft Edge. Você deve usar uma das alternativas a seguir:

Como instalar o Chrome para Testes:

# Opção 1: Via Playwright (recomendado — o Hermes já usa o Playwright internamente)
npx playwright install chromium

# O binário estará em um caminho como:
# ~/.cache/ms-playwright/chromium-XXXX/chrome-linux64/chrome           (Linux)
# ~/Library/Caches/ms-playwright/chromium-XXXX/chrome-mac/Chromium.app/Contents/MacOS/Chromium  (macOS)

# Opção 2: Via download direto do Chrome para Testes
# Visite: https://googlechromelabs.github.io/chrome-for-testing/
# Baixe a versão compatível com seu sistema

Após a instalação, anote o caminho completo do binário — você o precisará na próxima etapa.

Configuração Passo a Passo

A integração tem duas partes trabalhando juntas:

1. Um processo separado do Chrome que você inicia com a extensão do CapSolver carregada previamente e o CDP exposto em uma porta conhecida (usaremos 9222).
2. Uma pequena alteração no config.yaml do Hermes para informar que ele deve se conectar a essa porta CDP em vez de iniciar seu próprio navegador.

Isso é tudo — nenhum código, nenhuma modificação no Hermes.

Etapa 1: Baixe a Extensão do CapSolver Chrome

Baixe a extensão do CapSolver Chrome e extraia-a para um local estável:

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

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

4. Verifique se a extração funcionou:

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

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

Dica sobre caminhos: Use um caminho absoluto e resolvido (não ~) ao passar --load-extension=... para o Chrome posteriormente. Alguns builds do Chrome MV3 têm casos especiais onde os workers de extensão falham em se registrar por meio de links simbólicos em diretórios de dados de usuário personalizados. Se você estiver linkando a extensão de outro local, use readlink -f para resolver o caminho real e use esse.

Etapa 2: Defina sua Chave de API do CapSolver

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

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

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

Etapa 3: Inicie o Chrome com a Extensão e o CDP Habilitado

Essa é a etapa crucial. Iniciamos o Chrome uma vez, separadamente do Hermes, com três flags cruciais:

• --remote-debugging-port=9222 — expõe o protocolo DevTools para que o Hermes se conecte
• --load-extension=... — carrega previamente a extensão do CapSolver
• --user-data-dir=... — usa um perfil dedicado para que não haja conflito com seu Chrome pessoal

O Hermes tem uma convenção interna para o diretório de dados do usuário: ~/.hermes/chrome-debug. Usar esse caminho significa que o comando /browser connect do Hermes também "funciona" sem nenhuma bandeira adicional.

Opção A: Início manual de uma só vez (bom para testes rápidos)

/caminho/para/chrome-for-testing/chrome \
  --remote-debugging-port=9222 \
  --remote-debugging-address=127.0.0.1 \
  --user-data-dir="$HOME/.hermes/chrome-debug" \
  --load-extension="$HOME/.hermes/capsolver-extension" \
  --disable-extensions-except="$HOME/.hermes/capsolver-extension" \
  --no-first-run \
  --no-default-browser-check \
  --no-sandbox

Substitua /caminho/para/chrome-for-testing/chrome pelo seu binário real, por exemplo ~/.cache/ms-playwright/chromium-1200/chrome-linux64/chrome.

Servidores sem tela: Se você estiver executando isso em um servidor Linux sem tela física (um VPS, EC2, etc.), consulte a seção Melhores Práticas abaixo para a configuração do Xvfb. O subsistema de extensões do Chrome exige um contexto de tela.

Opção B: Processo de fundo persistente (recomendado para produção)

Para qualquer configuração que dure mais do que uma única execução de teste, envolva o lançamento em um pequeno script de shell para que você possa manter o Chrome rodando em segundo plano, reiniciá-lo limpo e supervisioná-lo com qualquer gerenciador de processos que já use (systemd, supervisor, runit, OpenRC, Docker, etc.).

Salve isso como ~/.hermes/chrome-debug.sh e chmod +x:

#!/usr/bin/env bash
# ~/.hermes/chrome-debug.sh
# Inicia o Chrome-for-Testing com a extensão do CapSolver carregada
# e o CDP exposto em 127.0.0.1:9222.

CHROME_BIN="$HOME/.cache/ms-playwright/chromium-1200/chrome-linux64/chrome"
EXT_DIR="$HOME/.hermes/capsolver-extension"
USER_DATA_DIR="$HOME/.hermes/chrome-debug"

export DISPLAY=:99   # para servidores sem tela — veja Melhores Práticas

exec "$CHROME_BIN" \
  --remote-debugging-port=9222 \
  --remote-debugging-address=127.0.0.1 \
  --user-data-dir="$USER_DATA_DIR" \
  --load-extension="$EXT_DIR" \
  --disable-extensions-except="$EXT_DIR" \
  --no-first-run \
  --no-default-browser-check \
  --no-sandbox \
  --disable-dev-shm-usage \
  --disable-features=Translate

A maneira mais simples de iniciar persistentemente é:

nohup ~/.hermes/chrome-debug.sh > /tmp/chrome-debug.log 2>&1 &

Para produção, supervise o script com o gerenciador de processos que você preferir. Um unit systemd mínimo em ~/.config/systemd/user/chrome-debug.service:

[Unit]
Descrição=Chrome com CapSolver para Hermes Agent
Depende=network.target

[Service]
ExecStart=%h/.hermes/chrome-debug.sh
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

Em seguida:

systemctl --user daemon-reload
systemctl --user enable --now chrome-debug

Qualquer configuração equivalente (programa do supervisord, serviço do runit, contêiner do Docker, etc.) funciona da mesma forma — a integração só se importa com o fato de algo manter o chrome-debug.sh rodando.

Etapa 4: Informe ao Hermes para se Conectar pelo CDP

Edite sua configuração do Hermes em ~/.hermes/config.yaml. Encontre a seção browser: (geralmente só tem inactivity_timeout) e adicione um cdp_url:

browser:
  inactivity_timeout: 120
  cdp_url: http://127.0.0.1:9222

Essa única linha informa ao browser_cdp do Hermes para rotear todas as operações do navegador através do Chrome que você iniciou na Etapa 3, em vez de iniciar o próprio.

Reversibilidade: Esta é a única alteração no Hermes. Para reverter, delete a linha cdp_url. O Hermes retorna para o provedor de navegador padrão que ele estava usando (Browserbase, Browser Use, etc.) sem outros efeitos colaterais.

Etapa 5: Reinicie o Hermes

Se o Hermes já estiver em execução, reinicie-o para que ele reconheça o novo cdp_url:

# Executando diretamente (em primeiro plano ou sob seu supervisor):
hermes gateway run

# Ou reinicie via qualquer gerenciador de processos que você use para supervisionar o Hermes —
# a única exigência é que o novo ambiente/configuração entre em vigor.

Etapa 6: Verifique a Configuração

O Hermes vem com um comando de diagnóstico embutido que verifica todas as partes da integração de uma só vez:

hermes doctor

Você está procurando por esses sinais:

◆ Disponibilidade de Ferramentas
  ✓ browser-cdp        ← Anexar CDP está ativo
  ✓ browser
  ...

◆ Conectividade de API
  Verificando API do OpenRouter...  ✓ API do OpenRouter

Se browser-cdp aparecer sob Disponibilidade de Ferramentas, o Hermes detectou seu endpoint CDP e a integração está configurada corretamente. Se estiver ausente, o Hermes desativa silenciosamente a ferramenta (sem erro) — esse é o diagnóstico a observar.

Você também pode confirmar que o Chrome está acessível diretamente:

curl -s http://127.0.0.1:9222/json/version

Uma resposta como a seguinte confirma que o CDP está ativo:

{
   "Browser": "Chrome/<sua versão>",
   "Protocol-Version": "1.3",
   "webSocketDebuggerUrl": "ws://127.0.0.1:9222/devtools/browser/..."
}

Sobre a visibilidade do serviço worker da CapSolver: Os service workers do Chrome MV3 entram em inatividade de forma agressiva, e em builds recentes do Chrome, /json/list pode omiti-los completamente, mesmo enquanto estão em execução. A ausência em /json/list não é diagnóstica — confirme que a CapSolver está funcionando carregando uma página real de reCAPTCHA por meio do agente e observando o resultado do widget na página, não por meio da verificação da lista de alvos.

Como Usar

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

A Regra Dourada

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

O agente 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 nas suas instruções para que a extensão tenha tempo de resolver o desafio antes do envio do formulário.

Exemplo 1: Teste de fumaça de uma única etapa

O modo de uma única etapa do Hermes (hermes -z "...") é ideal para testar a integração. Execute isso a partir de qualquer terminal onde o CLI do Hermes esteja disponível:

hermes -z 'Abra https://www.google.com/recaptcha/api2/demo. Espere 60 segundos para a página carregar completamente. Em seguida, clique no botão rotulado como "Enviar!" ou com o id "recaptcha-demo-submit". Após clicar, espere 5 segundos e me informe o texto visível na página.' --yolo

O que acontece em segundo plano:

1. O Hermes se conecta ao seu Chrome via CDP
2. O agente navega para a página de demonstração do reCAPTCHA da Google
3. O script de conteúdo da CapSolver (executado dentro do Chrome) detecta o widget de reCAPTCHA
4. O service worker da extensão chama a API da CapSolver e resolve o desafio (geralmente em 5–15 segundos)
5. O token é injetado no campo oculto g-recaptcha-response do formulário
6. Após 60 segundos, o agente clica em Enviar
7. O servidor da Google valida o token e retorna uma página de resultado
8. O agente lê o texto após o envio: "Verificação bem-sucedida... Hooray!"

Essa string "Verificação bem-sucedida... Hooray!" é uma mensagem própria da Google — ela só aparece quando um token de reCAPTCHA válido é enviado com o formulário.

Exemplo 2: A partir de um canal de mensagens

Envie isso a partir de qualquer canal conectado ao gateway do Hermes (Telegram, Discord, Slack, etc.):

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

O Hermes encaminhará a solicitação para o seu agente, se conectará ao mesmo Chrome, preencherá o formulário, dará tempo à extensão para resolver qualquer CAPTCHA na página de login, clicará em Entrar e responderá com o que a página pós-login disser — tudo sem você mencionar CAPTCHAs.

Exemplo 3: Enviar um formulário de contato com reCAPTCHA

Abra https://example.com/contact e 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, em seguida, clique em Enviar Mensagem.
Qual confirmação aparece na página?

Tempos de Espera Recomendados

Dica: Quando em dúvida, use 60 segundos. É melhor esperar um pouco mais do que enviar cedo demais. O tempo extra é essencialmente gratuito — sua fatura da CapSolver é por solução, não por segundo.

Padrões de Linguagem Natural que Funcionam

Aqui estão frasas comprovadas que você pode usar em qualquer canal do Hermes:

• "Vá para [URL], espere 60 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 informe o resultado"
• "Visite [URL], espere um momento para a página carregar completamente, depois envie"

O que NÃO Dizer

Evite essas frases — elas podem confundir o agente e foram observadas para causar recusas em alguns modelos com ajustes de segurança (notavelmente a família GLM):

• "Espere até que o CAPTCHA seja resolvido" (o agente não sabe sobre CAPTCHAs)
• "Use a CapSolver para resolver a verificação" (o agente não controla as extensões)
• "Clique na caixa de reCAPTCHA" (a extensão cuida disso — clicar pode interferir)
• "Bypass a verificação de segurança" (soa adversarial — alguns modelos recusarão)

Como Funciona por Baixo dos Panos

Para os curiosos técnicos, aqui está a arquitetura:

  Sua mensagem                  Gateway do Hermes
  ──────────────────────────────────────────────────────────
  "vá para a página,           ──►   O agente Hermes recebe a mensagem
   espere 60s, envie"           │
                                ▼
                           browser_cdp / ferramentas do navegador
                                │  (conecta-se via WebSocket
                                │   a ws://127.0.0.1:9222)
                                ▼
                           ┌────────────────────────────────────┐
                           │  chrome-debug Chromium (background)│
                           │                                     │
                           │  ┌───────────────────────────────┐ │
                           │  │ Extensão CapSolver MV3        │ │
                           │  │ (carregada via --load-extension; │ │
                           │  │  requer Chrome para Testes    │ │
                           │  │  ou Chromium — o Chrome 137+  │ │
                           │  │  ignora esta opção)           │ │
                           │  │                                │ │
                           │  │ 1. script de conteúdo detecta CAPTCHA │
                           │  │ 2. worker de serviço chama API CapSolver │
                           │  │ 3. token recebido                │ │
                           │  │ 4. token injetado no campo do formulário │ │
                           │  └───────────────────────────────┘ │
                           └────────────────────────────────────┘
                                │
                                ▼
                           O agente Hermes espera 60 segundos...
                                │
                                ▼
                           browser_cdp: clica em Enviar
                                │
                                ▼
                           Formulário é enviado com token válido
                                │
                                ▼
                           Página de confirmação após o envio

Por Que Anexar CDP em vez de "Apenas Passar uma Matriz de Extensões"?

A camada de ferramentas do navegador do Hermes é construída em torno de cinco provedores intercambiáveis (Browserbase, Browser Use, Firecrawl, Camoufox, Chromium headless). Três desses são em nuvem — você não controla o binário do navegador, então não há lugar para a opção --load-extension. Um (Camoufox) é baseado em Firefox. O quinto — anexar CDP — é a única forma onde um Chromium controlado pelo usuário pode ser conectado.

A troca é excelente: o Hermes permanece portável para nuvem por padrão, mas no momento em que você quiser poderes do lado do navegador (CapSolver, seu próprio bloqueador de anúncios, ferramentas MV3 personalizadas, cookies persistentes, etc.), você inicia o Chrome por conta própria e aponta o Hermes para ele. Uma linha de configuração. Controle total.

O que --load-extension Realmente Faz

Quando o Chrome é iniciado com --load-extension=/caminho/para/extensão, ele trata esse diretório como uma extensão não compactada — o mesmo mecanismo que o modo de desenvolvedor do Chrome usa. O manifesto da extensão, scripts de conteúdo e worker de serviço são registrados exatamente como se você tivesse instalado a extensão da Chrome Web Store. Não há diferença em termos de sandboxing, nem acesso reduzido a APIs — é uma extensão plenamente privilegiada.

A extensão CapSolver então assume o restante:

1. Script de conteúdo (injetado em cada página) monitora widgets de CAPTCHA conhecidos — reCAPTCHA, Cloudflare, AWS WAF, etc.
2. Quando um widget é detectado, o script de conteúdo envia uma mensagem ao worker de serviço
3. O worker de serviço autentica-se na API da CapSolver usando a chave de assets/config.js, envia os detalhes do desafio e verifica o token
4. Assim que o token é recebido, ele é injetado no campo oculto de resposta da página via script de conteúdo
5. No momento em que o agente clica em Enviar, o formulário já carrega um token resolvido

O agente Hermes está completamente desconectado — ele vê uma página normal, espera o tempo que você lhe disse e envia. A página simplesmente tem um token válido nela.

Nota de ambiente: Evite --disable-background-networking nas suas flags do Chrome. Ele bloqueia as solicitações de saída (XHR/fetch) do worker de serviço da CapSolver — então a extensão nunca consegue acessar a API da CapSolver. A receita na Etapa 3 omite intencionalmente essa opção.

Referência de Configuração Completa

Lado do Hermes: ~/.hermes/config.yaml

A única alteração necessária é adicionar cdp_url sob o bloco browser::

browser:
  inactivity_timeout: 120
  cdp_url: http://127.0.0.1:9222

Lado do Chrome: argumentos --load-extension

O conjunto completo de flags que você deve passar para o Chrome:

Lado da CapSolver: assets/config.js

A configuração mínima em ~/.hermes/capsolver-extension/assets/config.js:

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
  useCapsolver: true,
  enabledForRecaptcha: true,
  enabledForRecaptchaV3: true,
  // ... veja a documentação da CapSolver para o conjunto completo de opções
};

Solução de Problemas

hermes doctor não lista browser-cdp sob Disponibilidade de Ferramentas

Sintoma: Após reiniciar o Hermes, a ferramenta browser-cdp está ausente da saída do hermes doctor.

Causa: O Hermes apenas registra browser-cdp quando um endpoint CDP é configurado — seja browser.cdp_url definido em config.yaml, a variável de ambiente BROWSER_CDP_URL, ou uma sessão ativa de /browser connect. A verificação é presença de configuração, não acessibilidade (veja tools/browser_cdp_tool.py:_browser_cdp_check). A causa mais comum de uma ferramenta browser-cdp ausente é um erro de digitação ou chave mal aninhada em config.yaml, não um Chrome inacessível.

Solução:

# 1. Confirme que a chave está corretamente aninhada sob "browser:" (não no nível superior)
grep -A2 '^browser:' ~/.hermes/config.yaml
# saída esperada:
#   browser:
#     ...
#     cdp_url: http://127.0.0.1:9222

# 2. Em seguida, confirme que o Chrome está realmente ativo nesse endpoint
curl -s http://127.0.0.1:9222/json/version

# 3. Se o Chrome estiver desligado, verifique o log do chrome-debug:
tail -n 30 /tmp/chrome-debug.log     # ou: journalctl --user -u chrome-debug -n 30

Extensão Não Carrega (Problema com Chrome Marcado)

Sintoma: O Chrome inicia limpo, mas os CAPTCHAs nunca são resolvidos — todos os envios falham.

Causa: Você está usando o Chrome Marcado 137+, que ignora silenciosamente --load-extension.

Solução: Mude para Chrome para Testes ou Chromium. Verifique seu binário:

/caminho/para/seu/chrome --version
# Chrome para Testes: "Chromium 143.0.7499.4"
# Chrome Marcado:    "Google Chrome 143.0.7499.109"  ← não funciona

CAPTCHA Não Resolvido (Formulário Falha)

Possíveis causas:

1. Tempo de espera insuficiente — Aumente para 60 segundos
2. Chave da API da CapSolver inválida — Verifique seu painel da CapSolver
3. Saldo insuficiente — Recarregue sua conta da CapSolver
4. Rede de fundo desativada — Certifique-se de que não há flag --disable-background-networking nas suas flags do Chrome (ela impede as chamadas de API da extensão)
5. Chrome Marcado — veja acima

Timeout no Navegador na Primeira Ação Após Reiniciar

Sintoma: A primeira ação do navegador após uma reinicialização do Hermes falha com timeout, mas as ações subsequentes funcionam normalmente.

Causa: A negociação CDP inicial pode exceder o timeout padrão do Hermes. Ações subsequentes reutilizam o WebSocket aquecido e são rápidas.

Solução: Tente novamente o comando uma vez. Se persistir, aumente browser.inactivity_timeout em config.yaml.

Chrome Crasha Após Trocar de Binários

Sintoma: Após mudar de uma versão do Chrome para outra, o Chrome crasha com erros de cache de disco.

Causa: O user-data-dir foi criado por uma versão diferente do Chrome e agora é incompatível.

Solução:

# 1. Pare o processo atual do chrome-debug (como você o supervisar)
pkill -f "remote-debugging-port=9222"

# 2. Limpe o perfil obsoleto
rm -rf ~/.hermes/chrome-debug

# 3. Reinicie o chrome-debug (via seu gerenciador de processos, ou reinicie o script)
nohup ~/.hermes/chrome-debug.sh > /tmp/chrome-debug.log 2>&1 &

Worker de Serviço da CapSolver Não Aparece em /json/list

Sintoma: curl http://127.0.0.1:9222/json/list retorna apenas entradas de page, sem service_worker.

Causa: Os service workers do Chrome MV3 entram em inatividade de forma agressiva, e em builds recentes do Chrome, o endpoint /json/list pode não mostrar nenhum deles — mesmo enquanto estão ativamente tratando eventos.

Solução: Isso não é diagnóstico. Não dependa de /json/list para confirmar que a CapSolver está carregada. Em vez disso, navegue o agente para uma página real protegida por reCAPTCHA (ex.: https://www.google.com/recaptcha/api2/demo) e observe se o envio do formulário é bem-sucedido. Um envio bem-sucedido é a prova de que a extensão está carregada e resolvendo os desafios; uma entrada ausente na lista de alvos não é um sinal de falha.

Boas Práticas

1. Sempre Use Tempos de Espera Generosos

Mais tempo de espera é sempre mais seguro. O CAPTCHA geralmente é resolvido em 5–20 segundos, mas latência de rede, desafios complexos ou tentativas podem adicionar tempo. 30–60 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 e depois envie o formulário"
Frasagem natural funciona melhor com o agente e tende a ser mais amigável com modelos ajustados para segurança — palavras adversarias em torno de CAPTCHAs foram observadas para causar recusas em alguns modelos da classe GLM.

3. Monitore seu saldo do CapSolver

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

4. Use um diretório de dados de usuário dedicado

Nunca aponte --user-data-dir para seu perfil real do Chrome. Use ~/.hermes/chrome-debug (que o próprio Hermes também aponta por padrão com /browser connect). Dessa forma, o navegador do agente fica totalmente isolado do seu navegação pessoal.

5. Vincule o CDP apenas ao loopback

--remote-debugging-address=127.0.0.1 é não opcional em produção. O Protocolo de Ferramentas de Desenvolvimento do Chrome dá controle total do navegador a qualquer pessoa que consiga acessar a porta. Nunca expor a porta 9222 em uma rede pública.

6. Use o Xvfb em servidores sem interface gráfica

Extensões do Chrome exigem um contexto de tela, mesmo quando você não quer ver o navegador. Em um servidor Linux sem tela física, execute uma tela virtual:

# Instale o Xvfb (Ubuntu/Debian)
sudo apt-get install xvfb

# Inicie uma tela virtual
Xvfb :99 -screen 0 1920x1080x24 &

# Informe ao Chrome que ele deve usá-la (o launcher chrome-debug.sh já define DISPLAY=:99)
export DISPLAY=:99

Se você estiver usando o launcher chrome-debug.sh da Etapa 3, a linha export DISPLAY=:99 no topo já trata disso — certifique-se apenas de que Xvfb :99 esteja rodando no host.

7. Supervisione o Chrome com um gerenciador de processos em produção

Um chrome & solto morrerá quando o shell pai sair, quando o Chrome travar ou quando o servidor reiniciar. Envolva a execução no chrome-debug.sh (Etapa 3) e supervisione-o com qualquer ferramenta que você já use para o restante da sua pilha — systemd, supervisord, runit, Docker, etc. A integração é independente do gerenciador de processos; escolha aquele que já roda no host.

8. Use um modelo barato

Como o modelo nunca vê o CAPTCHA — a extensão o resolve de forma invisível — você não precisa de um modelo de ponta para trabalhos com muitos CAPTCHAs. Um modelo barato e capaz é suficiente (ex.: defina provider: openrouter e default: z-ai/glm-4.6 no config.yaml). Todo o inteligência está na extensão; o modelo só precisa navegar, digitar e clicar.

9. Confie no histórico

A mesma infraestrutura do CapSolver que alimenta esta integração com Hermes já resolve reCAPTCHA v2/v3, Cloudflare Turnstile e desafios AWS WAF em pipelines de automação de produção — não é uma solução pontual costurada para este tutorial, é a mesma camada de resolução que equipes já usam para raspagem e automação de QA em larga escala.

Conclusão

A integração Hermes + CapSolver representa uma abordagem fundamentalmente nova para resolução de CAPTCHAs em fluxos de trabalho de agentes. Em vez de escrever código para detectar CAPTCHAs, chamar APIs e injetar tokens, você simplesmente:

1. Inicie o Chrome uma vez com --load-extension=/caminho/absoluto/para/capsolver-extension e --remote-debugging-port=9222
2. Adicione cdp_url no bloco browser: em ~/.hermes/config.yaml:
   yaml Copy

   browser:
     cdp_url: http://127.0.0.1:9222

   (note a chave aninhada — cdp_url no nível superior é ignorado silenciosamente)
3. Converse com seu agente naturalmente — inclua um tempo de espera antes de submeter formulários
4. Leia o resultado normal da página após o envio do formulário

A extensão do Chrome do CapSolver cuida do restante — detectando CAPTCHAs, resolvendo-os via API do CapSolver e injetando tokens na página. Seu agente nunca precisa saber sobre CAPTCHAs de nenhuma forma.

Essa é a aparência da resolução de CAPTCHAs quando você tem um agente de IA autônomo: invisível, automática e sem código.

Pronto para começar? Registre-se no CapSolver e use o código de bônus herme para obter bônus em sua primeira recarga!

Perguntas frequentes

Eu preciso informar o agente sobre o CapSolver?

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

Por que não posso usar o Google Chrome normal?

O Google Chrome 137+ (lançado no meio de 2025) removeu o suporte ao sinalizador de linha de comando --load-extension em builds oficiais. Isso significa que extensões do Chrome não podem ser carregadas em sessões automatizadas. Você precisa do Chrome para Testes ou do Chromium autônomo, que ainda suportam esse sinalizador.

Posso usar os provedores de navegador da nuvem do Hermes (Browserbase, Browser Use) em vez disso?

Não — provedores de nuvem executam o navegador em outra infraestrutura, então você não pode carregar extensões arbitrárias na sessão. O padrão de anexação do CDP neste guia é a única forma de combinar o Hermes com uma extensão do Chrome. (Assim que browser.cdp_url for definido em config.yaml, o Hermes roteia o tráfego do navegador para o Chrome local e os provedores de nuvem ficam silenciosos até que você remova a linha.)

Posso usar outros navegadores além do Chrome para Testes?

Sim — qualquer navegador baseado em Chromium que ainda suporte --load-extension funciona. Você pode usar:

• Chrome para Testes (recomendado — o que este guia usa)
• Chromium (build autônomo)
• Chromium embutido no Playwright (já está no seu sistema se você já executou npx playwright install)
• Brave, Vivaldi, Opera — todos baseados em Chromium, todos aceitam o sinalizador
• Google Chrome antigos ≤ 136 — mas o sinalizador foi removido no 137+, então não use versões antigas

A receita de integração é a mesma: aponte --remote-debugging-port=9222 --load-extension=/caminho/para/capsolver-extension para o binário que preferir.

O que não funciona:

• Google Chrome 137+ — ignora silenciosamente --load-extension
• Microsoft Edge — mesmo remoção aplicada
• Navegadores baseados em Firefox (Firefox, LibreWolf, Camoufox) — a extensão do CapSolver é no formato MV3 do Chrome, não WebExtensions do Firefox
• Provedores de navegador da nuvem do Hermes (Browserbase, Browser Use, Firecrawl) — você não controla o binário remoto, então não há como carregar uma extensão personalizada

O que sobre o Camoufox? O Hermes suporta ele.

Sim — o Camoufox é um dos cinco provedores de navegador integrados do Hermes, e é uma excelente opção de stealth com Firefox para tarefas que não envolvem uma extensão do Chrome. A pegada é que o Camoufox é baseado em Firefox, e a extensão do CapSolver é no formato MV3 do Chrome — então os dois não podem ser usados juntos em uma mesma sessão.

Boa notícia: com o Hermes, você não precisa escolher permanentemente. A configuração browser.cdp_url em ~/.hermes/config.yaml é uma única chave — aponte-a para o Chrome com o CapSolver quando precisar de resolução de CAPTCHA, e aponte para o Camoufox quando precisar de stealth do Firefox. Um setup típico mantém ambos rodando:

# Linha ativa: mude entre perfis comentando/uncomentando
browser:
  cdp_url: http://127.0.0.1:9222          # Chrome com CapSolver (este guia)
  # cdp_url: http://127.0.0.1:9333        # Endpoint do Camoufox

Em seguida, reinicie o Hermes (hermes gateway run, ou dispare uma reinicialização através do supervisador que você usa no seu host) e a troca acontece em segundos. O mesmo Hermes, os mesmos canais, as mesmas habilidades — navegador diferente por workload.

O comando /browser connect do Hermes funciona com esta configuração?

Sim. O comando slash /browser connect integrado ao Hermes (na interface TUI interativa hermes) aponta para o mesmo diretório de dados de usuário padrão que usamos (~/.hermes/chrome-debug) e mesma porta (9222). Uma vez que o sidecar do chrome-debug esteja configurado, você pode usar /browser connect interativamente dentro do Hermes, ou deixar browser.cdp_url em config.yaml para anexação permanente — ambos funcionam contra o mesmo Chrome.

O que sobre usar o Hermes através de canais de mensagens?

A integração é totalmente independente de canais. Assim que browser.cdp_url for definido em config.yaml, toda ação de navegador — seja vinda do hermes -z na CLI, da interface TUI interativa hermes, ou de uma mensagem do Telegram, Discord, Slack, WhatsApp, Signal ou e-mail — roteia pelo Chrome com CapSolver. A extensão resolve CAPTCHAs da mesma forma em todos os casos.

Devo usar a página de demonstração do Google em testes automatizados?

Use a página de demonstração apenas como um teste rápido. Na FAQ oficial do reCAPTCHA do Google, eles recomendam criar chaves de site dedicadas para testes automatizados em vez de depender da página de demonstração pública em pipelines de produção.

Quais tipos de CAPTCHA o extensão do CapSolver suporta?

A extensão do Chrome do CapSolver resolve automaticamente reCAPTCHA v2 (checkbox e invisível), reCAPTCHA v3, Cloudflare, AWS WAF CAPTCHA e outros widgets amplamente utilizados. O script de conteúdo detecta o tipo de CAPTCHA na página e o resolve conforme necessário — nenhuma configuração por tipo do seu lado. (Nota: Cloudflare Turnstile e Cloudflare 5-second Challenge não são resolvidos pela extensão do navegador; estão disponíveis apenas através da API do CapSolver e estão fora do escopo deste guia.)

Quanto custa o CapSolver?

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

O Hermes Agent é gratuito?

O Hermes Agent é de código aberto (github.com/NousResearch/hermes-agent) e gratuito para rodar em seu próprio hardware. Você precisará de chaves de API para o provedor de modelo de IA de sua escolha (OpenRouter é recomendado — o Hermes suporta mais de 200 modelos através dele) e, para resolução de CAPTCHA, uma conta no CapSolver com créditos.

Quanto tempo devo dizer ao agente para esperar?

Para a maioria dos CAPTCHAs, 30–60 segundos é suficiente. O tempo de resolução real geralmente é de 5–20 segundos, mas adicionar um buffer adicional garante confiabilidade. Se em dúvida, use 60 segundos.

Posso usar isso em um servidor sem interface gráfica?

Sim. Você precisará do Xvfb (X Virtual Framebuffer) para a tela, já que extensões do Chrome exigem um contexto de tela. Execute Xvfb :99 -screen 0 1920x1080x24 & no host e certifique-se de que DISPLAY=:99 esteja exportado no launcher chrome-debug.sh (o launcher da Etapa 3 já faz isso). Além disso, mantenha --no-sandbox nos argumentos do Chrome, já que a maioria dos kernels de servidor não concede as capacidades que o sandbox do Chrome exige.

Posso executar múltiplas instâncias do Hermes apontando para o mesmo chrome-debug?

Tecnicamente sim, mas você terá que gerenciar a concorrência de guias/sessões sozinho. Para a maioria dos workloads, uma única instância do Hermes ↔ chrome-debug é a configuração mais limpa. Se você precisar de paralelismo verdadeiro, execute múltiplos sidecars do chrome-debug em portas diferentes (9222, 9223, ...) e aponte cada Hermes para o seu próprio.

Isso funciona com Skills do Hermes?

Sim. Skills do Hermes são memórias procedurais — sequências de passos que o agente aprendeu. Uma skill que envolva navegar em sites com CAPTCHA será automaticamente beneficiada pela integração do CapSolver da mesma forma que uma mensagem ad-hoc, porque é a ferramenta de navegador que está sendo aprimorada. Nenhuma alteração na skill é necessária.