# Como ligar o Hermes Agent ao Telegram e gerir tarefas a partir do telemóvel
> Configuração passo a passo: crie um bot através do BotFather, adicione o token e a lista de acesso ao Hermes Agent e inicie o gateway. Mensagens de voz, tarefas agendadas e controlo pelo telemóvel.
Source: https://ailoot.ai/blog/pt-pt/hermes-agent-telegram-setup/
Canonical: https://ailoot.ai/blog/pt-pt/hermes-agent-telegram-setup/
Language: pt-PT
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-118
Revision: sha256-60bd0f48d14599a2d3ec876adfbc0f696a3fda51a29527a7222147aed2d2e546
Pode enviar mensagens ao Hermes Agent ou ditar-lhe tarefas no Telegram a partir do telemóvel quando estiver longe do computador e receber o resultado na mesma conversa. Os resultados das tarefas agendadas chegam à conversa que designar como a sua conversa principal, uma única vez.
Se ainda não tem o Hermes, comece pelo guia sobre [o que é este agente e como o instalar](https://ailoot.ai/blog/pt-pt/hermes-agent-install-setup/) e depois volte para ligar o Telegram.
Estão disponíveis instruções adicionais na [documentação da Ailoot](https://ailoot.ai/docs/).
## O que precisa para ligar o Hermes Agent ao Telegram?
Pontos-chave
Precisa do Hermes Agent instalado e ligado a um modelo, e de uma conta do Telegram. Criar um bot no Telegram é gratuito e o Hermes é um projeto de código aberto. Poderá haver custos separados com o modelo, o reconhecimento de voz na cloud e um servidor, se decidir manter o bot em funcionamento permanentemente.
O comando `hermes doctor` verifica a instalação do Hermes e a ligação ao modelo. Vamos criar o bot na aplicação Telegram e precisará de um computador para executar comandos no terminal.
## Como criar um bot através do BotFather?
Pontos-chave
Abra o @BotFather no Telegram, envie /newbot, escolha um nome de apresentação e um nome de utilizador único que termine em `bot`. O BotFather responderá com um token no formato 123456789:ABCdef... — esta é a chave do seu bot. Guarde-a e não a mostre a ninguém.
Todos os bots do Telegram têm um token — uma chave secreta para controlar o bot. É emitido pelo bot oficial do Telegram, o @BotFather.
1. ### Abra o @BotFather
Pesquise por `@BotFather` no Telegram ou abra [t.me/BotFather](https://t.me/BotFather). O BotFather verdadeiro tem um visto azul de verificação. Inicie a conversa tocando em “Start”.
2. ### Envie o comando /newbot
O BotFather pedir-lhe-á dois nomes. O primeiro é o nome de apresentação; pode ser qualquer um, por exemplo, “O Meu Agente”. O segundo é o nome de utilizador: tem de ser único e terminar em `bot`, por exemplo, `moy_agent_bot`.
3. ### Obtenha o token
O BotFather enviar-lhe-á uma mensagem de felicitações e uma sequência longa no formato `123456789:ABCdefGHIjklMNOpqrSTUvwxYZ`. Este é o token do bot. Copie a sequência completa.
Atenção
O token dá controlo total sobre o bot: quem conhecer o token controla-o. Se o token for divulgado, revogue-o imediatamente com o comando `/revoke` na conversa com o BotFather e obtenha um novo.
Também existe uma forma rápida que dispensa uma conversa manual com o BotFather. No painel Web do Hermes (`hermes dashboard`) e na aplicação para computador, na página “Messaging → Telegram”, existe um botão “Create with QR”: leia o código com o telemóvel e o Hermes cria um bot, deteta o seu ID, guarda o token nas definições e reinicia o gateway. Os passos abaixo descrevem o método manual; se escolheu o QR, avance diretamente para a verificação da ligação.
## Como encontrar o seu ID do Telegram e para que precisa dele?
Pontos-chave
Encontre o seu ID numérico, por exemplo 123456789. Este é o número da sua conta; um nome de utilizador com @ não funcionará na lista de acesso. O Hermes usa o ID na lista de acesso: sem essa lista, o gateway não responderá a ninguém, nem mesmo a si.
Uma conta do Telegram tem dois identificadores: um nome de utilizador público com @ e um ID numérico interno. O Hermes usa o número.
O método rápido «Criar com QR» descrito acima deteta automaticamente o seu ID. Anote-o junto ao token.
## Como fornecer o token ao Hermes Agent e iniciar o gateway?
Pontos-chave
Execute o assistente de configuração com `hermes gateway setup` e selecione Telegram: irá pedir-lhe o token e o ID e depois guardará tudo. O método manual usa duas linhas no ficheiro `~/.hermes/.env`. Em seguida, inicie o gateway com `hermes gateway` e o bot estará operacional em poucos segundos.
| | Assistente de configuração | Manualmente |
|----|----|----|
| O que executar | `hermes gateway setup` | Um editor com o ficheiro `~/.hermes/.env` |
| O que introduzir | Token e ID em resposta às perguntas do assistente | Duas variáveis manualmente |
| Onde fica guardado | O próprio assistente guarda os dados nas definições | Os dados são introduzidos diretamente em `.env` |
| A quem se destina | A todos; método recomendado | A quem está habituado a configurações ou a configurar através de um script |
1. ### Execute o assistente de configuração
```bash
hermes gateway setup
```
Execute o comando na máquina onde o Hermes está instalado. O assistente apresentará uma lista de aplicações de mensagens.
2. ### Selecione Telegram e introduza os seus dados
O assistente pedir-lhe-á o token do bot e os IDs autorizados (pode introduzir vários, separados por vírgulas) e guardará tudo nas próprias definições.
3. ### Inicie o gateway
```bash
hermes gateway
```
O gateway iniciará e ligar-se-á ao Telegram. Após alguns segundos, envie qualquer mensagem ao bot pela aplicação: se o Hermes responder, a ligação está pronta.
O método manual, em vez de usar o assistente, é assim: abra o ficheiro `~/.hermes/.env` e adicione duas linhas, substituindo os valores pelo token do BotFather e pelo seu ID numérico:
```bash
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789
```
A segunda linha autoriza essas pessoas nas conversas privadas e nos grupos; uma autorização separada do chat de grupo também pode conceder acesso. Separe várias pessoas com vírgulas. Depois de guardar o ficheiro, inicie o gateway com o mesmo comando `hermes gateway`.
Se o bot continuar sem responder, mesmo numa conversa privada, verifique os registos do gateway no mesmo terminal e confirme primeiro o token e o seu ID na lista de acesso; os restantes erros estão descritos na tabela no fim do artigo.
## O que pode fazer o bot do Telegram no seu telemóvel?
Pontos-chave
O bot do Telegram lê mensagens de texto e de voz, aceita ficheiros e imagens, pede autorização antes de executar comandos perigosos diretamente na conversa e apresenta as opções de modelos como botões. Por predefinição, apenas as respostas finais, os pedidos de confirmação e as confirmações de comandos têm som nas notificações.
Há cinco funcionalidades de que mais precisará no telemóvel.
**Mensagens de texto e de voz.** Escreva uma tarefa ou dite uma mensagem de voz — com o reconhecimento de voz configurado, o Hermes transcreve-a e compreende-a. Com um fornecedor local, não são necessárias chaves; tudo é processado na máquina onde o agente é executado.
**Ficheiros e imagens.** Pode reencaminhar um documento, uma folha de cálculo ou uma captura de ecrã para o bot — o agente recebe-o como anexo. Também pode enviar ficheiros gerados: peça um relatório e ele enviá-lo-á como ficheiro na conversa.
**Confirmações para ações perigosas.** Quando o agente está prestes a fazer algo arriscado, como apagar ficheiros, pergunta primeiro na conversa: responda “yes” ou “y” para o fazer; responda “no” ou “n” para cancelar.
**Botões em vez de escrever uma resposta.** Quando o agente precisa de esclarecimentos, envia uma pergunta com botões de opções inline — toque numa opção e o agente continua a trabalhar. O comando `/model` sem argumentos apresenta um menu de seleção de modelos com botões do mesmo tipo.
**Notificações silenciosas.** Por predefinição, o telemóvel só toca para respostas finais, pedidos de confirmação e confirmações de comandos. As notificações de serviço, como “a chamar uma ferramenta” e “a comprimir o contexto”, chegam silenciosamente, para o telemóvel não tocar a cada passo. Se quiser notificações sonoras em todos os passos, altere o modo nas definições.
## Como receber na conversa os resultados de tarefas em segundo plano?
Pontos-chave
As tarefas agendadas enviam os resultados para a conversa principal: abra a conversa com o bot e envie o comando `/sethome`. As tarefas em segundo plano iniciadas a partir de um tópico devolvem o resultado a esse mesmo tópico. O requisito principal é que o gateway continue em execução; caso contrário, o bot não responde quando o computador está desligado.
**Conversa principal para tarefas agendadas.** O Hermes suporta tarefas agendadas: “todas as manhãs às 7:43, prepara-me um resumo”. Envia os resultados para a conversa principal, que designa uma única vez enviando o comando `/sethome` diretamente na conversa com o bot. Enquanto o gateway estiver em execução, os resumos chegam automaticamente.
**Tarefas em segundo plano.** Pode enviar uma tarefa longa para ser executada em segundo plano e continuar com o seu dia: o bot enviará uma mensagem quando estiver pronta. Uma tarefa iniciada a partir de um tópico devolve a resposta a esse mesmo tópico, para que nada se perca.
Limitação importante: o bot só responde enquanto o gateway estiver em execução. Se desligar ou suspender o computador onde o Hermes está a correr, o bot não responderá até a máquina voltar a estar em funcionamento. Para manter o bot sempre online, transfira o agente para um servidor: temos um guia separado sobre [como manter o Hermes Agent em funcionamento permanente](https://ailoot.ai/blog/pt-pt/hermes-agent-vps-24-7/). Por predefinição, o gateway consulta o Telegram à procura de mensagens novas; para plataformas cloud que entram em suspensão sem tráfego recebido, a documentação oferece um modo webhook, que inverte o sentido da ligação para que o próprio Telegram envie pedidos ao bot.
## Como impedir que estranhos acedam ao bot?
Pontos-chave
`TELEGRAM_ALLOWED_USERS` autoriza os IDs de remetentes indicados em conversas privadas e grupos. O acesso a grupos também pode ser concedido separadamente: `TELEGRAM_GROUP_ALLOWED_CHATS` autoriza todos os membros de cada grupo listado. Guarde o token em segredo; os filtros de menção controlam quando o bot responde, não quem tem acesso.
O seu bot pode ser encontrado na pesquisa do Telegram pelo nome de utilizador, pelo que a proteção depende de duas coisas: a lista de acesso e manter o token secreto.
Configure primeiro o acesso por remetente com `TELEGRAM_ALLOWED_USERS`. Nos grupos, examine também `TELEGRAM_GROUP_ALLOWED_CHATS`: incluir aí um chat permite o acesso a qualquer membro, mesmo sem o seu ID na lista pessoal. Uma lista pessoal vazia não prova, por isso, que todos os grupos estejam fechados.
Depois, há o token. Não pode aparecer em capturas de ecrã, mensagens reencaminhadas ou repositórios. Se o token for divulgado, revogue-o com o comando `/revoke` no BotFather. Em seguida, introduza o novo token nas definições e reinicie o gateway.
Uma nota sobre grupos: autorizar o remetente e autorizar o chat são coisas diferentes. Um membro de um grupo permitido por `TELEGRAM_GROUP_ALLOWED_CHATS` pode usar o bot mesmo sem ID em `TELEGRAM_ALLOWED_USERS`. Se o acesso tiver de ser individual, não autorize o grupo inteiro; configure e verifique as restrições de remetentes na versão instalada. Se quiser que o bot só responda num grupo quando for chamado, existe a definição `telegram.require_mention` — nesse caso, responde a uma menção com @, a uma resposta à sua mensagem, a um comando como `/command@yourbot` e a correspondências com os seus padrões em `telegram.mention_patterns`, ignorando as mensagens normais do grupo.
## Porque é que o bot não responde num grupo e como resolver?
Pontos-chave
A causa é o modo de privacidade do Telegram: por predefinição, um bot num grupo só vê comandos e respostas às suas próprias mensagens. Desative-o através do @BotFather: /mybots → Bot Settings → Group Privacy → Turn off. Depois, tem de remover o bot do grupo e voltar a adicioná-lo — o Telegram memoriza a definição antiga. Em alternativa, torne o bot administrador do grupo sem desativar o modo de privacidade.
Os novos bots do Telegram têm o modo de privacidade ativado por predefinição; a documentação do Hermes descreve-o como a causa mais comum de confusão com bots em grupos. Neste modo, o bot recebe apenas mensagens que começam com um comando `/`, respostas às suas próprias mensagens e notificações de serviço. Simplesmente não recebe as mensagens normais do grupo — o Telegram não lhas envia e nenhuma definição do agente resolverá isso.
Como resolver:
1. Abra o @BotFather e envie `/mybots`.
2. Selecione o seu bot.
3. Abra “Bot Settings” → “Group Privacy” → “Turn off”.
4. Remova o bot do grupo e volte a adicioná-lo.
É fácil esquecer o quarto passo e, nesse caso, o bot “continua sem responder”. O Telegram memoriza a definição de privacidade existente quando o bot entrou no grupo e não a atualiza até o bot ser removido do grupo e adicionado novamente.
Se não quiser desativar a privacidade globalmente, há uma segunda opção: torne o bot administrador do grupo. Os bots administradores recebem todas as mensagens, independentemente do modo de privacidade.
## Erros de ligação frequentes e o que fazer
Pontos-chave
Comece por verificar se o gateway está em execução e se o token e o ID na lista de acesso estão corretos. Para grupos, verifique o modo de privacidade; para o reconhecimento de voz, verifique o fornecedor de STT; e, para respostas de voz através do Edge TTS, verifique se tem o ffmpeg.
| Sintoma | Causa | O que fazer |
|----|----|----|
| O bot não responde de todo | Token incorreto ou gateway não está em execução | Verifique o token em `.env`, reinicie `hermes gateway` e consulte os registos no mesmo terminal |
| O bot responde “unauthorized” | O seu ID não está na lista de acesso | Verifique o seu ID, adicione-o a `TELEGRAM_ALLOWED_USERS` e reinicie o gateway |
| Responde numa conversa privada, mas não num grupo | Modo de privacidade | Selecione “Turn off” através do BotFather, depois remova o bot do grupo e volte a adicioná-lo, ou torne-o administrador |
| As mensagens de voz não são transcritas | O reconhecimento de voz não está configurado | O reconhecimento local é instalado com o pacote faster-whisper; as opções cloud requerem uma chave própria |
| Uma resposta de voz através do Edge TTS chega como ficheiro em vez de mensagem de voz normal | Falta o ffmpeg | Instale o ffmpeg — o Edge TTS precisa dele para converter para o formato de mensagem de voz do Telegram |
| O token deixou de funcionar | O token foi revogado | Obtenha um novo através de `/revoke` e `/newbot` (ou `/token`) com o BotFather, substitua o valor em `.env` e reinicie o gateway |
## Que outras perguntas fazem sobre o Hermes Agent no Telegram?
Pontos-chave
Não é necessário um servidor, mas o bot só está ativo enquanto o gateway estiver em execução. A ligação é gratuita; só paga o modelo. É possível ligar várias pessoas através da lista de IDs. O bot não consegue ver conversas privadas. Os ficheiros com mais de 20 MB requerem configuração adicional.
### Perguntas frequentes
É necessário um servidor para o bot funcionar?
Não, para começar basta o computador com o Hermes instalado. Lembre-se apenas: o bot está ativo enquanto o gateway estiver em execução. Desligue o computador ou suspenda-o e o bot fica sem responder até a máquina voltar a estar em funcionamento. Quando quiser que funcione permanentemente, transfira o agente para um servidor — temos um guia separado sobre isso.
Quanto custa ligar um bot?
A ligação é gratuita. O Telegram não cobra pelos bots e o Hermes Agent é um projeto de código aberto. Poderá haver custos separados com o modelo ligado ao agente e com um servidor, se quiser que funcione permanentemente.
Posso ligar a minha mulher ou a minha equipa ao bot?
Sim. Na lista `TELEGRAM_ALLOWED_USERS`, os IDs são separados por vírgulas e todas as pessoas da lista podem enviar mensagens privadas ao bot. E, se autorizar a própria conversa através de `TELEGRAM_GROUP_ALLOWED_CHATS`, qualquer membro desse grupo poderá usar o bot — é assim que a lista de conversas autorizadas funciona, segundo a documentação.
O bot consegue ver as minhas conversas privadas?
Não. A Bot API só fornece ao bot as mensagens que lhe são dirigidas nas conversas privadas, enquanto nos grupos se aplica o modo de privacidade do Telegram, como explicado na secção sobre grupos. O bot não tem acesso às suas conversas com outras pessoas.
Porque é que o bot se recusou a aceitar uma mensagem de voz grande?
A Bot API pública tem um limite de transferência de ficheiros de 20 MB; tudo o que for maior é rejeitado. A documentação do Hermes descreve uma solução alternativa com um servidor Bot API local, que aumenta o limite para 2 GB. Só precisa dela se pretender aceitar ficheiros com mais de 20 MB; há uma ligação para a documentação na secção “Fontes” no fim do artigo.
Posso adicionar novas capacidades ao bot?
Sim. O Hermes tem skills e plugins — capacidades prontas a usar para o agente. A instalação de um plugin neste tipo de bot com agente de IA é explicada separadamente: como instalar um plugin num bot com agente de IA no Telegram.
### Fontes
- [Hermes Agent: configuração do Telegram](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram) — a principal fonte do guia original, consultada pelo respetivo autor em 12.09.2026
- [Hermes Agent: gateway de mensagens](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)
- [Hermes Agent: instalação](https://hermes-agent.nousresearch.com/docs/getting-started/installation)
- [Hermes Agent: guia de início rápido](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)
- [Hermes Agent: tarefas agendadas](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)
- [BotFather](https://t.me/BotFather) — bot oficial do Telegram para criar bots
Quando estiver pronto, fique a conhecer a [Ailoot](https://ailoot.ai/).
## Perguntas frequentes
### Uma lista pessoal bloqueia pessoas não listadas num grupo autorizado?
Não quando o chat inteiro está autorizado por TELEGRAM_GROUP_ALLOWED_CHATS: qualquer membro desse grupo tem autorização. TELEGRAM_ALLOWED_USERS autoriza remetentes individuais; examine ambas as definições antes de abrir o bot a um grupo.
### Exigir uma menção @ torna o grupo privado para certos utilizadores?
Não. As definições de menções e padrões determinam que mensagens desencadeiam uma resposta. Não anulam uma autorização concedida a todos os membros de um chat permitido.
## Ailoot · A empresa e a sua carteira de projetos
A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI.
A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões.
A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.