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

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

Hermes Agent da Nous Research é um agente de IA autossustentável que roda 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 em 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 preso em CAPTCHAs.

CapSolver muda isso completamente. Ao carregar a extensão CapSolver no navegador que o Hermes se conecta, os CAPTCHAs são resolvidos automaticamente e invisivelmente em segundo plano. Nenhum código. Nenhuma chamada de API do seu lado. Nenhum exercício de 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 reproduz 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: Converse com seu agente pelo 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 Ferramentas de Desenvolvedor do Chrome

A Ferramenta de Navegador

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

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 alimentadas por IA para contornar desafios modernos de CAPTCHA. Com suporte para todos os principais tipos de CAPTCHA e tempos de resposta rápidos, o CapSolver se integra perfeitamente a fluxos automatizados — seja você controlando um navegador via Playwright, chamando sua API diretamente ou, como neste guia, executando sua extensão 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 requer 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 CapSolver roda no navegador conectado. O Hermes se conecta a esse navegador pelo CDP e o controla normalmente. Quando o agente navega até uma página com um CAPTCHA, a extensão — rodando no mesmo Chrome, completamente invisível ao agente — detecta o widget, chama a API 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 para "resolver 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.

Pré-requisitos

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 CapSolver com chave de API (inscreva-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 nas versões marcadas. 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 seguintes alternativas:

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 para o binário — você precisará dele 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 CapSolver carregada previamente e o CDP exposto em uma porta conhecida (usaremos 9222).
2. Uma pequena alteração no config.yaml do Hermes para dizer a ele para 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 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 lugar certo.

Dica sobre caminhos: Use um caminho absoluto, resolvido (não ~) ao passar --load-extension=... para o Chrome posteriormente. Alguns builds do Chrome MV3 têm casos especiais onde os trabalhadores de extensão falham em registrar-se por meio de links simbólicos em diretórios de dados de usuário personalizados. Se você estiver vinculando 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 próprio:

export const defaultConfig = {
  apiKey: 'CAP-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',  // ← seu chave aqui
  useCapsolver: true,
  enabledForRecaptcha: true,
  enabledForRecaptchaV3: true,
  // ... rest of config
};

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 prévia a extensão CapSolver
• --user-data-dir=... — usa um perfil dedicado para que não colida 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 automaticamente" sem flags adicionais.

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ão do Chrome requer 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 CapSolver carregada previamente
# 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 forma mais simples de lançamento persistente é apenas:

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

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

[Unit]
Descrição=Chrome equipado 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 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: Diga 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 diz ao ferramenta browser_cdp do Hermes para rotear todas as operações do navegador através do Chrome que você lançou 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 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 pegue o novo cdp_url:

# Rodando 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 em uma única etapa:

hermes doctor

Você está procurando por esses sinais:

◆ Disponibilidade de Ferramentas
  ✓ browser-cdp        ← Anexação CDP está ativa
  ✓ browser
  ...

◆ Conectividade de API
  Verificando API OpenRouter...  ✓ API 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 worker de serviço CapSolver: Os workers de serviço do Chrome MV3 entram em inatividade de forma agressiva, e em builds recentes do Chrome, o /json/list pode omiti-los completamente, mesmo enquanto estão em execução. A ausência no /json/list não é diagnóstico — confirme que o CapSolver está funcionando carregando uma página real de reCAPTCHA através do agente e observando o resultado do widget na página, não polindo a lista de destinos.

Como Usar

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

A Regra Dourada

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

O agente não precisa saber sobre CAPTCHAs. A extensão lida com 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 uma única execução

O modo de uma única execução 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 ser totalmente carregada. Em seguida, clique no botão rotulado "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 Chrome via CDP
2. O agente navega até a página de demonstração do reCAPTCHA da Google
3. O script de conteúdo do CapSolver (executado dentro do Chrome) detecta o widget de reCAPTCHA
4. O worker de serviço da extensão chama a API do CapSolver e resolve o desafio (geralmente em 5–15 segundos)
5. O token é injetado no campo oculto do formulário g-recaptcha-response
6. Após 60 segundos, o agente clica em Enviar
7. O servidor da Google valida o token e retorna a 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!" é a mensagem de confirmação própria da Google — ela só aparece quando um token válido de reCAPTCHA é 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 o 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 diz — 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 é praticamente gratuito — sua fatura do CapSolver é por resolução, não por segundo.

Padrões de Linguagem Natural que Funcionam

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

• "Vá para [URL], espere 60 segundos e depois envie o formulário"
• "Navegue até [URL], preencha [campos], espere 30 segundos e 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 ser totalmente carregada, 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 segurança ajustada (notavelmente a família GLM):

• "Espere pela resolução do CAPTCHA" (o agente não sabe sobre CAPTCHAs)
• "Use o CapSolver para resolver a verificação" (o agente não controla as extensões)
• "Clique na caixa de seleção do reCAPTCHA" (a extensão lida com isso — clicar pode interferir)
• "Bypass a verificação de segurança" (parece adversarial — alguns modelos recusam)

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"           │
                                ▼
                           ferramentas do navegador / browser_cdp
                                │  (conecta via WebSocket
                                │   para ws://127.0.0.1:9222)
                                ▼
                           ┌────────────────────────────────────┐
                           │  chrome-debug Chromium (background)│
                           │                                     │
                           │  ┌───────────────────────────────┐ │
                           │  │ Extensão CapSolver MV3        │ │
                           │  │ (carregada via --load-extension; │ │
                           │  │  requer Chrome para Testes    │ │
                           │  │  ou Chromium — Chrome 137+ ignora esse sinal) │ │
                           │  │                                │ │
                           │  │ 1. script de conteúdo detecta CAPTCHA │
                           │  │ 2. worker de serviço chama API do CapSolver │
                           │  │ 3. token recebido              │ │
                           │  │ 4. token injetado no campo do formulário │ │
                           │  └───────────────────────────────┘ │
                           └────────────────────────────────────┘
                                │
                                ▼
                           O agente Hermes espera 60 segundos...
                                │
                                ▼
                           browser_cdp: clique em Enviar
                                │
                                ▼
                           Formulário é enviado com token válido
                                │
                                ▼
                           Página de confirmação após o envio

Por Que Usar CDP em vez de "Apenas Passar uma Lista de Extensões"?

A camada de ferramentas do navegador do Hermes é baseada em cinco provedores intercambiáveis (Browserbase, Browser Use, Firecrawl, Camoufox, Chromium headless). Três desses são baseados em nuvem — você não controla o binário do navegador, então não há lugar para colocar a flag --load-extension. Um (Camoufox) é baseado em Firefox. O quinto — CDP attach — é o único ponto onde um Chromium controlado pelo usuário pode ser conectado.

A compensação é excelente: o Hermes permanece portável na nuvem por padrão, mas no momento em que você quiser poderes avançados no navegador (CapSolver, seu próprio bloqueador de anúncios, ferramentas MV3 personalizadas, cookies persistentes, você nomeia), você inicia o Chrome manualmente e aponta o Hermes para ele. Uma linha de configuração. Total controle.

O Que --load-extension Realmente Faz

Quando o Chrome é iniciado com --load-extension=/caminho/para/extension, ele trata esse diretório como uma extensão não compactada — o mesmo mecanismo que o modo de desenvolvedor do Chrome usa. A extensão é registrada exatamente como se você tivesse instalado a extensão da Chrome Web Store. Não há diferença de sandboxing, nenhum acesso reduzido às 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 por widgets de CAPTCHA conhecidos — reCAPTCHA, hCaptcha, FunCaptcha, 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 do 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 da página via script de conteúdo
5. Pelo momento em que o agente clica em Enviar, o formulário já carrega um token válido

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

Nota de ambiente: Evite --disable-background-networking nos seus flags do Chrome. Ele bloqueia as requisições de saída do worker de serviço do CapSolver — assim, a extensão nunca consegue acessar a API do CapSolver. A receita no Passo 3 omitiu intencionalmente esse sinal.

Referência Completa de Configuração

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

Todos os flags que você deve passar para o Chrome:

Lado do 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 do 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 só registra browser-cdp quando um endpoint CDP está 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 da Google 137+, que ignora silenciosamente --load-extension.

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

/caminho/para/seu/chrome --versão
# 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 do CapSolver inválida — Verifique seu painel do CapSolver
3. Saldo insuficiente — Recarregue sua conta do CapSolver
4. Rede de fundo desativada — Certifique-se de que não há sinal --disable-background-networking nos seus argumentos do Chrome (ele mata as chamadas de API da extensão)
5. Chrome Marcado — veja acima

Tempo de Espera do Navegador na Primeira Ação Após Reinicialização

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

Causa: O handshake 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 o comando novamente uma vez. Se persistir, aumente browser.inactivity_timeout em config.yaml.

Chrome Crasha Após Trocar de Binários

Sintoma: Após trocar 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 supervisiona)
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 do CapSolver Não Aparece em /json/list

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

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

Solução: Isso não é diagnóstico. Não confie no /json/list para confirmar que o CapSolver está carregado. Em vez disso, navegue o agente até 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 destinos 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á para 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 adversárias 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 do usuário dedicado

Nunca aponte --user-data-dir para o seu perfil real do Chrome. Use ~/.hermes/chrome-debug (que o próprio Hermes também usa por padrão com o /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 quem conseguir acessar a porta. Nunca exponha a porta 9222 a uma rede pública.

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

Extensões do Chrome exigem um contexto de tela, mesmo que você não queira 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 já está definida — certifique-se apenas de que Xvfb :99 esteja em execução 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 inicialização no chrome-debug.sh (Etapa 3) e o supervise com o que você já usa para o restante da sua stack — systemd, supervisord, runit, Docker, etc. A integração é independente do gerenciador de processos; escolha aquele que já roda no host.

8. Combine com 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, capaz de ferramentas, é 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.

Conclusão

A integração Hermes + CapSolver representa uma abordagem fundamentalmente nova para resolver 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

   (observe a chave aninhada — cdp_url de nível superior é ignorado silenciosamente)
3. Converse com o seu agente naturalmente — inclua um tempo de espera antes das submissões de formulário
4. Leia o resultado normal da página após a submissão após o formulário ser enviado

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

Essa é a cara da resolução de CAPTCHA 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 promocional herme para obter um bônus na sua primeira recarga!

Perguntas Frequentes

Eu preciso informar o agente sobre o CapSolver?

Não. Na verdade, você deve evitar mencionar CAPTCHAs ou CapSolver em suas mensagens. A extensão funciona invisivelmente no fundo. 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 nas versões comercializadas. 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 navegadores em nuvem do Hermes (Browserbase, Browser Use) em vez disso?

Não — provedores em nuvem executam o navegador em infraestrutura de terceiros, 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 no config.yaml, o Hermes roteia o tráfego do navegador pelo Chrome local e os provedores em nuvem ficam inativos até você remover 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 (versão autônoma)
• Chromium integrado ao Playwright (já está no seu sistema se você já executou npx playwright install)
• Brave, Vivaldi, Opera — todos baseados em Chromium, todos aceitam o sinalizador
• Versões antigas do Google Chrome ≤ 136 — mas o sinalizador foi removido no 137+, então não use versões obsoletas

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

O que não funciona:

• Google Chrome comercial 137+ — ignora silenciosamente --load-extension
• Microsoft Edge — mesma remoção aplicada
• Navegadores baseados em Firefox (Firefox, LibreWolf, Camoufox) — a extensão do CapSolver é no formato Chrome MV3, não WebExtensions do Firefox
• Provedores de navegadores em 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 é construída no formato Chrome MV3 — então os dois não podem ser executados juntos em uma mesma sessão.

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

# 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        # Ponto de conexão do Camoufox

Em seguida, reinicie o Hermes (hermes gateway run, ou acione uma reinicialização através do que supervisiona o gateway no seu host) e a troca ocorre em segundos. O mesmo Hermes, os mesmos canais, as mesmas habilidades — navegador diferente por carga de trabalho.

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

Sim. O comando slash /browser connect integrado ao Hermes (na interface de linha de comando interativa hermes) aponta para o mesmo diretório de dados do usuário padrão que usamos (~/.hermes/chrome-debug) e para a mesma porta (9222). Assim que você configurar o sidecar do chrome-debug, pode usar /browser connect interativamente dentro do Hermes, ou pode deixar browser.cdp_url no config.yaml para conexã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 do canal. Assim que browser.cdp_url for definido no config.yaml, toda ação do navegador — seja vinda de hermes -z na CLI, da interface interativa hermes TUI, ou de uma mensagem do Telegram, Discord, Slack, WhatsApp, Signal ou e-mail — roteia pelo seu 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 a extensão do CapSolver suporta?

A extensão do CapSolver no Chrome resolve automaticamente reCAPTCHA v2 (checkbox e invisível), reCAPTCHA v3, hCaptcha, FunCaptcha, 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 é necessária por sua parte. (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 executar 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 por meio dele) e, para resolver CAPTCHAs, uma conta do CapSolver com créditos.

Quanto tempo devo dizer ao agente para esperar?

Para a maioria dos CAPTCHAs, 30–60 segundos é suficiente. O tempo real de resolução geralmente é de 5–20 segundos, mas adicionar um buffer extra 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á o faz). Também 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 requer.

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 por conta própria. Para a maioria das cargas de trabalho, uma única instância do Hermes ↔ uma única instância do chrome-debug é a configuração mais limpa. Se precisar de paralelismo real, execute múltiplos sidecars do chrome-debug em portas diferentes (9222, 9223, ...) e aponte cada Hermes para a sua própria.

Isso funciona com Skills do Hermes?

Sim. As 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, pois é a ferramenta do navegador que está sendo aprimorada. Nenhuma alteração na skill é necessária.