Commencer par le diagnostic automatique
La première étape de tout dépannage est de lancer `hermes doctor`. Cette commande effectue une inspection complète de l'environnement : présence et version des dépendances, validité de la configuration, accessibilité du fournisseur de modèle, état des composants installés. Elle produit un rapport structuré avec un statut clair pour chaque vérification, ce qui permet d'identifier rapidement les éléments problématiques.
Lisez attentivement chaque ligne du rapport de `hermes doctor`. Les erreurs sont généralement accompagnées d'une indication sur la cause probable et parfois d'une suggestion de correction. Résolvez les problèmes dans l'ordre où ils apparaissent : certains problèmes en aval peuvent être causés par un problème en amont. Relancez `hermes doctor` après chaque correction pour confirmer que le problème est résolu avant de passer au suivant.
- `hermes doctor` — première commande à lancer
- Lire chaque ligne du rapport attentivement
- Résoudre les problèmes dans l'ordre d'apparition
- Relancer après chaque correction
- `hermes status --all` pour un état global des composants
Vérifier la configuration
Si `hermes doctor` signale des problèmes de configuration, utilisez `hermes config check` pour valider la syntaxe et la cohérence du fichier de configuration. Cette commande détecte les erreurs de format, les clés manquantes ou les valeurs invalides. Pour localiser le fichier de configuration à inspecter ou modifier, utilisez `hermes config path` qui retourne le chemin exact sur votre système.
Si vous avez modifié manuellement le fichier de configuration et que des problèmes sont apparus, comparez votre fichier avec la documentation officielle sur https://hermes-agent.nousresearch.com/docs. Une erreur de syntaxe YAML courante, comme une indentation incorrecte ou un caractère spécial mal échappé, peut empêcher Hermes de démarrer correctement. En cas de doute, relancez `hermes setup` pour régénérer une configuration valide.
- `hermes config check` — validation de la configuration
- `hermes config path` — localiser le fichier de configuration
- Vérifier la syntaxe YAML en cas de modification manuelle
- Relancer `hermes setup` pour régénérer une configuration valide
Diagnostiquer les problèmes de modèle
Les problèmes liés au modèle sont parmi les plus fréquents : clé API invalide ou expirée, modèle non disponible pour votre fournisseur, ou quota dépassé. Utilisez `hermes model` pour vérifier quel modèle est actuellement configuré et pour en changer si nécessaire. Si la clé API est en cause, relancez `hermes setup` pour la mettre à jour.
Vérifiez que le modèle sélectionné est bien disponible pour votre compte auprès du fournisseur. Certains modèles nécessitent un accès spécifique ou sont soumis à des limitations. Si vous suspectez un problème de quota ou de limite de débit, attendez quelques minutes avant de réessayer. Les messages d'erreur retournés par le fournisseur sont généralement visibles dans les logs de `~/.hermes/logs/`.
- `hermes model` — vérifier et changer le modèle configuré
- Relancer `hermes setup` pour mettre à jour la clé API
- Vérifier la disponibilité du modèle auprès du fournisseur
- Consulter `~/.hermes/logs/` pour les erreurs du fournisseur
Inspecter les outils et les serveurs MCP
Si un outil spécifique ne fonctionne pas, commencez par lister les outils disponibles avec `hermes tools list` pour vérifier qu'il est bien activé. Si l'outil est désactivé, activez-le avec `hermes tools enable NAME`. Si un outil est activé mais ne répond pas correctement, vérifiez ses dépendances et sa configuration.
Pour les serveurs MCP, utilisez `hermes mcp list` pour voir les serveurs configurés et `hermes mcp test NAME` pour tester la connexion à un serveur spécifique. Si un serveur MCP ne répond pas, vérifiez qu'il est bien démarré et accessible. Utilisez `hermes mcp configure NAME` pour ajuster sa configuration si nécessaire. En cas de problème persistant, `hermes mcp remove NAME` suivi de `hermes mcp add NAME` permet de reconfigurer proprement un serveur.
- `hermes tools list` — lister les outils disponibles
- `hermes tools enable NAME` — activer un outil
- `hermes mcp list` — lister les serveurs MCP
- `hermes mcp test NAME` — tester un serveur MCP
- `hermes mcp configure NAME` — reconfigurer un serveur MCP
Diagnostiquer le gateway si actif
Si vous utilisez le gateway Hermes pour l'intégration avec des plateformes de messagerie, vérifiez son état avec `hermes gateway status`. Si le gateway est arrêté alors qu'il devrait être actif, redémarrez-le avec `hermes gateway start`. Les logs spécifiques au gateway sont disponibles dans `~/.hermes/logs/gateway.log` et contiennent des informations détaillées sur les connexions et les erreurs.
Il est important de noter que le gateway est la passerelle des plateformes de messagerie et ne gère pas les modèles d'IA. Si vous rencontrez des problèmes avec les réponses du modèle, le gateway n'est pas en cause : concentrez-vous sur la configuration du modèle et la clé API. Le gateway ne doit être inspecté que si les problèmes concernent spécifiquement l'intégration avec les plateformes de messagerie.
- `hermes gateway status` — état du gateway
- `hermes gateway start` — démarrer le gateway
- Logs gateway : `~/.hermes/logs/gateway.log`
- Le gateway ne gère pas les modèles d'IA
- Inspecter le gateway uniquement pour les problèmes de messagerie
Consulter les logs et reproduire le problème
Les logs d'Hermes Agent sont stockés dans `~/.hermes/logs/`. Consultez les fichiers de log les plus récents pour obtenir des informations détaillées sur les erreurs. Les logs sont horodatés et structurés, ce qui facilite la corrélation entre une action et son résultat. Cherchez les messages d'erreur, les avertissements et les traces d'exception qui peuvent indiquer la cause du problème.
Pour les problèmes difficiles à identifier, construisez une reproduction minimale : isolez la commande ou la séquence d'actions qui déclenche le problème, en supprimant tout ce qui n'est pas nécessaire. Une reproduction minimale facilite grandement le diagnostic et, si vous devez signaler un problème, permet aux mainteneurs du projet de reproduire et corriger le bug plus rapidement. Consultez le dépôt https://github.com/NousResearch/hermes-agent pour vérifier si le problème est déjà connu.
- Consulter `~/.hermes/logs/` pour les logs détaillés
- Chercher erreurs, avertissements et traces d'exception
- Construire une reproduction minimale du problème
- Vérifier les issues connues sur https://github.com/NousResearch/hermes-agent
Sources et méthode
Cette page est une synthèse éditoriale indépendante. Les capacités et commandes doivent être vérifiées dans les sources officielles avant une utilisation en production.