PinchTab + CapSolver: Tratamento de CAPTCHA para Agentes de Navegador

TL;DR

• A versão 0.15.2 do PinchTab inclui um registro do AutoSolver que pode carregar o CapSolver quando autoSolver.external.capsolverKey é configurado.
• Mantenha o PinchTab vinculado ao loopback, exija seu token de servidor e limite a navegação do navegador para domínios aprovados para sua tarefa de automação.
• Use GET /solvers para confirmar o registro do provedor antes de chamar POST /solve/capsolver ou uma rota de solução com escopo de aba.
• Trate solved: true como o resultado da etapa do desafio, não como prova de que a forma, teste ou tarefa de dados original teve sucesso.
• A integração deve parar após tentativas limitadas e passar o controle para uma pessoa quando o tipo de desafio, sessão ou limite de autorização for incerto.

O PinchTab fornece um plano de controle compacto HTTP, CLI e MCP para o Chrome. Camada atual do AutoSolver também pode registrar provedores externos, incluindo o CapSolver, para que um fluxo de trabalho autorizado do navegador possa resolver um CAPTCHA suportado sem ensinar o modelo payloads de API brutos.

Este guia mostra como configurar o CapSolver no PinchTab, verificar o serviço local, chamar um solucionador nomeado e manter a verificação final fora do solucionador. Os exemplos usam a versão 0.15.2 do PinchTab e credenciais de substituição. Eles são destinados a QA, RPA e fluxos de trabalho de dados públicos que você tem permissão para automatizar.

O que a Integração PinchTab e CapSolver Permite

A integração PinchTab e CapSolver adiciona uma etapa de tratamento de CAPTCHA nomeada a uma sessão do navegador que o PinchTab já controla.

A documentação do AutoSolver do PinchTab descreve um registro de solucionadores internos e externos. O provedor capsolver é habilitado pelo campo de configuração autoSolver.external.capsolverKey. O PinchTab mantém a aba ativa e o estado do navegador, enquanto o provedor externo lida com a tarefa de desafio suportada.

Essa separação é importante para agentes de navegador. O agente não deve inventar tipos de tarefa, copiar credenciais em prompts ou assumir que uma solução retornada completou a ação comercial. O PinchTab detém a sessão da página. O CapSolver retorna o resultado do desafio documentado. Sua aplicação ainda decide se continua, tenta novamente, para ou solicita revisão humana.

Pré-requisitos

Você precisa do seguinte antes de configurar a integração:

• PinchTab 0.15.2 ou uma versão posterior cujos anúncios de lançamento e referência de solucionador ainda documentem os mesmos campos.
• Chrome ou outro runtime Chromium compatível com o PinchTab.
• Uma conta e chave de API do CapSolver armazenadas fora do controle de código-fonte.
• Um perfil de navegador dedicado e de baixo privilégio para o fluxo de trabalho.
• Uma página de teste que você possua ou que tenha autorização explícita para apresentar um desafio suportado.

O guia de segurança do PinchTab recomenda um token de servidor, vinculação ao loopback e controle de domínios. Essas medidas de segurança são relevantes mesmo em uma máquina local, pois qualquer processo local que possa acessar o plano de controle pode, de outra forma, controlar o navegador.

A execução de verificação para este artigo usou o binário oficial do PinchTab 0.15.2 para macOS ARM64. O binário retornou pinchtab 0.15.2, e sua rota /health autenticada retornou HTTP 200 com authRequired: true. Um desafio pago completo não foi submetido porque este ambiente não tinha uma chave do CapSolver aprovada ou um alvo de CAPTCHA autorizado.

Instale o PinchTab e Confirme a Versão

Instale o PinchTab a partir do lançamento oficial ou pelo método de instalação documentado pelo projeto, depois confirme o binário que está executando.

pinchtab version

Saída esperada para a versão verificada neste guia:

pinchtab 0.15.2

Inicialize um arquivo de configuração dedicado em vez de modificar uma configuração de navegador pessoal usada para trabalho não relacionado.

export PINCHTAB_CONFIG="$PWD/pinchtab-config.json"
pinchtab config init

config init cria um token de servidor. Não imprima esse token em logs de CI ou comprometa o arquivo resultante.

Configure o CapSolver no AutoSolver do PinchTab

Configure o CapSolver sob autoSolver.external, e mantenha o servidor de controle do navegador em 127.0.0.1 a menos que você tenha um design de acesso remoto revisado.

{
  "server": {
    "bind": "127.0.0.1",
    "port": "9867",
    "token": "PINCHTAB_SERVER_TOKEN"
  },
  "security": {
    "allowedDomains": ["qa.example.com"],
    "idpi": {
      "enabled": true,
      "strictMode": true,
      "scanContent": true,
      "wrapContent": true
    }
  },
  "autoSolver": {
    "enabled": true,
    "autoTrigger": false,
    "triggerOnNavigate": false,
    "triggerOnAction": false,
    "maxAttempts": 3,
    "solverTimeoutSec": 30,
    "retryBaseDelayMs": 500,
    "retryMaxDelayMs": 5000,
    "solvers": ["capsolver", "cloudflare", "semantic"],
    "llmFallback": false,
    "external": {
      "capsolverKey": "CAPSOLVER_API_KEY"
    }
  }
}

Use seu gerenciador de segredos para injetar os valores reais na configuração em tempo de execução. Os espaços reservados acima não são credenciais utilizáveis.

Começar com gatilhos automáticos desativados torna o primeiro teste mais fácil de auditar. Você pode chamar o solucionador nomeado apenas quando sua aplicação classificar a página como um ponto de verificação aprovado. Após o fluxo de trabalho estar estável, avalie os gatilhos automáticos separadamente e mantenha os mesmos limites de tentativa e tempo limite.

Resgate seu código promocional do CapSolver

Aumente seu orçamento de automação instantaneamente!
Use o código promocional CAP26 ao recarregar sua conta do CapSolver para obter um bônus adicional de 5% em cada recarga — sem limites.
Resgate-o agora em seu Painel do CapSolver

Inicie o Servidor e Verifique o Registro do Provedor

Verifique o plano de controle e o registro do solucionador antes de abrir o fluxo de trabalho alvo.

Inicie o PinchTab com a configuração dedicada:

PINCHTAB_CONFIG="$PWD/pinchtab-config.json" pinchtab server

Em um segundo terminal, leia o token do servidor da sua loja de segredos e chame a rota de saúde local:

curl -sS \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  http://127.0.0.1:9867/health

Uma resposta saudável relata status: "ok". Espere até que a instância do navegador padrão esteja pronta antes de verificar a lista de solucionadores.

curl -sS \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  http://127.0.0.1:9867/solvers

A referência da rota de solução do PinchTab afirma que capsolver está incluído quando sua chave de API é configurada. Se estiver ausente, verifique o caminho da configuração ativa, reinicie o serviço e confirme que a chave foi injetada no processo que iniciou o PinchTab.

Chame o CapSolver para a Aba Ativa

Chame a rota nomeada capsolver quando a aba ativa atingir uma página de desafio autorizada.

curl -sS -X POST \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  http://127.0.0.1:9867/solve/capsolver \
  -d '{"maxAttempts": 3, "timeout": 30000}'

Para uma aba específica, use a rota com escopo de aba para que agentes concorrentes não atuem sobre a aba que estiver ativa:

curl -sS -X POST \
  -H "Authorization: Bearer $PINCHTAB_TOKEN" \
  -H "Content-Type: application/json" \
  "http://127.0.0.1:9867/tabs/TAB_ID/solve/capsolver" \
  -d '{"maxAttempts": 3, "timeout": 30000}'

A resposta documentada inclui o ID da aba, o nome do solucionador, o sinalizador de resolvido, o tipo de desafio, a contagem de tentativas e o título da página final. Armazene esses campos com o ID de correlação da tarefa do navegador. Não armazene a chave de API ou os artefatos de desafio retornados em logs de aplicativos comuns.

Verifique a Tarefa Original do Navegador

A tarefa original do navegador precisa de sua própria verificação após a etapa do desafio retornar.

Para um fluxo de QA, verifique a URL esperada, o título da página, o estado autenticado ou o resultado do formulário na mesma aba. Para um fluxo de dados, valide que o esquema de registro esperado esteja presente e que a resposta não seja outra página de desafio ou erro. Um título de navegador sozinho não é suficiente.

Use uma pequena máquina de estados em vez de tratar cada resposta sem erro como sucesso:

A documentação de resultado da tarefa do CapSolver distingue uma tarefa de processamento de um resultado pronto. O PinchTab abstrai essa interação do provedor, mas sua aplicação ainda deve impor o prazo geral do fluxo de trabalho e a regra de aceitação final.

Problemas Comuns

capsolver não aparece em /solvers

O processo ativo do PinchTab provavelmente está usando um arquivo de configuração diferente, não foi reiniciado ou não recebeu a chave de API externa. Confirme PINCHTAB_CONFIG, reinicie o servidor e consulte o registro novamente sem imprimir o segredo.

/solvers retorna 503

A instância do navegador do PinchTab pode ainda estar iniciando ou reiniciando. Verifique /health, inspecione o estado da instância e confirme que o binário do Chromium configurado pode ser iniciado com o perfil selecionado.

O solucionador relata sucesso, mas o formulário ainda falha

A página pode ter navegado, o token pode pertencer a um contexto de navegador diferente ou a aplicação pode ter rejeitado a ação original. Mantenha a propriedade da aba estável e verifique o resultado comercial após o tratamento do desafio.

O agente fica preso no mesmo desafio

A resolução repetida não deve ser ilimitada. Mantenha maxAttempts pequeno, preservando a primeira evidência de falha e mova o fluxo de trabalho para needs_review quando o mesmo ponto de verificação retornar.

O fluxo de trabalho chega a login, 2FA ou verificação de conta

O tratamento de CAPTCHA não autoriza a entrada de credenciais, criação de conta, verificação de telefone ou acesso a dados restritos. Parem e solicitem ação humana sob a política normal de acesso da aplicação.

Conclusão

O PinchTab já expõe a costura de integração necessária para usar o CapSolver como um solucionador externo nomeado. Um ambiente de produção deve manter o servidor local ou fortemente autenticado, restringir domínios alvo, vincular cada solução a uma aba específica, limitar tentativas e verificar o resultado da página original.

Use o CapSolver apenas em fluxos que você tem permissão para automatizar. O resultado do provedor é uma etapa controlada na máquina de estados do navegador, não um sinal geral para continuar.

Adicione o Tratamento Controlado de CAPTCHA ao seu Fluxo de Trabalho do Agente do Navegador

Crie uma conta no CapSolver, teste a integração do PinchTab em uma página de QA própria e mantenha a chave de API no seu armazenamento de segredos em tempo de execução. Comece com chamadas de solucionador manuais e um orçamento de tentativas rigoroso antes de habilitar qualquer gatilho automático.

Perguntas Frequentes

Q: O PinchTab suporta diretamente o CapSolver?

Sim. A documentação do AutoSolver do PinchTab e a referência de solução listam capsolver como um provedor externo habilitado por autoSolver.external.capsolverKey.

Q: Posso usar o CapSolver através do MCP do PinchTab?

O PinchTab expõe o controle do navegador através do MCP, enquanto as rotas do AutoSolver HTTP lidam com solucionadores nomeados. Confirme a superfície exata da ferramenta na versão instalada do PinchTab e mantenha a invocação do solucionador dentro de um fluxo de trabalho limitado.

Q: Devo habilitar a resolução automática imediatamente?

Não. Comece com chamadas explícitas em uma página de teste aprovada, verifique a resposta com escopo de aba e adicione gatilhos automáticos apenas após ter regras claras de detecção, parada e auditoria.

Q: O que solved: true comprova?

solved: true relata o resultado da etapa do desafio. Sua aplicação ainda deve verificar se a navegação original, submissão do formulário, afirmação do teste ou solicitação de dados teve sucesso.

Q: O que o agente deve fazer quando o tipo de desafio for incompatível?

O agente deve parar após o orçamento de tentativas configurado e solicitar revisão humana. Ele não deve improvisar campos de provedor, mudar para um alvo não aprovado ou continuar para login, 2FA ou verificação de identidade.