Tutoriel 7 : Fichiers de configuration

Bienvenue, dompteurs d’agents ! Dans ce tutoriel, nous plongeons au cœur de Hermes : les fichiers de configuration. Si vous vous êtes déjà senti perdu dans une mer de YAML et de variables d’environnement, pas de panique — nous allons rendre cela aussi indolore que possible.

La Base de Hermes

Tout vit dans ~/.hermes/. Considérez-le comme l’appartement de votre agent. Voici ce qu’il contient :

~/.hermes/
├── config.yaml     # Paramètres (modèle, terminal, TTS, compression, etc.)
├── .env            # Clés API et secrets
├── auth.json       # Identifiants du fournisseur OAuth (Nous Portal, etc.)
├── SOUL.md         # Identité principale de l'agent (emplacement #1 dans le prompt système)
├── memories/       # Mémoire persistante (MEMORY.md, USER.md)
├── skills/         # Compétences créées par l'agent (gérées via l'outil skill_manage)
├── cron/           # Tâches planifiées
├── sessions/       # Sessions de passerelle
└── logs/           # Journaux (errors.log, gateway.log — secrets automatiquement masqués)

### Le Chemin le Plus Simple : Configuration en Une Commande

Avant d'entrer dans le vif du sujet, voici un conseil de pro : lancez `hermes setup --portal`. Un seul OAuth vous donne un fournisseur de modèle et les quatre outils Tool Gateway sans toucher à un seul fichier YAML. Les abonnés Portal bénéficient également de 10 % de réduction sur les fournisseurs facturés par token. C'est la façon paresseuse de démarrer, et on adore ça.

### Gérer Votre Configuration

Hermes vous offre une boîte à outils complète pour gérer les paramètres. Voici les commandes que vous utiliserez au quotidien :

```bash
hermes config              # Afficher la configuration actuelle
hermes config edit         # Ouvrir config.yaml dans votre éditeur
hermes config get KEY      # Afficher une valeur résolue
hermes config set KEY VAL  # Définir une valeur spécifique
hermes config unset KEY    # Supprimer une valeur définie par l'utilisateur
hermes config check        # Vérifier les options manquantes (après les mises à jour)
hermes config migrate      # Ajouter interactivement les options manquantes

Voici quelques exemples pratiques :

hermes config get model
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config unset terminal.backend
hermes config set OPENROUTER_API_KEY sk-or-...  # Enregistre dans .env

Le tour de magie : hermes config set achemine automatiquement les valeurs vers le bon fichier. Les clés API vont dans .env, tout le reste va dans config.yaml. Fini les devinettes !

Qu’est-ce qui Gagne en Cas de Conflit ?

Hermes résout les paramètres dans cet ordre (priorité la plus élevée en premier) :

Arguments CLI — comme hermes chat --model anthropic/claude-sonnet-4
~/.hermes/config.yaml — votre fichier de configuration principal
~/.hermes/.env — pour les secrets (clés API, jetons, mots de passe)
Valeurs par défaut intégrées — valeurs codées en dur et sûres

Règle d’or : Les secrets vont dans .env. Tout le reste va dans config.yaml. Lorsque les deux sont définis, config.yaml l’emporte pour les paramètres non secrets.

Substitution de Variables d’Environnement

Vous pouvez référencer des variables d’environnement dans config.yaml en utilisant la syntaxe ${VAR_NAME} :

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

delegation:
  api_key: ${DELEGATION_KEY}

Les références multiples fonctionnent aussi : url: "${HOST}:${PORT}". Si une variable n’est pas définie, l’espace réservé reste tel quel et un avertissement est journalisé. La syntaxe style Cursor ${env:VAR_NAME} fonctionne également, vous pouvez donc copier des extraits de configurations Cursor ou Claude sans modification.

Délais d’Attente des Fournisseurs

Vous pouvez définir des délais d’attente par fournisseur et par modèle :

providers:
  some-provider:
    request_timeout_seconds: 600
    models:
      some-model:
        timeout_seconds: 300

Il existe aussi stale_timeout_seconds pour détecter les appels non diffusés devenus obsolètes. Ces paramètres remplacent les variables d’environnement héritées HERMES_API_TIMEOUT et HERMES_API_CALL_STALE_TIMEOUT.

Limites d’Exécution

Pour les surfaces serveur de longue durée (passerelle, hermes serve --isolated), vous pouvez définir des limites de descripteurs de fichiers :

runtime:
  nofile_soft_limit: 4096

La valeur par défaut est 4096. Définissez-la sur 0, false ou null pour désactiver l’ajustement.

Comportement de Mise à Jour

Les paramètres de mise à jour vivent sous updates dans config.yaml :

updates:
  pre_update_backup: quick

Pour Conclure

Voilà pour la visite guidée de la configuration ! Rappelez-vous : hermes setup --portal pour le chemin facile, hermes config set pour les changements rapides, et gardez les secrets dans .env. Votre agent vous remerciera.

À suivre : nous explorerons les fournisseurs d’IA et comment connecter vos modèles préférés. Restez à l’écoute !