Intégration de la messagerie de la plateforme Hermes Agent
La passerelle de messagerie permetMême Agent—Les mêmes mémoires, compétences et outils—fonctionnant de manière transparente sur 20+ plateformes.
Ce chapitre présentera la configuration et le déploiement de la passerelle, le cycle de vie des sessions, les politiques d'isolation multi-utilisateur et le contrôle d'accès de sécurité.
Vue d'ensemble de la passerelle de messagerie
La passerelle de messagerie est un processus d'arrière-plan résident qui gère centralement les connexions, les sessions, les tâches planifiées et la livraison des médias pour toutes les plateformes de messagerie.
Tout ce que vous enseignez à l'Agent dans le CLI—mémoire, compétences, préférences—est entièrement cohérent sur toutes les plateformes.
Plateformes prises en charge
Hermes prend en charge 20+ plateformes de messagerie:CLI、Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、Email、SMS、DingTalk、Feishu/Lark、WeChat Work、micro信、QQ、元宝、BlueBubbles(iMessage)、Home Assistant、Microsoft Teams、Google Chat etc.
Comparaison des capacités des plateformes
| Plateforme | Parole | Images | Fichier | chaîne de message | Réaction emoji | Indicateur de saisie | Sortie en streaming |
|---|---|---|---|---|---|---|---|
| Telegram | Pris en charge | Pris en charge | Pris en charge | Pris en charge | — | Pris en charge | Pris en charge |
| Discord | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge |
| Slack | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge |
| — | Pris en charge | Pris en charge | — | — | Pris en charge | Pris en charge | |
| Signal | — | Pris en charge | Pris en charge | — | — | Pris en charge | Pris en charge |
| Feishu/Lark | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge |
| WeChat Work | Pris en charge | Pris en charge | Pris en charge | — | — | — | — |
| DingTalk | — | Pris en charge | Pris en charge | — | Pris en charge | — | Pris en charge |
| Microsoft Teams | — | Pris en charge | — | Pris en charge | — | Pris en charge | — |
| — | Pris en charge | Pris en charge | Pris en charge | — | — | — | |
| SMS | — | — | — | — | — | — | — |
| Matrix | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge | Pris en charge |
Continuité de session multiplateforme : le même Agent peut conserver le contexte sur différentes plateformes. Par exemple, si vous êtes en pleine conversation avec l’Agent sur Telegram et que vous passez à Discord, l’Agent se souvient encore de la conversation précédente.
Démarrage et configuration de la passerelle
Configuration de la version bureau
Ouvrez l’élément Plateformes de messagerie dans le menu de gauche pour voir les plateformes prises en charge. Cliquez sur la plateforme correspondante pour la configurer :

Configuration en mode interactif
Utilisez l’assistant interactif pour effectuer la configuration initiale de toutes les plateformes :
hermes gateway setup

L’assistant vous guidera dans la configuration de chaque plateforme : sélection de la plateforme, saisie du Bot Token, définition de la liste des utilisateurs autorisés, etc.
Par exemple, après avoir sélectionné Feishu, vous pouvez choisir de créer un bot en scannant un code QR ou en utilisant l'APP ID :

Commandes de gestion de la passerelle
Exemple
hermes gateway
# Installer comme service système au niveau utilisateur (Linux systemd / macOS launchd)
hermes gateway install
# Linux : Installer comme service système qui se lance au démarrage
sudo hermes gateway install --system
# Contrôle du service
hermes gateway start # Démarrer le service
hermes gateway stop # Arrêter le service
hermes gateway restart # Redémarrer le service
hermes gateway status # Voir l'état du service
Intégration du Bot Telegram en pratique
Prenons Telegram comme exemple pour réaliser un processus complet d'intégration de Bot.
Étape 1 : Créer un Bot Telegram.
Dans Telegram, recherchez @BotFather, envoyez la commande /newbot, et définissez le nom et le nom d'utilisateur du Bot comme demandé.
BotFather renverra un jeton d'API Bot, au format similaire à :1234567890:ABCdefGHIjklMNOpqrsTUVwxyz。
Étape 2 : Configurer le Hermes Gateway.
Exemple
# Configuration de la plateforme Telegram
platforms:
telegram:
enabled: true
bot_token: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
# Optionnel : liste des ID utilisateur autorisés (mode liste blanche).
allowed_users:
- "123456789"
# Optionnel : indique s'il doit être @mentionné dans le groupe pour répondre
require_mention: true
# Optionnel : liste des canaux qui ne nécessitent pas de @mention
free_response_channels:
- "-1001234567890"
Étape 3 : Démarrer et tester.
Exemple
hermes gateway start
# Envoyer un message de test à votre Bot dans Telegram
Pour l'intégration initiale, il est recommandé d'utiliser le mode liste blanche (allowed_users), en autorisant uniquement votre propre compte à interagir avec l'Agent, puis de l'ouvrir aux autres après avoir vérifié que tout fonctionne correctement.
Commandes slash disponibles dans la plateforme
Les commandes suivantes sont disponibles sur n'importe quelle plateforme de messagerie :
| Commande | Fonctionnalités |
|---|---|
| /new ou /reset | Démarrer une nouvelle session |
| /model [name] | Afficher ou changer les modèles |
| /retry | Réessayer le dernier message |
| /undo | Annuler le dernier tour de conversation |
| /stop | Interrompre la tâche en cours |
| /approve / /deny | Approuver/Rejeter les commandes dangereuses |
| /background <task> | Exécuter des tâches dans des sessions en arrière-plan |
| /status | Afficher les informations de la session en cours |
| /usage | Afficher l'utilisation des jetons pour cette session. |
| /voice [on/off/tts] | Contrôler les réponses vocales |
| /compress | Compresser manuellement le contexte de conversation |
| /resume [title] | Reprendre une session précédemment nommée |
| /<skill-name> | Invoquer n'importe quelle compétence installée |
| /reload-mcp | Recharger le serveur MCP |
| /update | Mettre à jour Hermes vers la dernière version |
| /help | Afficher toutes les commandes disponibles |
Cycle de vie de session
La Session est le concept central dans Hermes Gateway pour gérer les conversations.
Comprendre comment fonctionne Session vous aide à configurer des politiques d'isolation de session et des règles de réinitialisation appropriées.
SessionSource : descripteur de source de message
Chaque message entrant dans la Gateway porte un SessionSource, qui enregistre "d'où vient ce message."
| Fields | Type | Description |
|---|---|---|
| plateforme | string | Nom de la plateforme (telegram, discord, slack, etc.) |
| chat_id | string | Identifiant de session (ID de chat privé, ID de groupe, ID de canal) |
| chat_type | string | Types de session : dm (message direct), groupe, canal, fil |
| user_id | string | ID de plateforme de l'expéditeur du message |
| user_name | string | Nom d'affichage de l'expéditeur du message |
| thread_id | string | ID de sujet de forum (forum Telegram) / ID de fil Discord |
| guild_id | string | ID du serveur Discord (utilisé pour l'isolation des serveurs) |
Règles de génération de la clé de session
La clé de session est une chaîne déterministe composée de champs provenant de SessionSource.
Elle détermine quels messages appartiennent à la même session. Le format est le suivant :
agent:main:{platform}:{chat_type}:{chat_id}:{thread_id}:{user_id}
Exemples de clés de session dans différents scénarios :
| Scénarios | Clé de session |
|---|---|
| Chat privé Telegram | agent:main:telegram:dm:12345 |
| Groupe Telegram | agent:main:telegram:group:-10012345:user_abc |
| Sujets de forum Telegram | agent:main:telegram:group:-10012345:thread_678:user_abc |
| Chat privé Discord | agent:main:discord:dm:12345 |
| Salons du serveur Discord | agent:main:discord:channel:12345:user_abc |
| Fil Discord | agent:main:discord:thread:12345:thread_678 |
La règle de génération de la clé de session est l'une des configurations de passerelle les plus importantes. Si elle est mal configurée, elle peut provoquer des interférences entre les sessions de différents utilisateurs — deux personnes différentes voyant le contenu de la conversation de l'autre.
SessionEntry: enregistrement de session active
Chaque clé de session correspond à une SessionEntry, qui enregistre les métadonnées et l'état de la session.
| Fields | Description |
|---|---|
| session_id | Identifiant unique de session, format : YYYYMMDD_HHMMSS_8 chiffres hexadécimaux aléatoires |
| created_at | Heure de création de la session |
| updated_at | Heure de dernière activité (utilisée pour la détermination du délai d'inactivité) |
| total_tokens | Consommation cumulée de tokens |
| estimated_cost_usd | Estimation cumulée des coûts (USD) |
| suspended | Indique s'il a été suspendu de force (commande /stop ou boucle anormale) |
| resume_pending | Indique s'il est en attente de récupération (indicateur de récupération au redémarrage après un plantage) |
Politique d'isolation multi-utilisateur
L'isolation multi-utilisateur détermine si plusieurs utilisateurs d'un même groupe ou canal partagent une seule session ou ont leurs propres sessions indépendantes.
Cette configuration affecte directement l'expérience utilisateur—une session partagée signifie que l'utilisateur A peut voir le contexte de conversation de l'utilisateur B.
Configuration de la politique d'isolation
| Élément de configuration | Valeur par défaut | Signification |
|---|---|---|
| group_sessions_per_user | vrai | Chaque utilisateur d’un groupe/canal dispose d’une session indépendante |
| thread_sessions_per_user | false | Tous les utilisateurs du fil partagent la même session |
Comportement dans différents scénarios
| Scénarios | Comportement par défaut | Description |
|---|---|---|
| Chat privé (DM) | Toujours indépendant | Le chat privé est toujours privé et non configurable |
| Groupes/Canaux | Chaque utilisateur dispose d’une session indépendante | L’utilisateur A et l’utilisateur B disposent chacun de contextes de session indépendants dans le même groupe |
| Fil (sujet de forum) | Tous les utilisateurs partagent une session | Dans les sujets de forum Telegram et les fils Discord, tous les participants partagent le même contexte |
Modifications du prompt système pour les sessions partagées
Lorsque la session est en mode partagé (shared_multi_user_session = true), le prompt système change :
- Au lieu d'un nom d'utilisateur fixe, il indique « Session multi-utilisateur—le préfixe du message inclut le nom de l'expéditeur »
- Chaque message d'utilisateur est préfixé par le nom d'affichage de l'expéditeur afin que l'Agent sache qui parle
- Cette conception préserve l'efficacité de la mise en cache des prompts (le prompt système ne change pas selon l'expéditeur)
La politique d'isolation par défaut (par utilisateur pour les groupes, partagée pour les fils) est une bonne pratique vérifiée par une utilisation intensive dans des conditions réelles. Sauf si vous avez des exigences particulières, il n'est pas recommandé de la modifier.
Configuration de sécurité de la passerelle
Contrôle d'accès des utilisateurs
Par défaut, la passerelle rejette tous les utilisateurs qui ne figurent pas sur la liste blanche—Il s'agit du paramètre par défaut sécurisé pour un Bot disposant de privilèges d'accès au terminal.
Configurez les utilisateurs autorisés (dans le fichier .env) :
Exemple
# Liste blanche d'utilisateurs pour des plateformes spécifiques
TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SLACK_ALLOWED_USERS=U012AB4GH
FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
WECOM_ALLOWED_USERS=user-id-1,user-id-2
TEAMS_ALLOWED_USERS=aad-object-id-1
# Liste blanche qui s'applique à toutes les plateformes
GATEWAY_ALLOWED_USERS=123456789,987654321
# Autoriser tous les utilisateurs (non recommandé pour les bots avec accès au terminal)
GATEWAY_ALLOW_ALL_USERS=true
Appairage par message privé (alternative à la liste blanche)
Pas besoin de configurer manuellement les ID utilisateur. Lorsqu'un nouvel utilisateur envoie un message privé au bot, il recevra un code d'appairage à usage unique :
Exemple
# Vous approuvez l'accès de l'utilisateur
hermes pairing approve telegram XKGH5N7P
# Afficher la liste des utilisateurs en attente + approuvés
hermes pairing list
# Révoquer les autorisations d'accès d'un utilisateur
hermes pairing revoke telegram 123456789
Le code d'appairage expire après 1 heure, est soumis à une limitation de débit et est généré à l'aide de nombres aléatoires cryptographiques.
Jeton silencieux
Utilisé dans les discussions de groupe, les Hooks et les flux de travail automatisés pour que l'Agent n'envoie aucun message dans des conditions spécifiques :
# Agent 回复中仅包含以下内容之一时,网关不会向平台发送任何消息: [SILENT] SILENT NO_REPLY NO REPLY
le silence estune décision de livraison, sans affecter l'enregistrement de session—la réponse est toujours stockée dans l'historique de session, ce qui garantit que la logique de tour de parole de la conversation fonctionne normalement.
Politique de réinitialisation de session
Configurez quand la session se réinitialise automatiquement pour éviter une croissance illimitée du contexte :
Exemple
"reset_by_platform": {
"telegram": { "mode": "idle", "idle_minutes": 240 },
"discord": { "mode": "idle", "idle_minutes": 60 },
"slack": { "mode": "daily", "reset_hour": 4 }
}
}
| Politique | Valeur par défaut | Description |
|---|---|---|
| quotidien | 4:00 AM | Réinitialiser la session à une heure précise chaque jour |
| idle | 1440 minutes | Réinitialiser la session après un délai d'inactivité |
| both | combinaison | Celui qui se déclenche en premier réinitialise la session |
Référence rapide pour les commandes courantes
Exemple
hermes gateway setup # Configuration interactive de la plateforme
hermes gateway # Exécuter au premier plan (débogage)
hermes gateway install # Installer comme service utilisateur
hermes gateway start / stop / restart # Contrôle du service
hermes gateway status # Voir l'état du service
# ─── Appairage utilisateur ────────────────────────────────────────────────
hermes pairing list # Afficher la liste des appairages
hermes pairing approve <platform> <code> # Approuver l'appairage
hermes pairing revoke <platform> <user_id> # Révoquer l'accès
# ─── Commandes slash dans la session ──────────────────────────────────────────
/new # Démarrer une nouvelle session
/model [Name] # Afficher ou changer de modèle
/retry # Réessayer le dernier message
/undo # Annuler le tour précédent
/stop # Interrompre la tâche en cours
/approve / /deny # Approuver/Refuser les commandes dangereuses
/background <Task> # Exécuter la tâche en arrière-plan
/status # Informations sur la session actuelle
/usage # Utilisation des tokens
/voice [on/off/tts] # Contrôler la voix
/compress # Compresser le contexte
/resume [Titre] # Restaurer la session
/<skill-name> # Invoquer la compétence
/reload-mcp # Recharger MCP
/update # Mettre à jour Hermes
/help # Toutes les commandes