Lors de l'utilisation de Hermes avec le fournissuer Zai pour accéder aux modèles GLM, une erreur d'authentification fréquente peut survenir :

Appel API échoué (tentative 1/3) : AuthenticationError [HTTP 401]
   Fournisseur : zai  Modèle : glm-4.5-air
   Point d'accès : https://open.bigmodel.cn/api/paas/v4
   Erreur : HTTP 401 : Le jeton a expiré ou est invalide

Ce message indique que la clé API fournie n'est pas accepptée par le serveur distant. Voici comment diagnostiquer et corriger ce problème.

Diagnostic initial : vérifier le fichier de configuration

La cause la plus courante est une configuration incomplète ou corrompue. Ouvrez le fichier de configuration :

nano ~/.hermes/config.yaml

Recherchez la section providers. Si elle est vide (providers: {}), Hermes ne dispose d'aucune clé pour s'authentifier. Remplacez-la par :

providers:
  zai:
    api_key: "sk-votre-cle-api-complete-ici"

Attention : la clé doit être collée intégralement telle que fournie par la plateforme, sans espace superflu ni retour à la ligne. Conservez les guillemets.

Enregistrez avec Ctrl+O, validez avec Entrée, puis quittez avec Ctrl+X.

Vérifiez que la modification est bien prise en compte :

cat ~/.hermes/config.yaml | grep -A3 providers

Un piège fréquent : la présence de providers: {} plus bas dans le fichier, qui écrase la configuration définie précédemment. Supprimez toute ligne en double.

Tester la validité de la clé API

Si la configuraton semble correcte mais que l'erreur persiste, testez votre clé indépendamment de Hermes :

curl https://open.bigmodel.cn/api/paas/v4/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -d '{
    "model": "glm-4-flash",
    "messages": [{"role": "user", "content": "Bonjour, ceci est un test"}]
  }'

Si le test échoue, générez une nouvelle clé depuis le portail Zhipu :

1. Connectez-vous à votre compte Zhipu AI
2. Rendez-vous dans la section de gestion des clés API
3. Générez une nouvelle clé et copiez-la intégralement
4. Relancez le test curl avec la nouvelle clé

Un compte nouvellement créé peut nécessiter quelques minutes avant que la clé ne devienne active. Vérifiez également que votre compte est vérifié et dispose de crédits suffisants.

Une fois la validité confirmée, mettez à jour le fichier de configuration avec la nouvelle clé, puis redémarrez Hermes :

hermes

Alternative : injection via variable d'environnement

Si Hermes ne parvient toujours pas à lire la clé depuis le fichier YAML malgré une configuration correcte, il est possible qu'une variable d'environnement obsolète prenne le dessus. Hermes privilégie l'ordre suivant : variables d'environnement > arguments en ligne de commande > fichier config.yaml.

Pour contourner le problème, démarrez Hermes avec la clé passée directement en variable d'environnement :

CLE_ZAI="89efe60fXXXXXXXXXXXXXXXX.XXXXXXXXXX" hermes

Pour rendre cette configuration permanente, ajoutez-la à votre fichier ~/.bashrc :

echo 'export CLE_ZAI="89efe60fXXXXXXXXXXXXXXXX.XXXXXXXXXX"' >> ~/.bashrc
source ~/.bashrc

Dès lors, chaque invocation de hermes utilisera automatiquement cette clé, en ignorant toute valeur erronée du fichier de configuration.

Récapitulatif des points de vigilance

• Ne jamais saisir manuellement une clé API : copiez-la directement depuis la plateforme
• Supprimez les espaces et sauts de ligne autour de la clé collée
• Utilisez le modèle glm-4-flash pour les tests initiaux car il est disponible gratuitement
• Vérifiez l'absence de sections providers dupliquées dans le fichier YAML
• En cas de doute, privilégiez l'injection par variable d'environnement