Hermes Agent : Guide d'installation en auto-hébergement pour les utilisateurs de serveurs domestiques

Réponse rapide

Hermes Agent peut être auto-hébergé sur un serveur domestique lorsque vous souhaitez un agent IA capable de se connecter à un fournisseur de modèle, d'utiliser des outils et de communiquer via une passerelle de messagerie comme Telegram. Pour la plupart des débutants, la partie la plus difficile n'est pas seulement de faire tourner l'application, mais de comprendre où chaque action se déroule : sur le serveur hôte, à l'intérieur du conteneur, dans l'environnement de l'application ou via une plateforme de messagerie.

Une configuration auto-hébergée sûre doit répondre à six questions avant toute résolution de problème :

• Suis-je en train de travailler sur l'hôte ou à l'intérieur du conteneur ?
• Où vivent la configuration de l'application, les logs, 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 atteindre le fournisseur de modèle et l'API de messagerie ?
• Les clés API, jetons de bot et listes blanches sont-ils protégés ?
• Comment confirmer que l'agent fonctionne toujours après un redémarrage ?

Si vous gardez ces limites claires, la configuration de Hermes Agent devient beaucoup plus facile à comprendre, vérifier et corriger.

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

Hermes Agent est un workflow d'agent IA auto-hébergé qui peut se connecter à un fournisseur de modèle, utiliser des outils et interagir via des canaux terminal ou messagerie. Sur un serveur domestique, il se place souvent entre votre modèle IA, votre environnement serveur et une interface de communication comme un tableau de bord web ou une passerelle de bot.

L'essentiel est qu'un agent auto-hébergé n'est pas qu'un simple chatbot. Selon la configuration, il peut interagir avec des fichiers, des outils en terminal, des API de modèles, des plateformes de messagerie et des données d'exécution. C'est pourquoi les chemins, permissions et limites d'accès sont importants.

Ce que fait Hermes Agent pour l'interaction IA et la messagerie

Hermes Agent peut être configuré pour se connecter à un fournisseur de modèle, démarrer des conversations, utiliser des outils et connecter des passerelles de messagerie. Le flux de démarrage rapide Hermes Agent explique que les utilisateurs peuvent installer Hermes, configurer un fournisseur de modèle, démarrer une première conversation, utiliser des outils en terminal, puis connecter des plateformes de messagerie via une passerelle.

Pour un utilisateur de serveur domestique, cela signifie que Hermes peut devenir un assistant IA persistant qui fonctionne sur un appareil que vous contrôlez. Il peut aussi introduire de nouvelles couches de configuration : identifiants du modèle, environnement d'exécution de l'application, paramètres de la passerelle et permissions d'accès.

Quand une configuration WebUI suffit

Une configuration via WebUI suffit généralement lorsque l'application fournit tous les réglages nécessaires directement dans le tableau de bord. C'est la méthode la plus sûre pour la plupart des utilisateurs car elle évite d'entrer dans le terminal du conteneur sauf si quelque chose manque ou est cassé.

Une approche WebUI-first est adaptée lorsque :

• l'application s'installe proprement ;
• le fournisseur de modèle peut être configuré depuis l'interface ;
• la passerelle de messagerie peut être connectée sans accès shell ;
• le tableau de bord affiche clairement le statut ;
• les journaux ne montrent pas d'erreurs de permission ou de réseau.

Si le tableau de bord vous offre l'option dont vous avez besoin, utilisez-la d'abord. La configuration du terminal du conteneur doit être considérée comme une solution de secours ou une option avancée, pas comme la première étape par défaut pour chaque utilisateur.

Quand vous avez besoin de configurer le terminal du conteneur

Vous pourriez avoir besoin de configurer le terminal du conteneur lorsque le tableau de bord n'expose pas une option requise, lorsque l'application nécessite un assistant de configuration à l'intérieur du conteneur, ou lorsque le dépannage nécessite l'accès aux journaux, à l'environnement d'exécution ou aux commandes spécifiques à l'application.

C'est là que beaucoup d'utilisateurs se trompent. Une commande exécutée dans le shell 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 chemin sur l'hôte. Une erreur de permission peut être causée par l'utilisateur exécutant l'application, pas par le fournisseur de modèle ou le jeton du bot.

Avant d'utiliser le terminal du conteneur, confirmez exactement dans quel shell vous êtes et sous quel utilisateur vous exécutez.

Ce dont vous avez besoin avant de commencer

Une configuration d'agent auto-hébergé nécessite plus qu'un serveur en fonctionnement. Vous avez besoin d'un chemin réseau fonctionnel, d'un accès au modèle, des identifiants de messagerie et des permissions 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 toujours pouvoir atteindre ce point de terminaison sur le réseau local ou le réseau du conteneur.

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

Commencez par confirmer :

• le serveur dispose d'une connexion LAN stable ;
• le serveur peut atteindre le point de terminaison ou le fournisseur de modèle ;
• le serveur peut atteindre 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 au modèle avant de pouvoir produire des réponses utiles. Cela peut être un fournisseur cloud, une clé API ou un point de terminaison compatible OpenAI. Certains utilisateurs peuvent connecter un service de modèle local si leur matériel et leur pile de modèles le permettent.

Le détail important de la configuration est que la configuration du modèle est séparée de celle de la messagerie. Un bot peut être connecté correctement alors que le fournisseur de modèle est incorrect, et un fournisseur de modèle peut fonctionner alors que la passerelle du bot échoue.

Gardez l'URL de base du modèle, la clé API, le nom du modèle et les paramètres de contexte bien organisés avant de commencer la configuration.

Un compte de messagerie et un jeton de bot

Si vous souhaitez communiquer avec l'agent via Telegram ou une autre plateforme de messagerie, vous avez besoin d'un compte de messagerie et d'un identifiant de bot ou de 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 utilisé pour autoriser les requêtes à l'API Bot, et les requêtes incluent le jeton dans le chemin de l'API selon le modèle d'autorisation du jeton bot Telegram.

Ne collez pas un jeton de bot dans des discussions publiques, captures d'écran, journaux, problèmes GitHub ou documents partagés. Si un jeton est exposé, régénérez-le via le processus officiel de la plateforme de messagerie.

Adresse IP de l'hôte, accès de connexion et permissions 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 permet de gérer l'application en toute sécurité.

Dans les configurations basées sur des conteneurs, les permissions sont souvent en couches :

Couche de permission	Ce que cela contrôle	Erreur courante	Vérification de sécurité
Utilisateur hôte / compte SSH	Accès au système de fichiers du serveur domestique, aux commandes Docker et au tableau de bord du serveur.	Supposer que les permissions de l'hôte s'appliquent automatiquement à l'intérieur du conteneur.	Confirmez quel compte est connecté et quelles actions au niveau serveur il peut effectuer.
Utilisateur du conteneur	L'utilisateur qui exécute le processus de l'application et écrit les fichiers de l'application à l'intérieur du conteneur.	Exécuter l'installation en root alors que l'application fonctionne normalement avec un utilisateur non-root.	Vérifiez l'utilisateur du conteneur prévu avant de créer ou modifier les données de l'application.
Dossier hôte monté	Le dossier hôte ou le volume Docker exposé au conteneur.	Modifier un dossier hôte qui n'est pas monté sur le chemin que l'application lit.	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 redémarrage.	Confirmez que le chemin persiste après redémarrage et est accessible en écriture par l'utilisateur de l'application.

Ne supposez pas que root est toujours la bonne réponse. Utiliser root au mauvais moment peut créer des fichiers appartenant à root que l'utilisateur de l'application ne pourra pas modifier par la suite.

Chemin hôte vs chemin conteneur vs chemin des données d'application

C'est le concept le plus important de cet article. De nombreux problèmes d'installation de Hermes Agent proviennent de la confusion entre les chemins hôtes, les chemins de conteneurs, les chemins des données d'application, les journaux, les téléchargements et les volumes montés.

Utilisez La carte de contrôle des conteneurs Agent avant d'exécuter ou de déboguer des commandes.

Couche	Question à répondre	Signal de validation	Échec 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 est visible comme en cours d'exécution.	L'application semble installée, mais le serveur ou le conteneur est en réalité inaccessible.
Exécution du conteneur	Suis-je dans le bon conteneur et utilise-je 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 journaux persistent après redémarrage et sont modifiables par l'utilisateur de l'application.	Les paramètres disparaissent après redémarrage, ou l'application affiche des erreurs de permission refusée.
Chemin réseau	Le conteneur peut-il atteindre le fournisseur de modèle, le 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 attendue.	Le modèle ou le bot échoue même si l'application semble installée correctement.
Identifiants et accès	Les clés API, jetons de bot et utilisateurs autorisés sont-ils configurés en toute sécurité ?	Les messages de test privés fonctionnent, et les journaux ne montrent pas d'erreurs de jeton ou d'accès.	Le jeton du bot est invalide, 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 est sain, et les journaux restent propres après 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 réel 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 au niveau système.

Si une application s'exécute dans Docker, l'hôte peut ne pas voir le chemin interne de l'application de la même manière que le conteneur le voit. L'hôte peut voir un volume Docker, un dossier monté en liaison ou des métadonnées du conteneur à la place.

C'est pourquoi un chemin comme /opt/data ou /app/config peut ne pas signifier la même chose sur l'hôte et à l'intérieur du conteneur.

Ce que le conteneur peut voir

Un conteneur voit son propre système de fichiers. Il peut aussi voir les dossiers de l'hôte qui ont été montés dans le conteneur. Le chemin du conteneur est le chemin du point de vue de l'application.

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

Cette distinction est importante car un conteneur ne peut accéder qu'aux chemins de l'hôte qui y sont montés. Si l'application ne trouve pas un fichier, le problème peut être que le fichier existe sur l'hôte mais n'est 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

La configuration de l'application, les journaux, les téléchargements et les données d'exécution peuvent se trouver à différents endroits selon la façon dont l'application a été empaquetée. Certaines données peuvent être à l'intérieur du conteneur, d'autres dans un volume Docker, et d'autres encore montées en liaison depuis l'hôte.

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

• 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 d'outils ;
• données d'exécution spécifiques à l'application.

La question importante n'est pas seulement « où se trouve le fichier ? » mais « quelle couche possède ce fichier et quel utilisateur peut le modifier ? »

Pourquoi la confusion des chemins cause des problèmes de permission et de données

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

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

Avant de corriger un problème de données d’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 passer des vérifications à faible risque à la configuration, puis à la validation. Ne commencez pas par modifier les permissions ou redémarrer les services avant de savoir quelle couche échoue.

É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 d’application la plus simple prise en charge pour votre serveur domestique. Si le serveur fournit un tableau de bord d’application, utilisez-le pour confirmer 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. Commencez par confirmer le statut du tableau de bord, la version de l’application si affichée, et si une page de configuration est disponible.

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

Étape 2 : Confirmez l’IP de l’hôte et l’accès réseau

Confirmez l’adresse IP de l’hôte et assurez-vous que votre navigateur ou terminal peut atteindre le serveur. La même IP peut être utilisée pour l’accès au tableau de bord, l’accès SSH ou l’accès à la passerelle locale selon la configuration.

Puis confirmez l’accès réseau sortant. Un bot de messagerie ne répondra pas si le conteneur ne peut pas atteindre l’API de messagerie, et un fournisseur de modèle échouera si le serveur ne peut pas atteindre le point de terminaison du modèle.

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

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

Si une configuration du terminal du conteneur est nécessaire, entrez dans le conteneur avec l’utilisateur attendu par l’application. Cela est important car les fichiers créés par le mauvais utilisateur peuvent ensuite causer des erreurs de permission.

Ne considérez pas le shell de l’hôte et le shell du conteneur comme le même environnement. Une commande qui fonctionne sur l’hôte peut ne pas exister 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 de configuration, confirmez :

1. Vous êtes à l’intérieur du bon conteneur.
2. Vous utilisez l’utilisateur du conteneur prévu.
3. Vous êtes dans le répertoire de travail attendu.
4. La commande requise de l’application est disponible.
5. Vous savez comment sortir et rentrer dans le conteneur.

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

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

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

Si une commande échoue de manière inattendue, vérifiez si vous êtes dans le bon conteneur et si l'environnement de l'application est actif avant de réinstaller quoi que ce soit.

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

Configurez le fournisseur de modèle, le point de terminaison personnalisé ou le service de modèle local. Gardez l'URL de base, la clé API, le nom du modèle et les paramètres liés au contexte cohérents avec le fournisseur que vous utilisez.

Si la configuration du modèle échoue, vérifiez 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 de contexte long ?
• Y a-t-il des problèmes de réseau ou de DNS à l'intérieur du conteneur ?

Évitez de confondre les erreurs de modèle avec les erreurs de messagerie. Un bot Telegram qui ne répond pas et un fournisseur de modèle qui échoue sont liés uniquement parce que l'agent a besoin des deux pour compléter le flux de travail.

Étape 6 : Configurer la passerelle de messagerie

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

Une bonne configuration de passerelle doit définir qui peut envoyer des messages à l'agent, quel jeton de bot est utilisé, et si le bot est destiné à un chat privé, un chat de groupe, ou les deux.

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

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

Après des modifications du modèle ou de la passerelle de messagerie, la passerelle peut devoir redémarrer avant que la nouvelle configuration ne s'applique. Le comportement au redémarrage est important car une configuration peut sembler complète mais fonctionner encore avec d'anciens paramètres.

Après le redémarrage, validez du côté utilisateur et du côté serveur. Envoyez un message test, vérifiez le statut du tableau de bord et inspectez les journaux pour détecter des erreurs de permission, de jeton ou de réseau.

Si la reconfiguration ne persiste pas après le redémarrage, revenez au chemin des données et aux limites de permission.

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

Les agents auto-hébergés combinent les permissions d'exécution locales avec des identifiants externes. Cela signifie qu'une configuration peut fonctionner techniquement mais rester dangereuse si les jetons, les listes blanches ou les limites utilisateur sont incorrects.

Pourquoi l'utilisateur du conteneur est important

L'utilisateur du conteneur contrôle les fichiers que l'application peut lire et écrire à l'intérieur du conteneur. Si les commandes de configuration sont exécutées en root et que l'application s'exécute ensuite en tant qu'utilisateur non-root, les données de l'application peuvent devenir inaccessibles à l'application.

Cela apparaît souvent comme une erreur de permission dans le chemin des données de l'application. La solution n'est pas toujours de continuer à utiliser root. Dans de nombreux cas, la meilleure approche est de restaurer la propriété correcte et d'exécuter l'application en tant qu'utilisateur prévu.

Utilisez root uniquement lorsque nécessaire pour une étape spécifique de récupération, et évitez de créer des fichiers d'application courants en 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. Une clé API modèle peut donner accès à un fournisseur de modèle. Un jeton de bot peut autoriser des requêtes en tant que bot.

Ne mettez pas ces valeurs dans des dépôts publics, captures d'écran, journaux partagés ou messages de support. Lors du dépannage, censurez les jetons avant de partager toute configuration ou journal.

Si un jeton a été exposé, faites-le tourner plutôt que d'espérer qu'il ne sera pas utilisé.

Comment la liste blanche des utilisateurs contrôle l'accès privé

Une liste blanche limite les utilisateurs pouvant interagir avec l'agent via une passerelle de messagerie. Cela importe car un bot de messagerie peut être accessible par plus de personnes que prévu.

Pour un chat IA privé, utilisez la plus petite liste blanche raisonnable. Confirmez que l'ID utilisateur autorisé est correct et que les messages de test proviennent de ce compte.

Si plusieurs personnes doivent avoir accès, ajoutez-les intentionnellement au lieu de laisser le bot ouvert.

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

Un bot de messagerie peut sembler une interface de chat normale, mais derrière il peut y avoir un agent auto-hébergé avec accès au modèle, outils, sessions et permissions runtime locales.

Cela le différencie d'un simple bot de notification. Il doit avoir des règles d'accès claires, des jetons protégés et un chemin réseau contrôlé.

Pour les chats de groupe, soyez prudent. Les permissions de groupe, le mode confidentialité et le statut d'administrateur du bot peuvent changer les messages que le bot peut voir ou auxquels il peut répondre.

Problèmes courants de configuration et comment les résoudre

La plupart des problèmes de configuration peuvent être attribués à l'une des six couches : runtime, chemin des données, permission, passerelle, secret ou validation.

Erreurs de permission dans le chemin des données de l'application

Une erreur de permission signifie généralement que l'utilisateur actuel de l'application ne peut pas lire ou écrire un fichier ou dossier requis. Cela peut arriver lorsqu'une commande de configuration précédente a créé des fichiers en root ou lorsqu'un dossier monté a une mauvaise propriété.

Vérifiez d'abord ces points :

• Êtes-vous à l'intérieur du conteneur ou sur l'hôte ?
• Quel utilisateur exécute l'application ?
• À qui appartient le dossier des 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 été exécutée précédemment en tant que root ?

Ne modifiez pas récursivement les permissions sur de larges dossiers à moins de bien comprendre la cible. Corrigez le chemin spécifique le plus petit nécessaire.

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

Un bot peut ne pas répondre même si l'agent Hermes lui-même fonctionne. Le problème peut venir du jeton, de la liste blanche des utilisateurs, de la passerelle de messagerie, de l'accès réseau ou des permissions de groupe.

Vérifiez dans cet ordre :

1. Confirmez que le jeton du bot est correct.
2. Confirmez que l'ID utilisateur est autorisé.
3. Confirmez que la passerelle a été redémarrée après la configuration.
4. Confirmez que le conteneur peut atteindre l'API de messagerie.
5. Vérifiez les journaux de l'application pour les erreurs de jeton, de réseau ou d'autorisation.
6. Testez le chat privé avant de déboguer le comportement du chat de groupe.

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

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

Si le bot de messagerie répond mais que les réponses du modèle échouent, le problème peut venir du fournisseur de modèle. 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 si le service de modèle fonctionne et est accessible depuis le conteneur. Un service accessible depuis l'hôte peut ne pas être accessible depuis l'intérieur du conteneur si le réseau est différent.

Gardez la résolution des problèmes du fournisseur séparée de celle de la messagerie. Cela évite de modifier le bot lorsque la connexion au modèle est le vrai problème.

Le conteneur ne peut pas atteindre l'API de messagerie

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

Vérifiez si l'hôte a accès à Internet et si le conteneur a accès à Internet. Ce ne sont pas toujours les mêmes.

Si le serveur domestique utilise un VPN, un proxy ou un réseau restreint, confirmez que le conteneur est autorisé à effectuer des requêtes HTTPS sortantes.

Les autorisations de chat de groupe ou le mode confidentialité bloquent les réponses

Le comportement du chat de groupe est plus compliqué que celui du chat privé. Un bot peut répondre en chat privé mais pas en groupe parce qu'il ne peut pas voir le message, n'a pas la bonne autorisation ou est affecté par les paramètres de confidentialité.

Commencez par valider 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 des autorisations d'administrateur et si ses paramètres de confidentialité lui permettent de recevoir les messages requis.

Comment vérifier si l'agent Hermes fonctionne

Une configuration n'est pas terminée simplement parce que l'installation est terminée. Elle est complète 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 erreurs

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

Une erreur de l'assistant de configuration appartient généralement à l'une de ces catégories :

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

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

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

La validation la plus simple de la messagerie est un message de test privé. Envoyez un message basique et confirmez que le bot répond.

Si le chat privé fonctionne, le jeton, la liste blanche, la passerelle et la connexion au modèle sont probablement corrects. Si le chat de groupe échoue toujours, concentrez-vous sur les autorisations de groupe et le comportement de confidentialité plutôt que de réinstaller l'application.

Le chat privé doit être votre premier test de messagerie réussi.

Le tableau de bord affiche l'agent en cours d'exécution

Le tableau de bord doit indiquer que l’agent ou la passerelle fonctionne, selon le système. Le statut du tableau de bord est utile car il offre une vue côté serveur au lieu de se fier uniquement à l’application de messagerie.

Si le tableau de bord affiche un statut arrêté ou non sain, vérifiez les journaux avant de modifier les jetons ou les paramètres du modèle.

Le statut du tableau de bord et la réponse du bot doivent être cohérents. Si l’un fonctionne et l’autre échoue, l’écart indique la couche défaillante.

Les journaux ne montrent pas d’erreurs de permission ou de réseau

Les journaux ne doivent pas afficher de manière répétée des erreurs de permission refusée, jeton invalide, fournisseur inaccessible, échec de la passerelle ou délai d’attente réseau.

Utilisez les journaux pour déterminer l’étape suivante. Une erreur de permission indique un problème de propriété de fichier ou d’utilisateur du conteneur. Une erreur réseau indique un problème d’accessibilité de l’API. Une erreur de jeton indique un problème de configuration des identifiants.

Évitez de modifier toutes les couches en même temps. Changez une variable, redémarrez si nécessaire, puis testez à nouveau.

La reconfiguration fonctionne après redémarrage

Une installation durable doit survivre au redémarrage ou à la reconfiguration. Après avoir modifié les paramètres du modèle ou de la passerelle, redémarrez le service ou la passerelle requis et confirmez que les nouveaux paramètres s’appliquent toujours.

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 ici que la connaissance des chemins hôtes, des chemins de conteneurs et des volumes montés devient pratique.

Comment cela fonctionne dans un véritable environnement de serveur domestique

Dans un véritable environnement de serveur domestique, le modèle général d’installation 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 avec les journaux et le statut du tableau de bord.

Un guide d’installation spécifique à l’appareil peut ensuite fournir le chemin exact des commandes. Par exemple, le flux de configuration de Hermes Agent sous ZimaOS explique un chemin d’installation de Hermes Agent qui inclut la configuration du fournisseur de modèle, la liaison du bot Telegram, l’entrée dans le conteneur Hermes en tant qu’utilisateur de l’application, l’activation de l’environnement de l’application, l’exécution des commandes d’installation, la vérification du statut du tableau de bord et le dépannage des erreurs de permission ou de réponse du bot.

Pour les utilisateurs exécutant des applications auto-hébergées, des passerelles de messagerie et des flux de travail d'agents légers sur un serveur compact toujours allumé, ZimaBoard 2 serveur IA domestique correspond au type d’environnement où les applications Docker, l’accès au terminal, les services locaux et les chemins de données spécifiques 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 flux de travail serveur domestique décrit dans cet article.

La leçon clé est portable : ne mémorisez pas qu'une seule commande de configuration. Comprenez dans quelle couche vous opérez et comment valider le résultat.

FAQ

Puis-je configurer Hermes Agent uniquement via un tableau de bord web ?

Dans de nombreux cas, un tableau de bord web peut suffire pour une configuration basique, surtout s'il expose les paramètres du modèle et de la passerelle. La configuration via 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 quand c'est possible, puis utilisez le terminal du conteneur uniquement si le chemin de configuration l'exige.

Pourquoi dois-je entrer dans le conteneur plutôt que dans le shell de l'hôte ?

Certaines commandes d'application existent uniquement à l'intérieur du conteneur car c'est là que résident le runtime de l'application et ses dépendances. Exécuter la même commande sur l'hôte peut échouer ou affecter le mauvais environnement. Entrer dans le conteneur avec le bon utilisateur permet de s'assurer que les modifications de configuration s'appliquent bien à l'application elle-même.

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

Les données de l'hôte résident sur 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 hôte monté dans le conteneur. Le même chemin de dossier visible ne signifie pas forcément la même chose entre les couches hôte et conteneur, il faut donc vérifier les montages et les emplacements des données de l'application avant de modifier les 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 un fichier ou dossier requis. Cela peut arriver si les fichiers ont été créés par root, si un dossier monté a un propriétaire incorrect, ou si le conteneur s'exécute sous un utilisateur différent de celui attendu. Vérifiez la couche d'exécution, l'utilisateur du conteneur, le chemin des données de l'application et la propriété des fichiers avant de modifier les permissions de manière large.

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

Un bot Telegram peut ne pas répondre parce que le jeton est incorrect, l'ID utilisateur n'est pas autorisé, la passerelle n'a pas été redémarrée, le conteneur ne peut pas atteindre l'API Telegram, ou les permissions du chat de groupe bloquent le message. Testez d'abord le chat privé car cela élimine de nombreuses variables liées aux groupes. Ensuite, vérifiez les journaux pour des erreurs de jeton, de réseau ou de permissions.

Dois-je exposer directement Hermes Agent à Internet ?

L'exposition publique directe n'est généralement pas la meilleure option par défaut pour un agent auto-hébergé. Un bot de messagerie ou une passerelle peut se connecter aux outils, à l'accès aux modèles et éventuellement aux actions d'exécution locale, donc l'accès doit être restreint. Utilisez des schémas d'accès privés, des identifiants forts, des listes blanches et des permissions conservatrices avant d'envisager toute configuration accessible au public.