O que você precisa saber antes de começar
A maior parte das pessoas que chega no capivara click faz isso porque viu um vídeo de 30 segundos mostrando o botão verde piscando. O resultado real é bem diferente. Funciona para quem tem paciência e um computador razoavelmente configurado, mas não é mágica e vai travar se você tentar rodar em coisa velha. Eu comecei a mexer com isso há uns dois anos, tentando automação de processos repetitivos em planilhas e sistemas legados. A primeira vez que rodei, o script quebrou porque o Python estava desatualizado e a biblioteca de automação de mouse não reconhecia as coordenadas corretamente. Gastei três horas até entender que era problema de resolução de tela — meu monitor secundário estava em 1440p enquanto o sistema esperava 1080p.
Por que as pessoas falam sobre capivara click
O nome vem de um projeto open-source no GitHub que combina manipulação de clique automático com algum tipo de inteligência artificial básica para reconhecimento de padrões na tela. O conceito principal é simples: você grava uma sequência de movimentos e cliques, o sistema salva esse padrão como macro, e depois replica exatamente o que foi gravado quando acionado. O diferencial dele em relação a outras ferramentas parecidas é que ele usa visão computacional leve para ajustar a posição dos cliques quando a interface muda levemente. Isso significa que se um menu desceu dois pixels depois de uma atualização, o sistema consegue encontrar o botão certo sem quebrar completamente.
Como instalar e configurar
Você precisa ter Python 3.10 ou superior rodando na máquina. Se estiver usando Linux, provavelmente já tem. No Windows, baja o instalador oficial do site do Python e marque a opção "Add Python to PATH" antes de instalar. Isso economiza um tempo significativo de configuração depois. Depois disso, rode os comandos abaixo no terminal:
pip install opencv-python numpy pyautogui pillow Clone o repositório do capivara click e entre na pasta. Vá em config.yaml e ajuste as configurações básicas: resolução da tela, delay entre cliques e sensibilidade do reconhecimento visual. O valor padrão de sensibilidade funciona para a maioria dos casos, mas se seu monitor tiver densidade de pixels alta, aumente para 0.85 ou 0.9. Abaixo disso, o sistema começa a errar posições em telas Retina ou equivalentes.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Para testar se está funcionando, abra qualquer aplicação e rode o comando de gravação. Clique em alguns botões, mova o mouse, feche janelas. O script vai gerar um arquivo .yaml com todas as coordenadas e timestamps. Rode novamente e veja se ele repete as ações no mesmo ritmo.
Problemas que eu encontrei e como resolvi
O problema mais chato que eu tive foi com janelas que aparecem por cima dos elementos que eu estava automatizando. Imagine o cenário: você está gravando um fluxo de trabalho onde precisa preencher um formulário, mas de repente aparece uma notificação do Windows ou um pop-up de atualização. O script tenta clicar onde deveria estar o botão "Enviar", mas na realidade está clicando no pop-up e trava tudo. Minha solução foi adicionar verificações visuais antes de cada ação importante. Em vez de confiar cegamente nas coordenadas, o sistema agora tira uma screenshot rápida e procura pelo elemento-alvo usando template matching do OpenCV. Se não encontrar em um raio de 50 pixels ao redor da coordenada esperada, ele espera alguns segundos e tenta de novo. Isso adiciona cerca de meio segundo por clique, mas evita que o script destrua dados ou abra caixas de diálogo inesperadas.
Outro problema comum são janelas que não estão na frente. O capivara click funciona apenas com elementos visíveis na tela. Se você precisa clicar em algo que está atrás de outra janela, primeiro traga essa janela para frente manualmente ou maximize ela. O sistema não tem capacidade de atravessar camadas visuais.
Limitações e quando não usar
Existe um conjunto de situações onde essa ferramenta simplesmente não funciona e você precisa considerar alternativas. Jogos online com anti-cheat ativo bloqueiam automação de teclado e mouse, então não tente usar aqui com títulos competitivos. Alguns bancos e sistemas governamentais detectam padrões de mouse irreais e bloqueiam a conta temporariamente. Isso acontece porque o robô clica com precisão submilimétrica e em intervalos de tempo idênticos, o que é facilmente identificável. Se você precisa de algo mais robusto para automação corporativa pesada, considere Selenium para tarefas web ou AutoHotkey para scripts Windows mais complexos. O capivara click é útil para automações simples e rápidas que você precisa resolver hoje, não para construir pipelines industriais de automação.
O tempo médio de configuração para um script funcional gira em torno de 40 minutos para alguém com experiência média, mas pode levar duas horas se a interface que você está tentando automatizar mudar frequentemente ou se usar tecnologias modernas como React que mudam classes CSS a cada renderização. Nesse caso, o reconhecimento visual falha com frequência e você acaba passando mais tempo ajustando seletores do que o script rodando. Uma versão mais recente do projeto também adicionou suporte a múltiplos monitores, mas isso ainda é experimental. Eu testei com três telas e o sistema ocasionalmente clicava na tela errada quando os monitores tinham resoluções diferentes. Se você usa setup multi-monitor, mantenha todas as telas na mesma resolução até que o bug seja corrigido.
