Configurer Hermes Agent

Introduction

La configuration de Hermes Agent repose sur un fichier YAML principal (config.yaml), un fichier de secrets (.env) et un fichier d'authentification (auth.json). Cette page explique ou trouver ces fichiers, comment les modifier en securite, et comment gerer plusieurs configurations isolees.

La configuration est versionnee: chaque cle a une valeur par defaut definie dans le code source (662 cles au total, commit b4f8c491). Vous pouvez surcharger n'importe quelle cle via config.yaml ou via la commande hermes config set.

Les trois fichiers de configuration

config.yaml

Le fichier principal de configuration, situe dans ~/.hermes/config.yaml. Il contient tous les reglages non secrets: modele par defaut, toolsets actifs, timeouts, preferences d'affichage, configuration des canaux, etc.

Ce fichier est cree automatiquement au premier lancement de hermes setup ou hermes model. Il est edite en YAML et peut etre modifie manuellement ou via hermes config set.

.env

Le fichier ~/.hermes/.env stocke les secrets: cles API, tokens, identifiants. Il suit le format standard des fichiers d'environnement (CLE=valeur). Hermes Agent le charge au demarrage et injecte les variables dans le processus.

Ne mettez jamais de secrets dans config.yaml. Le fichier .env est separe precisement pour eviter de commiter des cles API par erreur.

auth.json

Le fichier ~/.hermes/auth.json stocke les tokens OAuth obtenus via hermes auth (pour Nous Portal, OpenAI Codex, Anthropic OAuth, etc.). Il est gere automatiquement par Hermes Agent: vous n'avez pas a l'editer manuellement.

Commandes essentielles

Afficher la configuration

hermes config          # affiche le chemin et un resume
hermes config show     # affiche le contenu complet

Modifier une option

hermes config set model.default "claude-sonnet-4-6"
hermes config set agent.max_turns 300
hermes config set timezone "Europe/Paris"

La commande hermes config set valide la cle et le type avant d'ecrire. Elle modifie uniquement config.yaml, jamais .env.

Gerer les secrets

hermes auth add openrouter    # ajoute une cle API OpenRouter
hermes auth list              # liste les providers authentifies
hermes auth status            # verifie l'etat des authentifications

Pour les cles API directes, editez ~/.hermes/.env:

echo 'OPENROUTER_API_KEY=sk-or-v1-...' >> ~/.hermes/.env

Valider la configuration

hermes doctor                 # diagnostique les problemes de configuration
hermes config                 # verifie que le fichier est syntaxiquement valide
hermes status                 # affiche l'etat agent, auth et plateforme

Gerer plusieurs configurations

Hermes Agent supporte les profils: des environnements isoles avec leur propre config.yaml, .env, historique de sessions, skills et plugins.

hermes profile create dev     # cree un nouveau profil "dev"
hermes profile use dev        # bascule vers le profil "dev"
hermes profile list           # liste tous les profils

Chaque profil a son propre repertoire sous ~/.hermes/profiles/<nom>/. Pour cloner un profil sans copier ses secrets:

hermes profile create staging --clone dev

Les secrets (.env et auth.json) ne sont pas copies par --clone: vous devrez les reconfigurer dans le nouveau profil.

Surcharger un reglage pour une invocation

Utilisez les options globales de hermes chat:

Attention : --yolo desactive les confirmations de securite. Hermes Agent peut executer des commandes destructrices sans vous demander d'autorisation. Utilisez cette option uniquement dans un environnement isole ou de test, et jamais sur une machine de production.

hermes chat --model "gpt-5" --provider openrouter
hermes chat --toolsets "hermes-cli,browser" --yolo
hermes chat --ignore-user-config    # utilise les defauts integres
hermes chat --safe-mode             # desactive TOUTES les personnalisations

Limiter les outils charges

Par defaut, Hermes Agent charge le toolset hermes-cli. Vous pouvez restreindre les outils:

# Dans config.yaml
toolsets:
  - hermes-cli

# Desactiver un toolset specifique
agent:
  disabled_toolsets:
    - browser

Ou en ligne de commande:

hermes chat --toolsets "hermes-cli"

Restaurer les valeurs par defaut

Pour revenir aux defauts sans perdre vos secrets:

hermes config set model.default ""   # vide la valeur, le defaut integre s'applique

Ou supprimez la section concernee de config.yaml. Les cles absentes heritent automatiquement des valeurs par defaut du code source.

Pour une reinitialisation complete de la configuration (hors secrets):

mv ~/.hermes/config.yaml ~/.hermes/config.yaml.bak
hermes setup    # recree un config.yaml propre

Sauvegarder avant une migration

Avant une mise a jour majeure ou une migration, sauvegardez:

hermes backup                        # cree un zip de ~/.hermes/
hermes config > ~/hermes-config-$(date +%Y%m%d).yaml   # export manuel

Les fichiers critiques a preserver:

• ~/.hermes/config.yaml
• ~/.hermes/.env
• ~/.hermes/auth.json
• ~/.hermes/profiles/ (tous les profils)

Questions couvertes

q-041: Ou se trouve le fichier config.yaml de Hermes Agent ?

Dans ~/.hermes/config.yaml. Ce chemin est fixe pour l'installation standard. Chaque profil a son propre config.yaml dans ~/.hermes/profiles/<nom>/config.yaml.

q-042: Comment modifier une option avec hermes config set ?

hermes config set <cle> <valeur>

Exemple: hermes config set timezone "Europe/Paris". La commande valide la cle et le type avant ecriture. Pour les cles imbriquees, utilisez la notation point: agent.max_turns.

q-043: Quelle difference entre config.yaml, .env et auth.json ?

• config.yaml: reglages non secrets (modele, timeouts, toolsets, preferences). Editable manuellement ou via hermes config set.
• .env: secrets (cles API, tokens). Format CLE=valeur. Charge au demarrage, jamais commite.
• auth.json: tokens OAuth geres automatiquement par hermes auth. Ne pas editer manuellement.

q-044: Comment gerer plusieurs configurations Hermes Agent ?

Utilisez les profils: hermes profile create <nom>, hermes profile use <nom>. Chaque profil a son propre config.yaml, .env, historique et skills. Pour cloner sans secrets: hermes profile create <nom> --clone <source>.

q-045: Comment surcharger un reglage pour une seule invocation ?

Avec les options de hermes chat: --model, --provider, --toolsets, --yolo, --ignore-user-config, --safe-mode. Ces options ne modifient pas config.yaml.

q-046: Comment configurer le fuseau horaire de Hermes Agent ?

hermes config set timezone "Europe/Paris"

Ou dans config.yaml:

timezone: Europe/Paris

La valeur par defaut est le fuseau horaire du systeme. Les noms de fuseaux suivent la norme IANA (ex: America/New_York, Asia/Tokyo).

q-047: Comment limiter les outils charges dans le prompt ?

Deux methodes:

1. Dans config.yaml: toolsets: [hermes-cli] et agent.disabled_toolsets: [browser]
2. En ligne de commande: hermes chat --toolsets "hermes-cli"

Les toolsets non listes ou explicitement desactives ne sont pas injectes dans le prompt systeme, ce qui reduit la consommation de tokens.

q-048: Comment restaurer les valeurs par defaut sans perdre ses secrets ?

Supprimez les cles concernee de config.yaml ou videz-les avec hermes config set <cle> "". Les secrets dans .env et auth.json ne sont pas affectes. Pour une reinitialisation complete: sauvegardez config.yaml, puis hermes setup.

q-049: Comment valider une configuration avant de lancer le gateway ?

hermes doctor       # diagnostic general
hermes config       # verification syntaxique
hermes status       # etat agent, auth et plateforme
hermes gateway status   # etat du gateway

Ces commandes detectent les erreurs de syntaxe YAML, les cles inconnues, les providers non configures et les problemes de permissions.

q-050: Quels reglages faut-il sauvegarder avant une migration ?

Les fichiers critiques: config.yaml, .env, auth.json, et le dossier profiles/. Utilisez hermes backup pour une sauvegarde complete en zip. Conservez aussi une copie manuelle de config.yaml et .env hors de ~/.hermes/.

Sources

• Documentation officielle Hermes Agent (https://hermes-agent.nousresearch.com/docs/)
• CLI commands reference (https://hermes-agent.nousresearch.com/docs/reference/cli-commands)
• Configuration defaults source (https://github.com/NousResearch/hermes-agent/blob/b4f8c491d3452926deb7628edbdb6fe2a85ff576/hermes_cli/config_defaults.py)
• Depot NousResearch/hermes-agent, commit b4f8c491

Liens internes proposes

• Modeles et providers
• Reference: Cles de configuration
• Profils et delegation
• Depannage
• Methodologie