Hermes Agent

Un fournisseur nommé dans ~/.hermes/config.yaml — api https://api.kunavo.com, transport anthropic_messages, sélectionné avec provider: custom:kunavo — fait fonctionner Hermes Agent avec Claude via le protocole Messages, en envoyant ses propres marqueurs de cache et sa limite de sortie.

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com        # origin — the Anthropic SDK adds /v1/messages
    key_env: KUNAVO_API_KEY            # the variable's NAME; the key goes in ~/.hermes/.env
    transport: anthropic_messages
    models:
      claude-sonnet-5:
        context_length: 1000000
        prompt_caching: true
      claude-haiku-4-5:
        context_length: 200000
        prompt_caching: true

model:
  default: claude-sonnet-5
  provider: custom:kunavo

Étape par étape

1. Créez une clé sur /app/keys et copiez-la — elle n’est affichée qu’une seule fois.
2. Enregistrez la clé à l’endroit où Hermes stocke les secrets : hermes config set KUNAVO_API_KEY sk-kn-... l’écrit dans ~/.hermes/.env. La ligne key_env du bloc désigne cette variable ; la clé elle-même n’est jamais inscrite dans config.yaml.
3. Ajoutez le bloc à ~/.hermes/config.yaml — hermes config edit permet de l’ouvrir. Si une section model: existe déjà, remplacez ses valeurs default et provider et conservez le reste.
4. Vous pouvez aussi laisser l’assistant de configuration écrire le fichier : exécutez hermes model dans un terminal, en dehors de toute session de discussion, sélectionnez Custom endpoint (self-hosted / VLLM / etc.) et répondez à ses questions — l’URL de base de l’API, la clé, le nom du modèle, le mode API et la longueur du contexte.
5. Démarrez hermes et lisez la bannière : le modèle et sa fenêtre de contexte y sont affichés ; ils doivent tous deux correspondre au bloc.
6. Envoyez deux messages et ouvrez /usage pour voir ce que les tours ont utilisé. Pour changer de modèle au cours d’une session, utilisez /model custom:kunavo:claude-opus-5-5.

Vérifié avec Page des fournisseurs d’IA de Hermes Agent le 5 octobre 2026. Les paramètres tiers évoluent ; si le nom d’un champ ne correspond plus à ce que vous voyez ici, cette page fait autorité, pas celle-ci.

Vérifiez avant de déboguer le client

Une requête suffit à déterminer si l’échec vient de l’endpoint, de la clé ou du fichier de configuration. Si cette requête renvoie du JSON, la même URL de base et la même clé fonctionnent dans Hermes Agent.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Quel identifiant de modèle saisir dans le champ

Tous les modèles textuels sont accessibles sous forme d’identifiant de modèle — la liste à jour se trouve sur GET /v1/models, et le catalogue avec les prix sur la page des modèles. Les tarifs sont en USD par million de tokens, entrée / sortie.

Le protocole compatible OpenAI

La même clé permet d’accéder à toutes les autres familles de modèles via /v1/chat/completions, et pour cela, la forme documentée la plus courte par Hermes suffit — un bloc model: avec provider: custom et un base_url, ce que demande également hermes model :

# ~/.hermes/config.yaml — the bare form, for an OpenAI-compatible endpoint
model:
  default: gpt-6-sol
  provider: custom
  base_url: https://api.kunavo.com/v1    # this wire keeps /v1
  key_env: KUNAVO_API_KEY
  context_length: 1050000

L’URL de base conserve /v1 ici, sous la forme utilisée dans la documentation de Hermes pour ses exemples de serveurs locaux, et context_length fixe la fenêtre afin que Hermes n’ait pas à la détecter. Pour configurer les deux protocoles en même temps, attribuez à celui-ci sa propre entrée nommée — transport: chat_completions — et changez de modèle avec /model custom:<name>:<model>.

Mise en cache des prompts selon le protocole

Sur le protocole Anthropic, Hermes ajoute lui-même les marqueurs de cache. Pour un fournisseur personnalisé, sa page de configuration des modèles documente le paramètre utilisé dans le bloc ci-dessus — prompt_caching: true sur le modèle — et indique que la disposition dépend du transport : blocs natifs sur anthropic_messages, disposition enveloppée sur le protocole compatible OpenAI. Le /v1/messages de Kunavo transmet le corps tel qu’il a été envoyé et n’ajoute aucun point de rupture. Sur ce protocole, les marqueurs sont donc ajoutés par Hermes ou bien absents.

La durée de vie est le point que la documentation de Hermes ne précise pas pour un point de terminaison personnalisé. prompt_caching.cache_ttl — 5m, 1h ou auto — est documenté pour Claude via l’API Anthropic native, OpenRouter et Nous Portal, mais rien n’est indiqué pour les autres points de terminaison. Kunavo transmet le marqueur reçu et facture l’écriture au même tarif. Vérifiez donc vos propres données d’utilisation : si un tour effectué après une pause de dix minutes affiche toujours une lecture du cache, c’est qu’une entrée d’une heure était conservée.

Sur le protocole compatible OpenAI, Kunavo place lui-même les points de rupture pour les modèles Claude — dans le prompt système, les définitions des outils et à la fin de la conversation — dès que le prompt est assez long pour être mis en cache, que le client envoie ou non un marqueur. Les modèles GPT sont mis en cache implicitement par leur fournisseur.

Quel que soit le côté qui place les points de rupture, la facture est la même. Sur Claude Sonnet 5 une lecture du cache coûte $0.14 par million de jetons, contre $1.40 pour une entrée fraîche, et une écriture dans le cache coûte $1.75 — la majoration d’écriture appliquée par Claude à l’entrée, facturée au même tarif lorsque l’entrée demande une durée de vie d’une heure. Une entrée dure cinq minutes et chaque lecture renouvelle sa durée ; le coût pour un agent dépend donc moins du modèle que du fait que sa prochaine requête arrive dans cette fenêtre. Les tarifs du cache de chaque modèle figurent sur la page consacrée à la mise en cache des prompts.

Un comportement de Hermes coûte plus cher que n’importe quel tarif : sa documentation indique qu’un changement de modèle au milieu d’une session, un basculement automatique ou une rotation des identifiants réinitialise le cache de prompt. Le message suivant relit alors l’intégralité de la conversation au plein tarif d’entrée. Choisissez le modèle avant de commencer une longue session.

Coût quotidien d’un agent toujours actif

Avec Hermes, les frais engagés pendant que personne ne saisit de texte proviennent des tâches que vous avez planifiées, ainsi que des tâches secondaires déclenchées par chaque conversation. Sa documentation sur cron indique que chaque exécution planifiée démarre une nouvelle session. Elle facture donc chaque fois l’intégralité du prompt — instructions, schémas d’outils et compétences jointes. La taille de ce prompt dépend de votre configuration. Le tableau repose donc sur des hypothèses explicites : 20 000 tokens par exécution et une exécution toutes les 30 minutes, soit 48 par jour. Remplacez ces deux valeurs par les vôtres.

Trois paramètres modifient cette valeur, tous tirés de la documentation de Hermes. Une tâche planifiée utilise le modèle défini pour cette tâche, sinon cron.model, sinon le modèle principal. Ainsi, hermes config set cron.model claude-haiku-4-5 retire du niveau tarifaire coûteux toutes les tâches pour lesquelles aucun modèle n’est fixé. Un script de tâche qui affiche {"wakeAgent": false} évite d’appeler le modèle pour cette exécution, et une tâche sans agent n’en appelle aucun. Enfin, les tâches secondaires — compression, titres et vision — utilisent le modèle principal, sauf si auxiliary les redirige ailleurs :

# ~/.hermes/config.yaml — what decides the cost of an unattended day
compression:
  threshold_tokens: 256000         # compact here, not at half of a 1M window

auxiliary:
  compression:
    provider: kunavo               # the named entry above
    model: claude-haiku-4-5        # summaries on the cheapest tier
  title_generation:
    provider: kunavo
    model: claude-haiku-4-5

threshold_tokens est le paramètre à régler pour une fenêtre de grande taille. Par défaut, la compression commence à la moitié de la longueur du contexte, et la documentation de Hermes indique que ce paramètre permet de fixer un plafond au coût d’un appel.

Les heures pendant lesquelles l’agent travaille réellement représentent l’autre moitié de la facture, et c’est là que le cache fait la différence. Prenons 100 requêtes consécutives, chacune envoyant à nouveau un contexte de 100 000 jetons, auquel s’ajoutent 2 000 nouveaux jetons, et produisant 800 jetons en sortie. Sur Claude Sonnet 5, cela revient à environ $2.31 lorsque le contexte est lu depuis le cache, et à environ $14.84 lorsque le contexte est facturé comme une nouvelle entrée à chaque requête. Même travail, même modèle : la différence tient à la présence des points de rupture et au fait que les requêtes soient espacées de moins de cinq minutes.

Pour donner un ordre de grandeur, mesuré et non supposé : parmi les comptes Kunavo qui exécutent un agent en continu, le coût d’une journée active médiane est de $12.67, et celui d’une journée au 90e percentile est d’environ $163. Ces montants ont été facturés jusqu’au 5 octobre 2026, aux tarifs en vigueur chaque jour. Le groupe est restreint : voyez ces chiffres comme l’étendue de la fourchette, et non comme une prévision pour votre agent.

Quand le solde est épuisé

Kunavo fonctionne en prépaiement : chaque appel est payé depuis le portefeuille, et un agent qui travaille pendant que vous dormez le vide pendant que vous dormez. Une requête que le portefeuille ne peut pas couvrir est refusée avec HTTP 402 et le code insufficient_balance, quel que soit le protocole, et elle n’est pas facturée. Le refus survient avant que le solde du portefeuille n’atteigne zéro : chaque requête réserve d’abord son coût maximal, soit son prompt plus la réponse la plus longue qu’elle est autorisée à produire. Ainsi, plus le plafond de sortie demandé par un agent est élevé, plus tôt ses appels commencent à être refusés. L’erreur indique le montant manquant, en balance_usd et en needed_usd.

Lorsque le fournisseur échoue, Hermes Agent utilise une chaîne de secours : fallback_providers dans config.yaml, gérée avec hermes fallback et essayée tour par tour. Sa documentation indique que les limites de débit, les erreurs de serveur, les échecs d’authentification et les réponses 404 déclenchent ce mécanisme pour le modèle principal. Elle cite également HTTP 402 parmi les erreurs de capacité qui font passer une tâche secondaire au fournisseur suivant de sa chaîne. Elle ne précise pas ce que fait un tour en cas de réponse 402 lorsqu’aucune solution de secours n’est configurée. Prévoyez l’interprétation la plus directe : le tour échoue, ainsi que la tâche planifiée qui le contient. Gardez à l’esprit qu’un tour qui bascule démarre avec un cache de prompt froid.

Deux paramètres empêchent un agent sans supervision d’en arriver là, et ils ont des fonctions différentes :

• Recharge automatique, sous Facturation. Enregistrez une carte une seule fois et définissez trois montants : le solde en dessous duquel le rechargement doit avoir lieu, le montant à ajouter à chaque fois et un plafond mensuel. Le portefeuille se recharge alors en quelques secondes dès qu’un appel fait passer son solde sous le seuil. Une requête reçue alors que le solde du portefeuille est encore insuffisant attend que le paiement soit effectué, puis est traitée au lieu d’être refusée. Un 402 est toujours renvoyé si le paiement ne peut pas être effectué — carte refusée, plafond mensuel atteint — ou si une requête réserve un montant supérieur au solde disponible après le rechargement. Cette fonctionnalité nécessite une carte ou Link ; Alipay, WeChat Pay, Pix et les autres moyens de paiement locaux ne peuvent pas être débités automatiquement.
• Une limite mensuelle pour la clé, sous Clés API. Attribuez à l’agent sa propre clé et définissez le montant maximal que cette clé peut dépenser au cours d’un mois civil. Au-delà de ce montant, ses appels sont refusés avec un 402 et aucun montant n’est débité, tandis que vos autres clés continuent de fonctionner. C’est le plafond qu’il faut pour contenir une boucle qui s’emballe, et que le portefeuille ne peut pas fournir, puisque toutes les clés utilisent le même portefeuille.

Définissez le seuil de recharge au-dessus du montant réservé pour une requête et choisissez le montant en fonction d’une journée d’utilisation de votre agent, pas du minimum : la recharge minimale est de $10, et la journée médiane d’un agent toujours actif indiquée plus haut coûte $12.67. Les limites de la recharge automatique sont indiquées sur la page de facturation, et le corps complet de l’erreur figure sur la page des erreurs.

Guides associés

• API personnalisée de Hermes Agent — pourquoi le fournisseur sortant n’est pas le serveur d’API entrant, explication du champ transport et vérifications à effectuer lors du premier appel.
• Tarification de Hermes Agent — le coût d’exécution au-delà des tarifs des tokens.
• Expiration du délai de compression du contexte de Hermes — ce que signifie l’erreur lorsque le composant chargé de produire le résumé se bloque, et comment y remédier.
• Hermes ou OpenClaw — et la même configuration pour l’autre agent, sur la page OpenClaw.