Hermes Agent ne fonctionne pas : diagnostic

Introduction

Quand Hermes Agent ne fonctionne pas, réinstaller immédiatement efface souvent les indices sans corriger la cause : PATH absent, fournisseur mal authentifié, gateway arrêtée, mauvais profil ou livraison cron invalide. Ce guide est utile aux utilisateurs qui disposent déjà d’une installation et veulent isoler la couche fautive avec des contrôles reproductibles. Il n’est pas le bon choix si vous cherchez encore une première installation complète : suivez plutôt le guide dédié. Le principe est simple : partir du symptôme, observer un signal, tester une seule hypothèse, corriger sans exposer de secret, puis vérifier le résultat au même niveau que la panne.

Résumé rapide

1. Lancez hermes doctor, puis relevez hermes --version et hermes status --all.
2. Reproduisez l’échec avec le profil et l’interface concernés, sans modifier plusieurs réglages à la fois.
3. Pour chaque symptôme, distinguez processus, configuration, authentification, connexion et livraison réelle.
4. Corrigez la cause la plus locale avant d’envisager mise à jour ou réinstallation.
5. Validez avec une requête minimale, puis avec le trajet complet qui échouait.

Le bon modèle mental pour dépanner Hermes

Hermes n’est pas un processus monolithique. Une commande peut être installée correctement alors que le modèle refuse l’authentification ; une gateway peut tourner alors que Telegram n’est plus connecté ; un cron peut s’exécuter sans parvenir à livrer sa réponse. Le guide d’architecture de Hermes Agent aide à situer ces frontières avant toute correction.

Commencez par une photo d’ensemble :

hermes --version
hermes doctor
hermes status --all
hermes config path
hermes config env-path

hermes doctor contrôle les dépendances et la configuration. La version permet de rapprocher une erreur d’une documentation ou d’un changement récent. status --all décrit les composants gérés ; les deux commandes de chemin évitent surtout d’inspecter le mauvais fichier. Ne copiez jamais le contenu de .env dans un ticket ou un chat : confirmez seulement qu’une variable attendue existe, puis masquez intégralement sa valeur.

Le diagnostic doit rester vertical. Si hermes est introuvable, inutile d’examiner Telegram. Si une requête locale minimale échoue avec 401, la gateway n’est probablement pas la première cause. À l’inverse, si le chat local répond mais pas le bot, concentrez-vous sur le service, l’autorisation et la plateforme. Cette séparation transforme un vague « Hermes Agent error » en hypothèse testable.

Diagnostiquer chaque symptôme sans tout réinstaller

Symptôme 1 — hermes: command not found ou dépendance absente

Signal. Le shell ne trouve pas hermes, ou une action lancée par l’agent échoue avec node, uv, nvm, pyenv ou asdf introuvable.

Contrôle. Vérifiez d’abord le binaire et les versions réellement visibles dans le contexte qui échoue :

command -v hermes
python3 --version
command -v uv
hermes --version

La documentation officielle indique Python 3.11 ou plus récent. Après une installation standard, le lanceur se trouve généralement dans ~/.local/bin. Un terminal interactif et une gateway de service peuvent toutefois hériter de PATH différents.

Cause probable. Le profil du shell n’a pas été rechargé, ~/.local/bin n’est pas dans PATH, ou l’outil dépendant est initialisé uniquement dans un fichier que le shell de session ne lit pas. Sous un service, un PATH minimal explique souvent qu’une commande marche dans votre terminal mais pas via Telegram.

Correction. Ouvrez d’abord un nouveau terminal ou rechargez le bon profil (source ~/.bashrc pour Bash, source ~/.zshrc pour Zsh). Si le PATH reste incomplet, ajoutez proprement ~/.local/bin à la configuration du shell. Pour les outils visibles uniquement après l’initialisation de nvm, pyenv ou asdf, configurez terminal.shell_init_files avec le fichier pertinent plutôt que de déplacer des binaires. Reprenez l’installation de Hermes Agent seulement si le binaire est réellement absent ; une suppression complète n’est pas une première étape de diagnostic.

Vérification. Fermez puis rouvrez le contexte concerné et répétez command -v hermes, hermes --version, puis une requête minimale :

hermes chat -q "Réponds uniquement OK"

Symptôme 2 — erreur modèle, contexte, 401, 403 ou 429

Signal. La CLI démarre, mais le premier appel échoue ; /model n’affiche qu’un fournisseur ; une longue session dépasse la fenêtre de contexte ; ou l’API renvoie un code HTTP.

Contrôle. Confirmez le fournisseur et le modèle actifs avec /status dans la session, ou consultez la configuration sans afficher les secrets :

hermes config
hermes auth list
hermes doctor

Testez ensuite une requête courte dans une nouvelle session. Un succès sur ce test et un échec sur une conversation longue orientent vers le contexte, pas vers la clé. Pour un modèle local, comparez la fenêtre déclarée dans Hermes avec celle réellement configurée côté serveur.

Cause probable. Un 401 correspond généralement à un identifiant absent, expiré ou affecté au mauvais fournisseur. Un 403 pointe plutôt vers une autorisation, un abonnement ou un modèle non accessible ; pour GitHub Copilot, un jeton obtenu par gh auth login ne remplace pas le flux OAuth propre à Copilot. Un 429 indique une limite de débit ou de quota. Une erreur 400 au premier appel provient souvent d’un identifiant de modèle invalide. Un dépassement de contexte vient d’une session trop longue ou d’une valeur context_length incohérente.

Correction. Utilisez hermes model hors session pour ajouter ou reconfigurer un fournisseur ; /model ne bascule qu’entre ceux déjà configurés. Pour OAuth, relancez hermes login --provider <fournisseur> ou l’assistant d’authentification correspondant. Ne collez pas une clé dans l’historique du terminal, les logs ou un rapport : passez par l’assistant et le fichier d’environnement indiqué par hermes config env-path. Sur 429, attendez le délai annoncé, réduisez la concurrence ou choisissez un autre modèle déjà autorisé ; une boucle de retries agressive aggrave la limitation. Si la continuité de service l’exige, préparez un fallback de modèle explicite plutôt qu’une bascule improvisée pendant l’incident. Sur contexte saturé, utilisez /compress, démarrez une nouvelle session, ou corrigez la fenêtre déclarée. Les stratégies de timeouts et retries sont utiles quand l’échec est réellement transitoire.

Vérification. Relancez une requête minimale avec le fournisseur corrigé, puis la charge qui échouait. Un changement de code HTTP sans réponse valide n’est pas encore une réussite : contrôlez aussi que le modèle répond et qu’un outil simple peut être appelé.

Symptôme 3 — gateway active, mais Telegram reste silencieux

Signal. hermes répond en local, mais le bot ne répond pas, les messages ne partent plus, ou le comportement diverge après un redémarrage.

Contrôle. Distinguez trois états : processus de gateway, connexion de la plateforme et activité réelle.

hermes gateway status
hermes status --all
hermes pairing list

Consultez ensuite les dernières entrées de ~/.hermes/logs/gateway.log, en retirant tokens, identifiants personnels et charges utiles sensibles avant partage. Un processus présent ne prouve ni que l’adaptateur Telegram est connecté, ni qu’il reçoit des mises à jour récentes.

Cause probable. La gateway peut être arrêtée, utiliser un autre profil, refuser l’utilisateur faute d’allowlist ou de pairing, ou perdre l’accès au bot. Deux profils ne doivent pas faire tourner simultanément le même token Telegram : la plateforme exige un accès exclusif. En groupe, permissions et règles de mention peuvent également expliquer le silence. Enfin, un service lancé avec un environnement incomplet peut ne pas voir les mêmes dépendances que la CLI.

Correction. Si le service est arrêté, utilisez hermes gateway start; pour observer directement l’erreur, arrêtez le service puis lancez hermes gateway run au premier plan. Reprenez hermes gateway setup si la plateforme est mal configurée, puis approuvez explicitement un pairing attendu. N’ouvrez pas l’accès à tous les utilisateurs pour contourner un problème d’autorisation. Si un réglage a changé, redémarrez la gateway afin qu’il soit relu. Le tutoriel Hermes Agent sur Telegram détaille la configuration complète.

Vérification. Envoyez un message unique depuis un compte autorisé et corrélez son heure avec le log. Validez successivement : réception, création ou reprise de session, réponse du modèle, puis livraison Telegram. Cette dernière étape évite de conclure à tort qu’une gateway « connectée » fonctionne de bout en bout.

Symptôme 4 — mauvais profil, outil absent ou serveur MCP invisible

Signal. Une commande fonctionne sans option mais pas avec --profile, une mémoire ou une skill semble avoir disparu, un outil n’est pas proposé, ou un serveur MCP est configuré sans exposer ses outils.

Contrôle. Identifiez le profil avant d’inspecter les composants :

hermes profile list
hermes profile show <nom>
hermes tools list
hermes mcp list
hermes mcp test <nom>

Chaque profil possède sa propre configuration, ses secrets, sessions, skills, crons et état de gateway. Un succès dans le profil par défaut ne valide donc pas le profil de production.

Cause probable. Vous modifiez le mauvais profil ; le toolset est désactivé pour la plateforme ; le changement n’a pas encore été chargé dans une nouvelle session ; ou le serveur MCP ne démarre pas parce que son binaire, son runtime ou son chemin est absent. Il peut aussi répondre sans supporter tools/list, ou ses outils peuvent être filtrés par include, exclude ou enabled.

Correction. Rejouez les contrôles avec hermes --profile <nom> .... Activez seulement le toolset nécessaire avec hermes tools enable <nom>, puis ouvrez une nouvelle session : la liste d’outils est figée au démarrage. Pour MCP, corrigez la commande ou l’URL, testez le serveur avec hermes mcp test <nom>, puis utilisez /reload-mcp. Sous WSL2, la FAQ officielle recommande un pont MCP pour piloter le Chrome Windows plutôt qu’une connexion navigateur forcée entre les deux environnements. Une stratégie de tests de non-régression permet ensuite de vérifier qu’une mise à jour ne retire pas un outil critique.

Vérification. Dans une session neuve du bon profil, demandez la liste des outils disponibles puis exécutez une opération de lecture sans effet de bord. Pour MCP, un test de transport réussi ne suffit pas : vérifiez qu’un outil découvert renvoie bien une réponse.

Symptôme 5 — le cron est actif, mais rien n’est livré

Signal. Le job apparaît dans la liste, mais il ne part pas à l’heure attendue, s’exécute sans message, ou livre dans un autre canal.

Contrôle. Examinez séparément planification, exécution et destination :

hermes cron list --all
hermes cron status
hermes gateway status
hermes cron run <ID>

Comparez aussi l’heure locale de la machine avec le prochain déclenchement affiché. La documentation officielle précise qu’un chat CLI ordinaire ne déclenche pas automatiquement les jobs : le scheduler durable dépend d’une gateway en cours d’exécution.

Cause probable. Le job est en pause ou terminé, le fuseau de la machine diffère de celui attendu, la gateway est arrêtée, la cible de livraison est mal orthographiée ou sensible à la casse, ou les permissions de la plateforme sont insuffisantes. Une réponse contenant le marqueur silencieux prévu pour les tâches de surveillance peut également supprimer volontairement la livraison.

Correction. Reprenez le job avec hermes cron resume <ID>, corrigez son horaire ou sa cible avec hermes cron edit <ID>, puis démarrez la gateway. Vérifiez les droits du bot dans le canal sans publier son token. Réservez le mode silencieux au cas « aucun changement » et demandez une réponse explicite pendant le diagnostic.

Vérification. Déclenchez le job manuellement, confirmez son exécution dans l’état ou les logs, puis vérifiez la réception sur la destination exacte. Enfin, observez un déclenchement planifié réel : un run manuel valide le prompt et la livraison, pas le calcul de la prochaine échéance.

Exemple concret : isoler un bot Telegram silencieux

Une équipe exploite Hermes avec le profil ops. Le chat local répond, mais le bot Telegram n’a rien livré depuis le redémarrage du serveur. Elle commence par figer le contexte sans copier le fichier d’environnement : version, heure, profil utilisé et texte exact de l’erreur, avec toute valeur sensible remplacée par [REDACTED].

hermes --version
hermes --profile ops doctor
hermes --profile ops gateway status
hermes --profile ops pairing list

Le diagnostic montre une configuration valide, mais une gateway inactive pour ops. Une gateway existe pourtant sur la machine : elle appartient au profil par défaut. L’équipe ne change ni token ni allowlist. Elle lance temporairement la bonne instance au premier plan pour obtenir un signal lisible :

hermes --profile ops gateway run

Depuis un compte déjà autorisé, elle envoie test-incident-247. Le log montre successivement la réception Telegram, l’ouverture de session, l’appel modèle et l’envoi de réponse. Après ce test, elle arrête le premier plan, installe ou redémarre le service du profil ops selon son mode d’exploitation, puis vérifie gateway status avec le même profil.

La validation finale comporte deux scénarios : un message interactif, puis hermes --profile ops cron run <ID> vers le même chat. Le premier prouve le trajet Telegram ; le second ajoute scheduler et routage de livraison. Si le cron échoue seul, l’équipe conserve la gateway et examine la cible du job. Cette démarche produit une preuve par couche, contrairement à une réinstallation qui aurait pu déplacer la panne sans l’expliquer.

Bonnes pratiques

Gardez une mini-checklist d’incident : heure et fuseau, OS, hermes --version, profil exact, commande de reproduction, résultat de hermes doctor, composant touché et dernière action connue. Ajoutez un identifiant de test neutre pour corréler message et logs. Un guide d’observabilité des agents IA aide à conserver ces signaux sans transformer les journaux en dépôt de données sensibles.

Appliquez ensuite quatre règles :

• ne modifiez qu’une couche à la fois et refaites le même contrôle ;
• ne supprimez configuration, profil ou sessions qu’après sauvegarde et preuve qu’ils sont corrompus ;
• ne partagez jamais .env, token, clé API, URL signée ou log brut contenant des identifiants ;
• vérifiez le trajet complet, pas seulement la présence d’un processus.

En production, consignez cause, correction, preuve et condition de retour arrière dans des runbooks d’incidents pour agents IA. Si le problème disparaît après plusieurs changements simultanés, vous n’avez pas un correctif reproductible : revenez à une configuration connue, réintroduisez les changements un par un et gardez la solution la plus simple.

Questions fréquentes

Que faire quand Hermes Agent ne fonctionne pas après l’installation ?

Commencez par command -v hermes, hermes --version et hermes doctor. Si le binaire existe, vérifiez le PATH du contexte qui échoue avant de réinstaller. Ouvrir un nouveau terminal ou recharger le profil du shell suffit souvent. Si seule une dépendance manque dans la gateway, comparez son environnement à celui de la CLI.

Comment corriger une erreur Hermes Agent 401 ou 429 ?

Un 401 demande de vérifier le fournisseur, l’état de l’authentification et la correspondance de la clé, sans jamais afficher sa valeur. Reconfigurez avec hermes model ou le flux de connexion adapté. Un 429 signale une limite : respectez l’attente indiquée, réduisez la concurrence ou utilisez un autre modèle autorisé plutôt que de relancer en boucle.

Pourquoi Hermes gateway ne répond pas sur Telegram ?

Vérifiez hermes gateway status, puis l’autorisation avec hermes pairing list et les logs expurgés. Distinguez un processus actif d’une plateforme connectée et d’un message réellement livré. Contrôlez aussi le profil : une gateway lancée sur le profil par défaut ne sert pas automatiquement le bot configuré dans un profil nommé.

Pourquoi un outil, un serveur MCP ou un cron n’apparaît pas ?

Ils peuvent appartenir à un autre profil ou ne pas avoir été rechargés. Contrôlez hermes profile list, hermes tools list, hermes mcp list et hermes cron list --all. Après une modification d’outils, ouvrez une nouvelle session ; après un changement MCP, utilisez /reload-mcp. Pour cron, assurez-vous qu’une gateway tourne et que le job n’est pas en pause.

Articles liés

Un dépannage fiable part d’un symptôme, traverse une seule couche à la fois et se termine par une preuve sur le trajet complet. Si l’installation locale est stable mais fragile au redémarrage, la prochaine étape consiste à formaliser ces contrôles avant d’envisager un hébergement persistant sur VPS ou Docker.

• Hermes Agent : architecture et usages pour builders IA
• Installer Hermes Agent sur une base propre
• Configurer Hermes Agent sur Telegram
• Maîtriser les timeouts et retries des agents IA
• Déployer Hermes Agent avec Docker sur un VPS