Hermes Agent Telegram : tutoriel complet

Introduction

Relier Hermes Agent à Telegram permet de lancer une tâche, envoyer une pièce jointe ou recevoir le résultat d’une automatisation depuis un téléphone. Ce canal est pertinent pour les builders qui disposent déjà d’une installation Hermes fonctionnelle et veulent un accès distant privé. En revanche, ce n’est pas le bon choix pour un bot public ouvert à des inconnus : Hermes peut utiliser le terminal et d’autres outils sensibles. Ce tutoriel Hermes Agent Telegram va de la création du bot à un test complet après redémarrage, avec une allowlist stricte, le cas des groupes et le diagnostic d’un bot silencieux.

Résumé rapide

1. Créez le bot auprès de @BotFather et conservez son token hors du code.
2. Relevez votre identifiant Telegram numérique, puis lancez hermes gateway setup.
3. Autorisez uniquement vos identifiants, démarrez la gateway et vérifiez son statut.
4. Testez successivement texte, commande, image, fichier et message vocal.
5. Pour un groupe, gardez le privacy mode ou exigez une mention, avec le chat explicitement autorisé.

Comprendre la connexion entre Hermes et Telegram

La gateway Hermes Agent est le processus qui relie une même instance aux plateformes de messagerie. Elle reçoit les mises à jour Telegram, rattache chaque conversation à une session Hermes, transmet le message à l’agent puis livre sa réponse. Elle gère aussi les tâches planifiées et les pièces jointes. Ce n’est pas une « gateway LLM » : le modèle reste fourni par OpenRouter, Anthropic, OpenAI ou un autre fournisseur configuré séparément. Un bot peut donc apparaître connecté à Telegram tout en échouant au moment de répondre si le fournisseur de modèle n’est pas opérationnel.

Par défaut, l’adaptateur Telegram utilise le long polling : la gateway interroge l’API Telegram pour récupérer les messages. Cette option convient à une machine locale ou un VPS toujours actif, sans URL publique ni certificat TLS. En mode webhook, Telegram pousse les mises à jour vers une URL HTTPS. C’est pertinent sur un cloud qui réveille une machine avec une requête entrante. Le choix affecte aussi la latence d’un agent IA. La comparaison entre webhooks et polling figure dans les articles liés.

La sécurité repose sur deux frontières. Le token BotFather authentifie le programme auprès de Telegram ; quiconque le possède peut contrôler le bot. L’allowlist Hermes détermine ensuite quels utilisateurs ou chats peuvent solliciter l’agent. Un pseudo @nom ne suffit pas : Hermes attend des identifiants numériques stables. Avant de commencer, terminez l’installation de Hermes Agent, configurez un modèle et vérifiez qu’une requête fonctionne dans le terminal.

Configurer et tester le bot Telegram pas à pas

1. Créer le bot avec BotFather

Dans Telegram, ouvrez le compte officiel @BotFather, puis envoyez /newbot. Donnez au bot un nom d’affichage libre, puis un nom d’utilisateur unique qui se termine par bot, par exemple atelier_hermes_bot. BotFather retourne un token. Ne le copiez ni dans une issue, ni dans une capture, ni dans un dépôt Git.

Les valeurs ci-dessous sont volontairement factices :

TELEGRAM_BOT_TOKEN=<TOKEN_TELEGRAM_ICI>
TELEGRAM_ALLOWED_USERS=<VOTRE_ID_NUMERIQUE>

Si le token a été exposé, utilisez /revoke auprès de BotFather, remplacez la valeur stockée par Hermes et redémarrez la gateway. Une suppression du message contenant le token ne constitue pas une rotation.

La personnalisation est facultative. /setdescription renseigne l’accueil, /setabouttext le profil, /setuserpic l’avatar et /setcommands le menu. Hermes enregistre aussi son menu au démarrage. Avec /setprivacy, ne désactivez pas la confidentialité d’un groupe sans avoir défini le comportement attendu.

2. Trouver l’identifiant utilisateur autorisé

Envoyez un message à @userinfobot ou @get_id_bot. Copiez le nombre retourné, pas votre pseudo. Si deux personnes doivent administrer Hermes, relevez les deux identifiants et autorisez-les explicitement. Évitez une valeur globale destinée à « simplifier le test » : un bot Hermes peut accéder aux outils de la machine, ce qui rend l’ouverture publique disproportionnée.

Le guide des permissions d’outils pour agents IA complète l’allowlist : la première limite qui peut parler au bot, la seconde limite ce que l’agent peut faire après réception d’une demande.

3. Configurer Hermes Telegram avec l’assistant

La méthode recommandée par la documentation officielle est interactive :

hermes gateway setup

Sélectionnez Telegram, saisissez le token lorsqu’il est demandé, puis la liste des identifiants autorisés. L’assistant écrit la configuration à votre place et propose de lancer ou redémarrer la gateway. Le secret doit rester dans le fichier d’environnement Hermes, normalement ~/.hermes/.env, tandis que la configuration générale se trouve dans ~/.hermes/config.yaml.

Pour une configuration manuelle, ajoutez les variables suivantes dans ~/.hermes/.env en remplaçant uniquement les marqueurs :

TELEGRAM_BOT_TOKEN=<TOKEN_FOURNI_PAR_BOTFATHER>
TELEGRAM_ALLOWED_USERS=<ID_1>,<ID_2>

N’ajoutez aucun espace superflu dans la liste. Restreignez les permissions du fichier d’environnement au compte qui exécute Hermes et traitez les pièces jointes comme des données potentiellement sensibles. Le guide sur les données sensibles et les agents IA détaille les risques de journalisation et de transmission à un modèle tiers.

4. Lancer la gateway et contrôler son état

Pour observer directement le démarrage et les erreurs, lancez d’abord la gateway au premier plan :

hermes gateway run

Pour une exécution durable, installez-la ensuite comme service utilisateur, démarrez-la et contrôlez son statut :

hermes gateway install
hermes gateway start
hermes gateway status

Sur Linux, un service utilisateur peut nécessiter le maintien de la session utilisateur après déconnexion. Ne concluez jamais que la gateway fonctionne en vous fiant seulement à la présence d’un processus Python : hermes gateway status est le contrôle prévu pour le service. Les journaux de la gateway se trouvent dans ~/.hermes/logs/gateway.log.

5. Valider texte, commande, image, fichier et voix

Ouvrez une conversation privée avec le bot et appuyez sur Démarrer. Procédez dans cet ordre afin d’isoler une panne :

1. envoyez Réponds seulement : canal Telegram opérationnel ;
2. envoyez /status et vérifiez que les informations de session arrivent ;
3. joignez une petite image et demandez une description factuelle ;
4. joignez un fichier texte sans secret et demandez d’en extraire trois points ;
5. envoyez un court message vocal et vérifiez sa transcription ou son traitement.

Le texte prouve le trajet Telegram → gateway → modèle → Telegram. /status vérifie le routage des commandes. Les trois derniers essais couvrent la réception et la mise en cache des médias. La voix exige en plus un fournisseur de transcription configuré ; son échec isolé ne signifie donc pas que le bot entier est hors service.

Pour envoyer un fichier généré, Hermes utilise une balise finale de type MEDIA:/chemin/rapport.pdf. Si le terminal de l’agent s’exécute dans Docker, ce chemin doit aussi être lisible par le processus gateway sur l’hôte. Montez un répertoire de sortie partagé plutôt que de retourner un chemin qui n’existe que dans le conteneur.

6. Utiliser le bot dans un groupe ou un topic

Le privacy mode de Telegram est activé par défaut. Dans un groupe, le bot reçoit alors les commandes commençant par /, les réponses directes à ses propres messages et certains messages de service, mais pas toute la conversation. Cette restriction est souvent souhaitable : elle réduit le bruit et évite que chaque phrase du groupe entre dans le contexte de l’agent.

Si Hermes doit lire les messages ordinaires, désactivez la confidentialité via Bot Settings → Group Privacy dans BotFather, puis retirez et réajoutez le bot au groupe. Telegram mémorise l’état lors de l’ajout. Une autre option consiste à promouvoir le bot administrateur, ce qui lui donne accès aux messages ; n’accordez toutefois que les droits nécessaires.

Même lorsque le bot peut voir la conversation, limitez les réponses au chat prévu et exigez une mention. Le schéma actuel documenté est le suivant :

telegram:
  allowed_chats:
    - "<ID_DU_GROUPE>"
  group_allowed_chats:
    - "<ID_DU_GROUPE>"
  require_mention: true
  observe_unmentioned_group_messages: true

Les messages non mentionnés alimentent alors le contexte partagé du chat ou du topic, sans déclencher l’agent. Une mention @atelier_hermes_bot ou une réponse directe déclenche le traitement. Réservez ce mode à un groupe de confiance : observer signifie quand même transmettre du contenu à Hermes. Les topics de forum séparent les conversations ; vérifiez dans chaque topic que la session attendue est utilisée avant d’y traiter un sujet sensible.

7. Diagnostiquer « Hermes Telegram ne répond pas »

Commencez par la frontière la plus proche du système :

hermes gateway status

Si le service est arrêté, démarrez-le. S’il redémarre en boucle ou si Telegram reste silencieux, consultez le journal. La démarche rejoint le traitement des timeouts et retries d’un agent IA : observer avant de relancer évite de masquer le signal initial.

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

Puis envoyez un nouveau message de test. Cherchez l’étape exacte qui manque : connexion Telegram, réception de la mise à jour, refus par allowlist, appel du modèle ou envoi de la réponse. Cette lecture chronologique évite de régénérer inutilement un token valide.

Contrôlez ensuite, dans cet ordre :

• Token : valeur complète, non révoquée, sans guillemets ajoutés par erreur ;
• Utilisateur : identifiant numérique présent dans TELEGRAM_ALLOWED_USERS ;
• Groupe : identifiant de chat autorisé et privacy mode cohérent avec le type de message ;
• Gateway : configuration rechargée par un redémarrage après modification ;
• Modèle : fournisseur et authentification fonctionnels indépendamment de Telegram ;
• Réseau : accès sortant à l’API Telegram en mode polling.

Si les commandes fonctionnent dans un groupe mais pas le texte ordinaire, le privacy mode est probablement la cause. Si le texte fonctionne mais pas la voix, inspectez la transcription et la taille du média. Si une réponse annonce un fichier sans le joindre, vérifiez que le chemin MEDIA: est visible depuis l’hôte de la gateway.

Checklist de validation

• Le token n’apparaît dans aucun fichier versionné ou message partagé.
• Seuls les identifiants prévus sont dans l’allowlist.
• hermes gateway status indique un service actif.
• Texte, commande, image, fichier et voix ont été testés séparément.
• Le comportement des groupes exige une commande, une réponse ou une mention.
• Le journal permet de relier chaque échec à une étape précise.

Exemple concret

Prenons une petite équipe qui utilise Hermes pour préparer une veille quotidienne. Une seule personne administre l’agent en message privé ; un groupe Telegram reçoit les synthèses et peut demander un approfondissement par mention. Le token reste dans ~/.hermes/.env, l’identifiant de l’administratrice figure dans TELEGRAM_ALLOWED_USERS et le groupe est ajouté aux chats autorisés. Le privacy mode reste actif tant que les membres utilisent des commandes ou répondent au bot : il n’est pas nécessaire de faire lire toute la conversation à Hermes.

Le test d’acceptation tient en quatre passages observables. D’abord, l’administratrice envoie Résume ce texte en trois points avec un fichier .txt dépourvu de données privées ; elle doit recevoir trois points et non un simple accusé de réception. Ensuite, elle envoie /status pour confirmer que les commandes sont routées. Puis elle demande au bot de produire un petit fichier Markdown ; Telegram doit recevoir une vraie pièce jointe, pas seulement un chemin local.

Enfin, elle redémarre le service :

hermes gateway restart
hermes gateway status

Après le retour à l’état actif, elle envoie Test après redémarrage. La réponse valide à la fois la reprise de connexion et la persistance opérationnelle. En cas d’échec, elle note l’heure précise, ouvre ~/.hermes/logs/gateway.log et associe le message à une erreur de réception, d’autorisation, de modèle ou de livraison. Ce protocole est assez court pour être rejoué après chaque mise à jour.

Bonnes pratiques

• Principe du moindre accès : commencez par un seul utilisateur autorisé. Ajoutez un groupe uniquement lorsqu’un besoin concret le justifie.
• Rotation immédiate : après toute exposition possible, révoquez le token avec BotFather au lieu d’essayer d’évaluer si quelqu’un l’a copié.
• Tests sans données réelles : utilisez des images et documents factices avant d’envoyer des contrats, exports clients ou journaux internes.
• Déclenchement explicite en groupe : préférez les commandes, réponses et mentions à l’écoute permanente de tous les messages.
• Exploitation observable : conservez hermes gateway status et ~/.hermes/logs/gateway.log dans votre procédure d’incident. Rejouez des tests de non-régression pour agents IA après une mise à jour et après un redémarrage de la machine.
• Séparation des pannes : vérifiez le modèle depuis le terminal avant d’accuser Telegram ; vérifiez un texte simple avant d’accuser la gestion des fichiers.

La réalité de production est simple : un bot utile doit rester disponible sans devenir un accès public à votre machine. Si l’usage devient régulier, faites tourner Hermes en continu sur un hôte supervisé, sauvegardez uniquement la configuration non secrète et prévoyez une procédure de rotation. Après le premier échange Telegram, apprenez à faire tourner Hermes en continu sur un VPS avec Docker via le guide d’installation lié ci-dessous.

Questions fréquentes

Comment configurer Hermes Agent avec Telegram ?

Créez un bot avec @BotFather, relevez votre identifiant numérique, puis exécutez hermes gateway setup. Sélectionnez Telegram, saisissez le token et les utilisateurs autorisés. Lancez ensuite hermes gateway run au premier plan ou installez le service. Validez avec un message simple, /status, une pièce jointe et hermes gateway status.

Pourquoi mon bot Telegram Hermes Agent ne répond pas ?

Vérifiez d’abord hermes gateway status, puis suivez ~/.hermes/logs/gateway.log pendant l’envoi d’un message. Les causes fréquentes sont un token révoqué, un identifiant absent de l’allowlist, une configuration non rechargée, le privacy mode dans un groupe ou un fournisseur de modèle indisponible. Testez le texte avant les médias pour isoler la panne.

Faut-il désactiver le privacy mode de BotFather dans un groupe ?

Non, pas si les membres utilisent des commandes, répondent au bot ou le mentionnent selon votre configuration. Désactivez le privacy mode seulement si Hermes doit recevoir les messages ordinaires. Retirez puis réajoutez alors le bot, autorisez explicitement le chat et activez require_mention pour éviter une réponse automatique à chaque message.

Hermes Agent Telegram accepte-t-il les fichiers et messages vocaux ?

Oui. L’intégration prend en charge le texte, les images, les fichiers et les messages vocaux. La voix nécessite une transcription correctement configurée. Pour les fichiers générés avec un terminal Docker, le chemin indiqué par MEDIA: doit être accessible au processus gateway sur l’hôte ; un chemin présent uniquement dans le conteneur ne peut pas être joint.

Articles liés

Hermes Agent Telegram est pertinent lorsqu’un petit nombre d’utilisateurs identifiés a besoin d’un canal distant pratique. Une allowlist, des déclenchements explicites en groupe et un test après redémarrage en font un accès exploitable plutôt qu’un simple prototype. L’étape logique suivante consiste à stabiliser l’hébergement et à réduire les permissions disponibles depuis le bot.

• Hermes Agent : guide pour builders IA
• Installer Hermes Agent pas à pas
• Webhooks ou polling pour connecter un agent
• Limiter les permissions des outils d’un agent IA
• Protéger les données sensibles utilisées par un agent IA