Hermes Agent ne répond plus sur Telegram : fixes rapides

Le bot marchait, et maintenant plus rien

Vous envoyez un message. Rien ne revient. Le bot est toujours dans votre chat, son avatar est toujours là, mais la réponse n'arrive pas. C'est le problème le plus courant avec Hermes Agent sur Telegram, et la raison pour laquelle on y passe une heure est presque toujours la même : on tente des correctifs avant de savoir quelle couche est cassée.

Hermes sur Telegram, ce sont en réalité trois choses empilées. Le processus agent Hermes (raisonnement et outils). Le gateway Hermes (long-polling contre Telegram). Et Telegram lui-même (config BotFather, allowed users, mode privé). Quand le bot devient muet, la panne se trouve dans exactement une de ces couches, et le chemin de retour le plus rapide consiste à isoler laquelle avant de toucher à quoi que ce soit.

Ce guide parcourt les vérifications dans l'ordre qui attrape le plus vite les causes principales. Si vous avez déjà suivi le guide général de troubleshooting Telegram, voici la version courte et guidée par le symptôme, pour le cas précis « pas de réponse du tout ».

Vérification 1 : votre user ID est-il vraiment dans la liste autorisée

Neuf fois sur dix, c'est ça. Hermes ne répondra à personne dont l'ID numérique Telegram ne figure pas dans telegram_allowed_users. Le bot reçoit le message, le gateway le route, et Hermes le rejette silencieusement. De votre côté, ça ressemble exactement à un bot mort.

Deux choses tournent mal ici :

Vous avez mis @pseudo au lieu de l'ID numérique. @pseudo n'est pas ce que Hermes attend. Envoyez /start à @userinfobot dans Telegram, copiez le numéro qu'il vous renvoie et utilisez celui-là.
Vous avez ajouté un nouvel utilisateur après le dernier redémarrage sans recharger la config. Hermes lit telegram_allowed_users au démarrage. Modifiez, redémarrez le gateway.

La config vit dans config.yaml :

telegram_allowed_users: "123456789,987654321"

Si vous êtes sur Hermify, le champ équivalent se trouve dans le formulaire d'identifiants du dashboard.

Vérification 2 : prouvez que le gateway tourne

Avant d'accuser Telegram, prouvez que le gateway est en ligne.

hermes gateway status

S'il ne tourne pas, c'est votre bug. Lancez-le :

hermes gateway start

S'il tourne mais que le bot reste muet, suivez le log en envoyant un message de test :

tail -f ~/.hermes/logs/agent.log

Vous cherchez une chose parmi trois. Une ligne « message received » signifie que le gateway fait son travail et que c'est Hermes qui rejette le message en silence (retour à la Vérification 1). Une ligne « 409 Conflict » signifie que deux processus font du polling sur le même token (voir Vérification 4). Rien du tout signifie que le gateway n'atteint pas Telegram (voir Vérification 5).

Vérification 3 : le bot token est-il encore valide

BotFather permet de révoquer les tokens et il est facile d'en révoquer un pour un vieux bot de test, d'oublier, et de se demander pourquoi rien ne marche.

Ouvrez Telegram, écrivez à @BotFather, envoyez /mybots, choisissez votre bot, tapez sur API Token et comparez la chaîne affichée à celle de votre config Hermes. Elles doivent coïncider caractère par caractère. Sinon, soit vous collez la courante dans Hermes et vous redémarrez, soit vous cliquez sur Revoke current token dans BotFather pour en générer une nouvelle et vous la collez.

Un token invalide se manifeste par une erreur « Unauthorized » dans le log Hermes au démarrage. Si vous voyez cette erreur, c'est toujours le token.

Vérification 4 : deux processus font-ils du polling sur le même bot

La Bot API de Telegram autorise exactement un consommateur de long-poll par token de bot. Si deux processus appellent getUpdates en même temps, Telegram renvoie « 409 Conflict: terminated by other getUpdates request » et les updates partent au processus qui gagne chaque cycle, ou à aucun. De votre côté, on dirait que le bot rate un message sur deux.

La façon la plus courante d'y tomber n'est pas exotique :

Une unit systemd lance Hermes et vous avez aussi ouvert une session Hermes à la main dans tmux.
Vous testez un bot de dev sur votre laptop mais l'instance de production utilise le même token.
Vous avez lancé un worker en arrière-plan et oublié que l'ancien conteneur tourne encore.

Trouvez le doublon :

ps aux | grep -E 'telegram|hermes' | grep -v grep

Tuez celui que vous ne vouliez pas garder, redémarrez le survivant. Les 409 s'arrêtent en quelques secondes parce que Telegram libère la session de long-poll obsolète dès que le client perdant se déconnecte.

Vérification 5 : le silence en groupe, c'est presque toujours le mode privé

Si le bot marche en DM mais pas dans un groupe, le coupable est presque toujours le mode privé des bots Telegram, pas Hermes.

Le mode privé est activé par défaut sur tout nouveau bot. Ça signifie que le bot ne voit que les messages qui le mentionnent directement, qui répondent à un de ses messages, ou qui arrivent en tant que commandes. Le brouhaha normal du groupe n'atteint jamais votre gateway Hermes.

Deux façons de corriger :

Passez le bot admin du groupe. Les bots admin voient tout, c'est l'option la moins surprenante.
Désactivez le mode privé. Dans BotFather envoyez /setprivacy, choisissez le bot, cochez Disable. Ensuite retirez le bot du groupe et rajoutez-le. Les changements de mode privé ne prennent effet qu'au prochain ajout.

Si vous faites tourner le bot dans un topic ou un thread de forum, confirmez aussi que la config Hermes couvre ce thread précis dans allowed_chats et dans les IDs de topic. Un bot autorisé à parler dans le canal général restera muet dans un thread d'opérations si cet ID de topic n'est pas sur la liste.

Vérification 6 : votre réseau tue le long-poll

Si le bot répond une fois au départ, puis se tait exactement le même temps à chaque fois avant de revivre, votre réseau ferme le long-poll inactif avant que Telegram puisse y pousser un update. Les routeurs grand public, les VPS bon marché et les réseaux d'entreprise le font souvent avec des timeouts NAT.

Activez les logs debug et regardez :

export HERMES_LOG_LEVEL=debug
hermes gateway restart

Des entrées « connection reset » répétées à intervalle fixe confirment le diagnostic. Raccourcissez le poll timeout de Hermes pour qu'il se reconnecte plus souvent que le idle timeout de votre réseau :

hermes config set messaging.telegram.poll_timeout 30

La valeur par défaut est 60. Descendez à 30 ou moins et le problème de reset disparaît, parce que vous refermez et rouvrez le long-poll avant que le réseau se lasse. C'est la même cause racine que beaucoup de « marche en local, casse après le deploy » sur des infrastructures bon marché.

Vérification 7 : la boucle de l'agent s'est écrasée silencieusement sur une erreur fournisseur

Le gateway est en ligne, le token est bon, la liste d'autorisés est correcte, mais les réponses n'arrivent toujours pas. Cherchez dans le log une erreur du provider du modèle près de la dernière réponse qui a fonctionné. Rate limits, quotas épuisés et réponses 5xx du provider du LLM peuvent faire tomber la boucle de l'agent dans certaines versions d'Hermes sans redémarrage. Le gateway continue de faire du polling, reçoit votre nouveau message, le passe, et de l'autre côté il n'y a personne pour répondre.

Le correctif est un redémarrage plus une vérification du dashboard du provider pour le problème sous-jacent. Si vous êtes sur le tier gratuit d'un provider et que vous avez épuisé le quota quotidien en pleine conversation, le bot va sembler « ne répond pas » jusqu'à ce que la fenêtre de quota tourne. Passez à un plan payant ou changez de provider dans la config Hermes vers un autre backend, puis redémarrez le gateway.

Un ordre de diagnostic en deux minutes qui marche

Quand vous êtes pressé, suivez cet ordre et vous tomberez sur la cause en moins de deux minutes sur tous les cas réels que nous avons vus :

hermes gateway status - est-il en ligne ?
tail -f ~/.hermes/logs/agent.log - un message frais atteint-il seulement Hermes ?
Si oui, vérifiez telegram_allowed_users.
Si non, cherchez « 409 Conflict » (poller en double) ou « Unauthorized » (token révoqué) dans le log.
Si rien de tout cela et que le bot n'est muet qu'en groupe, c'est le mode privé.
Si rien de tout cela et qu'il se tait à intervalles réguliers, c'est le idle timeout de votre réseau.
Si rien de tout cela et qu'il s'est tu après avoir bien tourné, c'est un crash provider en amont.

Sautez la boucle de debug entièrement

Chaque vérification ci-dessus existe parce que Telegram, le gateway, Hermes et votre provider sont quatre pièces mobiles qui peuvent tomber en panne indépendamment. Quand elles vivent toutes sur votre infrastructure, c'est vous qui recevez l'alerte à chaque fois que l'une dérape.

Hermify est un Hermes Agent géré sur Telegram. Votre bot token, la liste d'allowed users et la clé du provider vont dans le dashboard une fois. Le gateway, les redémarrages, la capture des logs et la logique de reconnexion sont chez nous. Quand quelque chose déraille en amont, la carte de statut du dashboard vous dit quelle couche, et un clic la redémarre. Vous n'ouvrez plus jamais ~/.hermes/logs/agent.log si vous ne le voulez pas.

Commencez avec Hermify et remettez le bot en ligne en une minute environ, avec une mémoire qui reste la vôtre.