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

PlateformeParoleImagesFichierchaîne de messageRéaction emojiIndicateur de saisieSortie en streaming
TelegramPris en chargePris en chargePris en chargePris en charge—Pris en chargePris en charge
DiscordPris en chargePris en chargePris en chargePris en chargePris en chargePris en chargePris en charge
SlackPris en chargePris en chargePris en chargePris en chargePris en chargePris en chargePris en charge
WhatsApp—Pris en chargePris en charge——Pris en chargePris en charge
Signal—Pris en chargePris en charge——Pris en chargePris en charge
Feishu/LarkPris en chargePris en chargePris en chargePris en chargePris en chargePris en chargePris en charge
WeChat WorkPris en chargePris en chargePris en charge————
DingTalk—Pris en chargePris en charge—Pris en charge—Pris en charge
Microsoft Teams—Pris en charge—Pris en charge—Pris en charge—
E-mail—Pris en chargePris en chargePris en charge———
SMS———————
MatrixPris en chargePris en chargePris en chargePris en chargePris en chargePris en chargePris 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

# Exécuter au premier plan (pour le débogage)
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

# Chemin du fichier : ~/.hermes/config.yaml
# 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

# Démarrer Gateway
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 :

CommandeFonctionnalités
/new ou /resetDémarrer une nouvelle session
/model [name]Afficher ou changer les modèles
/retryRéessayer le dernier message
/undoAnnuler le dernier tour de conversation
/stopInterrompre la tâche en cours
/approve / /denyApprouver/Rejeter les commandes dangereuses
/background <task>Exécuter des tâches dans des sessions en arrière-plan
/statusAfficher les informations de la session en cours
/usageAfficher l'utilisation des jetons pour cette session.
/voice [on/off/tts]Contrôler les réponses vocales
/compressCompresser 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-mcpRecharger le serveur MCP
/updateMettre à jour Hermes vers la dernière version
/helpAfficher 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."

FieldsTypeDescription
plateformestringNom de la plateforme (telegram, discord, slack, etc.)
chat_idstringIdentifiant de session (ID de chat privé, ID de groupe, ID de canal)
chat_typestringTypes de session : dm (message direct), groupe, canal, fil
user_idstringID de plateforme de l'expéditeur du message
user_namestringNom d'affichage de l'expéditeur du message
thread_idstringID de sujet de forum (forum Telegram) / ID de fil Discord
guild_idstringID 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énariosClé de session
Chat privé Telegramagent:main:telegram:dm:12345
Groupe Telegramagent:main:telegram:group:-10012345:user_abc
Sujets de forum Telegramagent:main:telegram:group:-10012345:thread_678:user_abc
Chat privé Discordagent:main:discord:dm:12345
Salons du serveur Discordagent:main:discord:channel:12345:user_abc
Fil Discordagent: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.

FieldsDescription
session_idIdentifiant unique de session, format : YYYYMMDD_HHMMSS_8 chiffres hexadécimaux aléatoires
created_atHeure de création de la session
updated_atHeure de dernière activité (utilisée pour la détermination du délai d'inactivité)
total_tokensConsommation cumulée de tokens
estimated_cost_usdEstimation cumulée des coûts (USD)
suspendedIndique s'il a été suspendu de force (commande /stop ou boucle anormale)
resume_pendingIndique 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 configurationValeur par défautSignification
group_sessions_per_uservraiChaque utilisateur d’un groupe/canal dispose d’une session indépendante
thread_sessions_per_userfalseTous les utilisateurs du fil partagent la même session

Comportement dans différents scénarios

ScénariosComportement par défautDescription
Chat privé (DM)Toujours indépendantLe chat privé est toujours privé et non configurable
Groupes/CanauxChaque utilisateur dispose d’une session indépendanteL’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 sessionDans 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

# Chemin du fichier : ~/.hermes/.env
# 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

# Après que l'utilisateur a envoyé un message privé au bot, il verra : "Code d'appairage : XKGH5N7P"
# 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 }
  }
}
PolitiqueValeur par défautDescription
quotidien4:00 AMRéinitialiser la session à une heure précise chaque jour
idle1440 minutesRéinitialiser la session après un délai d'inactivité
bothcombinaisonCelui qui se déclenche en premier réinitialise la session

Référence rapide pour les commandes courantes

Exemple

# ─── Gestion de la passerelle ────────────────────────────────────────────────
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
autres extensions