Hermes Agent : la référence du praticien (2026)

TL;DR : Hermes Agent est un agent IA open source auto-améliorant de Nous Research. Il fonctionne comme une CLI et comme un gateway de messagerie multiplateforme, stocke une identité durable et une mémoire persistante sur disque, agrège des skills qui s’améliorent avec l’usage, et fonctionne avec n’importe quel fournisseur LLM compatible OpenAI — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Qwen Cloud, Hugging Face, Google, xAI/SuperGrok, ou votre propre endpoint auto-hébergé.¹²¹⁹ Depuis la v0.14.0 (16 mai 2026), Hermes ajoute SuperGrok OAuth avec un contexte grok-4.3 1M, un proxy local compatible OpenAI pour les fournisseurs OAuth (hermes proxy), x_search en prise en charge native, l’installation via PyPI, l’installation paresseuse des dépendances, 22 plateformes de messagerie avec LINE et SimpleX Chat, /handoff, les diagnostics sémantiques LSP après écriture, video_generate unifié, computer_use via cua-driver pour les fournisseurs non-Anthropic, une bêta Windows native, ainsi que la clôture de 12 P0 / 50 P1.¹⁹ La partie la plus difficile pour la plupart des nouveaux utilisateurs est l’authentification auprès des fournisseurs : Hermes prend en charge environ 20 fournisseurs natifs plus des endpoints personnalisés, et trois chemins d’authentification distincts (clé API dans .env, OAuth via hermes model, ou endpoint personnalisé dans config.yaml). Le modèle d’authentification est la première chose à apprendre : tout le reste dépend du fournisseur résolu.

Hermes Agent fonctionne comme un runtime d’agent complet, pas comme une simple surcouche de chat. Il lit votre système de fichiers, exécute des commandes dans des backends sandboxés, extrait des données du web, lance des subagents, exécute des tâches cron planifiées, parle à Telegram/Discord/Slack/WhatsApp/Signal/Email depuis un processus gateway unique, et crée ses propres skills à partir de l’expérience.¹ La CLI est une interface terminal construite au-dessus d’une boucle de conversation dans run_agent.py ; le gateway est un processus longue durée qui route les messages des plateformes de messagerie vers cette même boucle de conversation.³

La différence entre un usage occasionnel et un usage expert de Hermes tient à cinq systèmes. Maîtrisez-les et Hermes devient un multiplicateur de force :

1. Résolution des fournisseurs : comment les flux d’authentification correspondent aux appels API
2. Hiérarchie de configuration : config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. Système Tool + toolset : ce que l’agent peut faire, contrôlé par plateforme
4. Système de skills : mémoire procédurale que l’agent crée et fait évoluer
5. Gateway + cron + profiles : exécuter Hermes là où vous vivez, pas seulement là où vous vous trouvez

Points clés

• L’authentification des fournisseurs suit trois chemins, pas un seul. Clé API dans .env, OAuth via hermes model/hermes auth, ou endpoint personnalisé dans config.yaml. Choisissez le chemin qui correspond à votre fournisseur, pas celui qui vous semble familier.
• Changer de fournisseur se fait avec une seule commande. hermes model vous guide de manière interactive à travers chaque fournisseur pris en charge, y compris les connexions OAuth, et /model provider:model change de modèle en cours de session sans perdre l’historique.²
• Deux fichiers constituent la surface de configuration modifiable par l’utilisateur. ~/.hermes/config.yaml contient les paramètres et ~/.hermes/.env contient les secrets. auth.json, SOUL.md, MEMORY.md et skills/ sont gérés directement par Hermes — vous pouvez modifier SOUL.md à la main, mais le reste est manipulé par l’agent lui-même.⁴
• Hermes est le successeur de OpenClaw. Si vous migrez, hermes claw migrate importe automatiquement plus de 30 catégories d’état.⁵
• La qualité de service dépend de votre modèle auxiliaire. Vision, résumé web, compression et vidage de mémoire utilisent tous un LLM auxiliaire distinct. Par défaut, il s’agit de Gemini Flash via auto-détection (OpenRouter → Nous → Codex) — si aucun de ces fournisseurs n’est configuré, ces fonctionnalités se dégradent silencieusement jusqu’à ce que vous pointiez les emplacements auxiliaires vers votre fournisseur principal.⁴

Ce que change la v0.14

La v0.14.0 concerne moins une fonctionnalité phare qu’une réduction des frictions de configuration, tout en élargissant les environnements où Hermes peut fonctionner.¹⁹ Les principaux changements opérationnels :

• L’installation et le démarrage sont plus légers. pip install hermes-agent fonctionne depuis PyPI, les adaptateurs lourds s’installent paresseusement à la première utilisation, et le chemin de lancement diffère assez de travail pour réduire le démarrage à froid d’environ 19 secondes.
• Les abonnements peuvent devenir des endpoints API locaux. hermes proxy transforme les fournisseurs adossés à OAuth, comme Claude Pro, ChatGPT Pro et SuperGrok, en endpoint local compatible OpenAI pour des outils comme Codex, Aider, Cline et Continue.
• La portée du gateway s’étend. LINE et SimpleX Chat portent le nombre de plateformes à 22, Microsoft Teams est câblé de bout en bout, le backfill de l’historique Discord est activé par défaut, et les prompts clarify Telegram/Discord utilisent désormais des boutons natifs.
• La vérification au moment de l’écriture progresse. Après les modifications, Hermes peut afficher des résumés de mutations de fichiers par tour et des diagnostics sémantiques de serveur de langage avant le tour suivant, ce qui le rapproche d’un travail d’agent fondé sur les preuves.
• Les outils desktop et média s’élargissent. computer_use fonctionne via cua-driver pour les fournisseurs non-Anthropic, video_generate est unifié derrière des backends enfichables, et vision_analyze envoie les pixels bruts aux modèles qui peuvent réellement voir.

Chaque section ci-dessous s’appuie sur la documentation upstream à l’adresse hermes-agent.nousresearch.com/docs et sur l’arborescence source à l’adresse github.com/NousResearch/hermes-agent. Chaque affirmation factuelle comporte une note de bas de page pointant vers la page upstream précise dont elle provient.

Choisissez votre chemin

Fonctionnement de Hermes : le modèle mental

Hermes est structuré autour d’une boucle de conversation unique que tout point d’entrée peut invoquer. Les points d’entrée sont le CLI (cli.py), le gateway de messagerie (gateway/run.py), l’adaptateur ACP pour l’intégration dans l’éditeur, le batch runner et un serveur API.³ Tous appellent au final AIAgent.run_conversation() dans run_agent.py, qui :

1. Construit le prompt système à partir de SOUL.md, MEMORY.md, USER.md, des skills, des fichiers de contexte et des consignes d’outils via prompt_builder.py³
2. Résout le provider d’exécution via runtime_provider.py — c’est l’étape qui choisit votre auth, l’URL de base et le mode API³
3. Appelle le provider avec l’un des trois modes API : chat_completions, codex_responses ou anthropic_messages³
4. Transmet tous les appels d’outils renvoyés via model_tools.py et le registre central des outils (tools/registry.py)³
5. Boucle jusqu’à ce que le modèle produise une réponse finale, puis persiste la session dans SQLite avec FTS5³

Comprendre cette boucle est essentiel, car chaque fonctionnalité — personnalités, mémoire, skills, compression, fallback — se rattache à l’une de ces étapes. Quand vous lisez une clé de config en vous demandant ce qu’elle fait, la réponse est généralement : « c’est un réglage de l’étape 1, 2, 3 ou 4 de la boucle ci-dessus ».

Noyau indépendant de la plateforme. Une seule classe AIAgent sert le CLI, le gateway, ACP, le batch et le serveur API. Les différences de plateforme résident dans le point d’entrée, pas dans l’agent lui-même.³ C’est pourquoi les mêmes slash commands fonctionnent dans le terminal et dans Telegram : elles sont dispatchées depuis un COMMAND_REGISTRY partagé dans hermes_cli/commands.py.⁶

La structure des dossiers est le système. Hermes stocke tout sous ~/.hermes/ (ou $HERMES_HOME pour les profils non par défaut) :⁴

~/.hermes/
├── config.yaml        # Settings (model, terminal, TTS, compression, etc.)
├── .env               # API keys and secrets
├── auth.json          # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md            # Primary agent identity (slot #1 in system prompt)
├── memories/          # Persistent memory (MEMORY.md, USER.md)
├── skills/            # Bundled + agent-created + hub-installed skills
├── cron/              # Scheduled jobs
├── sessions/          # Gateway session state
└── logs/              # agent.log, gateway.log, errors.log (secrets auto-redacted)

Chaque fichier ci-dessus a un rôle précis ; aucun ne se recoupe. Si vous cherchez « où Hermes stocke X », c’est dans l’un de ceux-là.

Nouveautés de v0.18.0 (The Judgment Release)

Hermes Agent v0.18.0 (tag v2026.7.1, 1 juillet 2026) doit son nom au jugement : l’agent vérifie son propre travail au lieu d’affirmer sa réussite, et le raisonnement d’ensemble devient réellement inspectable. Cette version clôt aussi tout le backlog P0/P1 — environ 692 éléments de priorité maximale résolus en douze jours.²²

• Mixture-of-Agents comme modèle de première classe. MoA peut désormais être sélectionné comme n’importe quel autre modèle dans toutes les interfaces, et le raisonnement d’ensemble est visible : la sortie complète de chaque modèle de référence s’affiche dans son propre bloc libellé, avec streaming en direct de la réponse — vous pouvez regarder l’ensemble réfléchir au lieu de recevoir une réponse fusionnée opaque.²²
• Contrats d’achèvement pour /goal. L’agent vérifie son propre travail en lançant les checks du projet avant de signaler qu’un objectif est terminé, plutôt que de revendiquer un succès — le jugement appliqué à lui-même.²²
• /learn — transformer n’importe quelle description en skill. Transformez un workflow en skill réutilisable en le décrivant ; les skills générés respectent automatiquement les conventions CONTRIBUTING.md du repo.²²
• Timeline /journey. Un historique visuel de la mémoire et des skills dans le temps, avec édition, plus un graphe de mémoire sur desktop.²²
• Diffusion de subagents en arrière-plan. Déléguez plusieurs tâches qui s’exécutent simultanément sans bloquer la conversation — le subagent unique en arrière-plan de v0.17.0 devient une flotte.²²
• Desktop Projects. Des Projects de codage de première classe avec un modèle d’organisation projet/repo/lane.²²
• Gateway scale-to-zero. Les gateways peuvent se mettre en veille lorsqu’ils sont inactifs et coordonner les drains pour des déploiements fluides — utile pour toute personne qui exécute Hermes comme service toujours actif.²²
• Prise en charge de Google Vertex AI. Accès à Gemini via des comptes de service GCP avec rafraîchissement automatique des tokens OAuth2, qui rejoint le catalogue des providers.²²
• Commande d’édition /prompt. Ouvre $EDITOR pour composer des prompts multiligne au lieu de lutter avec la ligne de saisie.²²

Si vous mettez à niveau depuis v0.17.x, rien ici ne casse le CLI. Les principales raisons de passer à cette version sont les contrats d’achèvement (des objectifs qui se vérifient eux-mêmes), MoA de première classe avec ensembles inspectables, et /learn pour capturer des skills.

Nouveautés de v0.17.0 (The Reach Release)

Hermes Agent v0.17.0 (tag v2026.6.19, 19 juin 2026) doit son nom à l’étendue que l’agent atteint désormais — nouveaux canaux de messagerie, nouveaux providers de modèles, et contrôle plus approfondi du desktop et du dashboard. Elle s’ajoute à v0.16.x ; la surface CLI reste inchangée.²¹

• Nouveaux canaux de messagerie. iMessage fonctionne désormais sans relais Mac via Photon Spectrum (device-code OAuth, hermes photon login) ; la API WhatsApp Business Cloud est un adaptateur Meta officiel qui remplace l’obligation d’un processus bridge ; SimpleX gagne les groupes, les pièces jointes natives, le regroupement de texte et l’acceptation automatique ; et Raft arrive comme plugin de plateforme intégré avec une conception de wake-channel privacy-by-contract.²¹
• Nouveaux modèles et providers. Le catalogue ajoute z-ai/glm-5.2 (contexte 1M), anthropic/claude-fable-5, laguna-m.1, nemotron-3-ultra et grok-composer-2.5-fast (le modèle de Cursor via OAuth xAI, contexte 200k). Le modèle xAI par défaut passe à grok-build-0.1, et les modèles adaptatifs Anthropic suivent désormais le contrat de réflexion moderne (ils n’envoient jamais de champ reasoning).²¹
• Desktop et dashboard. Desktop ajoute des subagents en arrière-plan avec streaming en direct via des « watch-windows » de l’activité déléguée (delegate_task(background=true)), un sélecteur de modèle Composer, des raccourcis clavier réassignables, des notifications OS natives, des brouillons de composer par thread, des thèmes VS Code Marketplace, ainsi qu’une interface en japonais et chinois traditionnel. Le dashboard ajoute un constructeur de profil complet (modèle/skills/MCPs sans modifier config.yaml), un sélecteur de profil global, un Skills Hub remanié avec scan de sécurité, des Automation Blueprints (templates paramétrés couvrant formulaire, slash command, conversation et docs), et une connexion sécurisée qui renvoie 401 derrière la barrière OAuth.²¹
• Skills et outils. image_generate peut désormais éditer et transformer une image source, pas seulement en créer une de zéro, sur chaque provider d’image pris en charge ; l’outil memory gagne un tableau operations pour l’ajout/le remplacement/la suppression atomiques en lot dans un seul appel ; un nouveau skill simplify-code lance une passe parallèle de revue et nettoyage par trois agents, encadrée par un niveau de risque de type Chesterton’s-Fence ; et un booléen write_approval remplace le write_mode à trois états.²¹
• Architecture. Les subagents en arrière-plan renvoient immédiatement un handle et réinjectent leur résultat comme nouveau tour ; un gestionnaire d’élicitation MCP permet une confirmation au milieu d’un appel d’outil, et les outils MCP à connexion tardive sont exposés entre les tours (cache-safe) ; cron devient un CronScheduler enfichable avec un provider Chronos managed-cron ; et un nouveau scope Managed (/etc/hermes) permet à un administrateur d’épingler une config immuable pour l’utilisateur, avec en plus un relais Gateway-Gateway pour les topologies multi-gateway.²¹
• Nouvelles commandes. /version, /billing (facturation interactive dans le terminal), hermes photon login (auth iMessage) et hermes curator run --consolidate — la consolidation est désormais opt-in, ce qui fait que la curation de routine en arrière-plan ne coûte aucun token.²¹
• Sécurité. v0.17.0 ferme un contournement de denylist par shell-escape, échoue de manière fermée en cas de modules d’approbation manquants et d’adaptateurs de gateway own-policy, assainit l’environnement pour les subprocesses de scripts de jobs cron, masque les secrets dans les dumps de debug de requêtes, analyse les configs stdio MCP à la recherche de motifs d’exfiltration, et met à jour urllib3 et PyJWT pour corriger des CVE.²¹

Si vous mettez à niveau depuis v0.16.x, rien ici ne casse le CLI ; il s’agit de nouveaux canaux, modèles et surfaces autour du même agent. iMessage sans relais, les adaptateurs WhatsApp officiels et le scope Managed administrateur sont les principales raisons de passer à cette version.

Nouveautés de la v0.16.0 (The Surface Release)

Hermes Agent v0.16.0 (tag v2026.6.5, 5 juin 2026) doit son nom aux nouvelles surfaces qu’elle place devant l’agent CLI-first. Le point essentiel : Hermes n’est plus limité au terminal.²⁰

• Application desktop native. Hermes Desktop est une nouvelle application Electron pour macOS, Linux et Windows, avec installation en un clic et mise à jour automatique intégrée. Elle vous donne une fenêtre de chat en streaming, le glisser-déposer de fichiers, le collage d’images depuis le presse-papiers, une palette Cmd+K, une liste de sessions avec archivage et recherche, ainsi qu’un sélecteur de modèle dans la barre d’état. Elle peut se connecter à un gateway Hermes distant via un WebSocket sécurisé, avec authentification par OAuth ou nom d’utilisateur/mot de passe, des hôtes distants par profile et des sessions multi-profile simultanées reliées par des références @session inter-profile. L’interface desktop inclut aussi une traduction complète en chinois simplifié (简体中文) via une couche i18n typée (display.language ; l’anglais reste la langue par défaut).²⁰
• Panneau d’administration dans le navigateur. Le dashboard web local est passé d’une vue d’état à un panneau d’administration complet : catalogue MCP avec bascules d’activation/désactivation, gestion des identifiants, création de webhooks et de hooks, configuration de la mémoire, contrôles de gateway, et page System avec vérification avant mise à jour plus Debug Share en un clic. Une nouvelle page Channels configure depuis le navigateur toutes les plateformes de messagerie gateway (Telegram, Discord, Slack et les autres). L’authentification est désormais modulaire : connexion par nom d’utilisateur/mot de passe, fournisseur OIDC auto-hébergé générique, hermes dashboard register pour un client OAuth auto-hébergé, et rotation des sessions par refresh-token.²⁰
• Nouveaux CLI et nouvelles commandes slash. /undo [N] sauvegarde les N derniers tours utilisateur avec préremplissage et suppression douce, et fonctionne dans le CLI, le TUI et sur les plateformes de messagerie. Une interface par défaut configurable (cli ou tui) arrive avec une option de remplacement --cli ; le TUI reçoit une commande /model unifiée et une surcouche Sessions. hermes portal est un alias lisible pour le flux d’onboarding Nous Portal, avec de nouveaux parcours de première exécution Quick Setup et Full Setup, et deux diagnostics arrivent : hermes prompt-size et hermes sessions optimize.²⁰
• Nouveaux modèles et providers. Le sélecteur ajoute deepseek-v4-flash, MiniMax-M3 (contexte 1M, providers MiniMax natifs), qwen3.7-plus (Nous + OpenRouter) et gemini-3.5-flash (Gemini OAuth + clé API). Un provider xAI Grok OAuth de premier rang rejoint le lanceur desktop, le sélecteur de modèles devient fuzzy sur toutes les surfaces, les providers multi-endpoint sont regroupés sur une seule ligne, et l’actualisation du catalogue passe d’une fréquence quotidienne à horaire.²⁰
• Skills allégés et divulgation progressive. Le jeu de skills par défaut a supprimé les skills redondants et morts (Spotify est passé à un plugin natif, Linear à hermes mcp install linear, et plusieurs entrées obsolètes ont été retirées), a déplacé davantage d’éléments dans les options, et a ajouté une barrière de pertinence en frontmatter environments: (kanban/docker/s6) qui garde les skills propres à un contexte hors de l’index jusqu’à ce qu’ils soient demandés. NVIDIA/skills est désormais un tap Skills Hub de confiance par défaut aux côtés d’OpenAI, Anthropic et HuggingFace. MCP et les outils de plugin ont reçu une divulgation progressive (à périmètre limité) des outils, et un bug MCP qui signalait à tort un succès OAuth alors qu’aucun token n’avait été obtenu est corrigé.²⁰
• Sécurité. v0.16.0 épingle Starlette corrigé (≥1.0.1) pour CVE-2026-48710 (BadHost), déplace les vérifications d’URL SSRF hors de l’event loop dans les chemins async, retire le bearer token d’inférence Bedrock de l’environnement des sous-processus, ajoute bws_cache.json au garde-fou de lecture file-safety, ajoute docker restart/stop/kill à la liste des motifs dangereux, et assainit l’unicode invisible dans le contenu de skills vérifié. La release a clôturé 2 problèmes P0 et 62 problèmes P1, dont 16 marqués sécurité.²⁰

Si vous mettez à niveau depuis v0.15.x, rien de tout cela ne constitue un changement cassant pour le CLI lui-même ; ce sont des surfaces et providers ajoutés autour du même agent. L’application desktop et le panneau d’administration sont la raison de mettre à niveau si vous voulez exécuter Hermes pour des utilisateurs hors terminal ou administrer un gateway distant depuis un navigateur.

Installation

L’installateur en une ligne reste le parcours guidé pour la plupart des utilisateurs. Il prend en charge Python, uv, Node.js, ripgrep, ffmpeg, le clone du repo, l’environnement virtuel et la commande globale hermes.⁷ v0.14.0 fournit aussi un vrai package PyPI, donc pip install hermes-agent est désormais une installation directe viable lorsque vous contrôlez déjà l’environnement Python.¹⁹

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

pip install hermes-agent
hermes

Fonctionne sur Linux, macOS, WSL2 et Android/Termux (l’installateur détecte automatiquement Termux et bascule vers un bundle Android testé).⁷ v0.14.0 ajoute la prise en charge native de Windows en bêta précoce via un installateur PowerShell, mais WSL2 reste la recommandation la plus sûre pour un usage en production tant que le parcours Windows n’a pas mûri.¹⁹

Une fois terminé :

source ~/.bashrc    # or ~/.zshrc
hermes              # Start chatting

Le seul prérequis est git. L’installateur provisionne automatiquement Python 3.11 via uv (sans sudo), Node.js v22 (pour l’automatisation de navigateur et le bridge WhatsApp), ripgrep et ffmpeg.⁷

Vérifier l’installation

hermes version      # Check version
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

hermes doctor vous indique exactement ce qui manque et comment le corriger.⁷ hermes dump est la commande de diagnostic à coller dans une issue GitHub ou un fil Discord lorsque vous demandez de l’aide : c’est un résumé en texte brut de toute votre configuration, avec les secrets masqués.⁸

Installation manuelle

Si vous avez besoin d’un contrôle total — version Python personnalisée, extras spécifiques, intégration Nix/NixOS — le flux manuel est documenté étape par étape dans le guide d’installation upstream.⁷ Principaux extras optionnels que vous pouvez combiner avec uv pip install -e ".[<extras>]" :

La commande d’installation Termux est différente — elle utilise pip avec un fichier de contraintes, pas uv pip :

python -m pip install -e ".[termux]" -c constraints-termux.txt

C’est parce que .[all] sur Android récupère faster-whisper via l’extra voice, qui dépend de roues ctranslate2 non publiées pour Android.⁷

Authentification et providers

Hermes prend en charge environ 19 providers de premier ordre, ainsi que des endpoints personnalisés, et trois parcours d’authentification distincts. Voici toute la surface d’authentification, organisée par parcours afin que vous puissiez trouver celui qui correspond à ce que vous avez.

Les trois parcours d’authentification

Chaque provider dans Hermes suit l’un de ces trois modèles d’authentification :

Parcours 1 — clé API dans .env. Placez votre clé dans ~/.hermes/.env et Hermes la lit au démarrage. Utilisé par OpenRouter, AI Gateway, z.ai/GLM, Kimi/Moonshot, MiniMax (et MiniMax China), Alibaba Cloud/DashScope, Kilo Code, OpenCode Zen, OpenCode Go, DeepSeek, Hugging Face, Google/Gemini et la plupart des providers tiers.²

Parcours 2 — OAuth via hermes model ou hermes auth. Lance un flux avec code d’appareil, ouvre un navigateur, stocke les identifiants dans ~/.hermes/auth.json (et peut importer des identifiants existants depuis des outils comme Claude Code ou Codex CLI). Utilisé par Nous Portal, OpenAI Codex (compte ChatGPT), GitHub Copilot et Anthropic (Claude Pro/Max).²

Parcours 3 — endpoint personnalisé dans config.yaml. Pour tout API compatible OpenAI : Ollama, vLLM, SGLang, llama.cpp, LM Studio, proxy LiteLLM, Together AI, Groq, Azure OpenAI ou votre propre serveur auto-hébergé. Configuré une fois via hermes model → Custom endpoint, puis conservé dans config.yaml.²

La matrice complète des providers

Voici la liste complète des providers de premier ordre, avec le flux de configuration exact pour chacun.²

Anthropic : trois méthodes d’authentification

Anthropic dispose de sa propre section, car Hermes prend en charge trois parcours distincts vers Claude, et le bon choix compte. D’après la documentation upstream :²

# Method 1: API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Method 2: OAuth through hermes model (preferred)
# Uses Claude Code's credential store when available
hermes model

# Method 3: Manual setup-token (fallback/legacy)
export ANTHROPIC_TOKEN=***
hermes chat --provider anthropic

# Auto-detect Claude Code credentials
hermes chat --provider anthropic   # reads Claude Code files automatically

Lorsque vous choisissez OAuth Anthropic via hermes model, Hermes préfère le magasin d’identifiants propre à Claude Code plutôt que de copier le token dans ~/.hermes/.env. Les identifiants Claude renouvelables restent ainsi renouvelables.² Si vous utilisez déjà Claude Code sur la même machine, c’est le parcours le plus propre.

Pour épingler Anthropic de façon permanente dans config.yaml :

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

--provider claude et --provider claude-code fonctionnent aussi comme raccourcis pour --provider anthropic.²

GitHub Copilot : deux modes

Copilot est pris en charge dans deux modes : API Copilot direct (recommandé) et Copilot ACP (qui lance le CLI Copilot local comme sous-processus).²

# Direct Copilot API
hermes chat --provider copilot --model gpt-5.4

# Copilot ACP (requires the Copilot CLI in PATH + an existing copilot login)
hermes chat --provider copilot-acp --model copilot-acp

L’authentification est vérifiée dans cet ordre, d’après la documentation upstream :² 1. Variable d’environnement COPILOT_GITHUB_TOKEN 2. Variable d’environnement GH_TOKEN 3. Variable d’environnement GITHUB_TOKEN 4. Repli sur le CLI gh auth token 5. Connexion par code d’appareil OAuth via hermes model

Le type de token compte. Le API Copilot ne prend pas en charge les Personal Access Tokens classiques (ghp_*). Les types pris en charge sont les tokens OAuth (gho_*), les PAT à granularité fine (github_pat_* avec l’autorisation Copilot Requests) et les tokens d’app GitHub (ghu_*). Si votre gh auth token renvoie un token ghp_*, utilisez plutôt hermes model pour vous authentifier via OAuth.²

Providers IA chinois (prise en charge de premier ordre)

Hermes intègre la prise en charge de z.ai/GLM, Kimi/Moonshot, MiniMax (endpoints global + Chine) et Alibaba Cloud avec des IDs de provider dédiés.²

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5                 # Requires: GLM_API_KEY

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding   # Requires: KIMI_API_KEY

# MiniMax (global)
hermes chat --provider minimax --model MiniMax-M2.7          # Requires: MINIMAX_API_KEY

# MiniMax (China)
hermes chat --provider minimax-cn --model MiniMax-M2.7       # Requires: MINIMAX_CN_API_KEY

# Alibaba Cloud / DashScope (Qwen)
hermes chat --provider alibaba --model qwen3.5-plus          # Requires: DASHSCOPE_API_KEY

Les URL de base peuvent être remplacées avec les variables d’environnement GLM_BASE_URL, KIMI_BASE_URL, MINIMAX_BASE_URL, MINIMAX_CN_BASE_URL ou DASHSCOPE_BASE_URL.²

Z.AI détecte automatiquement l’endpoint. Lorsque vous utilisez le provider z.ai/GLM, Hermes sonde plusieurs endpoints (global, Chine, variantes coding) afin de trouver celui qui accepte votre clé API. L’endpoint fonctionnel est mis en cache automatiquement — aucun GLM_BASE_URL n’est nécessaire pour la plupart des utilisateurs.²

xAI (Grok) active automatiquement le cache des prompts. Lorsque l’URL de base contient x.ai, Hermes envoie l’en-tête x-grok-conv-id avec chaque requête pour router vers le même serveur au sein d’une session de conversation, en réutilisant les prompts système et l’historique mis en cache.² C’est automatique ; aucune configuration n’est requise.

La commande hermes auth

hermes auth est la commande de gestion des identifiants pour les pools et les identifiants OAuth.⁶

hermes auth                              # Interactive wizard
hermes auth list                         # Show all credential pools
hermes auth list openrouter              # Show one provider's pool
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth
hermes auth remove openrouter 2          # Remove by index
hermes auth reset openrouter             # Clear cooldowns

Les pools d’identifiants servent à faire tourner plusieurs clés API ou tokens OAuth pour un même provider — utile pour répartir les limites de débit entre plusieurs clés sans changer le code.⁶ Les anciennes commandes hermes login / hermes logout ont été supprimées ; utilisez hermes auth à la place.⁶

Endpoints personnalisés et auto-hébergés

Hermes fonctionne avec tout endpoint API compatible OpenAI. Si un serveur implémente /v1/chat/completions, vous pouvez y connecter Hermes.²

Configuration interactive (recommandée) :

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

config.yaml manuel :

model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

Les deux approches persistent dans config.yaml, qui est la source de vérité unique pour le modèle principal, le provider et l’URL de base.² Les anciennes variables d’environnement OPENAI_BASE_URL et LLM_MODEL ne sont plus lues pour la configuration du modèle principal — utilisez hermes model ou modifiez directement config.yaml.² (OPENAI_BASE_URL + OPENAI_API_KEY restent honorées comme repli pour le chemin de routage auxiliaire provider: "main", donc ne les supprimez pas à l’aveugle si vous les utilisez là.)⁴

Changer d’endpoint personnalisé en cours de session :

/model custom:qwen-2.5             # Custom endpoint with explicit model
/model custom                      # Auto-detect the model from the endpoint
/model custom:local:qwen-2.5       # Named custom provider "local"
/model custom:work:llama3          # Named custom provider "work"
/model openrouter:claude-sonnet-4  # Back to a cloud provider

/model custom (seul, sans nom de modèle) interroge le API /v1/models de votre endpoint et sélectionne automatiquement le modèle si un seul est chargé — utile pour les serveurs locaux exécutant un seul modèle.²

Serveurs LLM locaux (templates de configuration)

La documentation upstream contient des guides complets pour Ollama, vLLM, SGLang, llama.cpp et LM Studio. Voici les commandes clés que vous exécuterez réellement. Chacune est conçue pour produire un endpoint fonctionnel vers lequel Hermes peut pointer.²

Ollama — le parcours local le plus simple, sans configuration :

ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # Raise from 4k default
hermes model   # Custom endpoint → http://localhost:11434/v1 → qwen2.5-coder:32b

Piège critique avec Ollama : Ollama utilise par défaut des longueurs de contexte très faibles (4 096 tokens sous 24GB de VRAM). Vous devez les augmenter via OLLAMA_CONTEXT_LENGTH ou un Modelfile — le API compatible OpenAI n’accepte pas la longueur de contexte depuis le client, donc Hermes ne peut pas la définir pour vous.² Pour un usage agent, définissez au moins 16k–32k.

vLLM — service GPU haute performance :

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

L’appel d’outils nécessite --enable-auto-tool-choice et --tool-call-parser <name>. Parseurs pris en charge : hermes (Qwen 2.5, Hermes 2/3), llama3_json, mistral, deepseek_v3, deepseek_v31, xlam, pythonic. Sans ces flags, les appels d’outils reviendront comme du texte brut.²

SGLang — service rapide avec RadixAttention pour la réutilisation du cache KV :

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

Piège avec SGLang : la valeur par défaut de max_tokens est 128. Définissez --default-max-tokens sur le serveur ou configurez model.max_tokens dans config.yaml si les réponses sont tronquées.²

llama.cpp / llama-server — CPU et Apple Silicon Metal :

./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

--jinja est obligatoire pour l’appel d’outils. Sans lui, llama-server ignore entièrement le paramètre tools et le modèle tente d’appeler les outils en écrivant JSON dans le texte de sa réponse — ce que Hermes ne peut pas analyser comme de véritables appels d’outils.²

LM Studio — application desktop avec GUI :

Démarrez le serveur depuis l’app LM Studio (onglet Developer → Start Server), ou via CLI : lms server start (démarre sur le port 1234) et lms load qwen2.5-coder --context-length 32768.² Pointez ensuite hermes model vers http://localhost:1234/v1.

Piège critique avec LM Studio : LM Studio lit la longueur de contexte depuis les métadonnées du modèle, mais de nombreux modèles GGUF indiquent des valeurs par défaut de 2048 ou 4096. Définissez toujours explicitement la longueur de contexte dans les paramètres du modèle LM Studio — cliquez sur l’icône d’engrenage à côté du sélecteur de modèle, réglez “Context Length” sur au moins 16384 (de préférence 32768), puis rechargez le modèle.²

Providers personnalisés nommés

Si vous travaillez avec plusieurs endpoints personnalisés (un serveur de développement local et un serveur GPU distant, par exemple), définissez-les comme providers personnalisés nommés dans config.yaml :²

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions      # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages    # for Anthropic-compatible proxies

Passez ensuite de l’un à l’autre en cours de session avec la syntaxe triple :

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4

Vous pouvez aussi sélectionner les providers personnalisés nommés depuis le menu interactif hermes model.²

Architecture de providers enfichable (v0.13.0+)

v0.13.0 livre une ABC ProviderProfile ainsi qu’un dossier plugins/model-providers/, afin que des providers d’inférence tiers puissent s’intégrer sans modifier le cœur.¹⁸ Si un provider parle un mode API compatible OpenAI, Anthropic ou Codex, vous pouvez implémenter une sous-classe ProviderProfile qui déclare le parcours d’authentification, l’URL de base, le catalogue de modèles et les en-têtes de cache ; Hermes la résout via le même chemin runtime_provider.py que les providers intégrés. C’est le changement architectural derrière l’expansion des providers en v0.13.0 : au lieu de modifier le code cœur pour ajouter un provider, vous livrez un plugin.

Proxy local compatible OpenAI (v0.14.0+)

hermes proxy expose un endpoint local compatible OpenAI adossé au provider OAuth auquel Hermes est déjà connecté — Claude Pro, ChatGPT Pro, SuperGrok ou un autre provider compatible configuré.¹⁹ Cela signifie que les outils qui attendent un API de style OpenAI, notamment Codex CLI, Aider, Cline, Continue ou des scripts personnalisés, peuvent réutiliser votre authentification Hermes adossée à un abonnement sans clé API séparée. Traitez le proxy comme une infrastructure de développement locale : liez-le intentionnellement, ne l’exposez pas largement et gardez à l’esprit les conditions propres à chaque provider.

Détection de la longueur de contexte

Deux paramètres sont constamment confondus, d’après la documentation upstream :²

• context_length — la fenêtre de contexte totale (budget combiné de tokens d’entrée + sortie, par exemple 1 000 000 pour Claude Opus 4.7 ou 200 000 pour Sonnet 4.6). Hermes l’utilise pour décider quand compresser l’historique.
• model.max_tokens — le plafond de sortie (nombre maximal de tokens que le modèle peut générer dans une seule réponse). Sans rapport avec la longueur de l’historique.

Définissez context_length lorsque l’auto-détection se trompe sur la taille de la fenêtre :

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072      # tokens

Hermes utilise une chaîne de résolution multi-source pour détecter les fenêtres de contexte : override de configuration → provider personnalisé par modèle → cache persistant → /models de l’endpoint → /v1/models Anthropic → API OpenRouter → Nous Portal → models.dev (registre maintenu par la communauté pour plus de 3800 modèles) → valeurs de repli par défaut (128K).² Le système tient compte du provider, de sorte qu’un même modèle peut avoir des limites de contexte différentes selon celui qui le sert (par exemple, claude-opus-4.6 est à 1M sur Anthropic direct, mais à 128K sur GitHub Copilot).²

Rotation des providers et repli

Pools d’identifiants. Lorsque vous avez plusieurs clés API pour un même provider, configurez une stratégie de rotation via hermes auth. C’est ainsi que vous répartissez les limites de débit entre plusieurs clés.⁶

Modèle de repli. Configurez un provider:model de secours vers lequel Hermes bascule automatiquement lorsque votre modèle principal échoue (limites de débit, erreurs serveur, échecs d’authentification) :²

fallback_model:
  provider: openrouter            # required
  model: anthropic/claude-sonnet-4  # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name

Le repli remplace le modèle et le provider en cours de session sans perdre votre conversation. Il se déclenche au maximum une fois par session.² Providers pris en charge pour le repli : openrouter, nous, openai-codex, copilot, copilot-acp, anthropic, huggingface, zai, kimi-coding, minimax, minimax-cn, deepseek, ai-gateway, opencode-zen, opencode-go, kilocode, alibaba, custom.²

Modèles auxiliaires

Hermes utilise des modèles « auxiliaires » légers pour les tâches annexes : analyse d’image, résumé de pages web, analyse de captures d’écran de navigateur, classification d’approbation de commandes dangereuses, compression du contexte, résumé de recherche de session, correspondance de skill, répartition d’outils MCP et vidage de mémoire.⁴ Par défaut, ces tâches utilisent Gemini Flash via auto-détection (OpenRouter → Nous → Codex).

Vous pouvez configurer le modèle et le provider utilisés par chaque tâche auxiliaire. Chaque slot auxiliaire utilise les trois mêmes réglages : provider, model, base_url.⁴

auxiliary:
  vision:
    provider: "auto"                # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                       # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""                    # Custom OpenAI-compatible endpoint
    api_key: ""                     # Falls back to OPENAI_API_KEY
    timeout: 30
    download_timeout: 30
  web_extract:
    provider: "auto"
    model: ""
    timeout: 360
  approval:
    provider: "auto"
    model: ""
    timeout: 30
  compression:
    timeout: 120
  session_search: { provider: "auto", model: "", timeout: 30 }
  skills_hub:    { provider: "auto", model: "", timeout: 30 }
  mcp:           { provider: "auto", model: "", timeout: 30 }
  flush_memories:{ provider: "auto", model: "", timeout: 30 }

L’option de provider "main" signifie « utiliser le provider qu’utilise mon agent principal » — valide uniquement dans les configurations auxiliary:, compression: et fallback_model:. Elle n’est pas valide pour votre paramètre model.provider de niveau supérieur. Si vous utilisez un endpoint personnalisé compatible OpenAI comme modèle principal, définissez provider: custom dans votre section model:.⁴

Pourquoi c’est important : si vous n’avez configuré que OAuth Anthropic (sans clé OpenRouter), votre vision, vos résumés web et votre compression se dégraderont ou échoueront, car la chaîne de repli auxiliaire par défaut essaie OpenRouter en premier. Ajoutez une OPENROUTER_API_KEY pour les tâches auxiliaires, ou reconfigurez chaque slot auxiliaire pour utiliser votre provider principal :

auxiliary:
  vision:
    provider: "main"
  web_extract:
    provider: "main"

C’est le piège « mes fonctionnalités ne marchent pas silencieusement » le plus courant chez les nouveaux utilisateurs de Hermes.

Système de configuration

Hermes dispose d’un système de configuration en couches. Comprendre la priorité est essentiel, car les couches supérieures remplacent les couches inférieures, et l’une de ces couches est un registre global de providers que vous ne pouvez pas voir dans config.yaml.

Structure des fichiers de configuration

D’après la documentation upstream, voici les fichiers qui composent une configuration Hermes :⁴

~/.hermes/
├── config.yaml       # All settings (model, terminal, TTS, compression, memory, toolsets, ...)
├── .env              # Secrets (API keys, bot tokens, passwords)
├── auth.json         # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md           # Primary agent identity (slot #1 in system prompt)
├── memories/         # Persistent memory (MEMORY.md, USER.md)
├── skills/           # Bundled + agent-created + hub-installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Gateway session state
└── logs/             # agent.log, gateway.log, errors.log (secrets auto-redacted)

config.yaml vs .env — lorsque les deux sont définis, config.yaml l’emporte pour les paramètres non secrets.⁴ La règle est la suivante : - Secrets (clés API, tokens de bot, mots de passe) → .env - Tout le reste (modèle, backend de terminal, paramètres de compression, limites de mémoire, toolsets) → config.yaml

Les secrets peuvent être référencés depuis config.yaml avec une interpolation de style shell :⁴

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}
  delegation:
    api_key: ${DELEGATION_KEY}

Gérer la configuration

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

Exemples :⁴

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

hermes config check et hermes config migrate sont les commandes à exécuter après chaque hermes update : elles détectent les nouvelles options de configuration ajoutées que votre fichier ne contient pas encore.⁶

Priorité de la configuration

Hermes charge la configuration depuis plusieurs sources. Lorsque plusieurs sources définissent la même valeur, la source avec la priorité la plus élevée l’emporte :⁴

1. Arguments CLI — hermes chat --model anthropic/claude-sonnet-4 (remplacement pour une invocation donnée)
2. Variables d’environnement — appliquées au démarrage du processus
3. config.yaml — le fichier principal de paramètres
4. .env — secrets uniquement
5. Valeurs par défaut intégrées — appliquées lorsque rien d’autre ne définit une valeur

Les flags CLI l’emportent toujours pour cette invocation unique. config.yaml est la source de vérité à long terme.

Localisation (v0.13.0+)

v0.13.0 a ajouté 7 locales pour les messages CLI et gateway : chinois (simplifié), japonais, allemand, espagnol, français, ukrainien et turc.¹⁸ v0.14.0 localise toutes les commandes gateway et le dashboard web, ajoute 8 locales supplémentaires et porte le total à 16.¹⁹ La documentation est actuellement localisée en zh-Hans uniquement. La locale est résolue depuis les variables d’environnement LC_ALL / LANG ou une clé explicite locale: dans config.yaml. L’anglais reste la valeur par défaut et la source de vérité pour toute chaîne qu’une traduction ne couvre pas encore.

Profiles — Plusieurs instances Hermes isolées

Les profiles vous donnent plusieurs instances Hermes isolées, chacune avec sa propre config, ses sessions, ses skills, sa mémoire et son PID gateway. C’est ainsi que vous exécutez « Hermes travail » et « Hermes personnel » côte à côte sans que l’un voie l’état de l’autre.⁶

hermes profile list
hermes profile create work --clone                  # Clone from current profile
hermes profile use work                             # Set sticky default
hermes profile alias work --name h-work             # Create wrapper script
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"    # One-off without switching

Chaque profile reçoit son propre HERMES_HOME (~/.hermes-<name>/ par défaut), ce qui permet à plusieurs profiles d’exécuter le gateway simultanément sans se marcher dessus.⁶³

Commandes CLI

Cette section sert de référence pratique pour les commandes CLI de premier niveau. Pour la référence officielle dérivée du code, consultez la Référence des commandes CLI.⁶

Options globales

hermes [global-options] <command> [subcommand/options]

Commandes de premier niveau

hermes chat — Le point d’entrée principal

hermes sans argument vous place dans le chat interactif. hermes chat est la forme explicite avec options :⁶

hermes chat -q "Summarize the latest PRs"           # One-shot, non-interactive
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills          # Enable specific toolsets
hermes chat --quiet -q "Return only JSON"           # Programmatic mode
hermes chat --worktree -q "Review repo and open a PR"

Options clés :

hermes setup — Assistant complet

Exécute l’assistant de configuration complet ou passe directement à une section :⁶

hermes setup                 # Full wizard
hermes setup model           # Provider and model only
hermes setup terminal        # Terminal backend only
hermes setup gateway         # Messaging platforms only
hermes setup tools           # Tool enable/disable per platform
hermes setup agent           # Agent behavior only
hermes setup --non-interactive
hermes setup --reset         # Reset config to defaults before setup

hermes logs — Requête structurée dans les journaux

hermes logs est plus puissant que tail -f sur les fichiers journaux, car il prend simultanément en charge le filtrage par niveau, ID de session et plage temporelle.⁶

hermes logs                          # Last 50 lines of agent.log
hermes logs -f                       # Follow in real time
hermes logs gateway -n 100           # Last 100 lines of gateway.log
hermes logs --level WARNING --since 1h   # Warnings from the last hour
hermes logs --session abc123         # Filter by session ID substring
hermes logs errors --since 30m -f    # Follow errors.log from 30m ago
hermes logs list                     # List all log files with sizes

Les fichiers journaux se trouvent dans ~/.hermes/logs/ :⁶ - agent.log — toute l’activité de l’agent (appels API, dispatch de tools, cycle de vie des sessions, INFO+) - errors.log — avertissements et erreurs uniquement (un sous-ensemble filtré de agent.log) - gateway.log — activité du gateway de messagerie (connexions aux plateformes, dispatch, webhooks)

La rotation est automatique via le RotatingFileHandler de Python — cherchez agent.log.1, agent.log.2, etc.⁶

hermes doctor — Diagnostics

hermes doctor [--fix] est la première commande à exécuter quand quelque chose ne va pas. Elle vérifie la validité de la configuration, la présence des dépendances, la disponibilité des clés API, l’état des services, et peut tenter des réparations automatiques avec --fix.⁶

Pour partager les diagnostics avec quelqu’un d’autre, utilisez hermes dump — la commande produit un résumé compact en texte brut avec les clés API masquées, prêt à coller dans une issue GitHub ou un fil Discord.⁶

Commandes slash

Les commandes slash s’exécutent dans une session de chat active (CLI ou plateforme de messagerie). Elles sont distribuées depuis un COMMAND_REGISTRY partagé dans hermes_cli/commands.py, ce qui explique pourquoi la plupart des commandes fonctionnent de la même manière sur toutes les surfaces.⁹

Contrôle de session

Configuration et modèle

La commande /model est l’outil central pour changer de provider en cours de session :⁹

/model                              # Show current model and options
/model claude-sonnet-4              # Switch model (auto-detect provider)
/model zai:glm-5                    # Switch provider:model
/model custom:qwen-2.5              # Use model on custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Named custom provider
/model openrouter:anthropic/claude-sonnet-4   # Back to cloud

Outils, skills et informations

Commandes slash dynamiques des skills

Chaque skill installé est automatiquement exposé comme commande slash :⁹

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/excalidraw       # Just the skill name loads it and lets the agent ask what you need

Vous pouvez également définir des commandes rapides dans config.yaml, qui associent un nom court à un prompt plus long :⁹

quick_commands:
  review: "Review my latest git diff and suggest improvements"
  deploy: "Run the deployment script at scripts/deploy.sh and verify the output"
  morning: "Check my calendar, unread emails, and summarize today's priorities"

Tapez ensuite /review, /deploy ou /morning dans le CLI.

Correspondance par préfixe

Les commandes prennent en charge la correspondance par préfixe : saisir /h se résout vers /help, /mod se résout vers /model. Lorsqu’un préfixe est ambigu, le premier enregistrement dans l’ordre du registre l’emporte. Les noms complets de commandes et les alias enregistrés sont toujours prioritaires sur les correspondances par préfixe.⁹

Commandes propres à la messagerie

Certaines commandes fonctionnent uniquement sur les plateformes de messagerie (Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant) :⁹

• /status — afficher les informations de session
• /sethome (alias /set-home) — définir le chat actuel comme home de la plateforme
• /approve [session|always] — approuver une commande dangereuse en attente
• /deny — rejeter une commande dangereuse en attente
• /update — mettre Hermes Agent à jour vers la dernière version
• /commands [page] — parcourir toutes les commandes et skills (paginé)

Et certaines sont réservées à CLI : /skin, /tools, /toolsets, /browser, /config, /cron, /skills, /platforms, /paste, /statusbar, /plugins.⁹

Tools et toolsets

Hermes est livré avec un vaste registre d’outils intégrés couvrant la recherche web, l’automatisation de navigateur, l’exécution dans le terminal, la modification de fichiers, la mémoire, la délégation, l’entraînement RL, l’envoi de messages, l’intégration Home Assistant, et plus encore.¹⁰ Les outils sont organisés en toolsets logiques qui peuvent être activés ou désactivés par plateforme.

Catégories de haut niveau

Les noms courants de toolsets incluent web, terminal, file, browser, vision, image_gen, moa, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant et rl.¹⁰

Gestion des outils

hermes chat --toolsets "web,terminal"       # Use specific toolsets
hermes tools                                # Interactive per-platform tool config
hermes tools --summary                      # Print enabled-tools summary

Les outils peuvent aussi être activés ou désactivés en cours de session via /tools disable <name> et /tools enable <name>, ce qui réinitialise la session pour que le nouveau jeu d’outils prenne effet.⁹

Backends de terminal

L’outil terminal peut exécuter des commandes dans six environnements différents :¹⁰

Changez de backend avec hermes config set terminal.backend <name> ou dans config.yaml :

terminal:
  backend: docker      # or: local, ssh, singularity, modal, daytona
  cwd: "."             # Working directory
  timeout: 180         # Command timeout in seconds

Backend SSH (recommandé pour la sécurité — l’agent ne peut pas modifier son propre code) :¹⁰

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Backend Docker :

terminal:
  backend: docker
  docker_image: python:3.11-slim

Ressources de conteneur (s’applique à docker, singularity, modal, daytona) :¹⁰

terminal:
  container_cpu: 1
  container_memory: 5120          # MB (default 5GB)
  container_disk: 51200           # MB (default 50GB)
  container_persistent: true      # Persist filesystem across sessions

Avec container_persistent: true, les paquets installés, les fichiers et la configuration persistent d’une session à l’autre.¹⁰

Tous les backends de conteneur s’exécutent avec un durcissement de sécurité : système de fichiers racine en lecture seule (Docker), toutes les capacités Linux supprimées sauf DAC_OVERRIDE, CHOWN et FOWNER, aucune élévation de privilèges, limites de PID (256 processus), isolation complète des espaces de noms, espace de travail persistant via volumes.¹⁰

Processus en arrière-plan

L’outil terminal prend en charge l’exécution en arrière-plan avec une gestion explicite des processus :¹⁰

terminal(command="pytest -v tests/", background=true)
# Returns: {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                            # Show all running processes
process(action="poll", session_id="proc_abc123")  # Check status
process(action="wait", session_id="proc_abc123")  # Block until done
process(action="log", session_id="proc_abc123")   # Full output
process(action="kill", session_id="proc_abc123")  # Terminate
process(action="write", session_id="proc_abc123", data="y")  # Send input

Le mode PTY (pty=true) active les outils CLI interactifs comme Codex et Claude Code.¹⁰

Sudo

Si une commande nécessite sudo, Hermes vous demande votre mot de passe (mis en cache pour la session). Vous pouvez aussi définir SUDO_PASSWORD dans ~/.hermes/.env.¹⁰

Multi-Agent Kanban (v0.13.0+)

v0.13.0 fait de la collaboration multi-agent une primitive de premier ordre : un tableau Kanban durable qui suit les tâches, leur statut et l’identité des workers entre agents et après les redémarrages.¹⁸ C’est ce tableau qui permet à un essaim de workers Hermes de terminer réellement le travail au lieu de se bloquer sur des passations mortes.

Le tableau Kanban s’associe naturellement à /goal (boucle Ralph à cible verrouillée) côté cible, et à l’outil delegate_task existant pour la sémantique de spawn. Le résultat est un modèle d’essaim où chaque agent partage une seule source de vérité sur ce qu’il faut faire ensuite, qui s’en occupe et ce qui est bloqué.

Système de skills

Les skills sont des documents de connaissance à la demande que l’agent peut charger selon ses besoins. Ils suivent un modèle de divulgation progressive afin de minimiser l’utilisation des tokens et sont compatibles avec le standard ouvert agentskills.io.¹¹

Tous les skills se trouvent dans ~/.hermes/skills/ — le dossier principal et la source de vérité. Lors d’une nouvelle installation, les skills fournis sont copiés depuis le repo. Les skills installés depuis le Hub et créés par l’agent y sont également placés.¹¹

Divulgation progressive

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata                 (varies)
Level 2: skill_view(name, path)  → Specific reference file                 (varies)

L’agent ne charge le contenu complet du skill que lorsqu’il en a réellement besoin.¹¹

Format SKILL.md

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]      # Optional — restrict to OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]     # Conditional activation
    requires_toolsets: [terminal]    # Conditional activation
    config:                          # Config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

Activation conditionnelle

Les skills peuvent s’afficher ou se masquer selon les outils disponibles. C’est particulièrement utile pour les skills de fallback — des alternatives gratuites ou locales qui ne doivent apparaître que lorsqu’un outil premium est indisponible :¹¹

Exemple : le skill intégré duckduckgo-search utilise fallback_for_toolsets: [web]. Lorsque vous avez défini FIRECRAWL_API_KEY, le toolset web est disponible et l’agent utilise web_search — le skill DuckDuckGo reste masqué. Sans la clé API, le skill DuckDuckGo apparaît automatiquement comme fallback.¹¹

Skills gérés par l’agent

L’agent peut créer, mettre à jour et supprimer ses propres skills via l’outil skill_manage. C’est la mémoire procédurale de l’agent — lorsqu’il identifie un workflow non trivial, il enregistre l’approche sous forme de skill pour pouvoir la réutiliser plus tard.¹¹

Quand l’agent crée des skills :¹¹ - Après avoir terminé avec succès une tâche complexe (5 appels d’outils ou plus) - Lorsqu’il a rencontré des erreurs ou des impasses et trouvé le chemin fonctionnel - Lorsque l’utilisateur a corrigé son approche - Lorsqu’il a découvert un workflow non trivial

Actions :¹¹

Skill Hub

Parcourez, recherchez, installez et gérez des skills depuis des registres en ligne :⁶¹¹

hermes skills browse                          # Browse all hub skills
hermes skills browse --source official        # Browse official optional skills
hermes skills search kubernetes               # Search all sources
hermes skills search react --source skills-sh # Search skills.sh directory
hermes skills inspect openai/skills/k8s       # Preview before installing
hermes skills install openai/skills/k8s       # Install with security scan
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check                           # Check for upstream updates
hermes skills update                          # Reinstall changed hub skills
hermes skills audit                           # Re-scan installed hub skills
hermes skills uninstall k8s
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo       # Add custom GitHub source

Sources de hub intégrées :¹¹

Taps GitHub par défaut (consultables sans configuration) : openai/skills, anthropics/skills, VoltAgent/awesome-agent-skills, garrytan/gstack.¹¹

Analyse de sécurité

Tous les skills installés depuis le hub passent par un scanner de sécurité qui recherche l’exfiltration de données, l’injection de prompt, les commandes destructrices, les signaux de supply chain et d’autres menaces.¹¹

Niveaux de confiance :¹¹

--force peut outrepasser les blocages de politique non dangereux pour les skills communautaires. Il ne permet pas d’ignorer un verdict de scan dangerous.¹¹

Dossiers de skills externes

Vous pouvez faire pointer Hermes vers des dossiers de skills supplémentaires, analysés en parallèle du dossier local :¹¹

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

Les chemins prennent en charge l’expansion de ~ et la substitution des variables d’environnement ${VAR}. Les dossiers externes sont en lecture seule — lorsque l’agent crée ou modifie un skill, il écrit toujours dans ~/.hermes/skills/. La priorité locale l’emporte si un nom de skill existe aux deux emplacements.¹¹

Mémoire persistante

Hermes dispose d’une mémoire bornée et organisée qui persiste entre les sessions. Deux fichiers composent la mémoire de l’agent, tous deux stockés dans ~/.hermes/memories/ :¹²

Les deux sont injectés dans le prompt système sous forme d’instantané figé au démarrage de la session. L’agent gère sa propre mémoire via l’outil memory — add, replace ou remove.¹²

Modèle d’instantané figé : l’injection dans le prompt système est capturée une seule fois au démarrage de la session et ne change jamais en cours de session. C’est volontaire — cela préserve le cache de préfixe de LLM pour les performances. Les modifications effectuées pendant une session sont immédiatement persistées sur disque, mais n’apparaissent dans le prompt système qu’à la session suivante.¹²

Ce qu’il faut enregistrer

Enregistrez ces éléments (l’agent le fait proactivement) :¹² - Préférences utilisateur : « Je préfère TypeScript à JavaScript » → user - Faits d’environnement : « Ce serveur exécute Debian 12 avec PostgreSQL 16 » → memory - Corrections : « N’utilisez pas sudo pour les commandes Docker, l’utilisateur est dans le groupe docker » → memory - Conventions : « Le projet utilise des tabulations, une largeur de ligne de 120 caractères et des docstrings de style Google » → memory - Travail terminé : « Base de données migrée de MySQL vers PostgreSQL le 15 janvier 2026 » → memory

Ignorez ces éléments :¹² - Informations triviales/évidentes - Faits faciles à retrouver - Dumps de données brutes (trop volumineux pour la mémoire) - Éléments éphémères propres à la session - Informations déjà présentes dans les fichiers de contexte

Recherche de sessions

Au-delà de MEMORY.md et USER.md, l’agent peut rechercher dans ses conversations passées avec l’outil session_search. Toutes les sessions CLI et de messagerie sont stockées dans SQLite (~/.hermes/state.db) avec recherche plein texte FTS5. Les requêtes renvoient les conversations passées pertinentes avec une synthèse Gemini Flash.¹²

Fournisseurs de mémoire externes

Pour une mémoire persistante plus profonde au-delà de MEMORY.md et USER.md, Hermes inclut huit plugins de fournisseurs de mémoire externes : Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover et Supermemory.¹²

Les fournisseurs externes fonctionnent en parallèle de la mémoire intégrée (sans jamais la remplacer) et ajoutent des capacités comme les graphes de connaissances, la recherche sémantique, l’extraction automatique de faits et la modélisation utilisateur entre sessions :⁶¹²

hermes memory setup         # Pick a provider and configure it
hermes memory status        # Check what's active
hermes memory off           # Disable external provider (built-in only)

Un seul fournisseur externe peut être actif à la fois. La mémoire intégrée est toujours active.⁶

Reprise automatique de session (v0.13.0+)

v0.13.0 rend les interruptions au milieu d’un agent récupérables. Le gateway reprend automatiquement les sessions interrompues après un redémarrage ; les redémarrages /update préservent l’état de session pendant la mise à niveau ; les rechargements de fichiers source pendant le développement conservent la session active au lieu d’en forcer une nouvelle.¹⁸ Effet pratique : les travaux gateway de longue durée et les tâches pilotées par cron ne réinitialisent plus leur fenêtre de contexte au redémarrage du processus.

Checkpoints v2 (v0.13.0+)

La persistance d’état est réécrite dans v0.13.0 sous forme d’architecture à magasin unique avec vrai élagage, garde-fous disque et aucun dépôt fantôme orphelin.¹⁸ Le système de checkpoint précédent accumulait de l’état sur disque dans les profiles de longue durée ; le magasin v2 impose un plafond strict au stockage local des checkpoints et supprime la comptabilité dupliquée qui provoquait cette croissance. Aucun changement de configuration visible par l’utilisateur n’est requis ; la prochaine écriture de checkpoint utilise le chemin v2.

Personnalité et SOUL.md

SOUL.md est l’identité principale d’une instance Hermes. Il occupe l’emplacement n° 1 dans le prompt système, en remplaçant l’identité par défaut codée en dur.¹³

Hermes initialise automatiquement un SOUL.md par défaut dans ~/.hermes/SOUL.md (ou $HERMES_HOME/SOUL.md pour les profiles personnalisés). Les fichiers utilisateur existants ne sont jamais écrasés. Hermes charge SOUL.md uniquement depuis HERMES_HOME — il ne le cherche pas dans le répertoire de travail courant. La personnalité reste ainsi prévisible entre les projets.¹³

Ce qui relève de SOUL.md

Utilisez-le pour les consignes durables de voix et de personnalité :¹³ - ton - style de communication - niveau de franchise - style d’interaction par défaut - éléments stylistiques à éviter - manière dont Hermes doit gérer l’incertitude, le désaccord, l’ambiguïté

Utilisez-le moins pour :¹³ - instructions ponctuelles de projet - chemins de fichiers - conventions de dépôt - détails temporaires de workflow

Ces éléments relèvent de AGENTS.md, pas de SOUL.md.

SOUL.md vs AGENTS.md

C’est la distinction la plus importante dans la gestion d’identité de Hermes :¹³

SOUL.md — identité, ton, style, comportements par défaut de communication, comportement au niveau de la personnalité.

AGENTS.md — architecture du projet, conventions de code, préférences d’outils, workflows propres au dépôt, commandes, ports, chemins, notes de déploiement.

Règle utile : si cela doit vous suivre partout, cela relève de SOUL.md. Si cela appartient à un projet, cela relève de AGENTS.md.¹³

Personnalités intégrées

Hermes inclut des personnalités intégrées auxquelles vous pouvez passer avec /personality :¹³

Personnalités personnalisées dans config.yaml :¹³

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

Puis passez-y avec /personality codereviewer.

SOUL.md vs /personality

SOUL.md est la voix de base. /personality est une surcouche au niveau de la session.¹³ Gardez un SOUL.md pragmatique par défaut, puis utilisez /personality teacher pour une conversation de tutorat ou /personality creative pour un brainstorming.

Nous Tool Gateway (v0.10.0+)

Depuis Hermes Agent v0.10.0 (16 avril 2026), les abonnés Nous Portal payants obtiennent un accès managé à un ensemble organisé d’outils via leurs identifiants Portal existants — aucune clé API supplémentaire à gérer.²⁶ Le CLI Hermes lui-même reste sous licence MIT et entièrement open source. Ce qui a changé, c’est que votre authentification Portal déverrouille désormais plus que l’inférence de modèles.

Ce que contient le gateway

Fonctionnement

Le gateway est opt-in par outil via un nouveau champ de configuration use_gateway. Si vous avez des identifiants Portal dans hermes auth et activez le gateway pour un outil, les appels de cet outil passent par Portal. Sinon, votre clé API directe (si présente) est utilisée.

# config.yaml — per-tool gateway opt-in
tools:
  web_search:
    provider: firecrawl
    use_gateway: true          # route via Nous Portal subscription
  image_generation:
    provider: fal
    use_gateway: true

Priorité à l’exécution : lorsque le gateway est disponible et qu’un outil a use_gateway: true, Hermes privilégie le gateway même si vous avez aussi configuré une clé API directe. C’est important pour la facturation — les appels gateway sont déduits de votre abonnement Portal, pas du solde de votre clé API directe.

Activer le gateway

hermes model                      # select Nous Portal (OAuth flow)
hermes tools                      # per-platform tool picker integrates gateway tools
hermes status                     # confirms gateway/subscription detection

Il n’existe pas de commande séparée hermes subscribe ou hermes login --portal. L’abonnement est détecté automatiquement à partir des identifiants OAuth Portal que vous avez déjà dans hermes auth.

Tarifs et accès

Les tarifs et noms d’offres sont publiés sur la page de tarification Nous Portal (https://portal.nousresearch.com/pricing). Ce guide n’énumère pas les offres, car elles relèvent du produit Portal, pas du CLI Hermes, et évoluent indépendamment des versions de Hermes. Inscrivez-vous sur https://portal.nousresearch.com/ et consultez la page de tarification pour connaître les offres actuelles.

Avis de dépréciation

• La variable d’environnement HERMES_ENABLE_NOUS_MANAGED_TOOLS est supprimée dans v0.10.0. Les outils managés sont désormais activés via le champ de configuration use_gateway propre à chaque outil et conditionnés à l’état de votre abonnement Portal.²⁶

Cadrage : ce que cette version n’est pas

Le CLI Hermes Agent n’est pas verrouillé derrière un abonnement. Le projet reste sous licence MIT, toutes les fonctionnalités de base (CLI, skills, mémoire, messaging gateway, cron, MCP, dashboard local, BYOK pour chaque fournisseur) fonctionnent de bout en bout sans payer qui que ce soit. v0.10.0 ajoute un parcours pratique pour les utilisateurs qui paient déjà Nous Portal — cela ne retire rien au parcours gratuit.

Gateway de messagerie

Hermes peut fonctionner comme un processus gateway de longue durée qui se connecte à 22 plateformes de messagerie depuis un seul processus gateway : Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin (WeChat), BlueBubbles (iMessage), QQBot, Microsoft Teams, Tencent Yuanbao, Google Chat, LINE, SimpleX Chat, ainsi qu’un adaptateur Webhook générique.^325171819 v0.9.0 a ajouté iMessage via BlueBubbles (enregistrement automatique de webhook, assistant de configuration, résilience aux plantages) et la prise en charge native de WeChat via iLink Bot API, avec le mode callback WeCom pour les applications d’entreprise.¹⁶ v0.11.0 a ajouté QQBot.²⁵ v0.12.0 a ajouté Microsoft Teams et Tencent Yuanbao.¹⁷ v0.13.0 a ajouté Google Chat comme 20e plateforme, en s’appuyant sur la même architecture d’adaptateurs enfichables ; IRC et Microsoft Teams ont également été migrés vers le nouveau modèle d’adaptateur avec les hooks de plugin génériques env_enablement_fn / cron_deliver_env_var.¹⁸ v0.14.0 ajoute LINE et SimpleX Chat et finalise la pile Microsoft Teams de bout en bout avec l’authentification Graph, le listener webhook, le runtime de pipeline et la livraison sortante.¹⁹ v0.17.0 (19 juin 2026) ajoute iMessage sans relais via Photon Spectrum (OAuth par code d’appareil avec hermes photon login — aucun relais Mac/BlueBubbles requis), l’adaptateur officiel WhatsApp Business Cloud API (qui remplace l’exigence d’un processus bridge), les groupes SimpleX et pièces jointes natives, ainsi que Raft comme plugin de plateforme inclus.²¹

Configuration

hermes gateway setup                # Interactive platform configuration
hermes gateway install              # Install as user service (systemd/launchd)
hermes gateway start                # Start the installed service
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes gateway run                  # Run in foreground (debugging)

La configuration interactive vous guide dans la connexion de chaque plateforme : tokens API, IDs de bots, mappages de canaux, listes d’autorisation.⁶

Fonctionnement du flux des messages

D’après la documentation d’architecture upstream :³

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

Chaque plateforme de messagerie passe par la même boucle de conversation AIAgent que le CLI. C’est pourquoi les slash commands fonctionnent de façon identique aux deux endroits, et pourquoi une tâche cron planifiée dans Telegram peut livrer sa sortie dans Discord : la différence de plateforme n’existe qu’en périphérie.³

Autorisation utilisateur et association

hermes pairing list                    # Show pending and approved users
hermes pairing approve <platform> <code>
hermes pairing revoke <platform> <user-id>
hermes pairing clear-pending

Les codes d’association empêchent des inconnus de parler à votre gateway. Un utilisateur envoie un code d’association depuis sa plateforme de messagerie ; vous l’approuvez avec hermes pairing approve ; à partir de là, il est autorisé.⁶

Tâches planifiées (Cron)

Hermes dispose d’un système cron de premier ordre dans lequel les jobs sont des tâches d’agent, pas des commandes shell. Chaque job planifié s’exécute via un nouvel AIAgent avec le prompt configuré, des skills éventuellement attachés, et livre les résultats à n’importe quelle plateforme :³⁶

hermes cron list
hermes cron create --prompt "Check HN for AI news and summarize" --schedule "0 9 * * *" --deliver telegram
hermes cron edit <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron run <id>         # Trigger now on the next tick
hermes cron remove <id>
hermes cron status           # Check if scheduler is running
hermes cron tick             # Run due jobs once and exit

Ou créez-en un conversationnellement dans une discussion de messagerie :

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

L’agent configurera le job cron via ses tools. Les jobs persistent dans JSON et survivent aux redémarrages.³

Intégration MCP

Hermes prend en charge le Model Context Protocol à la fois comme client et comme serveur :⁶

Comme client — connectez Hermes à des serveurs MCP externes pour étendre sa surface de tools :

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection

Ou manuellement dans config.yaml :¹⁴

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

Comme serveur — exposez les conversations Hermes à d’autres agents :

hermes mcp serve
hermes mcp serve -v    # Verbose

Compression du contexte

Hermes compresse automatiquement les longues conversations pour rester dans la fenêtre de contexte de votre modèle. Le summarizer de compression est un appel LLM distinct : vous pouvez le diriger vers n’importe quel provider ou endpoint.⁴

compression:
  enabled: true
  threshold: 0.50                           # Compress at this % of context limit
  target_ratio: 0.20                        # Fraction to preserve as recent tail
  protect_last_n: 20                        # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"                  # "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                    # Custom OpenAI-compatible endpoint

Options de provider :⁴

summary_model doit prendre en charge une longueur de contexte au moins aussi grande que celle de votre modèle principal, puisqu’il reçoit toute la section centrale de la conversation à compresser.⁴

Avertissements de pression sur le budget

Lorsque l’agent travaille sur une tâche complexe avec de nombreux appels de tools, il peut épuiser son budget d’itérations (par défaut : 90 tours) sans s’en rendre compte. La pression sur le budget avertit automatiquement le modèle :⁴

Timeouts de stream

La connexion de streaming LLM comporte deux couches de timeout qui s’ajustent automatiquement pour les providers locaux (localhost, IPs LAN) :⁴

Le timeout de lecture socket est porté à 30 minutes pour les endpoints locaux, car les LLM locaux peuvent prendre plusieurs minutes à préparer de grands contextes avant de produire le premier token.⁴

Dashboard web local (v0.9.0+)

Un dashboard dans le navigateur pour gérer localement votre Hermes Agent. Configurez les paramètres, surveillez les sessions, parcourez les skills et gérez votre gateway sans toucher aux fichiers de configuration ni au terminal.¹⁶ Lancez-le avec hermes dashboard. C’est le parcours d’onboarding le plus simple pour les nouveaux utilisateurs qui préfèrent une GUI.

Surveillance des processus en arrière-plan (v0.9.0+)

watch_patterns vous permet de définir des motifs à surveiller dans la sortie des processus en arrière-plan et de recevoir des notifications en temps réel lorsqu’ils correspondent.¹⁶ Surveillez les erreurs, attendez des événements précis (« listening on port ») ou observez les journaux de build — le tout sans polling. Combiné à notify_on_complete depuis v0.8.0 (qui notifie à la fin d’une tâche en arrière-plan), Hermes dispose désormais d’une couche complète d’observabilité des processus en arrière-plan.¹⁵

Context engine enfichable (v0.9.0+)

La gestion du contexte est désormais un emplacement enfichable via hermes plugins. Remplacez-le par des context engines personnalisés qui contrôlent ce que l’agent voit à chaque tour — filtrage, summarization ou injection de contexte spécifique au domaine.¹⁶ Cela découple la stratégie de contexte de la boucle principale de l’agent, ce qui permet une personnalisation du contexte par projet ou par domaine.

Sauvegarde et restauration (v0.9.0+)

hermes backup crée une archive complète de votre configuration, de vos sessions, skills et memory. hermes import restaure depuis une archive de sauvegarde.¹⁶ Utilisez cela pour migrer entre machines, créer des instantanés avant des changements majeurs ou partager une configuration connue comme fiable avec vos coéquipiers.

Prise en charge Termux / Android (v0.9.0+)

Hermes fonctionne nativement sur Android via Termux. Les chemins d’installation adaptés, les optimisations TUI pour les écrans mobiles, la prise en charge du backend vocal et la commande /image fonctionnent directement sur l’appareil.¹⁶

Renforcement de la sécurité (v0.13.0+)

v0.13.0 a corrigé 8 problèmes de sécurité P0 et modifié un paramètre par défaut en faveur de l’utilisateur.¹⁸ v0.14.0 poursuit avec 12 autres corrections P0 et 50 corrections P1, notamment le renforcement contre la force brute sudo / sudo-stdin, les correctifs de contournement de commandes dangereuses, la sanitisation des erreurs d’outils avant réinjection dans le modèle, l’auth API des plugins du dashboard, la couverture SSRF du skills-hub et l’analyse des avis de sécurité supply-chain pendant l’installation.¹⁹

Si vous maintenez un déploiement Hermes, considérez v0.13.0 et v0.14.0 comme des mises à niveau liées à la sécurité, pas seulement comme des livraisons de fonctionnalités. v0.13.0 corrige le contournement cross-guild Discord et deux fenêtres TOCTOU ; v0.14.0 ajoute une autre passe de renforcement sur la gestion de sudo, la réinjection des erreurs d’outils, les APIs de plugins, le SSRF du skills-hub et les avis de dépendances.

Architecture pour praticiens

Cette section s’adresse aux personnes qui veulent comprendre ce qui se passe sous le capot afin de pouvoir déboguer, étendre ou raisonner sur les performances. Elle synthétise les docs d’architecture amont.³

Points d’entrée → AIAgent

Chaque point d’entrée dans Hermes appelle au final AIAgent.run_conversation() :

┌──────────────────────────────────────────────────────────────────┐
│                        Entry Points                              │
│                                                                  │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)  │
│  Batch Runner    API Server                  Python Library     │
└──────────┬──────────────┬───────────────────────┬────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                       │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │ Prompt      │  │ Provider     │  │ Tool         │             │
│  │ Builder     │  │ Resolution   │  │ Dispatch     │             │
│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘             │
│         │                │                 │                    │
│  ┌──────┴───────┐ ┌──────┴───────┐  ┌──────┴───────┐             │
│  │ Compression  │ │ 3 API Modes  │  │ Tool Registry│             │
│  │ & Caching    │ │ chat_compl   │  │ 47 tools     │             │
│  │              │ │ codex_resp   │  │ 20 toolsets  │             │
│  │              │ │ anthropic    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

Diagramme adapté des docs d’architecture amont.³

« 47 tools / 20 toolsets » contre « 28 tools » dans votre bannière. Le décompte « 47 tools » correspond au registre total des outils du dépôt amont — tous les outils livrés par Hermes avec leur code source, dans tous les toolsets. Votre CLI réellement en cours d’exécution affichera un nombre plus faible dans sa bannière de démarrage (l’installation contre laquelle j’ai vérifié ce guide indique 28 tools / 89 skills). Ce n’est pas un bug. Beaucoup de toolsets sont optionnels et doivent être explicitement activés dans config.yaml sous toolsets: — adaptateurs de plateformes de messagerie, automatisation de navigateur, outils de scraping plus lourds, etc. Le total du registre correspond à « ce qui est disponible » ; le nombre de la bannière correspond à « ce qui est activé dans votre profile actuel ». Vérifiez quels toolsets sont actifs avec hermes tools --list et activez ou désactivez des toolsets individuels avec le bloc toolsets: dans ~/.hermes/config.yaml (ou /tools list / /tools enable <name> / /tools disable <name> dans une session en cours — retirer un outil déclenche une réinitialisation de session afin que l’agent reconstruise son manifeste d’outils).

Les trois modes API

Hermes abstrait les différences entre providers en trois modes API, sélectionnés automatiquement à l’exécution :³

Le résolveur runtime_provider.py mappe les tuples (provider, model) vers (api_mode, api_key, base_url) pour plus de 18 providers, en gérant les flux OAuth, les pools d’identifiants et la résolution d’alias.³

Flux de données dans une session CLI

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

Extrait de la page d’architecture amont.³

Ordre d’assemblage du prompt

La pile de prompt inclut :¹³

1. SOUL.md (identité de l’agent — ou fallback intégré si indisponible)
2. Consignes de comportement tenant compte des outils
3. Mémoire/contexte utilisateur (MEMORY.md, USER.md)
4. Consignes des skills
5. Fichiers de contexte (AGENTS.md, .cursorrules)
6. Horodatage
7. Indications de formatage propres à la plateforme
8. Surcouches optionnelles de system-prompt comme /personality

SOUL.md est la fondation — tout le reste se construit par-dessus.¹³

Stockage des sessions

Stockage de sessions basé sur SQLite avec recherche plein texte FTS5. Les sessions disposent d’un suivi de lignée (parent/enfant à travers les compressions), d’une isolation par plateforme et d’écritures atomiques avec gestion de la contention.³

Système de plugins

Trois sources de découverte : ~/.hermes/plugins/ (utilisateur), .hermes/plugins/ (projet) et les points d’entrée pip. Les plugins enregistrent des outils, hooks et commandes CLI via un contexte API. Les providers de mémoire constituent un type de plugin spécialisé sous plugins/memory/.³

hermes plugins                       # Interactive enable/disable UI
hermes plugins install <repo>        # Install from Git URL or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list

Principes de conception

Depuis la page d’architecture amont :³

Migration depuis OpenClaw

Hermes Agent est le successeur d’OpenClaw. Si vous migrez depuis une installation OpenClaw existante :⁶⁵

hermes claw migrate --dry-run                    # Preview what would be migrated
hermes claw migrate --preset full                # Full migration including API keys
hermes claw migrate --preset user-data --overwrite   # User data only, no secrets
hermes claw migrate --source /custom/path        # Non-default OpenClaw location

hermes claw migrate lit ~/.openclaw par défaut (et détecte aussi automatiquement les anciens dossiers ~/.clawdbot et ~/.moldbot) et écrit dans ~/.hermes.⁶

Importé directement (30+ catégories) : SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills depuis 4 dossiers sources, modèle par défaut, providers personnalisés, serveurs MCP, tokens de plateformes de messagerie et listes d’autorisation (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), paramètres par défaut de l’agent (effort de raisonnement, compression, délai humain, fuseau horaire, sandbox), politiques de réinitialisation de session, règles d’approbation, config TTS, paramètres du navigateur, paramètres des outils, timeout exec, liste d’autorisation des commandes, config gateway et clés API depuis 3 sources.⁶

Archivé pour revue manuelle : tâches cron, plugins, hooks/webhooks, backend de mémoire (QMD), config du registre de skills, UI/identité, journalisation, configuration multi-agent, liaisons de canaux, IDENTITY.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md.⁶

La résolution des clés API vérifie trois sources par ordre de priorité : valeurs de config → ~/.openclaw/.env → auth-profiles.json.⁶

Dépannage

« clé API non définie »

Exécutez hermes model pour configurer votre fournisseur de manière interactive, ou hermes config set OPENROUTER_API_KEY your_key. La commande hermes doctor vous indiquera exactement quelles clés sont manquantes.⁷

« Context limit: 2048 tokens » au démarrage (modèles locaux)

Hermes détecte automatiquement la longueur de contexte depuis l’endpoint /v1/models de votre serveur, mais beaucoup de serveurs locaux indiquent des valeurs par défaut basses. Définissez-la explicitement dans config.yaml :²

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

Les appels d’outils apparaissent sous forme de texte au lieu de s’exécuter

Votre serveur n’a pas activé les appels d’outils, ou le modèle ne les prend pas en charge via l’implémentation du serveur.²

Les réponses sont coupées en plein milieu d’une phrase

Deux causes possibles :²

1. Limite de sortie trop basse (max_tokens) côté serveur — SGLang utilise par défaut 128 tokens par réponse. Définissez --default-max-tokens sur le serveur ou configurez model.max_tokens dans config.yaml.
2. Épuisement du contexte — Le modèle a rempli sa fenêtre de contexte. Augmentez model.context_length ou activez la compression du contexte dans Hermes.

« Connection refused » depuis WSL2 vers un serveur de modèle hébergé sous Windows

WSL2 utilise un adaptateur réseau virtuel avec son propre sous-réseau — localhost dans WSL2 renvoie à la VM Linux, pas à l’hôte Windows. Deux options :²

Réseau en miroir (Windows 11 22H2+) : modifiez %USERPROFILE%\.wslconfig :

[wsl2]
networkingMode=mirrored

Puis exécutez wsl --shutdown et redémarrez. localhost fonctionne alors dans les deux sens.

Repli sur l’IP de l’hôte (anciennes versions de Windows) : récupérez l’IP de l’hôte Windows depuis WSL2 et utilisez-la à la place de localhost :

ip route show | grep -i default | awk '{ print $3 }'
# Use that IP as the base_url host

Le serveur de modèle doit aussi se lier à 0.0.0.0, et non à 127.0.0.1 — définissez OLLAMA_HOST=0.0.0.0 pour Ollama, ajoutez --host 0.0.0.0 pour llama-server/SGLang, ou activez « Serve on Network » dans LM Studio.²

Où se trouve tout le reste ?

hermes status et hermes dump sont vos alliés ici. hermes logs list affiche tous les fichiers journaux avec leur taille. hermes config path affiche l’emplacement du fichier de configuration. hermes config env-path affiche l’emplacement de .env.⁶

FAQ

Quelle est la différence entre Hermes Agent et Claude Code ?

Claude Code est le CLI officiel de Anthropic, limité aux modèles Anthropic. Hermes Agent est un framework d’agent open source de Nous Research qui fonctionne avec n’importe quel fournisseur compatible OpenAI — Nous Portal, OpenRouter, Anthropic, GitHub Copilot, z.ai, Kimi, MiniMax, DeepSeek, Hugging Face, Google, ou votre propre endpoint auto-hébergé.¹² Hermes inclut aussi un gateway de messagerie pour Telegram/Discord/Slack/WhatsApp/Signal que Claude Code ne propose pas.

Puis-je utiliser Hermes avec une clé API Anthropic ?

Oui. Trois possibilités :²

1. Définissez ANTHROPIC_API_KEY dans ~/.hermes/.env et exécutez hermes chat --provider anthropic --model claude-sonnet-4-6
2. Exécutez hermes model et sélectionnez Anthropic — Hermes utilisera le magasin d’identifiants de Claude Code lorsqu’il est disponible
3. Définissez manuellement un ANTHROPIC_TOKEN (token setup-token ou token OAuth) comme solution de repli

L’option 2 est préférable si vous utilisez déjà Claude Code sur la même machine — elle conserve le caractère actualisable des identifiants Claude.

Comment changer de fournisseur sans perdre ma conversation ?

Utilisez /model provider:model dans une session. L’historique de conversation, la mémoire et les skills sont tous conservés :⁹

/model zai:glm-5
/model openrouter:anthropic/claude-sonnet-4
/model custom:local:qwen-2.5

J’ai configuré Anthropic, mais vision/web/compression ne fonctionnent pas

Vous tombez sur le repli du modèle auxiliaire. La vision, la synthèse web, la compression et d’autres tâches secondaires utilisent un LLM auxiliaire distinct — par défaut Gemini Flash via auto-détection (OpenRouter → Nous → Codex). Si aucun de ces fournisseurs n’est configuré et que seul Anthropic l’est, ces fonctionnalités se dégradent silencieusement.⁴

Correctif : ajoutez soit une OPENROUTER_API_KEY pour les tâches auxiliaires, soit reconfigurez les emplacements auxiliaires pour utiliser votre fournisseur principal. Notez que la compression du contexte réside dans son propre bloc de premier niveau compression: et prend summary_provider, pas auxiliary.compression.provider — l’emplacement auxiliary.compression n’expose qu’un timeout. Correctif complet :

auxiliary:
  vision:      { provider: "main" }
  web_extract: { provider: "main" }

compression:
  summary_provider: "main"

Quelle est la différence entre SOUL.md et AGENTS.md ?

SOUL.md est l’identité de votre agent — ton, style, paramètres de communication par défaut. Il se trouve dans ~/.hermes/SOUL.md et vous suit partout. AGENTS.md est propre au projet — architecture, conventions, commandes, chemins — et se trouve dans le dossier de votre projet.¹³ Si cela doit vous suivre partout, utilisez SOUL.md. Si cela appartient à un projet, utilisez AGENTS.md.

Comment exécuter plusieurs instances Hermes côte à côte ?

Avec des profils. Chaque profil dispose de son propre HERMES_HOME, de sa configuration, de sa mémoire, de ses sessions et de son PID de gateway :⁶

hermes profile create work --clone
hermes profile use work                 # Sticky default
hermes -p work chat -q "..."            # One-off without switching
hermes profile alias work --name h-work # Wrapper script

Hermes prend-il en charge les LLMs locaux ?

Oui, via le chemin d’endpoint personnalisé. Hermes fonctionne avec n’importe quel serveur compatible OpenAI : Ollama, vLLM, SGLang, llama.cpp/llama-server, LM Studio, LocalAI, Jan, ou le vôtre.² Consultez Endpoints personnalisés et auto-hébergés pour la configuration propre à chaque serveur.

Pourquoi la bannière de démarrage affiche-t-elle moins d’outils que le guide n’en attribue à Hermes ?

Le guide cite 47 outils / 20 toolsets depuis le registre d’architecture amont — c’est le nombre total d’outils dont Hermes fournit le code source sur l’ensemble des toolsets. Votre installation en cours affiche un nombre plus faible dans la bannière (l’installation de référence utilisée pour ce guide indique 28 outils), car Hermes n’active au démarrage que l’ensemble de toolsets par défaut. Beaucoup de toolsets sont optionnels : adaptateurs de gateway de messagerie, automatisation du navigateur, piles de scraping plus lourdes et plusieurs intégrations spécialisées doivent être explicitement listés sous toolsets: dans ~/.hermes/config.yaml avant d’être chargés. Total du registre = « ce qui est disponible si vous l’activez ». Total de la bannière = « ce que votre profil actuel a réellement chargé ». Utilisez hermes tools --list pour voir quels toolsets sont actifs et lesquels sont disponibles mais désactivés. Activez ou désactivez des toolsets individuels à l’exécution avec /tools enable <name> et /tools disable <name> (la désactivation déclenche une réinitialisation de session afin que l’agent reconstruise son manifeste d’outils avec la nouvelle structure).

Comment Hermes gère-t-il le repli de modèle lorsque mon fournisseur principal échoue ?

Configurez un bloc fallback_model dans config.yaml :²

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

Lorsque le fournisseur principal échoue (limite de débit, erreur serveur, échec d’authentification), Hermes bascule vers le repli en cours de session sans perdre l’historique de conversation. Cela se déclenche au maximum une fois par session.

L’agent peut-il améliorer ses propres skills au fil du temps ?

Oui — c’est la partie « auto-améliorante » de Hermes Agent. L’agent peut créer, mettre à jour et supprimer des skills via l’outil skill_manage. Lorsqu’il identifie un workflow non trivial, il enregistre l’approche sous forme de skill pour la réutiliser plus tard.¹¹ L’agent crée des skills après des tâches complexes (5 appels d’outils ou plus), lorsqu’il rencontre des erreurs et trouve le chemin qui fonctionne, lorsque vous corrigez son approche, ou lorsqu’il découvre un workflow non trivial.

Existe-t-il une intégration IDE ?

Oui — Hermes peut fonctionner comme serveur ACP (Agent Client Protocol) pour VS Code, Zed et JetBrains :⁶

pip install -e '.[acp]'
hermes acp

Journal des modifications

Références