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

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

Hermes Agent da Nous Research é um agente de IA autoaperfeiçoável que funciona em qualquer lugar — de um VPS de $5 a um cluster de GPU — e alcança você em todos os canais que 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 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 em segundo plano. Nenhum código. Nenhuma chamada de API do seu lado. Nenhuma ginástica de engenharia de prompts.

O melhor de tudo? 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 desenvolvido pela Nous Research. Ele é projetado em torno de três princípios: memória persistente (lembra de você e dos seus projetos entre as sessões), criação de habilidades autônoma (aprende procedimentos a partir da experiência e os repete na próxima vez) e flexibilidade de infraestrutura (execute-o em um VPS pequeno, em um contêiner Docker, em um sandbox serverless ou em sua própria GPU).

Principais Funcionalidades

• Porta de canal múltiplo: Comunique-se com seu agente por 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 de sessão cruzada: Pesquisa de sessão FTS5 + resumo por LLM significa que o agente 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 + Chrome DevTools Protocol

A Ferramenta do Navegador

O Hermes pode controlar um navegador Chromium para realizar trabalhos reais — navegar, ler DOM, clicar, digitar, capturar tela, coletar dados. A camada de ferramenta do 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:

Fornecedores 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ê iniciou separadamente. É aí que o CapSolver se encaixa.

Este é um modelo diferente dos ferramentais como OpenClaw (que inicia seu próprio Chromium e aceita um browser.extensions array) 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 é o CapSolver?

CapSolver é um serviço líder de resolução de CAPTCHA que fornece soluções com inteligência artificial para contornar desafios de CAPTCHA modernos. Com suporte para todos os tipos principais de CAPTCHA e tempos de resposta rápidos, o CapSolver se integra perfeitamente em fluxos de trabalho automatizados — seja você estar 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 exige que você escreva código — criar chamadas de API, poliar por resultados, injetar 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 conectado. 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 para o 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 ter:

1. Hermes Agent instalado e o gateway rodando (instruções de instalação)
2. Uma conta no CapSolver com a 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 com 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ê precisa usar uma das alternativas abaixo:

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 SO

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 dois componentes trabalhando juntos:

1. Um processo separado do Chrome que você inicia com a extensão do CapSolver carregada 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 o último 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 e resolvido (não ~) ao passar --load-extension=... para o Chrome mais tarde. 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 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 de apiKey pela sua própria:

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

Você pode obter sua chave de API no 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 a extensão do CapSolver
• --user-data-dir=... — usa um perfil dedicado para que não haja conflito com o 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 único (bom para testes rápidos)

/caminho/para/chrome-para-testes/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-para-testes/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.), veja a seção Melhores Práticas abaixo para a configuração do Xvfb. O sistema de extensão do Chrome exige um contexto de tela.

Opção B: Processo em segundo plano persistente (recomendado para produção)

Para qualquer configuração que viva 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 processo que já use (systemd, supervisor, runit, OpenRC, Docker, etc.).

Salve isso como ~/.hermes/chrome-debug.sh e dê permissão de execução:

#!/usr/bin/env bash
# ~/.hermes/chrome-debug.sh
# Inicia o Chrome para Testes 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 as 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

O lançamento mais simples é apenas:

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

Para produção, supervise o script com o gerenciador de processo de sua preferência. Um serviço systemd mínimo em ~/.config/systemd/user/chrome-debug.service:

[Unit]
Description=Chrome com CapSolver para Hermes Agent
After=network.target

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

[Install]
WantedBy=default.target

Então:

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 que algo mantém 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 diz ao ferramenta browser_cdp do Hermes para redirecionar todas as operações de navegador para o Chrome que você iniciou na Etapa 3, em vez de iniciar o próprio.

Reversibilidade: Essa é a única alteração no Hermes. Para reverter, remova a linha cdp_url. O Hermes retorna para o fornecedor 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 rodando, reinicie-o para que ele pegue o novo cdp_url:

# Rodando diretamente (modo foreground ou sob seu supervisor):
hermes gateway run

# Ou reinicie via qualquer gerenciador de processo que você use para supervisionar o Hermes —
# a única exigência é que a nova env/config entre em vigor.

Etapa 6: Verifique a Configuração

O Hermes vem com um comando de diagnóstico interno 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        ← 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 ser observado.

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 de trabalho do CapSolver: os trabalhadores de serviço do Chrome MV3 entram em inatividade de forma agressiva, e em builds recentes do Chrome, /json/list pode omiti-los completamente, mesmo que estejam em execução. A ausência em /json/list não é diagnóstica — 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 verificando a lista de destino.

Como Usar

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

A Regra Dourada

Não mencione CAPTCHAs ou o CapSolver ao agente. Apenas dê tempo 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 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 que a página seja totalmente renderizada. Em seguida, clique no botão etiquetado 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 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 trabalhador 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 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 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.):

Acesse 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 seu agente, se conectará ao mesmo Chrome, preencherá o formulário, dará tempo à extensão resolver qualquer CAPTCHA na página de login, clicará em Entrar e responderá com o que a página após o login disser — tudo sem você mencionar CAPTCHAs alguma vez.

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, depois 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 do CapSolver é por solução, não por segundo.

Padrões de Linguagem Natural que Funcionam

Aqui estão frasings comprovados que você pode usar em qualquer um dos canais do Hermes:

• "Acesse [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 totalmente, depois envie"

O que NÃO Dizer

Evite essas frasings — elas podem confundir o agente e já 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 o 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 recusam)

Como Funciona por Baixo dos Panos

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

  Sua mensagem                  Gateway do Hermes
  ──────────────────────────────────────────────────────────
  "acesse a página,           ──►   O agente do Hermes recebe a mensagem
   espere 60s, envie"           │
                                ▼
                           browser_cdp / ferramentas do navegador
                                │  (conecta via WebSocket
                                │   ao 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 flag)           │ │
                           │  │                                │ │
                           │  │ 1. script de conteúdo detecta CAPTCHA │
                           │  │ 2. trabalhador de serviço chama API do CapSolver │
                           │  │ 3. token recebido               │ │
                           │  │ 4. token injetado no campo do formulário │ │
                           │  └───────────────────────────────┘ │
                           └──────────────────────────────────────┘
                                │
                                ▼
                           O agente do Hermes espera 60 segundos...
                                │
                                ▼
                           browser_cdp: clica em Enviar
                                │
                                ▼
                           O 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 colocar a flag --load-extension. Um (Camoufox) é baseado no Firefox. O quinto — anexar CDP — é a única forma onde um Chromium controlado pelo usuário pode ser conectado.

O equilíbrio é excelente: o Hermes permanece portável para a nuvem por padrão, mas assim que você quiser poderes de navegador (CapSolver, seu próprio bloqueador de anúncios, ferramentas MV3 personalizadas, cookies persistentes, etc.), você inicia o Chrome sozinho e aponta o Hermes para ele. Uma linha de configuração. Total controle.

O que a Flag --load-extension Realmente Faz

Quando o Chrome é iniciado com --load-extension=/caminho/para/a/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. A extensão é registrada exatamente como se você tivesse instalado a partir da Chrome Web Store. Não há diferença em termos de sandboxing, nem acesso reduzido às APIs — é uma extensão com privilégios completos.

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

1. Script de conteúdo (injetado em cada página) observa widgets de CAPTCHA conhecidos — reCAPTCHA, Cloudflare, AWS WAF, etc.
2. Quando um widget é detectado, o script de conteúdo envia uma mensagem ao trabalhador de serviço
3. O trabalhador 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 do formulário da página pelo script de conteúdo
5. Quando o agente clica em Enviar, o formulário já carrega um token resolvido válido

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

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

Referência de Configuração Completa

Lado 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 Chrome: argumentos --load-extension

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

Lado 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 alternâncias
};

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 na 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 de alcançabilidade (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 uma 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 inativo, 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 Comercial)

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

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

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

/caminho/para/seu/chrome --versão
# Chrome para Testes: "Chromium 143.0.7499.4"
# Chrome Comercial:    "Google Chrome 143.0.7499.109"  ← não funcionará

CAPTCHA Não Resolvido (Formulário Falha)

Causas possíveis:

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 — faça um recarregamento na conta do CapSolver
4. Rede de fundo desativada — certifique-se de que não há flag --disable-background-networking em seus argumentos do Chrome (ela mata as chamadas de API de saída da extensão)
5. Chrome Comercial — veja acima

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

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

Causa: O handshake CDP no início pode ocasionalmente 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. 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 trava com erros de cache no 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 &

O Trabalhador 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 trabalhadores 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 nenhum deles — mesmo que estejam ativamente lidando com eventos.

Solução: Isso não é diagnóstico. Não dependa de /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 desafios; a ausência de entrada na lista de destino 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 a latência da 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:

"Acesse a URL, espere cerca de um minuto, depois envie o formulário"
A frase natural funciona melhor com o agente e tende a ser mais amigável com modelos ajustados para segurança — palavras adversariais em torno de CAPTCHAs foram observadas para causar recusas em alguns modelos da classe GLM.

3. Monitore seu saldo no CapSolver

Cada resolução de CAPTCHA custa créditos. Verifique seu saldo regularmente em capsolver.com/dashboard 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 comando /browser connect integrado ao Hermes também usa por padrão). 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 fornece controle total do navegador a quem conseguir acessar a porta. Nunca exponha a porta 9222 para uma rede pública.

6. Use o Xvfb em servidores sem tela

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 rodando no host.

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

Um chrome & solto morre quando o shell pai termina, quando o Chrome crasha ou quando o servidor reinicia. Envolva a execução com chrome-debug.sh (Etapa 3) e monitore-o com qualquer gerenciador que já use 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 servidor.

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, com funcionalidades básicas, é 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 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 ao 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 enviar formulários
4. Leia o resultado normal da página após o envio do formulário

A extensão 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 jeito nenhum.

Este é o aspecto da resolução de CAPTCHA quando você tem um agente de IA autônomo: invisível, automático 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 na sua primeira recarga!

Perguntas Frequentes

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 de forma invisível 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 Chrome regular?

O Chrome 137+ (lançado no meio de 2025) removeu o suporte ao sinalizador de linha de comando --load-extension nas versões com marca. 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 independente, 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 infraestrutura de terceiros, então você não pode carregar extensões arbitrárias na sessão. O padrão CDP na esteira é 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 de 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 independente)
• 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
• Versões antigas do Google Chrome ≤ 136 — mas o sinalizador foi removido nas versões 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 preferir.

O que não funciona:

• Chrome da Google 137+ — ignora silenciosamente --load-extension
• Microsoft Edge — a mesma remoção foi 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 o suporta.

Sim — o Camoufox é um dos cinco provedores de navegador integrados ao Hermes e é uma excelente opção de stealth com Firefox para tarefas que não envolvam uma extensão do Chrome. O problema é que o Camoufox é baseado em Firefox e a extensão do CapSolver foi construída no formato MV3 do Chrome — então os dois não podem rodar 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 opção — aponte-a para o Chrome com CapSolver quando precisar de resolução de CAPTCHA, e para o Camoufox quando precisar de stealth do Firefox. Uma configuração típica mantém ambos rodando:

# Linha ativa: mude entre perfis comentando/eliminando o comentário
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 servidor) 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 (no TUI interativo hermes) aponta para o mesmo diretório de dados de usuário padrão que usamos (~/.hermes/chrome-debug) e para a mesma porta (9222). Assim que você configurar o sidecar 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.

Como funciona 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, todas as ações do navegador — se vierem de hermes -z na CLI, do TUI interativo hermes, ou de uma mensagem do Telegram, Discord, Slack, WhatsApp, Signal ou e-mail — serão roteadas pelo Chrome com CapSolver. A extensão resolve os 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 CapSolver resolve automaticamente reCAPTCHA v2 (caixa de seleção 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 de acordo — 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 com base no tipo de CAPTCHA e volume. Visite capsolver.com para 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 hardware próprio. 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 são suficientes. O tempo real de resolução é normalmente de 5–20 segundos, mas adicionar um buffer extra garante confiabilidade. Quando em dúvida, use 60 segundos.

Posso usar isso em um servidor sem tela?

Sim. Você precisará do Xvfb (X Virtual Framebuffer) para a tela, já que extensões do Chrome exigem 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 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 abas/sessões sozinho. 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 você precisar de paralelismo real, execute múltiplos sidecars do chrome-debug em portas diferentes (9222, 9223, …) e aponte cada Hermes para o seu próprio.

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 navegação em sites com CAPTCHA beneficiará automaticamente da integração com o CapSolver da mesma forma que uma mensagem ad-hoc, pois o próprio ferramenta de navegador é que está sendo aprimorado. Nenhuma alteração na skill é necessária.