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 seule boucle de conversation que n’importe quel 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 aux éditeurs, l’exécuteur de lots et un serveur API.³ Tous finissent par appeler 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 indications d’outils via prompt_builder.py³
2. Résout le fournisseur d’exécution via runtime_provider.py — c’est l’étape qui choisit votre authentification, l’URL de base et le mode API³
3. Appelle le fournisseur avec l’un des trois modes API : chat_completions, codex_responses ou anthropic_messages³
4. Transmet tous les appels d’outils retourné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 compte, car chaque fonctionnalité — personalities, memory, skills, compression, fallback — se rattache à l’une de ces étapes. Quand vous lisez une clé de configuration et vous demandez 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, les lots et le serveur API. Les différences de plateforme se trouvent 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 distribué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 profiles 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 l’un de ceux-là.

Installation

L’installateur en une ligne reste le parcours guidé pour la plupart des utilisateurs. Il gère Python, uv, Node.js, ripgrep, ffmpeg, le clonage du dépôt, l’environnement virtuel et la commande globale hermes.⁷ v0.14.0 fournit aussi un vrai package PyPI : pip install hermes-agent devient donc 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 l’installation terminée :

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 du 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 facultatifs 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, et non 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 des wheels ctranslate2 qui ne sont pas publiées pour Android.⁷

Authentification et fournisseurs

Hermes prend en charge environ 19 fournisseurs de premier plan, ainsi que des endpoints personnalisés, et trois chemins d’authentification distincts. Voici toute la surface d’authentification, organisée par chemin afin que vous puissiez trouver celui qui correspond à votre cas.

Les trois chemins d’authentification

Chaque fournisseur dans Hermes correspond à l’un de ces trois schémas d’authentification :

Chemin 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 fournisseurs tiers.²

Chemin 2 — OAuth via hermes model ou hermes auth. Lance un flux de 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).²

Chemin 3 — endpoint personnalisé dans config.yaml. Pour n’importe quel 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.²

Matrice complète des fournisseurs

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

Anthropic : trois méthodes d’authentification

Anthropic dispose de sa propre section parce que Hermes prend en charge trois chemins distincts vers Claude, et choisir le bon 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 chemin 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 vers 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 PATs fine-grained (github_pat_* avec l’autorisation Copilot Requests) et les tokens d’application GitHub (ghu_*). Si votre gh auth token renvoie un token ghp_*, utilisez plutôt hermes model pour vous authentifier via OAuth.²

Fournisseurs IA chinois (prise en charge de premier plan)

Hermes inclut une prise en charge intégrée de z.ai/GLM, Kimi/Moonshot, MiniMax (endpoints globaux + Chine) et Alibaba Cloud avec des IDs de fournisseur 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 fournisseur z.ai/GLM, Hermes teste plusieurs endpoints (global, Chine, variantes coding) afin d’en trouver un qui accepte votre clé API. L’endpoint fonctionnel est automatiquement mis en cache — pas besoin de GLM_BASE_URL pour la plupart des utilisateurs.²

xAI (Grok) active automatiquement la mise en 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 nécessaire.

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 le même fournisseur — utile pour répartir les limites de débit sur plusieurs clés sans modifier 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 n’importe quel 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 fournisseur 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 aveuglément si vous les utilisez à cet endroit.)⁴

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é — pratique pour les serveurs locaux exécutant un seul modèle.²

Serveurs LLM locaux (modèles de configuration)

La documentation upstream contient des guides de configuration 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 — chemin local le plus simple, zéro 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 24 Go 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 une utilisation agentique, 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

Le tool calling nécessite --enable-auto-tool-choice et --tool-call-parser <name>. Analyseurs 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 sous forme de texte brut.²

SGLang — service rapide avec RadixAttention pour réutiliser le KV cache :

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 requis pour le tool calling. Sans cela, llama-server ignore entièrement le paramètre tools et le modèle tente d’appeler les outils en écrivant du JSON dans son texte de réponse — ce que Hermes ne peut pas analyser comme de véritables appels d’outils.²

LM Studio — application desktop avec interface graphique :

Démarrez le serveur depuis l’application 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 déclarent 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 (idéalement 32768), puis rechargez le modèle.²

Fournisseurs personnalisés nommés

Si vous travaillez avec plusieurs endpoints personnalisés (par exemple un serveur de développement local et un serveur GPU distant), définissez-les comme fournisseurs 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

Vous pouvez ensuite passer de l’un à l’autre en cours de session avec la triple syntaxe :

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

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

Architecture de fournisseurs enfichables (v0.13.0+)

v0.13.0 fournit une ABC ProviderProfile ainsi qu’un dossier plugins/model-providers/ afin que des fournisseurs d’inférence tiers puissent s’intégrer sans modification du cœur.¹⁸ Si un fournisseur parle un mode API compatible OpenAI, Anthropic ou Codex, vous pouvez implémenter une sous-classe ProviderProfile qui déclare le chemin 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 fournisseurs intégrés. C’est le changement architectural derrière l’expansion des fournisseurs en v0.13.0 : au lieu de modifier le code du cœur pour ajouter un fournisseur, vous livrez un plugin.

Proxy local compatible OpenAI (v0.14.0+)

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

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 — la limite 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 la détection automatique se trompe sur la taille de 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 : remplacement dans la configuration → fournisseur 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 fournisseur, de sorte qu’un même modèle peut avoir des limites de contexte différentes selon qui le sert (par exemple, claude-opus-4.6 est à 1M sur Anthropic direct, mais à 128K sur GitHub Copilot).²

Rotation des fournisseurs et repli

Pools d’identifiants. Lorsque vous disposez de plusieurs clés API pour le même fournisseur, configurez une stratégie de rotation via hermes auth. C’est ainsi que vous répartissez les limites de débit sur 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 fournisseur en cours de session sans perdre votre conversation. Il se déclenche au maximum une fois par session.² Fournisseurs 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 secondaires : analyse d’images, résumé de pages web, analyse de captures d’écran du navigateur, classification d’approbation des commandes dangereuses, compression du contexte, résumé de recherche de session, correspondance de skill, dispatch de l’outil MCP et vidage de la mémoire.⁴ Par défaut, ils utilisent Gemini Flash via auto-détection (OpenRouter → Nous → Codex).

Vous pouvez configurer le modèle et le fournisseur utilisés par chaque tâche auxiliaire. Chaque emplacement 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 fournisseur "main" signifie « utiliser le fournisseur actuellement utilisé par mon agent principal » — valable uniquement dans les configurations auxiliary:, compression: et fallback_model:. Elle n’est pas valide pour votre paramètre model.provider de premier niveau. 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 avez seulement configuré Anthropic OAuth (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 d’abord OpenRouter. Ajoutez une OPENROUTER_API_KEY pour les tâches auxiliaires, ou reconfigurez chaque emplacement auxiliaire pour utiliser votre fournisseur principal :

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

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

Système de configuration

Hermes dispose d’un système de configuration en couches. Comprendre la précédence 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 voyez pas 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}

Gestion de 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 repèrent les nouvelles options de configuration ajoutées que votre fichier ne contient pas encore.⁶

Précédence de la configuration

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

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

Les flags CLI l’emportent toujours pour cette invocation unique. config.yaml reste 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 tableau de bord web, ajoute 8 locales supplémentaires et porte le total à 16.¹⁹ La documentation est actuellement localisée uniquement en zh-Hans. La locale est déterminée à partir des variables d’environnement LC_ALL / LANG ou d’une clé explicite locale: dans config.yaml. L’anglais reste la langue par défaut et la source de vérité pour toute chaîne qu’une traduction ne couvre pas encore.

Profils — Plusieurs instances Hermes isolées

Les profils vous donnent plusieurs instances Hermes isolées, chacune avec sa propre configuration, ses sessions, ses skills, sa mémoire et son PID gateway. C’est ainsi que vous exécutez « Hermes professionnel » 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 profil obtient son propre HERMES_HOME (~/.hermes-<name>/ par défaut), ce qui permet à plusieurs profils d’exécuter le gateway simultanément sans se marcher dessus.⁶³

Commandes CLI

Cette section constitue la référence praticien des commandes CLI de premier niveau. Pour la référence officielle dérivée du code, consultez le document CLI Commands Reference en amont.⁶

Options globales

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

Commandes de premier niveau

hermes chat — Le point d’entrée principal

hermes sans argument lance 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 principales :

hermes setup — L’assistant complet

Lance l’assistant de configuration complet ou accède 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êtes structurées sur les journaux

hermes logs est plus puissant qu’un simple tail -f sur les fichiers de journaux, car il prend en charge le filtrage simultané par niveau, identifiant 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 de journaux se trouvent dans ~/.hermes/logs/ :⁶ - agent.log — toute l’activité de l’agent (appels API, dispatch d’outils, cycle de vie des sessions, INFO+) - errors.log — avertissements et erreurs uniquement (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 — recherchez agent.log.1, agent.log.2, etc.⁶

hermes doctor — Diagnostics

hermes doctor [--fix] est la première commande à exécuter en cas de problème. 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 — cette 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 façon identique 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 infos

Commandes slash dynamiques des skills

Chaque skill installée est automatiquement exposée 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 aussi 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 : taper /h se résout en /help, /mod se résout en /model. Lorsqu’un préfixe est ambigu, le premier enregistrement dans l’ordre du registry l’emporte. Les noms complets de commandes et les alias enregistrés ont toujours la priorité sur les correspondances par préfixe.⁹

Commandes propres à la messagerie

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

• /status — afficher les informations de session
• /sethome (alias /set-home) — marquer 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.⁹

Outils et toolsets

Hermes est livré avec un vaste registre d’outils intégrés couvrant la recherche web, l’automatisation du 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 selon la plateforme.

Catégories générales

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

Gérer les 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 afin que le nouvel ensemble d’outils prenne effet.⁹

Backends de terminal

L’outil de 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 packages installés, les fichiers et la config persistent d’une session à l’autre.¹⁰

Tous les backends de conteneur s’exécutent avec un renforcement 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 escalade de privilèges, limites PID (256 processus), isolation complète par espaces de noms, espace de travail persistant via des volumes.¹⁰

Processus en arrière-plan

L’outil de terminal prend en charge l’exécution en arrière-plan avec 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 des 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.¹⁰

Kanban multi-agent (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.¹⁸ Le tableau permet à un essaim de workers Hermes de réellement terminer le travail, au lieu de se bloquer sur des handoffs morts.

Le tableau Kanban s’associe naturellement à /goal (boucle Ralph à cible verrouillée) côté cible, ainsi qu’à l’outil delegate_task existant pour la sémantique de spawn. Le résultat est un schéma d’essaim où chaque agent partage une source de vérité unique pour savoir quoi faire ensuite, qui s’en charge et ce qui est bloqué.

Système de skills

Les skills sont des documents de connaissances à la demande que l’agent peut charger lorsqu’il en a besoin. Elles suivent un modèle de divulgation progressive pour réduire l’utilisation des tokens et sont compatibles avec le standard ouvert agentskills.io.¹¹

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

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 de la 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 : la skill intégrée duckduckgo-search utilise fallback_for_toolsets: [web]. Lorsque FIRECRAWL_API_KEY est défini, le toolset web est disponible et l’agent utilise web_search — la skill DuckDuckGo reste masquée. Sans la clé API, la skill DuckDuckGo apparaît automatiquement comme fallback.¹¹

Skills gérées 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 comprend un workflow non trivial, il enregistre l’approche sous forme de skill pour la réutiliser plus tard.¹¹

Quand l’agent crée des skills :¹¹ - Après avoir mené à bien une tâche complexe (5 appels d’outils ou plus) - Lorsqu’il a rencontré des erreurs ou des impasses et trouvé la voie qui fonctionne - Lorsque l’utilisateur a corrigé son approche - Lorsqu’il a découvert un workflow non trivial

Actions :¹¹

Hub de skills

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é

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

Niveaux de confiance :¹¹

--force peut contourner les blocages de politique non dangereux pour les skills communautaires. Il ne contourne pas un verdict d’analyse dangerous.¹¹

Dossiers de skills externes

Vous pouvez faire pointer Hermes vers des dossiers de skills supplémentaires, analysés avec le 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 une 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 limitée et organisée qui persiste d’une session à l’autre. Deux fichiers constituent 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 de snapshot figé au démarrage de la session. L’agent gère sa propre mémoire via l’outil memory — add, replace ou remove.¹²

Pattern de snapshot 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 intentionnel : 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.¹²

Que sauvegarder

À sauvegarder (l’agent le fait de manière proactive) :¹² - Préférences utilisateur : « Je préfère TypeScript à JavaScript » → user - Faits sur l’environnement : « Ce serveur exécute Debian 12 avec PostgreSQL 16 » → memory - Corrections : « N’utilisez pas sudo pour les commandes Docker, l’utilisateur fait partie du 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

À ignorer :¹² - Informations triviales ou évidentes - Faits faciles à retrouver - Dumps de données brutes (trop volumineux pour la mémoire) - Éléments éphémères propres à une 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 une recherche plein texte FTS5. Les requêtes renvoient des conversations passées pertinentes, avec synthèse par Gemini Flash.¹²

Fournisseurs de mémoire externes

Pour une mémoire persistante plus approfondie 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 s’exécutent 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 intersessions :⁶¹²

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 gardent la session active en vie 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 lorsque le processus redémarre.

Checkpoints v2 (v0.13.0+)

La persistance d’état est réécrite en v0.13.0 sous la forme d’une conception à stockage unique, avec véritable élagage, garde-fous disque et aucun dépôt fantôme orphelin.¹⁸ L’ancien système de checkpoint accumulait de l’état sur disque dans les profiles de longue durée ; le store v2 impose un plafond strict au stockage local des checkpoints et supprime la comptabilité dupliquée qui provoquait cette croissance. Aucun changement de configuration côté 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 cherche pas dans le dossier de travail courant. La personnalité reste ainsi prévisible d’un projet à l’autre.¹³

Ce qui a sa place dans SOUL.md

Utilisez-le pour des 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 et l’ambiguïté

À utiliser moins pour :¹³ - instructions ponctuelles propres à un projet - chemins de fichiers - conventions de repo - détails temporaires de workflow

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

SOUL.md vs AGENTS.md

Voici la distinction la plus importante dans la gestion de l’identité Hermes :¹³

SOUL.md — identité, ton, style, valeurs 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 repo, 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 que vous pouvez activer 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.

Passez ensuite à /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 du brainstorming.

Nous Tool Gateway (v0.10.0+)

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

Contenu du 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écomptés 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 de paliers sont publiés sur la page de tarification Nous Portal (https://portal.nousresearch.com/pricing). Ce guide n’énumère pas les paliers, car ils relèvent du produit Portal, pas du CLI Hermes, et changent indépendamment des versions de Hermes. Inscrivez-vous sur https://portal.nousresearch.com/ et consultez la page de tarification pour connaître les paliers actuels.

Avis de dépréciation

• La variable d’environnement HERMES_ENABLE_NOUS_MANAGED_TOOLS est supprimée dans v0.10.0. Les outils gérés sont désormais activés via le champ de configuration par outil use_gateway et conditionnés par 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, et toutes les fonctionnalités de base (CLI, skills, mémoire, gateway de messagerie, cron, MCP, dashboard local, BYOK pour chaque fournisseur) fonctionnent de bout en bout sans payer qui que ce soit. v0.10.0 ajoute un chemin pratique pour les utilisateurs qui paient déjà Nous Portal — il ne retire rien au parcours gratuit.

Messaging Gateway

Hermes peut s’exécuter 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, et un adaptateur Webhook générique.^320171819 La v0.9.0 a ajouté iMessage via BlueBubbles (enregistrement automatique du webhook, assistant de configuration, résilience aux crashs) et la prise en charge native de WeChat via iLink Bot API, avec le mode de callback WeCom pour les apps d’entreprise.¹⁶ La v0.11.0 a ajouté QQBot.²⁰ La v0.12.0 a ajouté Microsoft Teams et Tencent Yuanbao.¹⁷ La 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 des hooks de plugin génériques env_enablement_fn / cron_deliver_env_var.¹⁸ La v0.14.0 ajoute LINE et SimpleX Chat et complète la stack Microsoft Teams de bout en bout avec l’auth Graph, le listener webhook, le runtime de pipeline et la livraison sortante.¹⁹

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, identifiants de bots, mappings de canaux, listes d’autorisation.⁶

Fonctionnement du flux de messages

D’après la documentation d’architecture en amont :³

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 dans les deux contextes, et pourquoi une tâche cron planifiée dans Telegram peut livrer sa sortie dans Discord — la différence de plateforme ne se trouve qu’à la périphérie.³

Autorisation utilisateur et appairage

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’appairage empêchent des inconnus de parler à votre gateway. Un utilisateur envoie un code d’appairage 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, où les jobs sont des tâches d’agent, et non des commandes shell. Chaque job planifié s’exécute dans un nouveau AIAgent avec le prompt configuré, des skills attachées en option, et livre les résultats vers 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 de façon conversationnelle 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 afin de 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 pour la compression.⁴

Avertissements de pression sur le budget

Quand l’agent travaille sur une tâche complexe avec de nombreux appels de tools, il peut consommer 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 possède deux couches de timeout qui s’ajustent automatiquement pour les providers locaux (localhost, IP LAN) :⁴

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

Dashboard Web local (v0.9.0+)

Un dashboard basé sur navigateur pour gérer votre Hermes Agent localement. 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 patterns à 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 suivez les logs de build — le tout sans polling. Combiné à notify_on_complete de la v0.8.0 (qui notifie la fin des tâches 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 slot enfichable via hermes plugins. Remplacez-le par des context engines personnalisés qui contrôlent ce que l’agent voit à chaque tour — filtrage, résumé ou injection de contexte propre à un domaine.¹⁶ Cela découple la stratégie de contexte de la boucle principale de l’agent, permettant 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 cette fonctionnalité pour migrer entre machines, créer des snapshots avant des changements majeurs, ou partager une configuration validée avec vos coéquipiers.

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

Hermes s’exécute nativement sur Android via Termux. Les chemins d’installation adaptés, les optimisations TUI pour é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é une valeur par défaut dans l’intérêt de l’utilisateur.¹⁸ v0.14.0 poursuit avec 12 autres corrections P0 et 50 P1, notamment le renforcement contre la force brute sudo / sudo-stdin, des correctifs de contournement de commandes dangereuses, l’assainissement des erreurs d’outils avant leur 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é de la chaîne d’approvisionnement 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 inter-serveurs Discord et deux fenêtres TOCTOU ; v0.14.0 ajoute une nouvelle 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 les 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 documents d’architecture upstream.³

Points d’entrée → AIAgent

Chaque point d’entrée dans Hermes finit par appeler 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 documents d’architecture upstream.³

« 47 tools / 20 toolsets » contre « 28 tools » dans votre bannière. Le décompte « 47 tools » correspond au registre total d’outils du dépôt upstream : tous les outils livrés par Hermes avec leur code source, tous toolsets confondus. Votre CLI réellement exécuté affichera un nombre plus faible dans sa bannière de démarrage (l’installation sur laquelle j’ai vérifié ce guide indique 28 tools / 89 skills). Ce n’est pas un bug. De nombreux 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 profil actuel ». Vérifiez quels toolsets sont actifs avec hermes tools --list et activez ou désactivez les toolsets individuellement avec le bloc toolsets: dans ~/.hermes/config.yaml (ou /tools list / /tools enable <name> / /tools disable <name> dans une session en cours : la suppression d’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 fournisseurs 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 fournisseurs, 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

Depuis la page d’architecture upstream.³

Ordre d’assemblage du prompt

La pile de prompts comprend :¹³

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

SOUL.md est la fondation — tout le reste s’appuie 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 entre 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 fournisseurs de mémoire sont 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 upstream :³

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) puis écrit dans ~/.hermes.⁶

Importés directement (30+ catégories) : SOUL.md, MEMORY.md, USER.md, AGENTS.md, skills provenant de 4 dossiers sources, modèle par défaut, fournisseurs personnalisés, serveurs MCP, tokens et listes d’autorisation des plateformes de messagerie (Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Mattermost), valeurs 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, configuration TTS, paramètres de navigateur, paramètres d’outils, délai d’expiration exec, liste d’autorisation des commandes, configuration de gateway et clés API provenant de 3 sources.⁶

Archivés pour examen manuel : tâches cron, plugins, hooks/webhooks, backend mémoire (QMD), configuration du registre de skills, UI/identité, journalisation, configuration multi-agent, associations 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 configuration → ~/.openclaw/.env → auth-profiles.json.⁶

Dépannage

« API key not set »

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 précisément quelles clés sont manquantes.⁷

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

Hermes détecte automatiquement la longueur du contexte depuis l’endpoint /v1/models de votre serveur, mais de nombreux serveurs locaux rapportent des valeurs par défaut faibles. 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 comme du texte au lieu de s’exécuter

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

Les réponses sont coupées en milieu de phrase

Deux causes possibles :²

1. Plafond de sortie faible (max_tokens) sur le 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 de contexte dans Hermes.

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

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

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

[wsl2]
networkingMode=mirrored

Puis wsl --shutdown et redémarrez. localhost fonctionne désormais de manière bidirectionnelle.

Repli sur l’IP de l’hôte (Windows plus anciens) : 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

Vous devez également faire en sorte que le serveur de modèle écoute sur 0.0.0.0, et non sur 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 quoi ?

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

FAQ

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

Claude Code est le CLI officiel de Anthropic, verrouillé sur les 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 embarque également une passerelle de messagerie pour Telegram/Discord/Slack/WhatsApp/Signal que Claude Code n’a pas.

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

Oui. Trois façons :²

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 un ANTHROPIC_TOKEN manuel (setup-token ou jeton OAuth) en repli

L’option 2 est à privilégier si vous utilisez déjà Claude Code sur la même machine — elle conserve les identifiants Claude rafraîchissables.

Comment changer de fournisseur sans perdre ma conversation ?

Utilisez /model provider:model à l’intérieur d’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 la vision/le web/la compression ne fonctionnent pas

Vous touchez au 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 détection automatique (OpenRouter → Nous → Codex). Si aucun de ces fournisseurs n’est configuré et que vous n’avez paramétré que Anthropic, ces fonctionnalités se dégradent silencieusement.⁴

Correctif : soit ajoutez une OPENROUTER_API_KEY pour les tâches auxiliaires, soit reconfigurez les emplacements auxiliaires pour utiliser votre fournisseur principal. Notez que la compression de contexte vit dans son propre bloc compression: de niveau supérieur 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, valeurs par défaut de communication. Il vit dans ~/.hermes/SOUL.md et vous suit partout. AGENTS.md est spécifique au projet — architecture, conventions, commandes, chemins — et vit dans votre répertoire de projet.¹³ Si cela doit vous suivre partout, SOUL.md. Si cela appartient à un projet, AGENTS.md.

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

Les profiles. Chaque profile dispose de son propre HERMES_HOME, configuration, mémoire, sessions et 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 LLM locaux ?

Oui, via le chemin d’endpoint personnalisé. Hermes fonctionne avec tout serveur compatible OpenAI : Ollama, vLLM, SGLang, llama.cpp/llama-server, LM Studio, LocalAI, Jan, ou le vôtre.² Voir Custom & Self-Hosted Endpoints pour la configuration par serveur.

Pourquoi ma bannière de démarrage affiche-t-elle moins d’outils que ce que le guide indique pour Hermes ?

Le guide cite 47 outils / 20 toolsets depuis le registre d’architecture amont — c’est le total des outils dont Hermes embarque le code source à travers tous les toolsets. Votre installation en cours d’exécution affiche un nombre plus petit dans la bannière (l’installation de référence utilisée pour ce guide rapporte 28 outils) parce que Hermes n’active que l’ensemble de toolsets par défaut au démarrage. De nombreux toolsets sont opt-in : les adaptateurs de la passerelle de messagerie, l’automatisation de navigateur, les 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 profile 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 forme).

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 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. Se déclenche au plus une fois par session.

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

Oui — c’est la partie « auto-amélioration » 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 en tant que skill pour une réutilisation future.¹¹ L’agent crée des skills après des tâches complexes (5+ appels d’outils), 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 s’exécuter en tant que serveur ACP (Agent Client Protocol) pour VS Code, Zed et JetBrains :⁶

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

Journal des modifications

Références