Agent Hermes : Guide de configuration auto-hébergée pour les utilisateurs de serveurs domestiques

Eva Wong est la rédactrice technique et bricoleuse résidente chez ZimaSpace. Geek depuis toujours, passionnée par les laboratoires informatiques personnels et les logiciels open source, elle se spécialise dans la vulgarisation de concepts techniques complexes au moyen de guides pratiques et concrets. Eva pense que l’hébergement personnel doit être amusant, et non intimidant. À travers ses tutoriels, elle aide la communauté à démystifier les configurations matérielles, de la construction de leur premier NAS à la maîtrise des conteneurs Docker.

Réponse rapide

Hermes Agent peut être auto-hébergé sur un serveur domestique si vous souhaitez disposer d’un agent IA capable de se connecter à un fournisseur de modèles, d’utiliser des outils et de communiquer par l’intermédiaire d’une passerelle de messagerie comme Telegram. Pour la plupart des débutants, le plus difficile n’est pas seulement de faire fonctionner l’application. Il faut comprendre où se déroule chaque action : sur le serveur hôte, dans le conteneur, dans l’environnement de l’application ou via une plateforme de messagerie.

Avant de tenter de résoudre un problème, une configuration auto-hébergée sûre devrait permettre de répondre à six questions :

  • Est-ce que je travaille sur l’hôte ou dans le conteneur ?
  • Où se trouvent la configuration de l’application, les journaux, les téléchargements et les données d’exécution ?
  • Quel utilisateur possède les fichiers et exécute l’application ?
  • L’application peut-elle accéder au fournisseur de modèles et à l’API de messagerie ?
  • Les clés API, les jetons de bot et les listes d’autorisation sont-ils protégés ?
  • Comment vérifier que l’agent fonctionne toujours après un redémarrage ?

Si vous définissez clairement ces limites, la configuration d’Hermes Agent devient beaucoup plus facile à comprendre, à vérifier et à dépanner.

Qu’est-ce qu’Hermes Agent dans une configuration de serveur domestique auto-hébergé ?

Hermes Agent est un flux de travail d’agent IA auto-hébergé qui peut se connecter à un fournisseur de modèles, utiliser des outils et interagir par l’intermédiaire du terminal ou de canaux de messagerie. Sur un serveur domestique, il se situe souvent entre votre modèle d’IA, l’environnement de votre serveur et une interface de communication, comme un tableau de bord Web ou une passerelle de bot.

L’essentiel, c’est qu’un agent auto-hébergé n’est pas simplement un chatbot. Selon sa configuration, il peut interagir avec des fichiers, des outils de terminal, des API de modèles, des plateformes de messagerie et des données d’exécution. C’est pourquoi il est important de bien délimiter les chemins d’accès, les permissions et les limites d’accès.

Ce que fait Hermes Agent pour les interactions avec l’IA et la messagerie

Hermes Agent peut être configuré pour se connecter à un fournisseur de modèles, démarrer des conversations, utiliser des outils et se connecter à des passerelles de messagerie. Le parcours de démarrage rapide d’Hermes Agent explique comment installer Hermes, configurer un fournisseur de modèles, démarrer une première conversation, utiliser des outils de terminal et connecter ensuite des plateformes de messagerie par l’intermédiaire d’une passerelle.

Pour les utilisateurs d’un serveur domestique, cela signifie qu’Hermes peut devenir un assistant IA permanent qui fonctionne sur un appareil que vous contrôlez. Cela peut aussi ajouter de nouvelles étapes à la configuration : identifiants du modèle, environnement d’exécution de l’application, paramètres de la passerelle et autorisations d’accès.

Quand une configuration via l’interface Web suffit

Une configuration via l’interface Web suffit généralement lorsque l’application propose tous les réglages nécessaires directement dans le tableau de bord. C’est la solution la plus sûre pour la plupart des utilisateurs, car elle évite d’ouvrir le terminal du conteneur, sauf si un élément manque ou ne fonctionne pas.

Une approche privilégiant l’interface Web convient lorsque :

  • l’application s’installe sans problème ;
  • le fournisseur de modèles peut être configuré depuis l’interface ;
  • la passerelle de messagerie peut être connectée sans accès au shell ;
  • le tableau de bord affiche clairement l’état ;
  • les journaux ne signalent aucune erreur d’autorisation ou de réseau.

Si le tableau de bord propose l’option dont vous avez besoin, utilisez-la en premier. La configuration du terminal du conteneur doit être considérée comme une solution de repli ou une méthode avancée, et non comme la première étape par défaut pour tous les utilisateurs.

Quand configurer le terminal du conteneur

Vous devrez peut-être configurer le terminal du conteneur lorsque le tableau de bord ne propose pas une option nécessaire, lorsque l’application exige d’exécuter un assistant de configuration dans le conteneur ou lorsque le dépannage nécessite d’accéder aux journaux, à l’environnement d’exécution ou à des commandes propres à l’application.

C’est là que de nombreux utilisateurs s’embrouillent. Une commande exécutée dans le shell de l’hôte peut ne pas affecter l’application à l’intérieur du conteneur. Un fichier visible dans le conteneur peut ne pas exister au même emplacement sur l’hôte. Une erreur d’autorisation peut être causée par l’utilisateur qui exécute l’application, et non par le fournisseur du modèle ou le jeton du bot.

Avant d’utiliser le terminal du conteneur, vérifiez exactement dans quel shell vous vous trouvez et sous quel utilisateur vous exécutez les commandes.

Ce dont vous avez besoin avant de commencer

La configuration d’un agent auto-hébergé nécessite plus qu’un serveur en fonctionnement. Vous avez besoin d’un chemin réseau opérationnel, d’un accès au modèle, d’identifiants de messagerie et d’autorisations suffisantes pour gérer l’application sans modifier accidentellement les mauvais fichiers.

Un serveur domestique avec accès à Internet

Le serveur domestique doit pouvoir accéder à Internet si vous prévoyez d’utiliser un fournisseur de modèle cloud ou une API de messagerie. Si vous utilisez un point de terminaison de modèle local, le serveur doit tout de même pouvoir accéder à ce point de terminaison sur le réseau local ou le réseau du conteneur.

L’accès au réseau est important, car un agent peut sembler installé correctement tout en ne répondant pas. Par exemple, la connexion au fournisseur du modèle, la passerelle de messagerie ou le tableau de bord peuvent chacun dépendre d’un chemin réseau différent.

Commencez par vérifier que :

  • le serveur dispose d’une connexion stable au réseau local ;
  • le serveur peut accéder au point de terminaison ou au fournisseur du modèle ;
  • le serveur peut accéder à l’API de messagerie ;
  • le port du tableau de bord est accessible depuis votre navigateur ;
  • aucune règle de pare-feu ne bloque la passerelle.

Un fournisseur de modèle ou un point de terminaison de modèle local

Hermes a besoin d’une connexion à un modèle pour fournir des réponses utiles. Il peut s’agir d’un fournisseur cloud, d’une clé API ou d’un point de terminaison compatible avec OpenAI. Certains utilisateurs peuvent connecter un service de modèle local si leur matériel et leur environnement de modèles le permettent.

Le point important à retenir est que la configuration du modèle est distincte de celle de la messagerie. Un bot peut être correctement connecté alors que le fournisseur du modèle est mal configuré, et un fournisseur de modèle peut fonctionner alors que la passerelle du bot est en panne.

Organisez l’URL de base du modèle, la clé API, le nom du modèle et les paramètres de contexte avant de commencer la configuration.

Un compte de messagerie et un jeton de bot

Si vous souhaitez discuter avec l’agent via Telegram ou une autre plateforme de messagerie, vous avez besoin d’un compte de messagerie et des identifiants d’un bot ou d’une passerelle. Pour Telegram, cela signifie généralement créer un bot et enregistrer son jeton.

Un jeton de bot doit être traité comme un mot de passe. Telegram explique que chaque bot reçoit un jeton unique servant à autoriser les requêtes à l’API Bot, et que les requêtes incluent le jeton dans le chemin de l’API selon le modèle d’autorisation par jeton des bots Telegram.

Ne collez pas de jeton de bot dans des discussions publiques, des captures d’écran, des journaux, des problèmes GitHub ou des documents partagés. Si un jeton est exposé, générez-en un nouveau en suivant la procédure officielle de la plateforme de messagerie.

Adresse IP de l’hôte, accès de connexion et autorisations du conteneur

Vous avez besoin de l’adresse IP de l’hôte pour accéder au tableau de bord du serveur ou vous connecter par SSH. Vous avez également besoin d’un accès de connexion qui vous permette de gérer l’application en toute sécurité.

Dans les configurations basées sur des conteneurs, les autorisations sont souvent réparties en plusieurs couches :

Couche d’autorisations Ce qu’il contrôle Erreur fréquente Vérification sécurisée
Utilisateur de l’hôte / compte SSH Accès au système de fichiers du serveur personnel, aux commandes Docker et au tableau de bord du serveur. Supposer que les autorisations de l’hôte s’appliquent automatiquement dans le conteneur. Vérifiez quel compte est connecté et quelles actions il peut effectuer au niveau du serveur.
Utilisateur du conteneur L’utilisateur qui exécute le processus de l’application et écrit les fichiers de l’application dans le conteneur. Effectuer la configuration en tant que root alors que l’application s’exécute normalement avec un utilisateur sans privilèges. Vérifiez l’utilisateur prévu dans le conteneur avant de créer ou de modifier des données de l’application.
Dossier de l’hôte monté Le dossier de l’hôte ou le volume Docker exposé au conteneur. Modifier un dossier de l’hôte qui n’est pas monté sur le chemin utilisé par l’application. Vérifiez le chemin source sur l’hôte et le chemin de destination dans le conteneur.
Chemin d’exécution de l’application Où sont stockés la configuration, les journaux, les téléchargements, les sessions et les données temporaires. Modifier des fichiers dans la mauvaise couche ou perdre les paramètres après le redémarrage. Vérifiez que le chemin persiste après le redémarrage et qu’il est modifiable par l’utilisateur de l’application.

Ne partez pas du principe que root est toujours la bonne solution. Une utilisation de root au mauvais moment peut créer des fichiers appartenant à root que l’utilisateur de l’application ne pourra pas modifier ensuite.

Chemin de l’hôte vs chemin du conteneur vs chemin des données de l’application

C’est le concept le plus important de cet article. De nombreux problèmes de configuration de Hermes Agent viennent de la confusion entre les chemins de l’hôte, les chemins du conteneur, les chemins des données de l’application, les journaux, les téléchargements et les volumes montés.

Utilisez La carte de contrôle des conteneurs de l’agent avant d’exécuter des commandes ou de déboguer.

Couche Question à résoudre Indicateur de validation Panne typique
Système hôte Le serveur, le tableau de bord, la session SSH et le gestionnaire de conteneurs sont-ils accessibles ? Le tableau de bord ou la session SSH s’ouvre, et le conteneur apparaît comme étant en cours d’exécution. L’application semble installée, mais le serveur ou le conteneur est en réalité inaccessible.
Environnement d’exécution du conteneur Suis-je dans le bon conteneur et avec l’utilisateur attendu ? Le shell, le répertoire de travail et l’utilisateur correspondent au chemin de configuration de l’application. Les commandes sont exécutées dans le shell de l’hôte et n’affectent pas l’application à l’intérieur du conteneur.
Chemin des données de l’application Où se trouvent les fichiers de configuration, les journaux, les téléchargements et les fichiers d’exécution ? Les paramètres et les journaux persistent après le redémarrage et sont modifiables par l’utilisateur de l’application. Les paramètres disparaissent après le redémarrage ou l’application affiche des erreurs d’accès refusé.
Chemin réseau Le conteneur peut-il accéder au fournisseur de modèle, au point de terminaison local et à l’API de messagerie ? Les vérifications du fournisseur, les appels à la passerelle et l’accès au tableau de bord fonctionnent depuis la couche prévue. Le modèle ou le bot ne fonctionne pas, alors que l’application semble correctement installée.
Identifiants et accès Les clés API, les jetons du bot et les utilisateurs autorisés sont-ils configurés de manière sécurisée ? Les messages de test privés fonctionnent et les journaux ne signalent aucune erreur de jeton ou d’accès. Le jeton du bot est invalide ou exposé, ou l’ID utilisateur autorisé est incorrect.
Validation du redémarrage La configuration fonctionne-t-elle toujours après le redémarrage de la passerelle ou du service ? Le bot répond, le tableau de bord fonctionne correctement et les journaux restent exempts d’erreurs après le redémarrage. L’ancienne configuration reste active ou les nouveaux paramètres ne sont pas conservés.

Ce que le système hôte peut voir

Le système hôte est le système d’exploitation du serveur domestique. Il peut voir les dossiers hôtes, les conteneurs Docker, les interfaces réseau, les périphériques de stockage et les services système.

Si une application s’exécute dans Docker, l’hôte peut ne pas voir son chemin interne de la même façon que le conteneur. L’hôte peut voir un volume Docker, un dossier monté ou les métadonnées du conteneur.

C’est pourquoi un chemin comme /opt/data ou /app/config peut ne pas désigner la même chose sur l’hôte et dans le conteneur.

Ce que le conteneur peut voir

Un conteneur voit son propre système de fichiers. Il peut aussi voir les dossiers hôtes qui y ont été montés. Le chemin du conteneur est celui que l’application voit.

Docker explique qu’un montage lié monte un fichier ou un dossier de la machine hôte dans un conteneur, tandis qu’un volume Docker est créé dans le répertoire de stockage de Docker sur l’hôte et géré par Docker selon le modèle de stockage des montages liés Docker.

Cette distinction est importante, car un conteneur ne peut accéder qu’aux chemins hôtes qui y sont montés. Si l’application ne trouve pas un fichier, il se peut que celui-ci existe sur l’hôte, mais qu’il ne soit pas monté au chemin attendu dans le conteneur.

Où se trouvent généralement la configuration de l’application et les données d’exécution

Les fichiers de configuration, les journaux, les téléchargements et les données d’exécution de l’application peuvent se trouver à différents endroits, selon la façon dont l’application a été empaquetée. Certaines données peuvent se trouver dans le conteneur, d’autres dans un volume Docker ou dans un dossier hôte monté.

Pour un agent auto-hébergé, les types de données courants comprennent :

  • paramètres du fournisseur de modèle ;
  • configuration de la passerelle ;
  • jeton du bot ou paramètres de messagerie ;
  • journaux et état de session ;
  • téléchargements temporaires ;
  • sorties des outils ;
  • données d’exécution propres à l’application.

La question importante n’est pas seulement « où se trouve le fichier ? », mais « quelle couche gère ce fichier et quel utilisateur peut le modifier ? »

Écran Hermes Agent pour choisir un fournisseur de modèle pendant la configuration

Pourquoi la confusion entre les chemins entraîne des problèmes d’autorisations et de données

La confusion entre les chemins entraîne deux problèmes courants. Premièrement, les utilisateurs modifient un fichier sur l’hôte, mais le conteneur lit un autre fichier dans son propre chemin. Deuxièmement, les utilisateurs exécutent la configuration en tant que root et créent des fichiers que l’utilisateur de l’application ne peut ensuite pas modifier.

Les montages liés peuvent également masquer des fichiers existants du conteneur si un dossier de l’hôte est monté sur un répertoire du conteneur qui n’est pas vide. Dans ce cas, les fichiers peuvent sembler manquants alors qu’ils sont simplement masqués par le montage.

Avant de résoudre un problème lié aux données d’une application, vérifiez la couche d’exécution, les chemins montés, le propriétaire des fichiers et l’utilisateur du conteneur.

Comment configurer un agent auto-hébergé étape par étape

La configuration d’un agent auto-hébergé doit progresser des vérifications à faible risque à la configuration, puis à la validation. Ne commencez pas par modifier les autorisations ou redémarrer des services avant d’avoir identifié la couche défaillante.

Étape 1 : Installez ou ouvrez l’application depuis le tableau de bord de votre serveur

Commencez par la méthode d’installation ou de lancement la plus simple prise en charge par votre serveur domestique. Si le serveur propose un tableau de bord des applications, utilisez-le pour vérifier que Hermes Agent est installé, visible et en cours d’exécution.

À ce stade, n’entrez pas dans le conteneur, sauf si l’application l’exige. Vérifiez d’abord l’état dans le tableau de bord, la version de l’application si elle est indiquée, et la disponibilité d’une page de configuration.

Si l’application ne démarre pas du tout, consultez les journaux avant de modifier les fichiers de configuration.

Étape 2 : Vérifiez l’adresse IP de l’hôte et l’accès au réseau

Vérifiez l’adresse IP de l’hôte et assurez-vous que votre navigateur ou votre terminal peut accéder au serveur. Selon la configuration, la même adresse IP peut servir à accéder au tableau de bord, à la connexion SSH ou à la passerelle locale.

Vérifiez ensuite l’accès au réseau sortant. Un bot de messagerie ne répondra pas si le conteneur ne peut pas accéder à l’API de messagerie, et un fournisseur de modèles ne fonctionnera pas si le serveur ne peut pas joindre le point de terminaison du modèle.

Cette vérification permet de distinguer « échec de la configuration de l’application » de « échec de l’accès au réseau ».

Étape 3 : Entrez dans le conteneur avec le bon utilisateur

Si la configuration du terminal du conteneur est nécessaire, entrez dans le conteneur avec l’utilisateur prévu pour l’application. C’est important, car des fichiers créés par le mauvais utilisateur peuvent ensuite entraîner des erreurs d’autorisations.

Ne considérez pas le shell de l’hôte et celui du conteneur comme un seul et même environnement. Une commande qui fonctionne sur l’hôte peut ne pas être disponible dans le conteneur, et un chemin de fichier dans le conteneur peut ne pas exister sur l’hôte.

Avant d’exécuter les commandes d’installation, vérifiez les points suivants :

  1. Vous êtes dans le bon conteneur.
  2. Vous utilisez l’utilisateur prévu pour le conteneur.
  3. Vous vous trouvez dans le répertoire de travail attendu.
  4. La commande requise pour l’application est disponible.
  5. Vous savez comment quitter le conteneur et y entrer à nouveau.

Étape 4 : Activez l’environnement de l’application avant d’exécuter les commandes d’installation

Certaines applications auto-hébergées utilisent un environnement virtuel ou une configuration de shell propre à l’application. Si l’environnement n’est pas activé, la commande de l’application risque de ne pas être trouvée ou de s’exécuter avec les mauvaises dépendances.

Cette étape n’est pas une simple formalité. Elle garantit que l’assistant de configuration, la commande de la passerelle et la commande de configuration du modèle s’exécutent dans le même environnement d’exécution que l’application.

Si une commande échoue de façon inattendue, vérifiez que vous êtes dans le bon conteneur et que l’environnement de l’application est actif avant de réinstaller quoi que ce soit.

Étape 5 : connecter un fournisseur de modèles ou un service de modèle local

Configurez le fournisseur de modèles, le point de terminaison personnalisé ou le service de modèle local. Veillez à ce que l’URL de base, la clé API, le nom du modèle et les paramètres liés au contexte soient cohérents avec le fournisseur utilisé.

Si la configuration du modèle échoue, procédez aux vérifications dans cet ordre :

  • La clé API est-elle correcte ?
  • L’URL de base est-elle accessible depuis le conteneur ?
  • Le nom du modèle est-il pris en charge par le point de terminaison ?
  • L’application nécessite-t-elle un modèle avec un long contexte ?
  • Y a-t-il des problèmes de réseau ou de DNS dans le conteneur ?

Évitez de confondre les erreurs de modèle avec les erreurs de messagerie. Si un bot Telegram ne répond pas et qu’un fournisseur de modèles rencontre une panne, ces problèmes ne sont liés que parce que l’agent a besoin des deux pour effectuer la tâche.

Étape 6 : configurer la passerelle de messagerie

La passerelle de messagerie relie l’environnement d’exécution de l’agent à une plateforme de messagerie. Pour Telegram, cela implique généralement un jeton de bot et l’identité d’un utilisateur autorisé.

Une bonne configuration de passerelle doit préciser qui peut envoyer des messages à l’agent, quel jeton de bot est utilisé et si le bot est destiné aux conversations privées, aux groupes, ou aux deux.

Ne considérez jamais par défaut un bot de messagerie comme une interface publique. Un agent auto-hébergé peut avoir accès à des outils, à des données locales ou à des actions qui ne devraient pas être accessibles à tous les utilisateurs pouvant contacter le bot.

Étape 7 : redémarrer la passerelle et appliquer la nouvelle configuration

Après une modification du modèle ou de la passerelle de messagerie, il peut être nécessaire de redémarrer la passerelle pour que la nouvelle configuration soit appliquée. Le comportement au redémarrage est important, car une configuration peut sembler terminée alors que les anciens paramètres sont toujours utilisés.

Après le redémarrage, effectuez des vérifications du côté utilisateur et du côté serveur. Envoyez un message de test, vérifiez l’état dans le tableau de bord et consultez les journaux pour repérer d’éventuelles erreurs de permission, de jeton ou de réseau.

Si la reconfiguration n’est pas conservée après le redémarrage, vérifiez à nouveau le chemin des données et les limites de permissions.

Écran de contrôle du bot Telegram Hermes Agent permettant de valider la passerelle de messagerie

Permissions, jetons et contrôle d’accès

Les agents auto-hébergés combinent les permissions d’exécution locales et les identifiants externes. La configuration peut donc fonctionner techniquement tout en restant peu sûre si les jetons, les listes d’autorisation ou les limites entre utilisateurs sont mal définis.

Pourquoi l’utilisateur du conteneur est important

L’utilisateur du conteneur détermine les fichiers que l’application peut lire et modifier dans le conteneur. Si les commandes de configuration sont exécutées en tant que root et que l’application s’exécute ensuite avec un utilisateur non root, ses données risquent de lui être inaccessibles.

Cela apparaît souvent sous forme d’erreur de permission dans le chemin des données de l’application. La solution ne consiste pas toujours à continuer d’utiliser le compte root. Dans bien des cas, mieux vaut rétablir le propriétaire correct et exécuter l’application avec l’utilisateur prévu.

N’utilisez root qu’en cas de besoin pour une étape de récupération précise et évitez de créer les fichiers courants de l’application en tant que root.

Pourquoi les clés API et les jetons de bot doivent être protégés

Les clés API et les jetons de bot sont des identifiants d’accès. Une clé API de modèle peut donner accès à un fournisseur de modèles. Un jeton de bot peut autoriser des requêtes au nom du bot.

Ne publiez pas ces valeurs dans des dépôts publics, des captures d’écran, des journaux partagés ou des messages d’assistance. Lors du dépannage, masquez les jetons avant de partager une configuration ou des journaux.

Si un jeton a été exposé, révoquez-le et remplacez-le au lieu d’espérer qu’il ne sera pas utilisé.

Comment la liste d’autorisation des utilisateurs contrôle l’accès privé

Une liste d’autorisation limite les utilisateurs qui peuvent interagir avec l’agent par l’intermédiaire d’une passerelle de messagerie. C’est important, car un bot de messagerie peut être accessible à davantage de personnes que prévu.

Pour les discussions privées avec l’IA, utilisez la liste d’autorisation la plus restreinte possible. Vérifiez que l’ID utilisateur autorisé est correct et que les messages de test proviennent bien de ce compte.

Si plusieurs personnes doivent y accéder, ajoutez-les délibérément au lieu de laisser le bot ouvert à tous.

Pourquoi les bots de messagerie ne doivent pas être considérés comme des interfaces publiques

Un bot de messagerie peut ressembler à une interface de discussion classique, mais il peut s’appuyer sur un agent auto-hébergé doté d’un accès à des modèles, d’outils, de sessions et d’autorisations d’exécution locales.

Cela le distingue d’un simple bot de notification. Il doit disposer de règles d’accès claires, de jetons protégés et d’un chemin réseau contrôlé.

Pour les discussions de groupe, soyez prudent. Les autorisations du groupe, le mode de confidentialité et le statut d’administrateur du bot peuvent modifier les messages que celui-ci peut voir ou auxquels il peut répondre.

Problèmes de configuration courants et solutions

La plupart des problèmes de configuration peuvent être attribués à l’une de ces six couches : l’environnement d’exécution, le chemin des données, les autorisations, la passerelle, le secret ou la validation.

Erreurs d’autorisation dans le chemin des données de l’application

Une erreur d’autorisation signifie généralement que l’utilisateur actuel de l’application ne peut pas lire ou écrire un fichier ou un dossier nécessaire. Cela peut arriver si une commande de configuration précédente a créé des fichiers en tant que root ou si un dossier monté a un propriétaire incorrect.

Vérifiez d’abord les points suivants :

  • Êtes-vous dans le conteneur ou sur l’hôte ?
  • Quel utilisateur exécute l’application ?
  • À qui appartient le dossier de données de l’application ?
  • Le chemin des données de l’application est-il monté depuis l’hôte ?
  • Une commande de configuration a-t-elle déjà été exécutée en tant que root ?

Ne modifiez pas récursivement les autorisations de dossiers entiers sans connaître la cible. Corrigez uniquement le chemin précis nécessaire.

Le bot ne répond pas après la configuration

Un bot peut ne pas répondre même lorsque Hermes Agent est en cours d’exécution. Le problème peut venir du jeton, de la liste d’autorisation des utilisateurs, de la passerelle de messagerie, de l’accès réseau ou des autorisations du groupe.

Vérifiez dans cet ordre :

  1. Vérifiez que le jeton du bot est correct.
  2. Vérifiez que l’ID utilisateur est autorisé.
  3. Vérifiez que la passerelle a été redémarrée après la configuration.
  4. Vérifiez que le conteneur peut accéder à l’API de messagerie.
  5. Consultez les journaux de l’application pour repérer les erreurs liées au jeton, au réseau ou aux autorisations.
  6. Testez le chat privé avant de dépanner le fonctionnement du chat de groupe.

Le test du chat privé est généralement plus simple que celui du chat de groupe, car les autorisations de groupe ajoutent des variables supplémentaires.

Les paramètres du fournisseur de modèles sont incorrects

Si le bot de messagerie répond, mais que les réponses du modèle échouent, le problème vient peut-être du fournisseur de modèles. Vérifiez l'URL de base, la clé API, le nom du modèle et la compatibilité du point de terminaison.

Pour les points de terminaison de modèles locaux, vérifiez également que le service de modèle fonctionne et qu'il est accessible depuis le conteneur. Un service accessible depuis l'hôte peut ne pas l'être depuis le conteneur si la configuration réseau est différente.

Traitez séparément le dépannage du fournisseur de modèles et celui de la messagerie. Vous éviterez ainsi de modifier le bot alors que le véritable problème vient de la connexion au modèle.

Le conteneur ne peut pas accéder à l'API de messagerie

Si le conteneur ne peut pas accéder à l'API de messagerie, la passerelle ne peut pas recevoir ni envoyer correctement les messages. Cela peut être dû à des problèmes DNS, à des règles de pare-feu, à des paramètres de proxy ou à l'absence d'accès à Internet sortant.

Vérifiez que l'hôte a accès à Internet et que le conteneur y a également accès. Ce n'est pas toujours la même chose.

Si le serveur domestique utilise un VPN, un proxy ou un réseau restreint, vérifiez que le conteneur peut envoyer des requêtes HTTPS.

Les autorisations du chat de groupe ou le mode de confidentialité empêchent les réponses

Le fonctionnement du chat de groupe est plus complexe que celui du chat privé. Un bot peut répondre en privé, mais pas dans un groupe, parce qu'il ne voit pas le message, qu'il n'a pas les autorisations nécessaires ou que les paramètres de confidentialité le bloquent.

Commencez par vérifier le chat privé. Testez ensuite le chat de groupe séparément.

Pour une utilisation en groupe, vérifiez si le bot doit être mentionné directement, s'il a besoin de droits d'administrateur et si ses paramètres de confidentialité lui permettent de recevoir les messages nécessaires.

Comment vérifier si Hermes Agent fonctionne

Une installation n'est pas terminée simplement parce que l'installation est achevée. Elle l'est lorsque le modèle, la passerelle, les autorisations, le tableau de bord, les journaux et le comportement de reconfiguration passent tous les vérifications de base.

L'assistant de configuration se termine sans erreur

L'assistant de configuration devrait se terminer sans erreur de commande manquante, erreur de fournisseur ni erreur d'autorisation. En cas d'échec, notez quelle couche a échoué avant de réessayer.

Une erreur de l'assistant de configuration relève généralement de l'une de ces catégories :

  • identifiants du fournisseur de modèles ;
  • environnement d'exécution ;
  • autorisations du conteneur ;
  • commande d'application manquante ;
  • accès au réseau ;
  • configuration de la passerelle.

Utilisez cette catégorie pour déterminer la vérification suivante.

Le bot de messagerie répond à un message test privé

La méthode la plus simple pour vérifier la messagerie consiste à envoyer un message test privé. Envoyez un message simple et vérifiez que le bot répond.

Si le chat privé fonctionne, le jeton, la liste d'autorisation, la passerelle et la connexion au modèle sont probablement configurés correctement. Si le chat de groupe ne fonctionne toujours pas, concentrez-vous sur les autorisations de groupe et les paramètres de confidentialité plutôt que de réinstaller l'application.

La conversation privée devrait être votre premier test de messagerie réussi.

Le tableau de bord indique que l’agent est en cours d’exécution

Le tableau de bord doit indiquer que l’agent ou la passerelle est en cours d’exécution, selon le système. L’état du tableau de bord est utile, car il donne une vue côté serveur au lieu de s’appuyer uniquement sur l’application de messagerie.

Si le tableau de bord indique un état arrêté ou défectueux, consultez les journaux avant de modifier les jetons ou les paramètres du modèle.

L’état du tableau de bord et la réponse du bot doivent correspondre. Si l’un fonctionne et que l’autre échoue, cet écart indique la couche défaillante.

Les journaux n’affichent aucune erreur d’autorisation ou de réseau

Les journaux ne doivent pas afficher de façon répétée des erreurs telles que « accès refusé », « jeton invalide », « fournisseur inaccessible », « échec de la passerelle » ou « délai d’attente du réseau dépassé ».

Utilisez les journaux pour déterminer la prochaine étape. Une erreur d’autorisation oriente vers les droits de propriété des fichiers ou l’utilisateur du conteneur. Une erreur réseau indique un problème d’accès à l’API. Une erreur de jeton indique un problème de configuration des identifiants.

Évitez de corriger toutes les couches en même temps. Modifiez une variable, redémarrez si nécessaire, puis refaites un test.

La reconfiguration fonctionne après le redémarrage

Une configuration durable doit résister à un redémarrage ou à une reconfiguration. Après avoir modifié les paramètres du modèle ou de la passerelle, redémarrez le service ou la passerelle concerné et vérifiez que les nouveaux paramètres sont toujours appliqués.

Si les paramètres disparaissent après un redémarrage, vérifiez où la configuration est stockée et si le chemin des données de l’application est persistant.

C’est là que la connaissance des chemins d’hôte, des chemins de conteneur et des volumes montés devient concrète.

Fonctionnement dans un environnement réel de serveur domestique

Dans un environnement réel de serveur domestique, le modèle général de configuration reste le même : confirmer la couche d’exécution, vérifier les chemins de données, protéger les identifiants, configurer l’accès à la passerelle et valider le tout à l’aide des journaux et de l’état du tableau de bord.

Un guide de configuration propre à l’appareil peut alors fournir le chemin de commande exact. Par exemple, le workflow de configuration de Hermes Agent sur ZimaOS présente une procédure de configuration de Hermes Agent qui comprend la configuration du fournisseur de modèles, la liaison d’un bot Telegram, l’accès au conteneur Hermes en tant qu’utilisateur de l’application, l’activation de l’environnement de l’application, l’exécution des commandes de configuration, la vérification de l’état dans le tableau de bord et le dépannage des erreurs d’autorisation ou de réponse du bot.

Pour les utilisateurs qui exécutent des applications auto-hébergées, des passerelles de messagerie et des workflows d’agents légers sur un serveur compact toujours allumé, serveur IA domestique ZimaBoard 2 correspond au type d’environnement où les applications Docker, l’accès au terminal, les services locaux et les chemins de données propres aux applications doivent être compris ensemble. Ce n’est pas la seule façon d’héberger un agent, mais c’est un exemple pertinent du type de workflow de serveur domestique décrit dans cet article.

La leçon à retenir est transposable : ne mémorisez pas une seule commande de configuration. Comprenez sur quelle couche vous intervenez et comment vérifier le résultat.

FAQ

Puis-je configurer Hermes Agent uniquement depuis un tableau de bord Web ?

Dans de nombreux cas, un tableau de bord Web peut suffire pour la configuration de base, surtout s’il permet de régler les modèles et la passerelle. La configuration depuis le terminal du conteneur devient nécessaire lorsque le tableau de bord ne propose pas une option requise ou lorsque le dépannage nécessite des commandes au niveau de l’application. Commencez par l’interface Web lorsque c’est possible, puis utilisez le terminal du conteneur uniquement si la procédure de configuration l’exige.

Pourquoi dois-je accéder au conteneur plutôt qu’au shell de l’hôte ?

Certaines commandes de l’application ne sont disponibles que dans le conteneur, car c’est là que se trouvent l’environnement d’exécution et les dépendances de l’application. Exécuter la même commande sur l’hôte peut échouer ou affecter le mauvais environnement. Accéder au conteneur avec le bon utilisateur permet de s’assurer que les modifications de configuration s’appliquent bien à l’application.

Quelle est la différence entre les données de l’hôte et celles de l’application dans le conteneur ?

Les données de l’hôte se trouvent dans le système de fichiers du serveur domestique. Les données de l’application dans le conteneur peuvent se trouver à l’intérieur du conteneur, dans un volume géré par Docker ou dans un dossier de l’hôte monté dans le conteneur. Un même chemin de dossier visible ne désigne pas nécessairement le même emplacement sur l’hôte et dans le conteneur. Vérifiez donc les montages et les emplacements des données de l’application avant de modifier des fichiers.

Pourquoi Hermes Agent affiche-t-il une erreur de permission ?

Une erreur de permission signifie souvent que l’utilisateur de l’application ne peut pas lire ou écrire dans un fichier ou un dossier requis. Cela peut arriver si les fichiers ont été créés par root, si un dossier monté a le mauvais propriétaire ou si le conteneur s’exécute sous un utilisateur différent de celui prévu. Vérifiez la couche d’exécution, l’utilisateur du conteneur, le chemin des données de l’application et le propriétaire des fichiers avant de modifier les permissions de manière générale.

Pourquoi mon bot Telegram ne répond-il pas ?

Un bot Telegram peut ne pas répondre si le jeton est incorrect, si l’identifiant utilisateur n’est pas autorisé, si la passerelle n’a pas été redémarrée, si le conteneur ne peut pas accéder à l’API Telegram ou si les permissions de la discussion de groupe bloquent le message. Testez d’abord dans une discussion privée, car cela élimine de nombreuses variables liées aux groupes. Vérifiez ensuite les journaux pour repérer les erreurs liées au jeton, au réseau ou aux permissions.

Dois-je exposer Hermes Agent directement sur Internet ?

L’exposition directe au public n’est généralement pas le meilleur choix par défaut pour un agent auto-hébergé. Un bot de messagerie ou une passerelle peut se connecter à des outils, à l’accès à des modèles et éventuellement à des actions d’exécution locales ; l’accès doit donc être restreint. Privilégiez des modes d’accès privés, des identifiants robustes, des listes d’autorisation et des permissions prudentes avant d’envisager une configuration accessible au public.

Assistance et conseils

À lire aussi

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.