Hermes Agent : comprendre et régler la config sans tout casser

À ce stade, Hermes Agent est installé, la commande hermes répond, et tu as déjà branché un modèle, distant ou local, avec hermes model. La chaîne marche. Sauf qu’à la première fois où tu veux changer quelque chose, tu te retrouves devant un dossier utilisateur, un fichier YAML, et l’envie raisonnable de ne pas tout casser pour un seul réglage.

Ce tuto règle ça. On va regarder ce que Hermes a écrit, comprendre ce qui compte vraiment dans sa config, et poser une méthode simple pour modifier un paramètre sans casser le reste. Pas un catalogue exhaustif de champs, pas une recopie de la doc officielle : un tuto de lecture et de réglage, qui te sort du mode “je clique et j’espère”.

Ce que tu auras à la fin
Tu sauras où vit la config Hermes, à quoi servent les blocs qui comptent au début, comment savoir si Hermes parle à un provider distant ou à un endpoint local, et comment modifier un réglage proprement, une chose à la fois, avec vérification.

Pour qui est ce tuto
Tu as déjà suivi l’installation et le branchement d’un modèle local. Tu veux arrêter de subir la config au lieu de la comprendre. Ici on stabilise la base : les MCP et les tools avancés, c’est pour plus tard dans la série.

Pourquoi la config Hermes mérite d’être comprise

La tentation, au début, c’est de copier une config trouvée sur un fil Discord, d’écraser son fichier, de relancer hermes et de voir si “ça passe”. Ça peut marcher une fois. Le problème arrive souvent plus tard, quand quelque chose se comporte bizarrement et que tu ne sais plus ce qui vient de ton setup et ce qui vient de la config d’un inconnu.

La config de Hermes décide réellement du comportement de l’agent. Elle dit à qui il parle, avec quel modèle, dans quel environnement il exécute ses commandes, quelle “quantité de réflexion” il met dans ses réponses, quels outils sont actifs. Elle n’est pas cosmétique. C’est l’ADN runtime de ton agent.

La logique TekBrut tient en une ligne : comprendre avant d’empiler. Tant que tu ne lis pas ta propre config, tu ne sais pas ce que tu corriges quand quelque chose déraille. Et tu finis par changer cinq trucs à la fois pour un seul symptôme.

Où vit la config Hermes

Hermes Agent range tout ce qui est personnel dans un dossier utilisateur dédié : ~/.hermes/. C’est le même répertoire, quelle que soit ta machine, tant que tu restes sur Linux, macOS ou WSL2, qui font partie des environnements supportés officiellement.

Dans ce dossier, deux fichiers comptent au début :

~/.hermes/config.yaml : la config principale, en YAML. C’est là que Hermes écrit les réglages que tu modifies via hermes model, hermes tools, hermes setup ou hermes config set.
~/.hermes/.env : le fichier de variables d’environnement. C’est là que vivent tes secrets, comme les clés API des providers distants, les tokens d’outils, ou d’autres credentials.

La séparation n’est pas décorative. Les réglages de comportement vont dans config.yaml. Les secrets vont dans .env. Tu n’as pas à mélanger les deux, et tu n’as surtout pas à coller une clé API au milieu du YAML.

Si tu veux vérifier proprement les chemins au lieu d’aller fouiller à la main, Hermes expose directement les deux commandes utiles :

hermes config path
hermes config env-path

À côté de ces deux fichiers, le dossier contient aussi les sessions, les skills, les logs, les mémoires et quelques caches. Ce n’est pas de la config au sens strict : tu n’as pas à y toucher à la main tant que tu ne sais pas précisément ce que tu fais.

Ce que `hermes model` change réellement

hermes model n’est pas un bouton magique. C’est un assistant interactif qui te fait choisir un provider, puis un modèle exposé par ce provider, et qui écrit ton choix dans la config. Point. Aucun téléchargement de modèle, aucune modification cachée ailleurs.

Concrètement, après un hermes model, deux choses ont bougé :

Dans config.yaml, le bloc qui décrit le provider actif et le modèle à utiliser a été mis à jour.
Si ton provider a besoin d’une clé API et que tu l’as collée pendant l’assistant, elle a été stockée côté secrets, pas en clair dans le YAML.

C’est exactement pour ça que le tuto précédent te faisait faire hermes config show après un branchement llama.cpp : la commande n’a pas touché autre chose, mais ce qu’elle a touché mérite d’être relu à l’œil nu.

Le réflexe à prendre est simple : après chaque passage dans hermes model, tu vas relire ta config. Pas pour douter de l’outil, pour t’habituer à reconnaître ce qui bouge quand tu fais bouger quelque chose.

Les blocs de config qui comptent vraiment au début

Tu n’as pas besoin de tout connaître. Au début, quatre éléments suffisent à comprendre ce qui se passe.

Le provider. C’est qui parle à Hermes côté LLM. Nous Portal, OpenRouter, un provider OpenAI-compatible maison, ou ton propre endpoint local. Le provider décide du format d’API, du type d’authentification, et de la liste de modèles disponibles. Quand tu changes de provider, tu changes souvent trois choses en même temps sans t’en rendre compte.

Le modèle. C’est l’identifiant précis du modèle utilisé dans ce provider. Il est presque toujours textuel. Un modèle change le comportement de l’agent bien plus qu’on ne le pense : vitesse, qualité, respect des outils, coût.

Le base_url. C’est l’URL à laquelle Hermes envoie ses requêtes pour ce provider. Pour les providers officiels, elle est implicite ou fixée par défaut. Pour un endpoint local, c’est elle qui fait tout : si elle ne pointe pas sur le bon port de la bonne machine, rien ne marchera, peu importe à quel point le modèle est bien chargé.

La clé API, quand elle existe. Elle vit côté .env, sous forme de variable d’environnement. Pour un endpoint local, il n’y en a souvent pas besoin, ou alors une valeur factice acceptée par le serveur. Pour un provider distant, elle est non négociable.

À côté de ces quatre-là, Hermes a d’autres sections visibles dans l’exemple officiel, comme le terminal, l’agent, la compression, les tools ou d’autres réglages plus avancés. Tu peux les ignorer tant que tu n’as pas un besoin précis. Régler par besoin, pas par curiosité.

Savoir si Hermes parle au bon endpoint

C’est l’erreur qui coûte le plus d’heures au début : tu crois tester ton modèle local, mais Hermes envoie tranquillement tes requêtes à un provider distant, parce que ton dernier hermes model pointait encore là-bas.

La distinction entre distant et local se lit assez facilement dans la config une fois que tu sais où regarder. Deux signes concrets :

L’URL du provider. Une URL qui pointe sur localhost, 127.0.0.1 ou l’IP privée de ta machine WSL, c’est local. Une URL en https://... sur un domaine public, c’est distant.
La présence, ou l’absence, d’une clé API active. Un provider distant sans clé, ça ne marche pas. Un endpoint local qui exige une clé, c’est rare.

Si tu as un doute, la méthode la plus propre reste la même qu’au tuto précédent : relis la config avec les outils officiels. hermes config te donne la vue d’ensemble, hermes config show est la forme explicite pour afficher l’état courant, hermes status résume rapidement ce qui est actif, et hermes doctor aide à repérer les incohérences plus larges.

Ensuite, pose une question à Hermes, et regarde ce qui se passe, côté terminal qui affiche la réponse, et côté serveur local si tu en as un qui tourne. Si ton llama-server n’affiche aucune activité alors que Hermes répond, tu es en train de taper un provider distant sans le savoir.

Modifier la config sans casser le setup

La règle tient en une phrase : tu changes une chose à la fois.

Ça paraît évident écrit comme ça. Dans la pratique, c’est la discipline la plus difficile à tenir, parce que quand un truc ne marche pas, la tentation naturelle est de tout ajuster en même temps “pour aller plus vite”. Tu ne vas pas plus vite. Tu te retrouves avec un état dont tu n’es plus capable de diagnostiquer quoi que ce soit.

La méthode propre ressemble à ça :

Sauvegarde ton fichier avant une modif non triviale. Une copie config.yaml.bak à côté, datée si tu veux. Deux secondes de travail, zéro risque.
Identifie exactement le paramètre que tu veux changer. Provider ? Modèle ? base_url ? Un réglage dans une autre section ? Nomme-le.
Fais la modif par le chemin le plus propre. Pour un provider ou un modèle, passe par hermes model plutôt que d’éditer le YAML à la main. Pour un réglage individuel et précis, hermes config set est prévu exactement pour ça. Pour une édition fine sur une section que tu comprends, un éditeur de texte est acceptable, mais tu ne touches qu’à la ligne concernée.
Relis le bloc modifié. Ouvre le fichier, regarde ce qui a changé, confirme qu’aucune autre ligne n’a bougé par accident.
Teste. Lance hermes, pose une question courte, observe la réponse et, si tu as un endpoint local, ton serveur.
Puis seulement, passe à la modif suivante.

Ce n’est pas une méthode scolaire pour débutants. C’est la seule méthode qui tient dans le temps. Un setup Hermes propre, ce n’est pas un setup compliqué : c’est un setup dont tu connais chaque ligne qui a été bougée.

Le premier vrai contrôle utile après modification

Pas besoin d’une checklist de vingt points. Après une modif, trois commandes officielles suffisent à savoir si tu es dans un état sain.

hermes config show
hermes status
hermes doctor

hermes config show te montre l’état courant tel que Hermes le voit réellement, ce qui compte, parce que tu veux vérifier que le fichier que tu as édité est bien celui que Hermes a relu. hermes status te donne un résumé plus court et plus orienté “tout est en place ou pas”. hermes doctor te sort un diagnostic plus large : dépendances, providers joignables, problèmes évidents.

Si les trois tombent d’accord et que ton changement est bien visible, tu peux passer au test de conversation. Si l’un d’eux hurle, tu corriges avant de relancer une conversation. Le pire réflexe à ce stade, c’est de lancer hermes et de se dire “on verra bien” : tu vas polluer tes logs et ta session avec un état déjà cassé.

Les erreurs de config les plus fréquentes

Celles-là reviennent tout le temps, et quasi toutes sont des variantes du même problème : on a changé plusieurs choses, mal, sans relire.

Mauvais provider actif. Tu croyais être sur ton endpoint local, Hermes est resté sur un provider distant. Classique après un aller-retour entre deux providers pendant les tests.
Mauvais base_url. Port qui ne correspond pas à celui de ton serveur local, ou URL qui traîne d’un ancien setup. Tu tapes dans le vide.
Endpoint local oublié. Hermes pointe correctement, mais ton serveur local n’est pas lancé, ou il est lancé dans un terminal que tu as fermé. Symptôme : timeout immédiat ou erreur de connexion.
Ancienne config encore active. Tu as édité le fichier, mais Hermes tourne déjà dans un terminal ouvert avant la modif. Relance proprement pour être sûr de l’état lu.
Mélange local / distant. Tu as un bloc provider local et un bloc provider distant, et tu n’es pas sûr duquel est effectivement actif. C’est le signe qu’il faut repasser par hermes model pour remettre les choses au propre.
Clé API mal posée. Elle est dans le YAML au lieu du .env, ou dans le .env mais mal nommée, ou dans la bonne variable mais sans recharge du shell. Résultat : Hermes ne la voit pas et t’envoie une erreur d’authentification.
Vieille variable d’environnement qui traîne. Tu as changé de provider ou de base_url, mais une ancienne variable dans ~/.hermes/.env continue d’influencer certains flux. C’est typiquement le genre de détail qui te fait croire qu’Hermes “n’obéit pas”, alors qu’il lit juste encore une vieille valeur.
Changement multiple impossible à débugger. Tu as touché quatre paramètres, quelque chose ne marche plus, tu ne sais pas quoi a cassé. Retour à la sauvegarde, et on recommence une modif à la fois.
Croire qu’un modèle répond localement alors qu’Hermes part ailleurs. La réponse arrive trop vite, ton GPU n’a pas bougé, ton serveur local n’affiche aucune activité. Relis la config avant de blâmer le modèle.

Aucune de ces erreurs n’est dramatique prise isolément. Toutes deviennent pénibles quand elles se cumulent.

Ce que tu ne dois pas faire

Copier une config trouvée au hasard sur Internet. Tu hérites des choix et des secrets de quelqu’un d’autre, et tu ne sais même pas quelle version de Hermes il utilisait.
Réécrire tout le fichier pour changer un seul point. C’est le meilleur moyen d’introduire deux régressions par mégarde.
Activer trop de choses d’un coup. Nouveau provider, nouveau modèle, nouveau base_url, nouveau backend terminal, le tout dans la même session. Tu t’es auto-saboté.
Bricoler sans relecture ni test. Tu changes, tu relances, tu testes. Chaque étape compte.
Confondre config propre et config complexe. Une config propre tient en quelques lignes utiles. Tu n’as pas à la charger pour “faire sérieux”.

La suite logique

À ce stade, Hermes est installé, un modèle tourne, la config est lisible, et tu sais quoi toucher quand quelque chose ne va pas. C’est une base qui tient.

La suite logique de la série, c’est le tuto sur les tools utiles pour démarrer : quels outils activer en premier, pourquoi, et lesquels laisser de côté tant que tu n’en as pas un besoin clair. Parce que la vraie valeur de Hermes arrive quand tu branches des tools sur une base stable, pas quand tu empiles dix outils sur une config que tu ne comprends qu’à moitié.

D’ici là, le meilleur réflexe est celui qu’on a répété tout au long de cet article : une modif, une relecture, un test. Si cette discipline-là te rentre dans les doigts maintenant, tout ce qui vient ensuite dans la série sera beaucoup plus facile à poser proprement.