Menu

Configurer Hermes Agent sur Telegram

Configurer Hermes Agent sur Telegram

Cette page fait partie du guide pratique francophone consacré à Hermes Agent. Elle répond à l'intention de recherche : créer un bot Telegram.

Le contenu s'appuie sur la documentation officielle Hermes Agent associée à cette page. L'objectif n'est pas de remplacer la documentation de Nous Research, mais de fournir une lecture claire en français, structurée pour aller vite, avec un maillage logique vers les pages complémentaires du même site.

À retenir

  • Sujet principal : hermes agent telegram.
  • Type de page : spoke.
  • Cluster : messagerie.
  • Source canonique : documentation officielle Hermes Agent.
  • Aucun lien vers l'autre domaine n'est utilisé dans cette page.

Quand utiliser cette page

Utilisez cette page quand vous voulez créer un bot Telegram. Elle part du principe que Hermes Agent est déjà identifié comme l'outil à mettre en place ou à comprendre, puis détaille les points importants issus de la documentation officielle.

Si vous découvrez seulement l'outil, revenez d'abord au hub parent puis suivez les liens internes proposés en fin de page.

Base officielle

Hermes Agent integrates with Telegram as a full-featured conversational bot. Once connected, you can chat with your agent from any device, send voice memos that get auto-transcribed, receive scheduled task results, and use the agent in group chats. The integration is built on python-telegram-bot and supports text, voice, images, and file attachments.

Step 1: Create a Bot via BotFather

Every Telegram bot requires an API token issued by @BotFather, Telegram's official bot management tool.

  1. Open Telegram and search for @BotFather, or visit t.me/BotFather
  2. Send /newbot
  3. Choose a display name (e.g., "Hermes Agent") — this can be anything
  4. Choose a username — this must be unique and end in bot (e.g., my_hermes_bot)
  5. BotFather replies with your API token. It looks like this:
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Keep your bot token secret. Anyone with this token can control your bot. If it leaks, revoke it immediately via /revoke in BotFather.

Step 2: Customize Your Bot (Optional)

These BotFather commands improve the user experience. Message @BotFather and use:

  • Command — Purpose
  • /setdescription — The "What can this bot do?" text shown before a user starts chatting
  • /setabouttext — Short text on the bot's profile page
  • /setuserpic — Upload an avatar for your bot
  • /setcommands — Define the command menu (the / button in chat)
  • /setprivacy — Control whether the bot sees all group messages (see Step 3)

For /setcommands, a useful starting set:

help - Show help information
new - Start a new conversation
sethome - Set this chat as the home channel

Online/Offline status indicator (Optional)

Telegram bots have no real online/offline presence dot — that green dot is a

*user-account* feature, not something the Bot API exposes for bots. The closest

surface is the bot's short description (the line shown under its name in the

bot's profile).

Enable status_indicator and Hermes sets that short description to Online

when the gateway connects and Offline on a clean shutdown:

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        # Optional custom strings (defaults: "Online" / "Offline"):
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

Notes:

  • The short description is global to the bot (visible to all users), not

per-chat. Users see it on the bot's profile page, not as a live badge inside

an open chat.

  • Only a clean gateway shutdown (/stop, disconnect) writes "Offline".

A hard crash leaves the last-known status — the inherent limitation of a

profile-text indicator.

  • Off by default, since it mutates the bot's global profile.

Command menu priority and cap (Optional)

Hermes registers its command menu automatically when the Telegram gateway starts. The menu is built from the central slash-command registry plus eligible plugin/skill commands, then capped so Telegram accepts the payload reliably. The default cap is 60 commands — enough to keep all built-in commands plus common skill commands visible.

If you have local or plugin commands that should stay visible in Telegram's / picker, prioritize them in ~/.hermes/config.yaml:

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command

priority_mode controls how your list combines with Hermes' built-in priority list:

  • prepend: put your commands first, then Hermes defaults
  • append: keep Hermes defaults first, then your commands
  • replace: use only your list for priority ordering

Telegram allows up to 100 BotCommands, but large command payloads can fail. Hermes defaults to 60 for reliability and clamps configured values to 1..100; use /commands for the full command list.

Step 3: Privacy Mode (Critical for Groups)

Telegram bots have a privacy mode that is enabled by default. This is the single most common source of confusion when using bots in groups.

With privacy mode ON, your bot can only see:

  • Messages that start with a / command
  • Replies directly to the bot's own messages
  • Service messages (member joins/leaves, pinned messages, etc.)
  • Messages in channels where the bot is an admin

With privacy mode OFF, the bot receives every message in the group.

How to disable privacy mode

  1. Message @BotFather
  2. Send /mybots
  3. Select your bot
  4. Go to Bot Settings → Group Privacy → Turn off

You must remove and re-add the bot to any group after changing the privacy setting. Telegram caches the privacy state when a bot joins a group, and it will not update until the bot is removed and re-added.

An alternative to disabling privacy mode: promote the bot to group admin. Admin bots always receive all messages regardless of the privacy setting, and this avoids needing to toggle the global privacy mode.

Observe group chatter without auto-replying

For OpenClaw/Yuanbao-style group behavior, configure Telegram so the bot can see ordinary group messages but only responds when directly triggered:

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

With this mode enabled, unmentioned group messages from explicitly allowlisted chats/topics are appended to the shared chat/topic session transcript as observed context, but they do not dispatch the agent. allowed_chats gates where the bot responds; group_allowed_chats authorizes the shared group session used for observed context, so use the same chat IDs for this mode. A later @botname mention, reply to the bot, or configured mention pattern in that same allowlisted chat/topic can use that observed context. The triggered message is also tagged with [nickname|user_id] and gets a per-turn safety prompt so the model treats prior observed lines as context, not instructions addressed to the bot.

Equivalent environment variable:

TELEGRAM_ALLOWED_CHATS=-1001234567890
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true

This requires Telegram to deliver ordinary group messages to the gateway, so disable BotFather privacy mode or promote the bot to group admin as described above.

Step 4: Find Your User ID

Hermes Agent uses numeric Telegram user IDs to control access. Your user ID is not your username — it's a number like 123456789.

Method 1 (recommended): Message @userinfobot — it instantly replies with your user ID.

Method 2: Message @get_id_bot — another reliable option.

Save this number; you'll need it for the next step.

Step 5: Configure Hermes

Option A: Interactive Setup (Recommended)

hermes gateway setup

Select Telegram when prompted. The wizard asks for your bot token and allowed user IDs, then writes the configuration for you.

Option B: Manual Configuration

Add the following to ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users

Start the Gateway

hermes gateway

The bot should come online within seconds. Send it a message on Telegram to verify.

Sending Generated Files from Docker-backed Terminals

If your terminal backend is docker, keep in mind that Telegram attachments are

sent by the gateway process, not from inside the container. That means the

final MEDIA:/... path must be readable on the host where the gateway is

running.

Common pitfall:

  • the agent writes a file inside Docker to /workspace/report.txt
  • the model emits MEDIA:/workspace/report.txt
  • Telegram delivery fails because /workspace/report.txt only exists inside the

container, not on the host

Recommended pattern:

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/.hermes/cache/documents:/output"

Then:

  • write files inside Docker to /output/...
  • emit the host-visible path in MEDIA:, for example:

MEDIA:/home/user/.hermes/cache/documents/report.txt

If you already have a docker_volumes: section, add the new mount to the same

list. YAML duplicate keys silently override earlier ones.

Supported MEDIA: file extensions

The gateway extracts MEDIA:/path/to/file tags from agent replies and ships the referenced file as a platform-native attachment. Supported extensions across all gateway platforms:

  • Category — Extensions
  • Images — png, jpg, jpeg, gif, webp, bmp, tiff, svg
  • Audio — mp3, wav, ogg, m4a, opus, flac, aac
  • Video — mp4, mov, webm, mkv, avi
  • **Docume

Points de vigilance

  • Vérifiez toujours la version active de Hermes Agent avant d'appliquer une commande ou une configuration.
  • Ne collez pas de clé API dans un chat public ou dans une page visible.
  • Gardez les secrets dans les fichiers ou gestionnaires prévus pour cela.
  • Si une fonctionnalité dépend d'un provider, d'un plugin ou d'une plateforme de messagerie, vérifiez que le composant est bien activé dans votre profil.
  • Pour une installation de production, testez d'abord le flux complet sur une machine ou un profil isolé.

Exemple de parcours logique

  1. Lire la page courante pour comprendre hermes agent telegram.
  2. Ouvrir le hub parent du cluster messagerie.
  3. Passer ensuite aux pages complémentaires proposées dans « À lire ensuite ».
  4. Revenir à la documentation officielle si vous avez besoin du détail exact ou d'une commande récemment modifiée.

FAQ rapide

Cette page remplace-t-elle la documentation officielle ?

Non. Elle sert de guide francophone structuré. Le lien vers la source officielle est disponible en bas de page.

Les commandes sont-elles garanties à jour ?

Elles sont basées sur la documentation officielle récupérée au moment de la génération. Pour un usage critique, vérifiez toujours la page officielle liée en bas.

Pourquoi autant de liens internes ?

Hermes Agent est un système modulaire. L'installation, les providers, les outils, la mémoire, les skills, la sécurité et les plateformes se répondent. Le maillage interne aide à suivre ce chemin sans tomber sur des pages orphelines.

À lire ensuite