02 - Configurer les modèles et providers dans Hermes Agent

Introduction

Après avoir installé Hermes Agent et vérifié que le CLI répond correctement, l'étape suivante est cruciale : choisir et configurer le modèle IA qui alimente l'agent. Le modèle détermine directement la qualité des réponses, la capacité à utiliser les outils, et le coût de chaque interaction. Cet article couvre en détail la configuration des providers, la gestion des clés API, le routing multi-provider, et les bonnes pratiques pour un setup stable et performant.

La commande hermes model : le point d'entrée central

Hermes fournit une commande interactive unique pour gérer toute la configuration liée aux modèles :

hermes model

Cette commande ouvre un menu interactif qui vous guide à travers :

• Le choix du provider (Anthropic, OpenRouter, DeepSeek, Nous Portal, GitHub Copilot, etc.)
• La sélection du modèle parmi ceux disponibles chez le provider
• La configuration de l'authentification (clé API ou OAuth)
• La configuration des modèles auxiliaires (vision, compression, extraction web)

Vous pouvez basculer de provider à tout moment — il n'y a aucun lock-in. Relancez hermes model, sélectionnez un autre provider, et la configuration est mise à jour instantanément.

Menu interactif en détail

Le menu de hermes model propose plusieurs entrées :

• Choose a provider : sélection parmi tous les providers supportés
• Configure auxiliary models : configurer les modèles secondaires (vision, web_extract, compression, etc.)
• View current configuration : récapitulatif de la configuration active

Cette approche interactive élimine la nécessité de fouiller dans les fichiers de configuration manuellement, même si la configuration directe reste possible pour les utilisateurs avancés.

Providers supportés

Hermes Agent supporte un large écosystème de providers. Voici les principaux, classés par type d'accès.

Providers avec authentification OAuth (sans clé API)

Ces providers utilisent un flux OAuth via le navigateur, idéal si vous ne voulez pas gérer de clés API :

• Nous Portal : abonnement mensuel, zéro configuration. Connexion via hermes model.
• OpenAI Codex : utilise les modèles Codex avec votre compte ChatGPT. Authentification par device code via hermes model.
• Anthropic (OAuth) : nécessite un plan Claude Max + crédits supplémentaires. L'authentification route via Claude Code.
• MiniMax (OAuth) : accès aux modèles MiniMax-M2.7 sans API key. Connexion navigateur via hermes model.
• GitHub Copilot : utilise votre abonnement Copilot pour accéder à GPT-5.x, Claude, Gemini, etc. OAuth via hermes model ou token COPILOT_GITHUB_TOKEN.

Providers avec clé API

Ces providers nécessitent une clé API obtenue depuis leur console respective :

• Anthropic (ANTHROPIC_API_KEY) : accès direct aux modèles Claude. Obtenez votre clé sur console.anthropic.com.
• OpenRouter (OPENROUTER_API_KEY) : le plus polyvalent, route vers des dizaines de modèles (Claude, GPT, Gemini, DeepSeek, Qwen, etc.). Clé sur openrouter.ai/keys.
• DeepSeek (DEEPSEEK_API_KEY) : accès direct aux modèles DeepSeek. Obtenez votre clé depuis la console DeepSeek.
• Google AI Studio (GOOGLE_API_KEY ou GEMINI_API_KEY) : modèles Gemini natifs. Clé sur aistudio.google.com.
• Hugging Face (HF_TOKEN) : route vers 20+ modèles open-source via un endpoint unifié. Obtenez votre token depuis les paramètres de votre compte Hugging Face.
• Alibaba Cloud / DashScope (DASHSCOPE_API_KEY) : modèles Qwen.
• Kimi / Moonshot (KIMI_API_KEY) : modèles de coding et chat Moonshot.
• NVIDIA NIM (NVIDIA_API_KEY) : modèles Nemotron.
• xAI (XAI_API_KEY) : modèles Grok.

Custom Endpoint (self-hosted)

Pour les utilisateurs qui font tourner leurs propres modèles via Ollama, vLLM, SGLang ou tout endpoint compatible OpenAI, sélectionnez "Custom Endpoint" dans le menu hermes model, puis indiquez la base URL et le nom du modèle. Vous pouvez aussi configurer cela manuellement avec les variables OPENAI_BASE_URL et OPENAI_API_KEY.

Stockage des configurations : .env vs config.yaml

Hermes sépare proprement les secrets de la configuration normale. Tout se trouve dans le répertoire ~/.hermes/, qui contient notamment config.yaml pour les paramètres non-secrets (modèle, terminal, compression), .env pour les clés API et tokens, ainsi que auth.json pour les credentials OAuth (Nous Portal, etc.).

Règle fondamentale

• Secrets (clés API, tokens, mots de passe) → ~/.hermes/.env
• Tout le reste (modèle, backend terminal, limites, toolsets) → ~/.hermes/config.yaml

La commande hermes config set

C'est la méthode recommandée pour modifier toute configuration. Elle route automatiquement la valeur au bon fichier :

hermes config set model anthropic/claude-sonnet-4
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxx

Cette commande distingue automatiquement les secrets (qui vont dans .env) des paramètres classiques (qui vont dans config.yaml). Utilisez hermes config pour voir la configuration complète, et hermes config edit pour ouvrir directement le fichier dans votre éditeur.

Priorité de résolution

Les paramètres sont résolus dans cet ordre (priorité décroissante) :

1. Arguments CLI : hermes chat --model anthropic/claude-sonnet-4 (override par invocation)
2. ~/.hermes/config.yaml : fichier de configuration principal
3. ~/.hermes/.env : fallback pour les variables d'environnement, requis pour les secrets
4. Valeurs par défaut : défauts intégrés sûrs quand rien n'est configuré

Configuration concrète par provider

Anthropic (Claude)

Lancez hermes model, choisissez "Anthropic", puis entrez votre clé API. Alternativement, en ligne de commande :

hermes config set model anthropic/claude-sonnet-4
hermes config set ANTHROPIC_API_KEY sk-ant-xxxxx

OpenRouter

Obtenez votre clé sur openrouter.ai/keys, puis configurez :

hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxx
hermes config set model anthropic/claude-opus-4

Les modèles populaires sur OpenRouter incluent anthropic/claude-opus-4 (raisonnement avancé), anthropic/claude-sonnet-4 (rapide, bon rapport qualité/prix), openai/gpt-4o (polyvalent) et google/gemini-2.5-flash (rapide, bon marché).

DeepSeek

hermes config set DEEPSEEK_API_KEY sk-xxxxx
hermes config set model deepseek/deepseek-chat

GitHub Copilot

Deux options d'authentification : via hermes model en choisissant "GitHub Copilot" pour un flux OAuth dans le navigateur, ou en configurant manuellement un token existant :

hermes config set COPILOT_GITHUB_TOKEN gho_xxxxx
hermes config set model github/copilot

Nous Portal

Lancez hermes model, choisissez "Nous Portal", puis suivez la connexion OAuth. Aucune clé API n'est requise.

Custom Endpoint (Ollama, vLLM, etc.)

Pour Ollama local, configurez OPENAI_BASE_URL sur http://localhost:11434/v1, OPENAI_API_KEY sur ollama, puis définissez le modèle (ex: llama3.1:70b). Pour vLLM, utilisez http://localhost:8000/v1 comme base URL avec un modèle comme meta-llama/Llama-3.1-70B-Instruct.

Exigence minimum : 64 000 tokens de contexte

Hermes Agent requiert un modèle avec au moins 64 000 tokens de fenêtre de contexte. Les modèles avec une fenêtre plus petite sont rejetés au démarrage.

Pourquoi cette exigence ? Les workflows multi-étapes de Hermes (tool-calling, lecture de fichiers, exécution de commandes) consomment rapidement du contexte. Un modèle avec 32K tokens n'a pas assez de mémoire de travail pour maintenir une conversation productive avec des appels d'outils.

La plupart des modèles hébergés (Claude, GPT, Gemini, Qwen, DeepSeek) dépassent largement ce seuil. Pour les modèles locaux via llama.cpp, passez l'argument --ctx-size 65536. Avec Ollama, utilisez le flag -c 65536 ou la variable de contexte appropriée.

Changer de modèle en une commande

Le switch entre providers ou modèles est instantané :

• Via hermes model (menu interactif)
• Via hermes config set model anthropic/claude-sonnet-4 (direct)
• Via la commande /model en session de chat pour une sélection interactive sans quitter la conversation

Aucun redémarrage n'est nécessaire. Le changement prend effet à la prochaine interaction.

Configurer les modèles auxiliaires

Hermes utilise des modèles secondaires pour des tâches spécifiques (vision, extraction web, compression de contexte). Par défaut, les tâches auxiliaires utilisent votre modèle principal. Vous pouvez les configurer indépendamment pour optimiser les coûts via le menu hermes model → "Configure auxiliary models".

Le menu interactif vous permet de configurer :

• vision : modèle pour l'analyse d'images
• web_extract : modèle pour la summarisation de pages web
• session_search : modèle pour la recherche dans les sessions passées
• title_generation : modèle pour générer les titres de session
• compression : modèle pour la compression du contexte

Par exemple, pour utiliser un modèle moins cher pour la compression, ajoutez dans ~/.hermes/config.yaml une section auxiliary avec la clé compression contenant le provider (ex: "openrouter") et le model (ex: "google/gemini-2.5-flash"). Le pattern universel pour chaque modèle auxiliaire est toujours le même : provider + model + optionnellement base_url.

Routing et fallback multi-provider

Fallback automatique

Configurez un modèle de secours qui prend le relais automatiquement si le provider principal rencontre une erreur. Dans ~/.hermes/config.yaml, ajoutez une section fallback_model avec le provider et le model de secours. Hermes tente d'abord le modèle principal, puis bascule vers le fallback après des erreurs transitoires (rate limits, timeouts, 5xx).

Provider routing

Pour les utilisateurs avancés qui veulent contrôler finement le routage, la section provider_routing dans config.yaml offre plusieurs options : sort ("price", "throughput" ou "latency"), only pour limiter aux providers autorisés, ignore pour en exclure, order pour définir l'ordre de fallback, require_parameters pour n'utiliser que les providers supportant tous les params, et data_collection (ex: "deny") pour exclure les providers qui stockent les données.

Rotation de credentials

Si vous avez plusieurs clés API pour un même provider, configurez la stratégie de rotation via la section credential_pool_strategies. Les options disponibles sont fill_first (défaut), round_robin (répartition équitable), least_used (toujours la clé la moins utilisée) et random.

Tester qu'un provider fonctionne

Avant de vous lancer dans des tâches complexes, vérifiez que votre configuration est fonctionnelle.

Étape 1 : Diagnostic

hermes doctor

Cette commande détecte les problèmes de configuration, les clés manquantes, et les incompatibilités.

Étape 2 : Conversation de test

Lancez hermes puis envoyez un prompt simple et vérifiable, comme demander de lister les fichiers du répertoire courant et d'identifier le langage principal du projet. Les signes de succès sont : la bannière de démarrage affiche votre modèle et provider, Hermes répond sans erreur, les outils fonctionnent (terminal, lecture de fichiers, etc.), et la conversation continue normalement sur plusieurs tours.

Étape 3 : Reprise de session

hermes --continue   # ou hermes -c

Vérifiez que la session précédente est bien reprise.

Dépannage rapide

Si quelque chose ne fonctionne pas, suivez cette séquence : lancez hermes doctor pour diagnostiquer, puis hermes model pour revérifier la configuration, hermes setup pour relancer le setup complet, et enfin hermes --continue pour tester la reprise.

Déploiement sur un VPS

Pour un déploiement en production (gateway Telegram, Discord, etc.), un VPS dédié est recommandé. Un VPS avec 2 vCPU et 4 Go de RAM suffit pour faire tourner Hermes avec le gateway.

Hostinger propose des VPS performants à partir de quelques euros par mois, idéaux pour héberger Hermes Agent en mode always-on. Configurez le backend terminal en Docker pour l'isolation :

hermes config set terminal.backend docker

Variables d'environnement essentielles

Voici un récapitulatif des variables les plus courantes, à placer dans ~/.hermes/.env ou à définir via hermes config set :

• OPENROUTER_API_KEY : clé OpenRouter
• ANTHROPIC_API_KEY : clé Anthropic
• DEEPSEEK_API_KEY : clé DeepSeek
• OPENAI_API_KEY : clé pour endpoint custom OpenAI-compatible
• OPENAI_BASE_URL : URL de base pour endpoint custom
• GOOGLE_API_KEY : clé Google AI Studio / Gemini
• COPILOT_GITHUB_TOKEN : token GitHub pour Copilot
• HF_TOKEN : token Hugging Face

Erreurs courantes

• "Context window too small" : votre modèle n'atteint pas les 64K tokens requis. Vérifiez la taille de contexte configurée, surtout pour les modèles locaux avec Ollama ou llama.cpp.
• Clé API non reconnue : assurez-vous d'avoir placé la clé dans ~/.hermes/.env via hermes config set, et non dans config.yaml. Les secrets doivent toujours aller dans le fichier .env.
• Timeout avec un custom endpoint : vérifiez que l'URL base se termine par /v1 et que le modèle est bien accessible (testez avec un simple curl).
• Fallback non déclenché : vérifiez que la section fallback_model est bien formatée dans config.yaml avec les clés provider et model.

FAQ

Puis-je utiliser plusieurs providers en même temps ?
Oui, via le système de provider routing et de fallback. Vous pouvez définir un provider principal et un ou plusieurs fallbacks, ou configurer un routage automatique par prix, latence ou débit.

Dois-je redémarrer Hermes après un changement de modèle ?
Non. Le changement de modèle via hermes config set, hermes model ou /model prend effet immédiatement à la prochaine interaction.

Comment savoir quel modèle auxiliaire est utilisé ?
Lancez hermes config pour voir la configuration complète, y compris les modèles auxiliaires. Si aucun n'est configuré explicitement, le modèle principal est utilisé pour toutes les tâches.

Les clés API sont-elles stockées en clair ?
Oui, dans ~/.hermes/.env. Protégez l'accès à ce fichier avec des permissions restrictives (chmod 600 ~/.hermes/.env).

Outils recommandés

• Hermes Agent : les 68 outils disponibles — guide complet : pour comprendre tous les outils que votre modèle configuré pourra invoquer
• Fichiers de contexte : CLAUDE.md, AGENTS.md et au-delà : pour configurer le contexte que le modèle recevra à chaque session
• Mémoire persistante : comment Hermes se souvient : pour combiner votre configuration modèle avec une mémoire à long terme

L'essentiel

• Utilisez hermes model pour la configuration interactive, hermes config set pour les ajustements rapides
• Séparez toujours les secrets (.env) des paramètres (config.yaml)
• Garantissez un minimum de 64K tokens de contexte
• Testez toujours avec hermes doctor et une conversation simple après chaque changement
• Configurez un fallback pour la continuité de service
• Optimisez les coûts en configurant des modèles auxiliaires moins chers pour les tâches secondaires

Conclusion

La configuration des modèles et providers dans Hermes Agent est conçue pour être accessible via hermes model tout en restant entièrement configurable manuellement pour les utilisateurs avancés. La séparation claire entre .env (secrets) et config.yaml (paramètres), le support de plus de 25 providers en 2025, et les mécanismes de fallback et routing offrent une flexibilité remarquable.

Pour aller plus loin, découvrez les 68 outils disponibles dans Hermes Agent et apprenez à structurer le contexte de vos sessions avec les fichiers CLAUDE.md et AGENTS.md.