Aller au contenu
EN 4 QUESTIONSTrouver mon modèle
Agents et automatisation · guide expert · 22 min de lecture

Bien configurer Hermes Agent : modèle, Telegram, sécurité

Hermes Agent se règle dans deux fichiers, config.yaml et .env, que complètent quelques fichiers Markdown. Ce guide passe en revue les réglages qui comptent, du choix du modèle au durcissement, avec les exemples de la documentation officielle et les pièges vus en usage réel.

Disponible en France

Illustration du thème Agents et automatisation

Le guide Hermes Agent et OpenClaw explique ce que sont ces agents personnels et comment ils sont bâtis. Celui-ci va plus loin dans les réglages de Hermes Agent, l’agent libre de Nous Research : où ils vivent, lesquels changer en premier, et comment fermer les portes avant de laisser l’agent seul sur une machine allumée jour et nuit. Tout vient de la documentation officielle lue le 19 novembre 2026, pour la version v0.23.2 ; les noms de clés et les commandes restent en anglais, comme dans le logiciel.

Installer et lancer une première fois

Hermes existe en appli de bureau (Mac à puce Apple, Windows) et en ligne de commande. Pour un agent qui tourne sur un serveur ou un mini-PC, prenez la ligne de commande :

Installer Hermes Agent

Linux, macOS, Windows par WSL2 (ligne de commande seule)

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

D'après hermes-agent.nousresearch.com, lue le 3 octobre 2026.La fiche de Hermes Agent →

Le script clone le code dans ~/.hermes/hermes-agent/, pose un lanceur dans ~/.local/bin/hermes et prépare le dossier de données ~/.hermes/. Il installe aussi un Chromium dédié pour la navigation ; --skip-browser l’évite sur une machine sans écran. Ensuite :

  1. Rechargez le terminal (source ~/.bashrc), puis lancez hermes setup : l’assistant fait choisir le fournisseur, le modèle, les outils et les messageries.
  2. Vérifiez le résultat avec hermes doctor. La commande sort en code 1 tant qu’un problème reste, ce qui permet de l’utiliser dans un script de surveillance ; hermes doctor --fix répare ce qui peut l’être.
  3. Pour revenir sur un seul point plus tard, gardez les commandes dédiées : hermes model, hermes tools, hermes gateway setup, hermes config set.

Bon à savoir. Sous Windows, Hermes tourne désormais en natif (%LOCALAPPDATA%\hermes) ou dans WSL2. Les deux installations ne partagent pas leurs données : choisissez l’une ou l’autre pour un agent permanent.

Où sont les réglages

Tout tient dans ~/.hermes/ (la variable HERMES_HOME le déplace). Deux fichiers portent l’essentiel, avec une règle simple : les secrets dans .env, tout le reste dans config.yaml.

Les fichiers du dossier ~/.hermes et l'ordre dans lequel Hermes Agent tranche entre deux réglages, d'après les pages Configuration et Which File Does What de la documentation, lues le 19 novembre 2026.

hermes config set range lui-même chaque valeur au bon endroit : un nom en capitales (OPENROUTER_API_KEY, TELEGRAM_ALLOWED_USERS) part dans .env, une clé en minuscules dans config.yaml.

hermes config                       # tout afficher
hermes config get model             # une valeur, telle qu'Hermes la résout
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # rangé dans .env
hermes config check                 # options manquantes ou périmées

Dans config.yaml, une valeur peut renvoyer à une variable d’environnement avec ${NOM} ; une variable absente reste écrite telle quelle et Hermes le signale dans son journal. Une passerelle déjà lancée relit .env au début de chaque tour : une nouvelle clé sert dès le message suivant, sans redémarrage.

Documentation de Hermes Agent, page Hermes Agent Configuration : arborescence de ~/.hermes avec config.yaml, .env, auth.json, SOUL.md, memories, skills, cron, sessions et logs, puis la section Managing Configuration avec les commandes hermes config, edit, get, set, unset, check et migrate.
La page Configuration de la documentation de Hermes Agent, en anglais : la structure du dossier ~/.hermes puis les commandes hermes config (capture du 19 novembre 2026, hermes-agent.nousresearch.com).

Les fichiers Markdown, eux, façonnent l’agent :

  • SOUL.md : la personnalité et le ton, que vous écrivez. Il est injecté en tête de chaque conversation.
  • memories/MEMORY.md et memories/USER.md : ce que l’agent a appris et ce qu’il sait de vous. C’est lui qui les écrit.
  • AGENTS.md ou .hermes.md dans un projet : les consignes de ce projet. Un seul fichier de projet est lu par session, dans cet ordre : .hermes.md, AGENTS.md, CLAUDE.md, .cursorrules.

Choisir le modèle

hermes model ouvre le sélecteur ; en conversation, /model change de modèle parmi les fournisseurs déjà configurés, mais ne sait pas en ajouter un. Ce que la commande écrit dans config.yaml ressemble à ceci :

model:
  provider: openrouter
  default: anthropic/claude-opus-4.7
  base_url: ''
  api_mode: chat_completions

Une API en ligne. OpenRouter donne accès à des centaines de modèles avec une seule clé, OPENROUTER_API_KEY dans .env (ou une connexion par navigateur avec hermes auth add openrouter --type oauth). Nous Portal, le service de Nous Research, se branche en une commande, hermes setup --portal, qui active aussi ses outils payants (recherche web, images, synthèse vocale).

Un modèle local. Ollama, LM Studio, llama.cpp ou vLLM se déclarent comme un point d’accès personnalisé, au format de l’API d’OpenAI :

model:
  default: qwen2.5-coder:32b
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 64000

Trois règles évitent la plupart des pannes :

  1. 64 000 jetons de contexte au minimum. Hermes refuse de démarrer en dessous : son invite système et la description de ses outils prennent déjà une bonne part de la fenêtre. Or Ollama, d’après la documentation, ouvre par défaut 4 096 jetons sous 24 Go de mémoire vidéo et 32 768 entre 24 et 48 Go. Le contexte ne se règle pas par l’API : posez OLLAMA_CONTEXT_LENGTH=64000 dans l’environnement du service Ollama, ou créez une variante du modèle avec un Modelfile (PARAMETER num_ctx 64000), puis vérifiez la colonne CONTEXT de ollama ps.
  2. Un modèle qui sait appeler des outils. Un modèle sans appel d’outils discute, mais n’agit pas. Si l’agent écrit du JSON brut au lieu de lancer l’outil, c’est souvent le serveur : llama.cpp demande --jinja, vLLM --enable-auto-tool-choice et --tool-call-parser.
  3. provider: custom et une base_url. L’alias ollama sans adresse déclarée échoue avec « provider ‘ollama’ has no endpoint configured ». Sur la machine de QUELLE IA, une version plus ancienne refusait carrément cet alias : custom avec l’adresse en /v1 marche dans tous les cas.
Documentation de Hermes Agent, page AI Providers, section Ollama : commandes ollama pull et ollama serve, procédure hermes model, bloc YAML model avec default qwen2.5-coder:32b, provider custom, base_url localhost:11434/v1 et context_length 64000, puis un encadré jaune sur les contextes trop courts d'Ollama.
La section Ollama de la page AI Providers : provider custom, adresse en /v1 et context_length à 64 000, suivie de l'avertissement sur le contexte trop court qu'Ollama donne par défaut (capture du 19 novembre 2026, hermes-agent.nousresearch.com).

Pour un agent qui doit répondre vite après une longue pause, gardez le modèle en mémoire : Ollama le décharge après cinq minutes d’inactivité, et le rechargement s’ajoute au temps de lecture de l’invite. OLLAMA_KEEP_ALIVE=24h dans le service d’Ollama règle ce point ; HERMES_API_TIMEOUT=1800 dans .env laisse 30 minutes à un modèle lent sur processeur.

Le meilleur des deux. Gardez le modèle local par défaut et un modèle en ligne en secours, appelé seulement quand le premier échoue :

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4

Hermes confie aussi des travaux annexes à des modèles « auxiliaires » : résumé du contexte, titres, vision, et le jugement des commandes en mode de validation smart. Par défaut, ils prennent le modèle principal. Un modèle rapide et bon marché suffit pour ces tâches ; la page Configuring Models montre comment les régler un par un dans la rubrique auxiliary.

Les modèles les mieux classés sur les tâches d’agent, d’après QUELLE IA :

Le haut du classement Agents

  1. GPT-6 AstraOpenAI100,3
  2. Claude Opus 5.5Anthropic100,1
  3. Gemini 4 ArgonGoogle DeepMind99,3
  4. Claude Fable 5.1Anthropic97,4
  5. GPT-6.1 SolOpenAI96,0

Score Agents, édition du 16 novembre 2026. Deux modèles dont les marges se recouvrent sont ex æquo.

Classement Agents des modèles de langage →

Brancher Telegram

Telegram est la messagerie la plus simple à relier : un jeton de bot suffit.

  1. Dans Telegram, écrivez à @BotFather, envoyez /newbot, choisissez un nom et un identifiant qui finit par bot. Gardez le jeton qu’il renvoie ; s’il fuit, /revoke chez BotFather l’annule.
  2. Trouvez votre identifiant Telegram, un nombre distinct de votre nom d’utilisateur, par exemple avec @userinfobot.
  3. Lancez hermes gateway setup et choisissez Telegram, ou écrivez les deux lignes vous-même dans ~/.hermes/.env :
TELEGRAM_BOT_TOKEN=<jeton donné par BotFather>
TELEGRAM_ALLOWED_USERS=<votre identifiant numérique>
  1. Démarrez la passerelle au premier plan pour tester : hermes gateway. Le bot répond en quelques secondes.
  2. Dans la conversation, tapez /sethome : ce sera le salon où arrivent les résultats des tâches planifiées.

Sans aucune liste d’utilisateurs, Hermes refuse tout le monde et l’écrit dans son journal au démarrage. Un inconnu qui écrit au bot reçoit un code d’appairage de huit caractères, valable une heure, que vous acceptez avec hermes pairing approve telegram <code> ; hermes pairing revoke retire un accès.

Dans un groupe. Un bot Telegram ne voit par défaut que les commandes et les réponses à ses messages. Pour qu’il lise tout, désactivez le mode « Group Privacy » chez BotFather, puis retirez le bot du groupe et ajoutez-le de nouveau : Telegram garde l’ancien réglage sinon.

Un jeton, un programme. Telegram ne livre les messages d’un bot qu’à un seul programme à la fois. Sur la machine de QUELLE IA, un même jeton servait à deux bots, et chacun volait les messages de l’autre : créez un bot par agent.

Mémoire et compétences

La mémoire intégrée tient en deux fichiers bornés, réglés dans config.yaml :

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens
  write_approval: false     # true = require approval for memory-tool writes

Ces fichiers sont copiés dans l’invite au début de la session, puis figés. Un fait que l’agent note en cours de route est bien écrit sur le disque, mais il ne le « voit » qu’à la session suivante (/new). Passez write_approval à true si l’agent lit des contenus extérieurs : chaque écriture attend alors votre accord (/memory pending depuis une messagerie).

Les compétences sont des dossiers avec un fichier SKILL.md, au format ouvert d’agentskills.io, rangés dans ~/.hermes/skills/. Hermes en fournit un catalogue et en écrit lui-même quand une méthode a marché.

hermes skills browse                          # parcourir les catalogues
hermes skills inspect official/security/1password
hermes skills install official/mcp/fastmcp
hermes skills check                           # mises à jour disponibles

Deux réglages méritent d’être activés sur un agent exposé :

skills:
  guard_agent_created: true   # analyse les compétences que l'agent écrit
  write_approval: true        # chaque écriture de compétence attend votre accord

Lisez une compétence avant de l’installer, comme un script. --force passe outre certains blocages ; un verdict « dangerous » de l’analyse reste bloquant.

Tâches planifiées

Les tâches tournent dans la passerelle, qui relit toutes les 60 secondes ~/.hermes/cron/jobs.json : sans passerelle lancée, rien ne part. On les crée en phrase ordinaire, en conversation (/cron add) ou en ligne de commande :

hermes cron create "every 2h" "Check server status"
hermes cron create "every 1h" "Summarize new feed items" --skill blogwatcher
hermes cron list
hermes cron status        # le planificateur tourne-t-il ?

Le résultat part par défaut vers la conversation d’origine quand la tâche est créée depuis une messagerie, dans ~/.hermes/cron/output/ quand elle l’est en ligne de commande ; --deliver telegram l’envoie au salon choisi par /sethome. Une tâche planifiée ne peut pas créer d’autres tâches, ce qui évite les boucles.

Pour une simple surveillance, le mode sans agent fait tourner un script sans appeler aucun modèle, donc sans coût : une sortie vide ne déclenche rien, une erreur envoie une alerte.

hermes cron create "every 5m" \
  --no-agent \
  --script memory-watchdog.sh \
  --deliver telegram \
  --name "memory-watchdog"

Le script doit se trouver dans ~/.hermes/scripts/. Préférez ce mécanisme à une ligne de crontab écrite à la main : sur la machine de QUELLE IA, une tâche lancée par le crontab du compte root écrivait son état dans un autre dossier personnel que celui de l’agent, et personne ne s’en est aperçu pendant un mois.

Quel modèle pour les tâches ? À l’heure dite, Hermes prend le modèle fixé pour la tâche, sinon cron.model, sinon le modèle principal du moment. Fixez cron.model sur un modèle bon marché pour que les tâches de fond ne suivent pas vos changements de modèle en conversation.

Brancher des serveurs MCP

Les serveurs MCP se déclarent dans config.yaml, rubrique mcp_servers, ou avec hermes mcp add. Un serveur local se lance par une commande, un serveur distant se joint par son adresse :

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
    tools:
      include: [create_issue, list_issues]

La rubrique tools garde seulement les outils utiles (include) ou retire les dangereux (exclude) : moins d’outils déclarés, c’est aussi une invite plus courte, donc moins chère. Testez un serveur avec hermes mcp test <nom>. Le catalogue de Nous Research (hermes mcp sans argument) installe des serveurs relus, mais l’installation exécute le code du serveur : lisez son manifeste avant.

Validations et permissions

Avant chaque commande, Hermes compare le texte à une liste de motifs dangereux. Le comportement se règle dans la rubrique approvals :

approvals:
  mode: smart                     # smart | manual | off
  timeout: 300
  cron_mode: deny
  single_query_mode: deny
  unattended_mode: deny
  deny:
    - "git push --force*"
    - "dd if=* of=/dev/*"
  • smart (par défaut) fait juger la commande par le modèle auxiliaire : il laisse passer le sans risque, refuse le franchement dangereux et vous demande le reste.
  • manual vous demande toujours. C’est le bon choix tant que vous ne connaissez pas le comportement de votre modèle, surtout un petit modèle local.
  • off ne demande rien, comme --yolo ou /yolo. À réserver à un conteneur jetable.

Sans réponse dans les 300 secondes, la commande est refusée. Les tâches planifiées, les requêtes uniques (hermes chat -q) et les accès par API refusent par défaut toute commande dangereuse, faute de quelqu’un pour répondre. La liste deny bloque ses motifs en toutes circonstances, /yolo compris ; mettez chaque motif entre guillemets, un * en tête casse le YAML sinon. Répondre « always » à une demande ajoute le motif à command_allowlist dans config.yaml : relisez cette liste de temps en temps.

Documentation de Hermes Agent, page Security, section Approval Modes : bloc YAML approvals avec mode smart, timeout 300, cron_mode deny, single_query_mode deny, unattended_mode deny, puis le début du tableau des clés avec leur valeur par défaut.
La rubrique approvals de la page Security : mode smart, délai de 300 secondes, et refus par défaut pour les tâches planifiées, les requêtes uniques et les accès par API (capture du 19 novembre 2026, hermes-agent.nousresearch.com).

Durcir l’installation

La liste de contrôle de la page Security, pour une passerelle qui tourne en permanence :

  1. Des listes d’utilisateurs explicites ; GATEWAY_ALLOW_ALL_USERS=true est à bannir.
  2. Les commandes dans un conteneur : terminal.backend: docker. Par défaut (local), elles tournent directement sur votre machine. Le conteneur de Hermes supprime toutes les capacités, interdit l’élévation de privilèges et limite processeur, mémoire et disque :
terminal:
  backend: docker
  docker_volumes:
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"
  docker_network: true    # false = aucun accès réseau pour les commandes
  container_cpu: 1
  container_memory: 5120
  1. Les secrets protégés : chmod 600 ~/.hermes/.env, et ce fichier reste hors de tout dépôt Git. Les outils d’écriture de fichiers refusent toujours ~/.ssh/, ~/.aws/ ou .env ; HERMES_WRITE_SAFE_ROOT cantonne en plus les écritures à quelques dossiers, à condition d’y inclure ~/.hermes pour que l’agent puisse encore gérer ses tâches et compétences.
  2. Un dossier de travail neutre : terminal.cwd, loin de vos dossiers sensibles.
  3. Jamais en root, et des mises à jour régulières.
  4. Une liste de sites interdits pour la navigation (security.website_blocklist), utile si l’agent tourne sur un réseau où vivent des interfaces d’administration.
  5. Une analyse de la chaîne d’approvisionnement : hermes security audit cherche les failles connues dans les dépendances, les extensions et les serveurs MCP.

Pour isoler davantage, la documentation propose de faire tourner les commandes sur une autre machine par SSH (terminal.backend: ssh, hôte et clé dans .env).

Faire tourner en service

hermes gateway install               # service utilisateur systemd (Linux) ou launchd (macOS)
hermes gateway start
hermes gateway status
journalctl --user -u hermes-gateway -f
sudo loginctl enable-linger $USER    # Linux : le service survit à la déconnexion

Sous macOS, le fichier de service est ~/Library/LaunchAgents/ai.hermes.gateway.plist et le journal ~/.hermes/logs/gateway.log. Sur un serveur sans session ouverte, le service utilisateur avec « linger » démarre au boot et laisse hermes update le redémarrer sans droits root ; sudo hermes gateway install --system installe à la place un service système.

Trois pièges vus en vrai :

  • Deux services, deux dossiers. Un service reste attaché au HERMES_HOME avec lequel il a été installé. Sur la machine de QUELLE IA, un ancien service lisait un autre dossier de configuration que celui qu’on modifiait : hermes gateway status dit lequel tourne, et Hermes avertit quand un service utilisateur et un service système coexistent.
  • Pas de surcharge ExecStopPost qui tue le processus : la documentation prévient qu’elle provoque une boucle de redémarrages, et un message Telegram à chaque fois.
  • Le tableau de bord web (hermes dashboard) : dans la version installée sur la machine de QUELLE IA, il exige un identifiant dès qu’il écoute ailleurs que sur la machine locale. Gardez-le sur l’adresse locale ou un réseau privé, fermé à Internet.

Mettre à jour et sauvegarder

hermes backup                 # archive zip de config, compétences, sessions et données
hermes update                 # passe à la dernière version publiée
hermes gateway restart        # recharge le service mis à jour

hermes update suit par défaut le canal stable : il saute d’une version publiée à la suivante (hermes update --set-channel main pour suivre le développement). hermes backup copie les bases SQLite proprement même pendant que l’agent tourne ; hermes backup --quick ne garde que l’essentiel (config, .env, tâches). Sur une autre machine, hermes import restaure l’archive.

Ce que ça coûte

Hermes est gratuit. Le coût vient du modèle : à chaque appel, Hermes envoie son invite système et la description de tous les outils activés avant votre message. hermes prompt-size mesure ce socle ; désactiver les outils inutiles (hermes tools) et les compétences superflues le réduit d’autant.

La page sur Ollama donne un ordre de grandeur, en dollars : environ 0,80 $ pour une séance de code d’environ 100 000 jetons lus et 20 000 écrits avec Claude Sonnet, contre l’électricité seule en local, de 0,01 à 0,05 $ par séance selon la machine. Les leviers : un modèle auxiliaire bon marché, cron.model pour les tâches de fond, le mode sans agent pour les simples surveillances, et un modèle local avec un secours en ligne.

Les erreurs fréquentes

  • Refus au démarrage à cause du contexte : le serveur local ouvre moins de 64 000 jetons. Réglez le contexte côté serveur et vérifiez avec ollama ps.
  • Le bot ne répond pas : identifiant absent de TELEGRAM_ALLOWED_USERS (le journal dit « No user allowlists configured »), passerelle arrêtée, ou même jeton utilisé par un autre programme.
  • L’agent a « oublié » ce que vous venez de lui dire : la mémoire est figée en début de session. Ouvrez une nouvelle session.
  • Réglage sans effet : il est écrit dans .env alors qu’une valeur de config.yaml l’emporte, ou le service lit un autre HERMES_HOME. hermes config get <clé> montre la valeur résolue.
  • Appairage ignoré sous Docker : la commande a tourné en root. Passez -u hermes à docker exec.
  • Une tâche planifiée « blocked_config » : clé du fournisseur absente ou serveur MCP injoignable pour ce profil. Hermes n’appelle alors aucun modèle et envoie une seule alerte ; hermes cron status et hermes doctor disent pourquoi.

Pour OpenClaw, l’autre agent personnel libre, voyez Bien configurer OpenClaw.

Pour aller plus loin

Sur mini lab AI, un guide du même auteur reprend ce sujet pour monter son atelier d'IA à la maison.

Tous les guides →

Sources

  1. GitHub, NousResearch/hermes-agent (licence MIT, version v0.23.2 du 16 novembre 2026), lue le
  2. Documentation de Hermes Agent, Installation, lue le
  3. Documentation de Hermes Agent, Updating & Uninstalling, lue le
  4. Documentation de Hermes Agent, Configuration, lue le
  5. Documentation de Hermes Agent, Which File Does What, lue le
  6. Documentation de Hermes Agent, Configuring Models, lue le
  7. Documentation de Hermes Agent, AI Providers, lue le
  8. Documentation de Hermes Agent, Run Hermes Locally with Ollama, lue le
  9. Documentation de Hermes Agent, Messaging Gateway, lue le
  10. Documentation de Hermes Agent, Telegram, lue le
  11. Documentation de Hermes Agent, Persistent Memory, lue le
  12. Documentation de Hermes Agent, Skills System, lue le
  13. Documentation de Hermes Agent, Scheduled Tasks (Cron), lue le
  14. Documentation de Hermes Agent, MCP, lue le
  15. Documentation de Hermes Agent, Security, lue le
  16. Documentation de Hermes Agent, CLI Commands Reference, lue le