Depannage Hermes Agent : erreurs frequentes, diagnostics et solutions

Introduction

Cette page repertorie les erreurs les plus frequentes rencontrees avec Hermes Agent et fournit des procedures de diagnostic et de resolution. Chaque section est structuree autour d'une question canonique, avec des etapes reproductibles et des references aux sources officielles.

Les erreurs sont classees par priorite : P1 (blocantes au premier lancement), P2 (frequentes en usage courant) et P3 (avancees ou rares). Avant de plonger dans une erreur specifique, commencez toujours par hermes doctor pour un diagnostic general (src-004).

Questions couvertes

q-151: Pourquoi la commande hermes est-elle introuvable apres installation ?

Ce probleme survient quand le binaire hermes n'est pas dans le PATH de votre shell. Causes possibles et solutions :

1. Installation pip sans activation du venv : si vous avez installe avec pip install hermes-agent dans un environnement virtuel, activez-le d'abord (source venv/bin/activate).

2. Installation git sans lien symbolique : l'installation depuis le depot cree le binaire dans le dossier d'installation. Verifiez avec :

   which hermes

   Si rien n'est trouve, ajoutez le dossier au PATH ou creez un alias.

3. Shell non recharge : apres installation, rechargez votre shell (exec bash ou source ~/.bashrc).

4. Verification de l'installation :

   hermes --version

   La version testee localement est Hermes Agent v0.19.0 (src-020). Si la commande echoue, reexecutez la procedure d'installation correspondant a votre plateforme.

q-152: Pourquoi Hermes Agent ne voit-il pas Node.js ou un outil installe ?

Hermes Agent herite du PATH et de l'environnement du shell qui l'a lance. Si un outil est installe mais inaccessible :

1. Verifiez que l'outil est dans le PATH du shell parent :

   which node
   which npm

2. Lancez Hermes Agent depuis le meme shell ou les outils sont disponibles. Ne le lancez pas depuis un raccourci ou un lanceur qui herite d'un PATH different.

3. Pour les outils installes via nvm, asdf ou pyenv : ces gestionnaires modifient le PATH via des scripts de profil. Assurez-vous que ~/.bashrc ou ~/.zshrc est bien source avant de lancer Hermes Agent.

4. Alternative : utilisez hermes config set pour ajouter des chemins personnalises si necessaire, ou lancez Hermes Agent avec un PATH explicite :

   PATH="/chemin/vers/node:$PATH" hermes chat

q-153: Comment corriger une erreur de cle API dans Hermes Agent ?

Les erreurs de cle API sont les plus frequentes au premier lancement (src-013). Le message typique est Authentication error ou 401 Unauthorized.

1. Verifiez que la cle est bien dans .env :

   cat ~/.hermes/.env | grep API_KEY

   Les cles doivent etre dans ~/.hermes/.env, pas dans config.yaml.

2. Verifiez le format de la cle : pas d'espaces, pas de guillemets superflus. Format correct :

   OPENROUTER_API_KEY=sk-or-v1-abcdef...

3. Verifiez le provider configure :

   hermes config show | grep provider
   hermes auth status

4. Pour les providers OAuth (Anthropic, OpenAI Codex, Nous Portal) : utilisez hermes auth pour verifier l'etat du token. Si le token a expire, relancez hermes model pour vous reauthentifier.

5. Testez la cle independamment : pour les cles API directes, testez avec un appel curl simple vers l'endpoint du provider pour confirmer que la cle est valide.

q-154: Pourquoi un modele configure est-il introuvable ?

Plusieurs causes possibles :

1. Nom de modele incorrect : les noms de modeles sont sensibles a la casse et aux tirets. Verifiez le nom exact dans la documentation du provider ou via hermes model.

2. Provider non configure : le modele existe mais le provider correspondant n'a pas de cle API ou de token OAuth. Verifiez avec hermes auth status.

3. Modele non disponible pour votre compte : certains modeles necessitent un abonnement specifique (Claude Max, SuperGrok, etc.). Verifiez votre niveau d'acces sur le portail du provider.

4. Cache de catalogue obselete : le catalogue de modeles est mis en cache localement. Pour le rafraichir :

   hermes model

   Et selectionnez a nouveau le modele souhaite.

5. Fallback providers : si vous avez configure une chaine de fallback, verifiez que le modele est disponible sur au moins un provider de la chaine.

q-155: Comment resoudre une erreur 429 de provider ?

L'erreur 429 (Too Many Requests) indique que vous avez depasse les limites de taux (rate limit) du provider.

1. Identifiez le provider concerne : le message d'erreur indique quel provider a renvoye le 429.

2. Solutions immediates :

   • Attendez la fenetre de reinitialisation (generalement 1 minute pour les limites par minute, 1 heure pour les limites horaires)
   • Reduisez le nombre de tours (hermes config set agent.max_turns 50)
   • Passez a un autre provider si vous avez configure des fallbacks

3. Solutions durables :

   • Passez a un plan payant avec des limites plus elevees
   • Configurez une chaine de fallback entre plusieurs providers
   • Utilisez un provider avec des limites plus genereuses (OpenRouter agrege plusieurs providers)

4. Surveillance : activez le monitoring (hermes config set monitoring.enabled true) pour etre alerte avant d'atteindre les limites.

q-156: Comment corriger une conversation qui depasse la fenetre de contexte ?

Quand la conversation devient trop longue, le modele sous-jacent peut echouer avec une erreur de contexte ou degrader ses performances.

1. Symptomes : messages d'erreur mentionnant context length, token limit, reponses tronquees ou degradations de qualite.

2. Solutions :

   • Compression automatique : Hermes Agent compresse automatiquement les anciens messages (src-005, section compression). Verifiez que la compression est active :

     hermes config show | grep compression

   • Reduire le nombre de tours : hermes config set agent.max_turns 100
   • Nouvelle session : demarrez une nouvelle session et resumez le contexte manuellement
   • Changer de modele : utilisez un modele avec une fenetre de contexte plus large (ex: Claude avec 200K tokens)

3. Bonnes pratiques :

   • Divisez les taches longues en sessions plus courtes
   • Utilisez session_search pour retrouver le contexte des sessions precedentes
   • Sauvegardez les resultats intermediaires dans des fichiers

q-157: Pourquoi une commande terminal est-elle bloquee ?

Hermes Agent bloque certaines commandes pour des raisons de securite, selon le mode d'approbation configure (src-011).

1. Identifiez le mode d'approbation actif :

   hermes config show | grep approvals

   Les modes sont : smart (par defaut, bloque les commandes dangereuses), manual (demande approbation pour tout), off (yolo, desactive les approbations).

2. Commandes bloquees en mode smart : rm -rf, sudo, chmod 777, curl | bash, et autres patterns dangereux. La liste complete est dans le guide de securite (src-011).

3. Pour autoriser une commande specifique :

   • Passez en mode manual pour approuver chaque commande individuellement
   • Ajoutez la commande a la liste blanche : hermes config set command_allowlist "ma-commande"

4. Commandes toujours bloquees meme en mode yolo : certaines commandes restent bloquees quel que soit le mode (src-011). Consultez le guide de securite pour la liste exhaustive.

q-158: Pourquoi le gateway Hermes Agent ne demarre-t-il pas ?

Le gateway est le serveur qui expose Hermes Agent via Telegram, Discord, Slack et d'autres canaux.

1. Verifiez la configuration du gateway :

   hermes gateway status
   hermes doctor

2. Causes frequentes :

   • Port deja utilise : le port par defaut est 8787. Verifiez avec lsof -i :8787.
   • Secrets manquants : chaque canal (Telegram, Discord) necessite ses propres tokens dans .env.
   • Erreur de syntaxe dans config.yaml : hermes config valide la syntaxe.
   • Permissions insuffisantes : le gateway peut necessiter des droits sur certains dossiers.

3. Logs : consultez les logs pour identifier l'erreur precise :

   hermes logs gateway

4. Diagnostic en premier plan : lancez le gateway au premier plan, puis suivez son journal depuis un second terminal :

   hermes gateway run
   hermes logs gateway --follow

q-159: Pourquoi un outil MCP est-il visible mais ses appels echouent-ils ?

Un serveur MCP peut etre detecte (listage des outils reussi) mais echouer a l'execution.

1. Verifiez la connectivite : le listage utilise une connexion initiale, mais l'execution peut necessiter une connexion persistante. Verifiez que le serveur MCP est toujours en cours d'execution.

2. Timeout : les appels d'outils MCP ont un timeout. Verifiez la configuration :

   hermes config show | grep mcp

3. Permissions : certains outils MCP necessitent des permissions specifiques (acces fichier, reseau). Verifiez les logs du serveur MCP.

4. Erreurs de protocole : le serveur MCP peut ne pas implementer correctement la specification. Verifiez la compatibilite avec la version MCP supportee par Hermes Agent (src-010).

5. Diagnostic :

   hermes mcp list          # liste les serveurs configures
   hermes mcp status        # etat de chaque serveur

q-160: Quelles preuves collecter avant d'ouvrir un ticket Hermes Agent ?

Avant de signaler un bug ou de demander de l'aide, rassemblez ces elements pour un diagnostic efficace :

1. Version de Hermes Agent :

   hermes --version

2. Diagnostic complet :

   hermes doctor
   hermes status

3. Logs pertinents : extrayez les logs de la session problematique.

4. Configuration (sans secrets) :

   hermes config show

   Ne partagez jamais votre fichier .env ou auth.json. Masquez les cles API et tokens avant de partager config.yaml.

5. Message d'erreur complet : copiez le message d'erreur exact, pas une paraphrase.

6. Etapes pour reproduire : decrivez la sequence exacte d'actions qui declenche l'erreur.

7. Environnement : systeme d'exploitation, version de Python (python --version), shell utilise.

Ces informations permettent aux mainteneurs (ou a la communaute) de diagnostiquer le probleme sans aller-retour inutiles.

Sources

• Documentation officielle Hermes Agent (https://hermes-agent.nousresearch.com/docs/)
• CLI commands reference (https://hermes-agent.nousresearch.com/docs/reference/cli-commands)
• FAQ officielle (https://hermes-agent.nousresearch.com/docs/reference/faq)
• Guide de securite (https://hermes-agent.nousresearch.com/docs/user-guide/security)
• Guide MCP (https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)
• Depot NousResearch/hermes-agent, commit b4f8c491d3452926deb7628edbdb6fe2a85ff576
• CLI Hermes Agent v0.19.0 testee localement

Liens internes proposes

• FAQ
• Configurer Hermes Agent
• Securite
• Outils et MCP
• Installer Hermes Agent
• Methodologie