Plugins para um bot de Telegram com agente de IA: instalação e verificação

O meu agente funciona num servidor e dou-lhe comandos através do Telegram: escrevo no chat, ele lê ficheiros, executa tarefas e envia-me o resultado. A certa altura, chega-se a um limite: o bot básico faz muito pouco e queremos que reveja código, crie commits no GitHub ou compile um resumo agendado. A resposta são os plugins.

As pessoas pesquisam «como instalar um plugin no Telegram» precisamente por isto. Não estão a falar de uma loja de autocolantes. Querem saber como dar novas capacidades a um bot. A seguir, explicamos passo a passo o que é um plugin, onde é realmente instalado, como instalar um em cinco minutos e como evitar introduzir código malicioso no agente. Esta descrição baseia-se na documentação oficial.

Encontra na documentação informações práticas sobre como trabalhar com o Ailoot.

O que é um plugin de agente de IA, em termos simples?#

Vamos por partes. De origem, um agente de IA consegue fazer o básico: ler ficheiros, escrever código e responder a perguntas. Um plugin é uma pasta com capacidades adicionais que o agente deteta e começa a utilizar. A documentação oficial do Claude Code descreve um plugin precisamente desta forma: expande o agente com competências, agentes auxiliares independentes, ações automatizadas e ligações a serviços externos.

Um exemplo simples. Instale um plugin para trabalhar com o GitHub e o agente passa a ter comandos para criar um commit, abrir um pull request e rever o histórico de alterações. Instale um plugin de revisão e o agente verifica se há erros e falhas de segurança no seu código, seguindo uma lista de verificação predefinida. Não teve de configurar nada disto manualmente: o autor do plugin preparou tudo e só teve de o ligar.

Há mais uma coisa importante: um plugin não ensina nada ao agente «para sempre». É um módulo que pode ser removido. Liga-o hoje, desliga-o amanhã e o bot volta ao conjunto de capacidades que tinha antes do plugin. Isto torna os plugins fáceis de experimentar: escolha um, use-o numa tarefa real e, se não lhe servir, remova-o sem deixar rasto.

Em que difere um plugin de uma competência, do MCP e de um subagente?#

Os termos relacionados com agentes podem ser confusos, por isso resumi as diferenças numa tabela. Também responde a metade das perguntas dos principiantes.

No universo do Claude Code, uma ligação a um serviço externo chama-se MCP. É uma norma que permite ao agente aceder ao GitHub, a uma base de dados ou a um browser. As primeiras quatro linhas da tabela são elementos independentes.

Veja a última linha. Um plugin está um nível acima dos outros quatro elementos. Reúne numa só caixa uma competência, um agente auxiliar, uma ação automatizada e o MCP. O autor juntou tudo, acrescentou um ficheiro de descrição e publicou-o. Com um único comando, obtém um conjunto completo e pronto a usar, em vez de montar quatro componentes separadamente.

Assim, a escolha é simples. Se precisar de uma pequena capacidade para uma tarefa, escreva a competência: demora quinze minutos. Se precisar de um conjunto pronto a usar, criado por pessoas que já resolveram o seu problema, obtenha um plugin. Tenho um guia à parte sobre como escolher competências para o Claude Code, incluindo formas de não sobrecarregar o agente com competências adicionais.

O que significa «instalar um plugin no Telegram» e o que tem o Telegram que ver com isso?#

É aqui que surge uma confusão comum. O Telegram não tem plugins: o mensageiro não armazena as capacidades do bot. Encaminha as suas mensagens para o agente e mostra as respostas. O cérebro está noutro local — no seu portátil ou num servidor onde funciona um agente como o Hermes Agent, o OpenClaw ou o Claude Code ligado ao chat.

Há duas formas de instalar um plugin, e ambas funcionam:

1. Diretamente a partir do chat. Escreva um pedido em linguagem natural ao agente no Telegram: «instala um plugin do GitHub para ti». O agente instala-o na sua própria máquina e responde que está pronto. É prático quando o servidor está longe e tem o telemóvel consigo.
2. No terminal. Inicie sessão na máquina onde o agente funciona e instale aí o plugin com um comando. É mais fiável da primeira vez: pode ver todo o resultado e não deixa passar nada.

O método a escolher depende de confiar ou não que o bot instale extensões por si, sem supervisão. Instalei manualmente os meus primeiros plugins no terminal para ver exatamente o que estava a ser ligado. Depois de ganhar à-vontade, passei a confiar ao agente a instalação diretamente a partir do chat. Vou mostrar-lhe as duas formas.

Como instalar um plugin num agente em cinco minutos?#

Vou mostrar-lhe o Claude Code porque o processo está descrito palavra por palavra na documentação e é fácil de repetir. Os comandos são os mesmos no terminal e quando os envia ao agente pelo Telegram.

1. Abra a lista de plugins. O comando /plugin abre um painel diretamente no terminal, com um separador que mostra todas as extensões disponíveis e um diretório em claude.com/plugins. É uma loja onde pode explorar antes de instalar.
2. Ligue o mercado oficial. Introduza /plugin marketplace add anthropics/claude-plugins-official. Um mercado é um diretório a partir do qual o agente descarrega plugins. O oficial é gerido pela Anthropic.
3. Instale o plugin de que precisa. Escreva o nome do plugin seguido do nome do mercado, separado por um sinal de arroba:

/plugin install github@claude-plugins-official

4. Recarregue os plugins. Se, após a instalação, o bot disser «Run /reload-plugins to activate.», execute /reload-plugins. Enquanto não os recarregar, os novos comandos não aparecem na conversa atual. Se receber um aviso de que o recarregamento voltará a ler a conversa, repita o comando como /reload-plugins --force.

E já está. O agente passa a ter os comandos do plugin. No Claude Code, estes usam o nome do plugin como prefixo, por exemplo /commit-commands:commit, para que possa ver imediatamente que o comando veio de um plugin.

Quando envia um comando ao bot pelo Telegram em vez de usar o terminal, o Claude Code também disponibiliza um comando de instalação independente, sem o painel interativo: claude plugin install. A documentação assinala um pormenor: este comando não carrega o plugin numa conversa já aberta. O agente deteta-o no próximo arranque ou depois de /reload-plugins. Por outras palavras, depois de instalar, tem de reiniciar o bot para obter os novos comandos.

No Hermes Agent, as extensões são ativadas e desativadas com o comando hermes tools, enquanto as competências ficam na sua própria pasta. O OpenClaw funciona de forma semelhante: ligue um conjunto e reinicie o bot. Os nomes variam, mas a ordem é a mesma: ligar uma origem, instalar pelo nome e reiniciar o agente.

Os plugins são um dos elementos da engenharia de contexto: decide que capacidades o agente terá à mão antes do primeiro pedido. Para trabalhar de forma sistemática, é útil combinar: clone de IA (os seus conhecimentos especializados em competências e plugins) + Segundo Cérebro (a estrutura do conhecimento do projeto) + engenharia de contexto (o que dar ao agente e quando). Estes são os três pilares sem os quais a IA começa a adivinhar.

Onde obter plugins e em quais pode confiar?#

Um plugin é código de outra pessoa e recebe as mesmas permissões que o seu agente: acesso a ficheiros, ao terminal e a serviços. Por isso, a origem é mais importante do que uma descrição apelativa. Eis as origens, da mais fiável à mais duvidosa.

Para instalar a partir do mercado comunitário, utilize um comando semelhante, mas com outro mercado: /plugin install plugin-name@claude-community. A documentação salienta especificamente que estes plugins passaram uma verificação de segurança automatizada e estão todos fixados numa versão específica do código. Isto significa que receberá exatamente o que foi verificado, sem alterações posteriores introduzidas pelo autor.

Antes da instalação, o Claude Code apresenta uma secção «Will install»: uma lista dos comandos, auxiliares, competências, ações automatizadas e ligações que o plugin irá adicionar. Leia-a. Pode assim reparar, por exemplo, que uma extensão para notas está a pedir acesso ao terminal sem razão aparente. A documentação oficial é clara quanto à regra:

Em termos simples: os mercados oficiais e revistos oferecem mais tranquilidade; utilize um repositório aleatório do GitHub apenas depois de ler o que contém e perceber por que razão precisa das permissões que pede. A confiança no código de terceiros vai além da instalação de plugins; abordo o tema no meu artigo sobre segurança no vibe-coding.

Como verificar se o plugin está instalado e a funcionar no Telegram?#

Dedique um minuto à verificação: ver a mensagem «instalado» ainda não significa que o bot tenha realmente detetado o plugin. Siga estes passos:

1. Verifique a lista. Abra novamente o painel /plugin ou peça ao agente para mostrar os comandos disponíveis. Os comandos do novo plugin devem aparecer na lista, com o nome do plugin como prefixo no Claude Code.
2. Dê-lhe uma tarefa de teste. Escolha algo seguro, não uma tarefa real. Se instalou um plugin do GitHub, peça-lhe para mostrar os commits mais recentes. Se instalou um plugin de revisão, dê-lhe um ficheiro pequeno. Verifique uma coisa: o bot assume a tarefa usando essa nova capacidade?
3. Verifique no mesmo chat que utiliza para trabalhar. Se controlar o agente pelo Telegram, envie o comando de teste no Telegram. Por vezes, o plugin está visível no terminal, mas o bot no chat ainda não o recarregou.

A razão mais comum para um plugin estar instalado mas os respetivos comandos não funcionarem é ter ignorado o recarregamento. O comando de instalação foi executado com sucesso, mas o agente na conversa aberta continua a usar o conjunto antigo de capacidades. /reload-plugins ajuda; se não resultar, reinicie completamente o bot. A segunda razão é ter instalado a partir de um mercado diferente: o nome do plugin coincide, mas o diretório está errado e o agente informa corretamente que o plugin não se encontra nos mercados ligados.

Se o bot responde no chat, mas não compreende o novo comando, isso não significa que o agente esteja avariado ou que tenha feito algo mal. Quase sempre, trata-se de uma de duas coisas: ainda não recarregou os plugins ou ligou o mercado errado. Ambas se resolvem num minuto.

Como atualizar e remover plugins sem sobrecarregar o agente?#

Há um pormenor pouco óbvio nas atualizações. Quando o autor lança uma nova versão de um plugin, ela não chega por si só. Primeiro, atualize o diretório do mercado com /plugin marketplace update e só depois instale a versão mais recente. Enquanto não atualizar o mercado, o agente considera atual a versão que descarregou da última vez. Isto é intencional: as alterações de outras pessoas não são acrescentadas posteriormente sem o seu conhecimento.

Remova um plugin através do mesmo painel /plugin que usou para o instalar: encontre-o na lista de plugins instalados e remova-o. Não deixa rasto no agente e os comandos desaparecem assim que o recarregar. É exatamente por isso que não precisa de recear experimentar plugins: instale vários, mantenha os dois que funcionam e remova os restantes.

E mantenha tudo organizado. Cada plugin ligado acrescenta comandos que o agente tem de ter presentes e ocupa parte da janela de contexto com as respetivas descrições. Cinco plugins que não utiliza tornam o bot mais lento e confundem-no sem motivo. A regra é simples: se um plugin não tiver sido útil durante duas semanas, remova-o. Pode voltar a instalá-lo com um comando.

Que plugins instalaria primeiro?#

Não lhe vou dar uma lista das 100 melhores opções — isto merece um guia próprio e já tenho um artigo sobre os 10 melhores plugins do Claude Code. Eis três áreas que recomendo a principiantes que gerem um agente pelo Telegram.

1. Trabalhar com o GitHub. Um plugin que dá ao agente comandos para commits, branches e pull requests. Escreva ao bot no chat «guarda o trabalho e envia-o para o repositório» e ele trata disso. Isto elimina a principal preocupação de quem faz vibe-coding sem experiência: o medo de perder código.
2. Revisão de código. Um plugin com uma lista de verificação para procurar erros, falhas de segurança e pontos fracos. É especialmente útil com o Telegram: envie um trecho de código no chat e obtenha uma revisão sem abrir um editor.
3. Commits com um estilo consistente. Um pequeno plugin que faz o agente formatar os commits de acordo com um único modelo. Pode parecer um pormenor, mas ao fim de um mês o histórico do projeto fica organizado, como o de uma equipa, em vez de se transformar numa confusão.

A partir daí, escolha plugins para tarefas específicas. Trabalha com uma base de dados? Obtenha um plugin para bases de dados. Compila resumos? Obtenha um plugin de agendamento. A regra geral é a mesma: comece por uma tarefa e depois procure um plugin para ela. Instalar plugins antecipadamente, «por precaução», é uma forma segura de afogar o bot em comandos que nunca vai utilizar.

Que outras perguntas fazem sobre plugins num agente para Telegram?#

Para trabalhar de forma sistemática, é útil combinar: clone de IA + Segundo Cérebro + engenharia de contexto.

Abra o Ailoot.