= Prérequis =
(Hermes seul)
* Une machine ou VM dédiée (LXC compatible)
Pour un Hermes de base (sans LLM local) :
* RAM :
** 1 Go → minimum (test uniquement)
** 2 Go → recommandé
** 4 Go -> confortable
* CPU / vCPU :
** 1 vCPU → suffisant
** 2 vCPU → recommandé
* Espace disque :
** 5 Go → minimum
** 10 Go → confortable
* GPU :
** Inutile
= Installation Hermes (service dédié) =

== Installation (Debian) ==
# apt update && apt upgrade
# apt install curl git
# curl -fsSL <nowiki>https://</nowiki>raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

How would you like to set up Hermes?
> (○) Quick setup — provider, model & messaging (recommended)
-----
* Ollama local :
Select provider:
>(○) Custom endpoint (enter URL manually)

Custom OpenAI-compatible endpoint configuration:
API base URL [e.g. <nowiki>https://</nowiki>api.example.com/v1]: http://IP_OLLAMA:11434/v1
API key [optional]:

Detected model: mon_model
Use this model? [Y/n]: Y

Context length in tokens [leave blank for auto-detect]:

Display name [192.168.2.216:11434]: Ollama
-----
* Llama.cpp :
Select provider:
>(○) Custom endpoint (enter URL manually)

Custom OpenAI-compatible endpoint configuration:
API base URL [e.g. <nowiki>https://</nowiki>api.example.com/v1]: https://IP_OLLAMA:11434/v1
-----
Remplir les options désirées puis fin de l'installation :
Launch hermes chat now? [Y/n]: y
Ensuite, inscrire Hermes comme service pour qu'il se lance automatiquement :
-----
* Sur une machine physique ou VM :
# hermes gateway install --system
* Dans un LXC :
# hermes gateway install --system --run-as-user root
-----
# systemctl enable hermes-gateway.service
# systemctl start hermes-gateway.service

== Configuration ==
=== Activer le serveur API ===
On édite le fichier :
# vi ~/.hermes/.env
Ajouter :
...
API_SERVER_ENABLED=true
API_SERVER_KEY="maclefsecrete"
# pour autoriser toutes les interfaces :
API_SERVER_HOST=0.0.0.0
# pour autoriser une seule interface :
# API_SERVER_HOST=IP_HERMES
API_SERVER_PORT=8642
{{Méta bandeau
| niveau = grave
| icône = grave
| texte = Si <code>API_SERVER_HOST=0.0.0.0</code> : l’API est accessible sur le réseau. Définir impérativement une clé <code>API_SERVER_KEY</code> longue et aléatoire, au minimum 16 caractères, idéalement générée avec <code>openssl rand -hex 32</code>. Limiter aussi l’accès via firewall ou réseau privé recommandé.
}}
On relance le service :
# systemctl restart hermes-gateway.service
Pour tester :
# curl http://IP_HERMES:8642/health
Doit renvoyer :
{"status":"ok"}
Pour vérifier le modèle exposé :
# curl http://IP_HERMES:8642/v1/models -H "Authorization: Bearer maclefsecrete"

=== Retarder le démarrage de Hermes au boot pour laisser le temps aux autres services de se lancer ===

# systemctl edit hermes-gateway.service

Ajouter dans la zone d’édition (partie supérieure du fichier) :
...
### Anything between here and the comment below will become the contents of the drop-in file

[Service]
ExecStartPre=/bin/sh -c 'uptime=$(cut -d. -f1 /proc/uptime); [ "$uptime" -lt 120 ] && sleep 30 || true'

### Edits below this comment will be discarded
...
{{Méta bandeau
| niveau = information
| icône = information
| texte =
Cette commande ajoute une pause de 30 secondes uniquement si la machine a démarré depuis moins de 120 secondes.
Cela permet d’éviter que Hermes tente de se connecter trop tôt à certains services encore en cours de démarrage.
}}
=== Utiliser une CA privée avec Hermes ===
Si Hermes doit se connecter à un service HTTPS signé par une CA privée locale, il peut être nécessaire d’indiquer explicitement à Python et aux bibliothèques HTTP quel bundle de certificats utiliser.

Éditer l’override systemd du service :
# systemctl edit hermes-gateway.service

Ajouter dans la zone d’édition (partie supérieure du fichier) :
...
### Anything between here and the comment below will become the contents of the drop-in file

[Service]
Environment="SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt"
Environment="REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt"
Environment="CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt"

### Edits below this comment will be discarded
...

Explication rapide :
* <code>SSL_CERT_FILE</code> : utilisé par Python / OpenSSL
* <code>REQUESTS_CA_BUNDLE</code> : utilisé par la bibliothèque Python <code>requests</code>
* <code>CURL_CA_BUNDLE</code> : utilisé par <code>curl</code> et parfois comme variable de repli

Puis recharger et redémarrer le service :
# systemctl daemon-reload
# systemctl restart hermes-gateway.service
==== Cas particulier : bundle certifi du venv Hermes ====
Dans certains cas, le runtime Python embarqué par Hermes peut continuer à utiliser le bundle interne de certifi au lieu du magasin système.

Si curl valide déjà le certificat avec /etc/ssl/certs/ca-certificates.crt mais que Hermes/OpenAI/httpx échoue avec CERTIFICATE_VERIFY_FAILED, on peut remplacer le bundle certifi du venv Hermes par le bundle système.

Sauvegarder le bundle actuel :
# cp /root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/certifi/cacert.pem /root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/certifi/cacert.pem.bak

Remplacer par le bundle système :
# cp /etc/ssl/certs/ca-certificates.crt /root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/certifi/cacert.pem

Attention : cette modification peut être écrasée lors d’une mise à jour de Hermes, du venv Python ou du paquet certifi.
===== Automatiser le remplacement du certificat du venv =====
On édite le service Hermes :
# systemctl edit hermes-gateway.service

Ajouter dans la zone d’édition (partie supérieure du fichier) :
...
### Anything between here and the comment below will become the contents of the drop-in file

[Service]
ExecStartPre=/bin/cp /etc/ssl/certs/ca-certificates.crt /root/.hermes/hermes-agent/venv/lib/python3.11/site-packages/certifi/cacert.pem

### Edits below this comment will be discarded
...
Puis recharger systemd et redémarrer le service :
# systemctl daemon-reload
# systemctl restart hermes-gateway.service

=== Éditer le prompt système ===
On édite le fichier suivant :
# vi ~/.hermes/SOUL.md
Puis on modifie le contenu de <code>SOUL.md</code>, qui constitue la partie personnalisée du prompt système de Hermes, par exemple :
You are Hermes Agent, an intelligent AI assistant created by Nous Research. You are helpful, knowledgeable, and direct. You assist users with a wide range of tasks including answering questions, writing and editing code, analyzing information, creative work, and executing actions via your tools. You communicate clearly, admit uncertainty when appropriate, and prioritize being genuinely useful over being verbose unless otherwise directed below. Be targeted and efficient in your exploration and investigations.
TOOLS:
- For current, recent, upcoming, time-sensitive, location-specific, or uncertain factual questions, use searxng_web_search.
- To read a specific URL, use web_url_read.
- For search suggestions, use searxng_search_suggestions.
- For SearXNG instance capabilities, categories, engines, locales, and plugins, use searxng_instance_info.
- For indexed documents, internal documentation, knowledge bases, or when the user asks to check the docs, use the RAGFlow MCP tools: ragflow_retrieval, ragflow_list_datasets, and ragflow_list_chats.
RULES:
- Respond in the same language as the user.
- Do not invent tool results.
- If a tool fails, say so explicitly.
- Do not promise to continue later, follow up later, or say that results are still coming.
- When the user asks multiple questions, use the tools needed, then answer all requested items in one final structured response.
- Never answer current, recent, upcoming, time-sensitive, location-specific, or uncertain factual questions without using the required tool first.
- This includes weather, news, prices, schedules, releases, availability, rankings, versions, and other facts that may have changed.
- If no tool result is available, say you cannot verify and do not guess.
- Use search categories when relevant.
- For image searches, use searxng_web_search with categories=images.
- For video searches, use searxng_web_search with categories=videos.
- For image search results, use the `img_src` field as the direct image URL.
- When displaying an image result, ALWAYS output the direct image URL exactly in this format: ![](URL)
- Do not output the image URL as a normal Markdown link.
- For video results, output links in this format: ~_~N [Titre de la vidéo](URL)
- Do not use tools for simple rewriting, translation, or opinion unless needed.
- Do not use terminal/curl to query RAGFlow unless explicitly asked for a network diagnostic.
- If no RAGFlow dataset exists or no relevant result is found, say so clearly.
Enfin, on redémarre le service :
# systemctl restart hermes-gateway.service

=== Signal ===
Signal est une messagerie instantanée axée sur la confidentialité.
Tous les messages et appels y sont chiffrés de bout en bout par défaut via le Signal Protocol, de sorte que ni Signal ni un tiers ne peuvent en lire le contenu. Signal se distingue également par une collecte de données très limitée, l’absence de publicité et de traqueurs, ainsi qu’un effort particulier pour réduire les métadonnées accessibles au service.

Signal permet de relier Hermes à la messagerie chiffrée Signal.
La connexion ne se fait pas directement avec le téléphone, mais via <code>signal-cli</code> exécuté en mode daemon HTTP, auquel Hermes se connecte ensuite.

* Installation :
==== Via [[Docker|Docker]] ====
{{Méta bandeau
| niveau = information
| icône = information
| texte = Installation séparée (Docker sur autre machine) : Les images et fichiers audio générés par Hermes ne peuvent pas être envoyés en pièces jointes natives, signal-cli n'a pas accès au cache local de Hermes (/root/.hermes/image_cache/). Seules les URLs brutes seront transmises.
Pour les pièces jointes natives (images, audio TTS, vidéos), installer signal-cli sur le même serveur qu'Hermes via [[Hermes#Native|l'installation native]].
}}
# mkdir -p /opt/signal-cli
# vi /opt/signal-cli/docker-compose.yml

services:
signal-cli:
image: registry.gitlab.com/packaging/signal-cli/signal-cli-jre:latest
container_name: signal-cli
restart: unless-stopped
command: daemon --http 0.0.0.0:8080
ports:
- "IP_SERVEUR:8080:8080" # Remplacer par IP du serveur, ou 127.0.0.1 pour restreindre acces local uniquement
volumes:
- signal-cli-data:/var/lib/signal-cli
tmpfs:
- /tmp:exec

volumes:
signal-cli-data:

# docker compose -f /opt/signal-cli/docker-compose.yml --project-directory /opt/signal-cli up -d
* Connexion au téléphone :
Installer <code>qrencode</code> :
# apt install qrencode

Dans le terminal :
# docker exec signal-cli signal-cli link -n "HermesAgent" > /tmp/signal-link.txt 2>&1 & sleep 3 && grep -o 'sgnl://[^ ]*' /tmp/signal-link.txt | qrencode -t ANSIUTF8 && wait

Puis scanner le QR code avec l’application Signal via <code>Paramètres</code> -> <code>Appareils associés</code>.
* Connecter Hermes à Signal :
# hermes setup

Connect a messaging platform? (Telegram, Discord, etc.)
-> ●) Set up messaging now (recommended)
Puis redémarrer le service :
# systemctl restart hermes-gateway.service
* Communiquer avec le serveur via Signal (depuis le téléphone dans l'application Signal) :
** Appuyer sur l’icône ✏️ (nouveau message)
** Tout en haut de la liste, "Note to Self" ou votre propre nom apparaît
** Taper votre message : Hermes répond dans cette même conversation
** (Optionnel) taper <code>/sethome</code> pour définir le canal par défaut pour les notifications et les tâches planifiées.

==== Native ====
* Installation :
On installe les dépendances si nécessaire :
# apt update && apt upgrade
# apt install tar qrencode openjdk-25-jre-headless
{{Méta bandeau
| niveau = information
| icône = information
| texte = Si l'installation échoue, vérifier la compatibilité Java : <code>signal-cli --version</code>. En cas d'erreur <code>UnsupportedClassVersionError</code>, installer la version Java requise via <code>apt install openjdk-XX-jre-headless</code>.
}}
On Installe le programme :
# cd /tmp
# VERSION=$(curl -Ls -o /dev/null -w %{url_effective} <nowiki>https://</nowiki>github.com/AsamK/signal-cli/releases/latest | sed 's/^.*\/v//')
# curl -L -O "<nowiki>https://</nowiki>github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}.tar.gz"
# tar xf "signal-cli-${VERSION}.tar.gz" -C /opt
# ln -sf "/opt/signal-cli-${VERSION}/bin/signal-cli" /usr/local/bin/
# rm /tmp/signal-cli-${VERSION}.tar.gz
Appareillage du téléphone :
# signal-cli link -n "HermesAgent" > /tmp/signal-link.txt 2>&1 & sleep 5 && grep -o 'sgnl://[^ ]*' /tmp/signal-link.txt | qrencode -t ANSIUTF8 && wait
Puis scanner le QR code avec l’application Signal via <code>Paramètres</code> -> <code>Appareils associés</code>.

On créé un service :
# vi /etc/systemd/system/signal-cli.service

[Unit]
Description=signal-cli daemon
After=network.target

[Service]
ExecStart=/usr/local/bin/signal-cli --account +VOTRE_NUMERO daemon --http 127.0.0.1:8080
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

# systemctl daemon-reload
# systemctl enable --now signal-cli
# systemctl status signal-cli
* Connecter Hermes à Signal :
# hermes setup

Connect a messaging platform? (Telegram, Discord, etc.)
-> ●) Set up messaging now (recommended)
Puis redémarrer le service :
# systemctl restart hermes-gateway.service
* Communiquer avec le serveur via Signal (depuis le téléphone dans l'application Signal) :
** Appuyer sur l’icône ✏️ (nouveau message)
** Tout en haut de la liste, "Note to Self" ou votre propre nom apparaît
** Taper votre message : Hermes répond dans cette même conversation
** (Optionnel) taper <code>/sethome</code> pour définir le canal par défaut pour les notifications et les tâches planifiées.
==== Mise à jour automatique ====
{{Méta bandeau
| niveau = information
| icône = information
| texte = Il est recommandé de mettre à jour l'application Signal au moins tous les trois mois.
}}
* Version native :
On créé un script :
# vi /usr/local/bin/update-signal-cli.sh

#!/bin/bash
set -e

systemctl stop signal-cli || true
cd /tmp

VERSION=$(curl -Ls -o /dev/null -w '%{url_effective}' <nowiki>https://</nowiki>github.com/AsamK/signal-cli/releases/latest | sed 's/^.*\/v//')

curl -L -O "<nowiki>https://</nowiki>github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}.tar.gz"

rm -rf "/opt/signal-cli-${VERSION}"
tar xf "signal-cli-${VERSION}.tar.gz" -C /opt

ln -sf "/opt/signal-cli-${VERSION}/bin/signal-cli" /usr/local/bin/signal-cli
rm -f "/tmp/signal-cli-${VERSION}.tar.gz"

# Vérifier la compatibilité Java
if ! signal-cli --version > /dev/null 2>&1; then
ERROR="$(signal-cli --version 2>&1 || true)"

echo "$ERROR"

REQUIRED="$(echo "$ERROR" | grep -oE 'class file (version|major version) [0-9]+' | grep -oE '[0-9]+' | tail -n1 || true)"

if [ -z "$REQUIRED" ]; then
echo "Impossible de détecter automatiquement la version Java requise."
echo "Installation de Java 21 par défaut..."
JAVA_VERSION=21
else
JAVA_VERSION=$((REQUIRED - 44))
echo "Class file version $REQUIRED détectée => Java $JAVA_VERSION requis."
fi

apt update
apt install -y "openjdk-${JAVA_VERSION}-jre-headless"

if [ -x "/usr/lib/jvm/java-${JAVA_VERSION}-openjdk-amd64/bin/java" ]; then
update-alternatives --set java "/usr/lib/jvm/java-${JAVA_VERSION}-openjdk-amd64/bin/java"
else
echo "Java $JAVA_VERSION installé, mais chemin update-alternatives non trouvé. Vérifie avec :"
echo "update-alternatives --config java"
fi
fi

systemctl start signal-cli

# chmod +x /usr/local/bin/update-signal-cli.sh
On ajoute le script au crontab :
# crontab -e
Ajouter :
...
0 3 1 * * /usr/local/bin/update-signal-cli.sh
{{Méta bandeau
| niveau = information
| icône = information
| texte =
* 0 → minute 0
* 3 → 3h du matin
* 1 → le 1er du mois
* * → tous les mois
* * → peu importe le jour de la semaine
}}
* Version docker :
Voir [[Watchtower]] pour la mise à jour automatique de tous les containers Docker. (tuto à faire..)
=== SearXNG ===
{{Méta bandeau
| niveau = modéré
| icône = information
| texte = L’intégration native de SearXNG dans Hermes Agent convient aux recherches web classiques et offre une configuration plus simple. Pour un accès plus complet aux fonctions de SearXNG, notamment aux catégories images, vidéos, actualités et à certains paramètres avancés, il est préférable d’utiliser [[Hermes#SearXNG_2|le serveur MCP SearXNG]].
}}
Il faut d’abord avoir [[SearXNG|installé une instance SearXNG]].

Sur le serveur Hermes, lancer :
# hermes tools

→ (○) Reconfigure an existing tool's provider or API key

→ (○) 🔍 Web Search & Scraping

→ (●) SearXNG [free · self-hosted] — Free, privacy-respecting metasearch. Point SEARXNG_URL at your instance. [active]
Entrer ensuite l’adresse de l’instance SearXNG :
SearXNG instance URL (e.g. <nowiki>http://</nowiki>localhost:8080) (Enter to keep current):
=== Scraping via Firecrawl ===
Il faut d’abord avoir [[Firecrawl|installé une instance Firecrawl]].

On renseigne l'adresse de l'instance Firecrawl :
# vi ~/.hermes/.env

...
FIRECRAWL_API_URL=http://IP_DE_FIRECRAWL:3002
...
Si besoin configurer l'API key :
...
FIRECRAWL_API_KEY=c-xxxxxxxxxxxxxxxx
...
Ensuite on édite la configuration de Hermes :
# vi ~/.hermes/config.yaml
On remplace :
web:
backend: searxng
search_backend: ''
extract_backend: ''
Par :
web:
backend: searxng
search_backend: searxng
extract_backend: firecrawl
Enfin on redémarre Hermes :
# systemctl restart hermes-gateway.service

=== Camofox ===
==== Installation native ====
{{Méta bandeau
| niveau = information
| icône = loupe
| texte =
Méthode recommandé mais déconseillé en cas d'utilisation conjointe avec le MCP SearXNG afin de pouvoir désactiver les outils web natifs de Hermes.
}}
Il faut d’abord avoir [[Camofox|installé une instance Camofox]].

Sur le serveur Hermes, lancer :
# hermes tools

→ (○) Reconfigure an existing tool's provider or API key

→ (○) 🌐 Browser Automation

→ (●) Camofox [free · local] — Anti-detection browser (Firefox/Camoufox)
Entrer ensuite l’adresse de l’instance Camofox:
Camofox server URL (Enter to keep current):
* Règle prompt système facultative :

...
RULES:
- If `web_extract` fails or is blocked, use `browser_navigate` through the Camofox browser provider.
...

==== Via MCP ====
Voir [[Hermes#MCP-CamoFox|MCP-CamoFox]]

=== Forcer les timeouts d'une IA locale pour une IA derrière une URL ===
Si l'API de votre IA locale est desservie derrière une URL publique, Hermes peut ne pas la détecter comme un fournisseur local. Il est possible de modifier les timeouts utilisés pour les fournisseurs locaux :

# vi ~/.hermes/.env

...
HERMES_API_TIMEOUT=1800
HERMES_STREAM_READ_TIMEOUT=1800
# HERMES_STREAM_STALE_TIMEOUT=180
HERMES_API_CALL_STALE_TIMEOUT=900
HERMES_AGENT_TIMEOUT=900

# systemctl restart hermes-gateway.service

=== Fonctions auxiliaires ===
Configuration des modèles utilisés par Hermes pour les tâches secondaires, indépendamment du modèle principal de conversation.

Editer la section <code>auxiliary</code> dans :
# vi ~/.hermes/config.yaml

* <code>vision</code> : analyse d’images (modèle multimodal avec vision)
* <code>web_extract</code> : extraction et synthèse de contenu web (LLM texte)
* <code>compression</code> : compression et résumé du contexte (LLM texte avec un contexte suffisamment long)
* <code>skills_hub</code> : recherche et sélection de compétences (LLM texte léger)
* <code>approval</code> : évaluation et validation des actions sensibles (LLM texte léger et fiable)
* <code>mcp</code> : sélection et routage des outils MCP (LLM texte efficace en appel d’outils)
* <code>title_generation</code> : génération de titres de conversations (petit LLM texte rapide)
* <code>tts_audio_tags</code> : génération de balises expressives pour la synthèse vocale (LLM texte léger)
* <code>triage_specifier</code> : classification et orientation des demandes (LLM texte léger)
* <code>kanban_decomposer</code> : décomposition d’un projet en tâches Kanban (LLM texte avec de bonnes capacités de planification)
* <code>profile_describer</code> : génération d’une description de profil (LLM texte)
* <code>curator</code> : sélection et organisation du contenu (LLM texte avec de bonnes capacités de synthèse)
* <code>monitor</code> : analyse des résultats de surveillance (LLM texte léger)
* <code>background_review</code> : révision et analyse en arrière-plan (LLM texte)
* <code>moa_reference</code> : production d’une réponse de référence pour le MoA (LLM texte performant)
* <code>moa_aggregator</code> : agrégation et synthèse des réponses MoA (LLM texte performant avec un contexte long)
* <code>session_search</code> : analyse et sélection des résultats de recherche dans les sessions (LLM texte léger)
* <code>flush_memories</code> : sélection et consolidation des souvenirs pertinents (LLM texte léger et fiable)

==== Note sur vision et les modèles principaux multimodaux ====

Certains modèles principaux (ex. Qwen3.6-27B) sont '''nativement multimodaux''' (encodeur vision intégré au checkpoint) — ce n’est donc pas systématiquement une histoire de « modèle texte qui ne sait pas voir ». Même dans ce cas, garder <code>vision</code> sur un petit modèle auxiliaire séparé reste recommandé pour trois raisons :

# Évite de mobiliser le modèle principal (VRAM + temps de calcul) pour une tâche que 4B suffit à traiter.
# Le petit modèle peut se décharger automatiquement (<code>--sleep-idle-seconds</code>), pas forcément possible/souhaitable sur le principal.
# Latence : un 4B répond bien plus vite qu’un 27B pour une simple description/OCR d’image.

==== Recommandations ====

Dans une configuration locale disposant de peu de VRAM disponible, il est recommandé d’attribuer certaines fonctions auxiliaires à des modèles plus petits et plus rapides, afin d’éviter de mobiliser inutilement le modèle principal.

* <code>vision</code> : fortement recommandé avec un modèle multimodal séparé (environ 3 à 4 milliards de paramètres ; par exemple Qwen2.5-VL-3B-Instruct, Qwen3-VL-4B-Instruct ou Gemma 3 4B). Un modèle quantifié en Q4 est généralement suffisant pour l’analyse d’images courante. '''Pour de l’OCR/transcription de texte dense''', augmenter <code>--image-min-tokens</code>/<code>--image-max-tokens</code> (ex. 2048/8192) et ajouter un <code>--repeat-penalty 1.1</code> pour éviter les boucles de génération sur du texte peu lisible à basse résolution.
* <code>title_generation</code> : recommandé avec un petit modèle texte très rapide (environ 0,5 à 3 milliards de paramètres ; par exemple Qwen3 0.6B, 1.7B ou un modèle instruct équivalent). Tâche simple, ne nécessite pas un modèle puissant.
* <code>web_extract</code> : recommandé avec un modèle texte rapide disposant d’un contexte suffisamment long (environ 3 à 8 milliards de paramètres ; par exemple Qwen3 4B Instruct ou Gemma 3 4B). Privilégier un modèle capable de traiter au moins 32 000 jetons.
* <code>compression</code> : recommandé avec un modèle texte intermédiaire doté d’un contexte long et de bonnes capacités de résumé (environ 7 à 14 milliards de paramètres). Un modèle de 3-4B peut fonctionner mais risque de perdre davantage d’informations sur de longues conversations — '''à éviter si le modèle principal tourne avec un gros contexte (100K+)''', préférer laisser cette tâche sur le principal dans ce cas plutôt qu’un 4B sous-dimensionné.
* <code>mcp</code> : petit modèle texte fiable en sélection/appel d’outils (environ 3 à 8 milliards de paramètres ; ex. Qwen3 4B Instruct). Éviter les modèles extrêmement petits si plusieurs outils ont des descriptions proches.
* <code>approval</code> : petit modèle texte fiable (environ 3 à 8 milliards de paramètres). Qualité et respect des consignes plus importants que la vitesse brute — valide des actions sensibles, ne pas sous-dimensionner.
* <code>skills_hub</code>, <code>triage_specifier</code>, <code>tts_audio_tags</code>, <code>session_search</code>, <code>monitor</code> : petit modèle texte rapide suffisant (environ 1 à 4 milliards de paramètres).
* <code>flush_memories</code> : petit modèle fiable capable de distinguer l’important du temporaire (environ 3 à 8 milliards de paramètres).
* <code>profile_describer</code> : petit ou moyen modèle texte (environ 3 à 8 milliards de paramètres).
* <code>kanban_decomposer</code>, <code>background_review</code> : modèle texte intermédiaire avec de bonnes capacités de planification/analyse (environ 7 à 14 milliards de paramètres).
* <code>curator</code> : modèle texte intermédiaire à performant pour synthèse (7 à 14 milliards de paramètres, plus pour analyses complexes).
* <code>moa_reference</code> : modèle texte performant (14 milliards de paramètres ou plus).
* <code>moa_aggregator</code> : modèle texte performant avec contexte long (14B+, au moins 64 000 jetons de contexte).

Pour une première optimisation, il est conseillé de configurer en priorité :

* <code>vision</code> : modèle multimodal de 3 à 4 milliards de paramètres
* <code>title_generation</code> : modèle texte de 0,5 à 3 milliards de paramètres
* <code>web_extract</code> : modèle texte de 3 à 8 milliards de paramètres avec contexte long
* <code>compression</code> : modèle texte de 7 à 14 milliards de paramètres avec de bonnes capacités de résumé

Les autres fonctions peuvent rester sur <code>provider: auto</code> tant qu’elles ne provoquent pas de lenteurs, de délais d’attente ou une consommation excessive de ressources.

==== Contexte recommandé par fonction ====

Le sur-dimensionnement du contexte (<code>-c</code>) est l’un des plus gros gaspillages de VRAM sur les petits modèles auxiliaires — le mettre par défaut à une valeur « confortable » unique pour toutes les routes coûte cher sans bénéfice.

{| class="wikitable"
! Fonction !! Contexte suggéré !! Remarque
|-
| <code>title_generation</code> || 2-4K || Ne voit que les 1-2 premiers messages
|-
| <code>tts_audio_tags</code> || 2-4K || Passage de texte court à annoter
|-
| <code>triage_specifier</code> || 4K || Juste la requête à classifier
|-
| <code>skills_hub</code> || 4-8K || Liste de compétences + requête
|-
| <code>session_search</code> || 8K || Résultats de recherche à trier
|-
| <code>monitor</code> || 8K || Selon la taille des logs surveillés
|-
| <code>flush_memories</code> || 8K || Candidats mémoire à évaluer
|-
| <code>profile_describer</code> || 8K || Historique modéré
|-
| <code>approval</code> || 8-16K || Action proposée + contexte suffisant
|-
| <code>mcp</code> || 8-16K || Selon le nombre d’outils déclarés
|-
| <code>kanban_decomposer</code> || 8-16K || Description de projet
|-
| <code>vision</code> || 16K || Ajuster si usage OCR intensif (image seule jusqu’à 8K tokens)
|-
| <code>curator</code> || 16-32K || Peut agréger plusieurs sources
|-
| <code>background_review</code> || 16-32K || Selon ce qui est passé en revue
|-
| <code>web_extract</code> || 32K || Recommandation explicite
|-
| <code>moa_reference</code> || 32K || Réponses de référence potentiellement longues
|-
| <code>compression</code> || 32-64K || Dépend de la longueur laissée s’accumuler avant déclenchement
|-
| <code>moa_aggregator</code> || 64K minimum || Exigence explicite (agrège plusieurs longues réponses)
|}

==== Quantification (poids du modèle) ====

* '''Tâches à faible enjeu''' (<code>title_generation</code>, <code>tts_audio_tags</code>, <code>skills_hub</code>, <code>monitor</code>, <code>session_search</code>, <code>triage_specifier</code>) : Q4_K_M suffit largement.
* '''Tâches à enjeu réel''' (<code>approval</code>, <code>mcp</code>, <code>web_extract</code>, <code>compression</code>, <code>vision</code>) : privilégier Q5_K_M ou Q6_K — sur des modèles 4-8B, l’écart VRAM entre Q4 et Q6 reste faible (souvent < 1,5 Go), autant prendre la marge.

==== KV cache (contexte) ====

* '''En dessous de 16K de contexte''' : Pas de quantization ou q8_0/q8_0 en KV cache partout par défaut, sur toutes les routes auxiliaires — risque de dégradation négligeable, aucune raison de s'en priver même à faible contexte.
* '''À partir de 32K''' (<code>web_extract</code>, <code>moa_reference</code>, <code>compression</code>) : <code>q8_0</code>/<code>q8_0</code> simple devient intéressant, gain notable pour un risque quasi nul.
* '''<code>moa_aggregator</code> à 64K+''' : seule route où une approche plus poussée type <code>q8_0</code>/<code>q6_0</code> + Hadamard (si le fork le supporte) se justifie, vu le volume réel de KV cache à comprimer.
=== Réglages de la voix ===
==== Text-to-Speech (TTS) ====
# vi ~/.hermes/config.yaml
Configuration par défaut :
...
tts:
provider: edge
edge:
voice: en-US-AriaNeural
...
Parmi les options gratuites et simples proposées par Hermes, Edge constitue probablement le meilleur choix par défaut. Il est toutefois recommandé de sélectionner une voix adaptée à la langue utilisée. Exemple pour le français :
...
tts:
provider: edge
edge:
voice: fr-FR-DeniseNeural
...
===== TTS via CrispASR =====
Voir [[CrispASR#Text-to-Speech|CrispASR]]

CrispASR expose une API de synthèse vocale compatible avec l’API audio d’OpenAI. Hermes doit donc utiliser le fournisseur <code>openai</code> pour envoyer le texte au serveur TTS.

* Dans le fichier <code>~/.hermes/config.yaml</code> :
...
tts:
provider: openai
...
openai:
model: qwen3-tts-12hz-0.6b-base-q8_0
voice: default
base_url: http://IP_CRISPASR:7981/v1
...

Lorsque CrispASR est lancé avec une voix de référence fixe, la valeur <code>default</code> peut être utilisée pour l’option <code>voice</code>. La voix réellement utilisée dépend alors du fichier WAV et de sa transcription chargés par le serveur.

Le nom du modèle exposé peut être vérifié avec la commande suivante :

curl http://IP_CRISPASR:7980/v1/models

* Dans le fichier <code>~/.hermes/.env</code> :
...
VOICE_TOOLS_OPENAI_KEY=local
...

{{Méta bandeau
| niveau = information
| icône = important
| texte =
La valeur <code>local</code> sert uniquement de clé fictive lorsque l’authentification n’est pas activée sur CrispASR. Hermes exige néanmoins qu’une clé soit définie pour utiliser le fournisseur OpenAI.
}}

==== Speech-to-Text (STT) ====
# vi ~/.hermes/config.yaml
Configuration par défaut :
...
stt:
enabled: true
provider: local
local:
model: base
language: ''
openai:
model: whisper-1
mistral:
model: voxtral-mini-latest
elevenlabs:
model_id: scribe_v2
language_code: ''
tag_audio_events: false
diarize: false
...
Le Speech-to-Text permet de convertir les enregistrements vocaux en texte. Par défaut, Hermes utilise localement <code>faster-whisper</code> avec le modèle <code>base</code>. Cette solution est gratuite, ne nécessite aucune clé API et conserve les enregistrements sur la machine.

Lorsque le champ <code>language</code> reste vide, la langue est détectée automatiquement. Il est toutefois possible de préciser la langue afin de limiter les erreurs de détection, par exemple avec <code>fr</code> pour le français.

Le modèle <code>base</code> offre un bon compromis entre rapidité et consommation de ressources, mais il peut manquer de précision avec les noms propres, les nombres, les adresses IP ou les termes techniques. Il est alors possible d’utiliser un modèle local plus volumineux, par exemple <code>small</code> ou <code>medium</code>. Plus le modèle est grand, plus la transcription est généralement précise, mais plus elle demande de mémoire et de temps de traitement.

Exemple avec un modèle local plus précis configuré pour le français :

...
stt:
enabled: true
provider: local
local:
model: small
language: fr
...

Hermes peut également utiliser un service externe de reconnaissance vocale, par exemple OpenAI, Mistral ou ElevenLabs. Dans ce cas, il suffit de sélectionner le fournisseur souhaité avec l’option <code>provider</code> et de renseigner la clé API correspondante dans le fichier <code>~/.hermes/.env</code>.
===== STT via CrispASR =====
Voir [[CrispASR#Speech-to-Text|CrisASR]]

CrispASR expose une API compatible avec l’API audio d’OpenAI. Hermes doit donc utiliser le fournisseur <code>openai</code> pour envoyer les fichiers audio au serveur.

* Dans le fichier <code>~/.hermes/config.yaml</code> (exemple avec parakeet-tdt-0.6b-v3) :
...
stt:
enabled: true
provider: openai
local:
model: small
language: 'fr'
openai:
model: parakeet-tdt-0.6b-v3-q8_0
...
* Dans le fichier <code>~/.hermes/.env</code> :
...
VOICE_TOOLS_OPENAI_KEY=local
STT_OPENAI_BASE_URL=http://IP_CRISPASR:7980/v1
{{Méta bandeau
| niveau = information
| icône = important
| texte =
La valeur <code>local</code> sert uniquement de clé fictive lorsque l’authentification n’est pas activée sur CrispASR. Hermes exige néanmoins qu’une clé soit définie pour utiliser le fournisseur OpenAI.
}}

Après modification, on redémarre Hermes afin que la nouvelle configuration soit prise en compte.

= Commandes =
* Lancer l’interface interactive :
# hermes

* Choisir le modèle et le provider LLM :
# hermes model

* Configurer les outils disponibles :
# hermes tools

* Modifier une configuration spécifique :
# hermes config set

* Démarrer le gateway (Telegram, Discord, etc.) :
# hermes gateway

* Lancer le script de configuration complet :
# hermes setup

* Migrer depuis OpenClaw :
# hermes claw migrate

* Mettre à jour Hermes :
# hermes update

* Diagnostiquer les problèmes :
# hermes doctor
= MCP =
== MCP pour remplacer les outils web natifs de Hermes ==
{{Méta bandeau
| niveau = grave
| icône = important
| texte = Expérimental et non recommandé. Après de nombreux essais, l'utilisation de serveurs MCP pour remplacer des outils natifs destinés à des tâches basiques, comme la recherche web, complexifie fortement l'architecture de Hermes au quotidien.
}}
{{Méta bandeau
| niveau = modéré
| icône = important
| texte =
Utiliser des serveurs MCP pour remplacer les outils web natifs de Hermes augmente fortement le nombre d'outils disponibles, ce qui peut rendre leur gestion plus complexe pour les LLM.
}}
=== Désactiver Tool Search ===
Hermes utilise <code>Tool Search</code> pour éviter d'envoyer au modèle la description complète de tous les outils disponibles à chaque requête.

Lorsque <code>Tool Search</code> est activé, Hermes conserve directement dans le contexte les outils principaux, tandis qu'une partie des outils supplémentaires — notamment ceux provenant des serveurs MCP et de certains plugins — est placée dans une liste d'outils différés.

Le modèle doit alors retrouver l'outil dont il a besoin à l'aide de mécanismes comme :

tool_search
tool_describe
tool_call

Cela permet de réduire la taille du prompt lorsque des dizaines ou des centaines d'outils sont disponibles.

{{Méta bandeau
| niveau = modéré
| icône = important
| texte = Lorsque les outils web natifs de Hermes sont remplacés par des serveurs MCP, les outils de recherche web et de navigation peuvent eux-mêmes devenir des outils différés. Le modèle doit alors commencer par les rechercher ou en demander la description avant de pouvoir les utiliser.
}}
-----
Dans :

# vi ~/.hermes/config.yaml

Ajouter ou modifier :

tools:
tool_search:
enabled: off

Puis redémarrer Hermes :

# systemctl restart hermes-gateway.service

=== [[IA_MCP#MCP-SearXNG|MCP-SearXNG]] ===
{{Méta bandeau
| niveau = information
| icône = important
| texte = Depuis la version 0.7, SearXNG est pris en charge nativement par Hermes Agent pour les recherches web classiques. Un serveur MCP dédié n’est donc plus indispensable dans ce cas. En revanche, le MCP SearXNG reste utile pour accéder aux catégories spécialisées telles que les images, les vidéos ou d’autres paramètres avancés qui ne sont pas encore pleinement exposés par l’intégration native. Voir [[Hermes#SearXNG|configuration native SearXNG]]
}}
# vi ~/.hermes/config.yaml

On inscrit le serveur MCP SearXNG (créer la section <code>mcp_servers</code> si absente) :

...
mcp_servers:
searxng:
url: http://IP_MCP:3000/mcp
...

{{Méta bandeau
| niveau = modéré
| icône = modéré
| texte = La section <code>mcp_servers</code> doit être au niveau racine (tout à gauche). Vérifier également que le port correspond bien à celui exposé par le conteneur MCP SearXNG.
}}

On redémarre le service :

# systemctl restart hermes-gateway.service

Ou depuis Hermes :

/reload-mcp

Test :

# hermes mcp list
# hermes mcp test searxng

Le serveur <code>ihor-sokoliuk/mcp-searxng</code> expose notamment les outils suivants :

searxng_web_search
searxng_search_suggestions
searxng_instance_info
web_url_read

* Prompt système recommandé (voir [[#Éditer_le_prompt_système|Éditer le prompt système]]) :

...
TOOLS:
- For current, recent, upcoming, time-sensitive, location-specific, or uncertain factual questions, use searxng_web_search.
- To read a specific URL, use web_url_read.
- For search suggestions, use searxng_search_suggestions.
- For SearXNG instance capabilities, categories, engines, locales, and plugins, use searxng_instance_info.
- For system tasks, use terminal.

RULES:
- Respond in the same language as the user.
- Do not invent tool results.
- If a tool fails, say so explicitly.
- Do not promise to continue later, follow up later, or say that results are still coming.
- When the user asks multiple questions, use the tools needed, then answer all requested items in one final structured response.
- Never answer current, recent, upcoming, time-sensitive, location-specific, or uncertain factual questions without using the required tool first.
- This includes weather, news, prices, schedules, releases, availability, rankings, versions, and other facts that may have changed.
- If no tool result is available, say you cannot verify and do not guess.
- Use search categories when relevant.
- For image searches, use searxng_web_search with categories=images.
- For video searches, use searxng_web_search with categories=videos.
- For image search results, use the `img_src` field as the direct image URL.
- When displaying an image result, ALWAYS output the direct image URL exactly in this format: ![](URL)
- Do not output the image URL as a normal Markdown link.
- For video results, output links in this format: 🎬 [Titre de la vidéo](URL)
- Do not use tools for simple rewriting, translation, or opinion unless needed.

-----

* Recommandation :

Il est recommandé de désactiver le service natif correspondant :

# hermes tools

Décocher pour les environnements concernés :

🔍 Web Search & Scraping (web_search, web_extract) [no API key]
=== Skill pour aider la recherche et l'affichage d'images ===

Dans <code>SOUL.md</code> on remplace :

- For image searches, use searxng_web_search with categories=images.
- For image search results, use the `img_src` field as the direct image URL.
- When displaying an image result, ALWAYS output the direct image URL exactly in this format: ![](URL)
- Do not output the image URL as a normal Markdown link.

Par :

- For any image or photo search, ALWAYS load and follow the `searxng-photo` skill before using any search, browser, or web tool.

Puis on crée le skill :

# mkdir -p ~/.hermes/skills/searxng-photo
# vi ~/.hermes/skills/searxng-photo/SKILL.md

<pre>
---
name: searxng-photo
description: Find and display an image using the SearXNG MCP image search tool.
---

Use this skill when asked to find, show, or search for an image or photo.

Steps:

1. Call `mcp__searxng__searxng_web_search` with:
- `query`: a concise image search query
- `categories`: `"images"`
- `num_results`: `5`
- `response_format`: `"json"`

2. Select a relevant result containing `img_src`.

3. For each selected image result, output its direct `img_src` URL using this exact Markdown format:

![](DIRECT_IMAGE_URL)

Replace `DIRECT_IMAGE_URL` with the exact value of the result's `img_src` field.

Rules:

- `categories` must be the string `"images"`, not an array.
- Use `num_results`, not `max_results`.
- Use the exact returned `img_src`.
- Once a usable `img_src` is found, do not call another tool.
- If no usable `img_src` is found, retry once with a better query.
- Do not output the image URL as a normal link.
</pre>

Enfin on redémarre Hermes :

# systemctl restart hermes-gateway.service

=== [[IA_MCP#CamoFox_MCP|MCP-CamoFox]] ===
On inscrit le serveur MCP CamoFox (créer la section <code>mcp_servers</code> si absente) :

...
mcp_servers:
camofox:
url: http://IP_MCP:3000/mcp
headers:
Authorization: Bearer UNE_CLE_ALEATOIRE_DE_32_CARACTERES_MINIMUM
...

{{Méta bandeau
| niveau = modéré
| icône = modéré
| texte = La section <code>mcp_servers</code> doit être au niveau racine (tout à gauche).
}}

On redémarre le service :

# systemctl restart hermes-gateway.service

Ou depuis Hermes :

/reload-mcp

Test :

# hermes mcp list
# hermes mcp test camofox
* Prompt système recommandé (avec le [[Hermes#MCP-SearXNG|MCP-SearXNG]]) (voir [[#Éditer_le_prompt_système|Éditer le prompt système]]) :

...
TOOLS:
- For browser navigation, clicking, typing, page interaction, snapshots, screenshots, or rendered page inspection, use the Camofox MCP tools.
- Do not use Camofox web_search for general web searches; use searxng_web_search instead.
...
RULES:
- Do not use memory for ordinary factual lookups, web searches, image searches, or one-off questions unless the user explicitly asks to remember or recall something.
- Do not search local files for ordinary factual or web questions unless the user explicitly asks about local files or documents.
-----

* Recommandation :

Il est recommandé de désactiver le service natif correspondant :

# hermes tools

Décocher pour les environnements concernés :
[ ] 🌐 Browser Automation (navigate, click, type, scroll)
=== Désactiver les outils web natifs de Hermes ===
Afin d'être sûr qu'Hermes n'expose plus ses outils web natifs aux modèles, il faut modifier la section <code>platform_toolsets</code> :

# vi ~/.hermes/config.yaml

On supprime les occurrences de <code>web</code> et <code>browser</code> dans les sections souhaitées.

Il faut également éviter les toolsets composites susceptibles de les réintroduire, comme <code>hermes_cli</code>, et définir explicitement les outils souhaités.

Pour les requêtes effectuées via l'API Hermes, notamment depuis OpenWebUI, on crée également une section <code>api_server</code>.

Exemple :

...
platform_toolsets:
cli:
- clarify
- code_execution
- computer_use
- cronjob
- delegation
- file
- image_gen
- mcp
- memory
- messaging
- session_search
- skills
- terminal
- todo
- tts
- vision

telegram:
- hermes-telegram

discord:
- clarify
- code_execution
- computer_use
- cronjob
- delegation
- file
- image_gen
- mcp
- memory
- session_search
- skills
- terminal
- todo
- tts
- vision

api_server:
- clarify
- code_execution
- computer_use
- context_engine
- cronjob
- delegation
- discord
- discord_admin
- file
- homeassistant
- image_gen
- mcp
- memory
- session_search
- skills
- spotify
- stt
- terminal
- todo
- tts
- video
- video_gen
- vision
- x_search
- yuanbao
...

{{Méta bandeau
| niveau = modéré
| icône = modéré
| texte = La liste ci-dessus est un exemple. Conserver uniquement les outils réellement utilisés. Le point important est de ne pas inclure <code>web</code>, <code>browser</code> ni un toolset composite susceptible de les réintroduire, tout en conservant <code>mcp</code> si les serveurs MCP doivent rester accessibles.
}}

Enfin on redémarre Hermes :

# systemctl restart hermes-gateway.service

== [[RAGFlow|RAGFlow]] ==
# vi ~/.hermes/config.yaml

On inscrit le serveur MCP RAGFlow (créer la section <code>mcp_servers</code> si absente) :

...
mcp_servers:
ragflow:
url: http://IP_MCP:9382/mcp
...

{{Méta bandeau
| niveau = modéré
| icône = modéré
| texte = La section <code>mcp_servers</code> doit être au niveau racine (tout à gauche).
}}

On redémarre le service :

# systemctl restart hermes-gateway.service

Ou depuis Hermes :

/reload-mcp

Test :

# hermes mcp list
# hermes mcp test ragflow

Prompt système recommandé :
TOOLS:
- For indexed documents, internal documentation, knowledge bases, or when the user asks to check the docs, use the RAGFlow MCP tools: ragflow_retrieval, ragflow_list_datasets, and ragflow_list_chats.

RULES:
- Do not use terminal/curl to query RAGFlow unless explicitly asked for a network diagnostic.
- If no RAGFlow dataset exists or no relevant result is found, say so clearly.
=== Rerank ===

Il faut d’abord identifier l’identifiant complet du modèle de reranking.

[[File:Hermes ragflow rerank.webp|Exemple de reranker configuré dans RAGFlow.]]

Dans cet exemple, l’identifiant est :

/opt/models/jina-reranker-v3/Q8_0/jina-reranker-v3-Q8_0.gguf@Serveur Rerank@OpenAI-API-Compatible

Il faut ensuite créer un skill Hermes afin de demander l’utilisation systématique du reranker lors des appels à <code>ragflow_retrieval</code>.

* Créer le dossier du skill :

# mkdir -p ~/.hermes/skills/ragflow-search

* Créer le fichier principal du skill :

# vi ~/.hermes/skills/ragflow-search/SKILL.md

Y placer le contenu suivant :

---
name: ragflow-search
description: Use this skill whenever querying RAGFlow datasets through the `ragflow_retrieval` MCP tool. Always include the configured reranker.
version: 1.0.0
---

# RAGFlow Search

Use this skill for every call to the `ragflow_retrieval` MCP tool.

## Tool

Call the MCP tool:

`ragflow_retrieval`

Do not use a generic web search when the requested information is expected to be present in RAGFlow.

## Mandatory reranker

For every call to `ragflow_retrieval`, always include this exact argument:

```yaml
rerank_id: "/opt/models/jina-reranker-v3/Q8_0/jina-reranker-v3-Q8_0.gguf@Serveur Rerank@OpenAI-API-Compatible"
```

Do not omit, shorten, rename, translate, or modify this value.

## Dataset selection

- Use `ragflow_list_datasets` when the relevant dataset ID is unknown.
- Prefer selecting only the datasets relevant to the question.
- Do not invent dataset IDs.
- Omit `dataset_ids` only when searching across all datasets is appropriate.

## Recommended retrieval parameters

Use these defaults unless the task requires otherwise:

```yaml
page: 1
page_size: 10
top_k: 30
similarity_threshold: 0.2
vector_similarity_weight: 0.3
keyword: false
```

## Verification

Do not claim that reranking was used unless `rerank_id` was actually included in the tool call.

If `ragflow_retrieval` is called without `rerank_id`, treat the call as invalid and retry it with the exact configured value.

Une fois le fichier enregistré, démarrer une nouvelle session Hermes afin que le skill soit détecté.