Configuration Telegram de Hermes Agent : problèmes courants et solutions

Telegram est là où la plupart des déploiements Hermes bloquent

Le démarrage rapide de Hermes est rapide. La configuration Telegram est là où la plupart des utilisateurs rencontrent des problèmes. Ce n'est pas que le processus soit compliqué : c'est que chaque étape a quelques façons d'échouer, et quand plusieurs choses échouent silencieusement, il est difficile de savoir où chercher.

Ce guide couvre les problèmes les plus courants dans l'ordre où ils apparaissent généralement.

Obtenir le token du bot Telegram

Le token vient de BotFather, l'interface officielle de gestion des bots de Telegram. Cette étape semble simple, mais elle comporte quelques modes d'échec.

Comment bien faire :

1. Ouvrez Telegram et recherchez @BotFather.
2. Envoyez /newbot.
3. BotFather demande un nom (nom d'affichage) et un nom d'utilisateur (qui doit se terminer par bot).
4. Après la création, BotFather vous envoie un message contenant le token. Il ressemble à 7123456789:ABCDef....
5. Copiez le token complet, y compris les deux points et tout ce qui suit.

Erreurs courantes :

• Copier seulement l'ID numérique : le token est la chaîne complète après les deux points, pas seulement le chiffre avant eux.
• Utiliser un bot de test d'un environnement de développement : si vous avez créé un bot il y a des mois et oublié quel token correspond à quel bot, BotFather peut vous afficher les bots existants avec /mybots. Vous pouvez alors révoquer et régénérer des tokens.
• Espaces ou sauts de ligne dans le token collé : certains flux de copie ajoutent des espaces. Collez d'abord dans un éditeur de texte brut pour vérifier que le token est propre avant de l'utiliser.

La configuration TELEGRAM_ALLOWED_USERS

C'est la partie la plus souvent mal configurée d'un déploiement Hermes sur Telegram.

Hermes exige que vous spécifiiez quels ID utilisateurs Telegram sont autorisés à envoyer des messages au bot. Sans cela, le bot ne répondra à personne. Avec une valeur incorrecte, le bot ne vous répondra pas même s'il semble tourner.

Ce dont vous avez besoin :

Un ID utilisateur Telegram est un nombre, pas un nom d'utilisateur. @nomutilisateur n'est pas ce que Hermes attend. Vous avez besoin de l'ID numérique, qui ressemble à 123456789.

Comment obtenir votre ID utilisateur Telegram :

Ouvrez Telegram, recherchez @userinfobot, et envoyez /start. Il vous répondra avec votre ID utilisateur.

Comment le configurer :

Dans config.yaml :

telegram_allowed_users: "123456789"

Pour plusieurs utilisateurs, utilisez une liste séparée par des virgules :

telegram_allowed_users: "123456789,987654321"

Note Hermify : dans le flux d'onboarding de Hermify, vous saisissez votre ID utilisateur Telegram (ou une liste séparée par des virgules) dans le formulaire d'identifiants. C'est séparé du champ token du bot. Les deux sont obligatoires.

Problème : le bot ne répond pas du tout

Si vous envoyez un message à votre bot et que rien ne se passe, suivez cette liste de vérification :

1. La passerelle Hermes est-elle en cours d'exécution ?

hermes gateway status

Si la passerelle ne fonctionne pas, le bot n'a pas de récepteur. Démarrez-la :

hermes gateway start

2. Votre ID utilisateur est-il dans la liste autorisée ?

Vérifiez la configuration telegram_allowed_users. C'est la cause la plus fréquente d'un bot silencieux. Le processus tourne, la passerelle est connectée, mais Hermes ignore délibérément vos messages parce que votre ID n'est pas dans la liste.

3. Le token du bot a-t-il expiré ou été révoqué ?

BotFather permet de révoquer des tokens. Si vous avez régénéré le token après l'avoir ajouté à Hermes, l'ancien token ne fonctionne plus. Vérifiez BotFather avec /mybots, sélectionnez votre bot, allez dans Token API, et vérifiez que le token dans votre configuration correspond.

4. Le bot est-il déjà dans un autre chat ?

Les bots Telegram répondent au chat spécifique où ils reçoivent des messages. Si vous avez précédemment ajouté le bot à un groupe et que Hermes est configuré pour répondre différemment aux messages de groupe, vous devrez peut-être démarrer la conversation dans un chat direct (DM) avec le bot.

Problème : erreur « Unauthorized » dans les logs

Cette erreur signifie que le token est invalide ou a été révoqué. La solution consiste toujours à régénérer le token dans BotFather et à mettre à jour votre configuration Hermes avec la nouvelle valeur.

Dans BotFather :

1. Envoyez /mybots.
2. Sélectionnez votre bot.
3. Allez dans Token API → Révoquer le token actuel.
4. Copiez le nouveau token.
5. Mettez à jour config.yaml ou le formulaire d'identifiants du tableau de bord Hermify.
6. Redémarrez Hermes (ou le runtime Hermify).

Problème : le bot répond une fois, puis devient silencieux

Cela signifie généralement que le processus Hermes s'est arrêté ou que la passerelle s'est déconnectée. Causes courantes :

Le processus a été tué. Sur les déploiements locaux ou l'hébergement partagé bon marché, les processus sont tués quand la mémoire est insuffisante ou quand l'hôte recycle les conteneurs. Consultez les logs de processus pour un crash ou un événement OOM (mémoire insuffisante).

La session WSL2 a pris fin. Si vous faites tourner Hermes dans WSL2, fermer le terminal arrête le processus. Consultez le guide WSL2 pour faire tourner Hermes de façon persistante.

La boucle de polling Telegram a expiré. La passerelle Hermes utilise le long-polling pour recevoir les messages Telegram. Parfois la connexion se coupe et n'est pas automatiquement rétablie. Redémarrer la passerelle (hermes gateway restart) règle ce problème.

Une erreur de modèle a provoqué un plantage. Si l'API LLM a renvoyé une erreur (limite de débit, quota épuisé, mauvaise réponse), certaines versions de Hermes peuvent quitter la session plutôt que de récupérer. Consultez la sortie du terminal ou les logs pour un message d'erreur récent avant le silence.

Problème : les messages arrivent mais l'agent ignore le contenu

C'est différent d'un bot silencieux. Le bot reçoit les messages, mais les réponses de l'agent semblent incorrectes ou vides.

Cause la plus probable : la fenêtre de contexte du modèle est pleine. Hermes lit votre MEMORY.md et l'historique de conversation dans chaque prompt. Si le contexte combiné est trop long pour la fenêtre du modèle, le modèle reçoit un prompt tronqué et la qualité des réponses se dégrade ou devient vide.

Solutions :

• Passez à un modèle avec une fenêtre de contexte plus large (Claude et Gemini supportent 128 000 tokens ou plus).
• Élaguez manuellement votre MEMORY.md s'il a beaucoup grossi.
• Utilisez hermes memory compact si disponible dans votre version pour résumer et compresser la mémoire.

Cause moins probable : problème de correspondance partielle dans la liste des utilisateurs autorisés. Si votre configuration d'utilisateurs autorisés contient 12345 et que votre véritable ID utilisateur est 123456789, Hermes ne correspondra pas correctement. Vérifiez l'ID numérique complet, pas une version tronquée.

Problème : fonctionne bien en local, cassé après déploiement

La cause la plus fréquente ici est une discordance entre l'environnement de test et l'environnement serveur.

Vérifiez ces éléments dans l'ordre :

1. Le token est correct dans la configuration serveur, pas dans la configuration locale. Il est facile de mettre à jour le mauvais fichier.
2. Le serveur peut atteindre l'API de Telegram. Certains fournisseurs d'hébergement bloquent les connexions sortantes. Testez avec curl https://api.telegram.org/bot<VOTRE_TOKEN>/getMe depuis le serveur.
3. Le processus Hermes a démarré avec succès. Consultez les logs du conteneur ou du processus pour des erreurs de démarrage.
4. Le répertoire mémoire est monté. Si vous utilisez Docker, confirmez que le volume de données est attaché. Un agent qui démarre sans son répertoire de données se comportera de façon étrange.

Ignorer tout cela avec l'hébergement géré

La raison pour laquelle la plupart des personnes rencontrent des problèmes de configuration Telegram est qu'elles gèrent le déploiement elles-mêmes, en jonglant simultanément avec les tokens, les fichiers de configuration, les processus et les environnements serveur.

Hermify est spécifiquement conçu autour de ce problème. Le flux d'onboarding gère le câblage Telegram : vous fournissez le token du bot et les ID utilisateurs autorisés une seule fois, et la plateforme les stocke chiffrés, les injecte dans le runtime et gère le processus de passerelle.

Si le bot cesse de répondre sur Hermify, vous ne déboguez pas la passerelle. Vous consultez la carte de statut dans le tableau de bord et déclenchez un redémarrage si nécessaire. La boucle opérationnelle est basée sur le tableau de bord, pas sur SSH.

C'est la principale chose que l'hébergement Telegram géré change : non pas la configuration Telegram elle-même, mais qui est responsable de la maintenir en bonne santé. Vous pouvez comparer cette approche directement avec un VPS autogéré dans la comparaison hébergement vs auto-hébergement.