API personnalisée de Hermes Agent : fournisseurs, transports et vérifications du premier appel

Un endpoint personnalisé de Hermes Agent est configuré en sortie, comme une entrée nommée sous providers: dans ~/.hermes/config.yaml, où api est l’URL de base et transport le protocole filaire. C’est différent du serveur API de Hermes, qui pointe dans l’autre direction. Les résultats de recherche appellent les deux « l’API personnalisée Hermes », et les pages de documentation officielles de chacun apparaissent pour les mêmes requêtes — commencez donc par corriger la direction.

Cette page concerne Hermes Agent, l’agent open source de Nous Research. Une vérification de l’API GitHub le 21 septembre 2026 a renvoyé archived: false, disabled: false, une licence MIT et une poussée le même jour ; la dernière version publiée est Hermes Agent v0.21.3, marquée v2026.9.14 le 14 septembre 2026, et non une préversion. Les surfaces dont cette page reprend la configuration sont ce dépôt et hermes-agent.nousresearch.com. hermes-agent.org couvre le même projet depuis un domaine extérieur à nousresearch.com et charge les analyses Microsoft Clarity (vérifié le 21 septembre 2026) ; il ne s’agit pas de l’une des surfaces officielles du projet, ne prenez donc pas sa configuration comme référence. Il ne s’agit pas non plus de Hermes 3 ou Hermes 4, la famille de modèles open-weight de Nous, ni du moteur JavaScript du même nom.

Deux éléments opposés appelés l’API personnalisée Hermes

Les deux lignes sont citées des propres pages de Hermes, consultées le 21 septembre 2026 : la référence des fournisseurs et la page du serveur API. Une subtilité de nommage mérite d’être vérifiée dans votre propre installation : la page du serveur API documente hermes gateway comme commande qui le lance, tandis que la référence de la CLI décrit hermes gateway comme le gestionnaire du service de messagerie, avec les sous-commandes run, start, stop et status. Exécutez hermes gateway --help au lieu de deviner. Tout ce qui suit concerne la partie sortante.

La configuration sortante minimale

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com/v1   # aliases accepted: base_url, url
    key_env: KUNAVO_API_KEY          # or inline api_key:, or key_cmd:
    transport: chat_completions      # set it by hand; see the transport section
    models:
      claude-sonnet-5:
        prompt_caching: true

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

KUNAVO_API_KEY=your-key

Champ par champ, d’après la référence des fournisseurs : la clé de configuration est providers.<name>, le champ de l’URL de base est api (avec base_url et url acceptés comme alias), l’identifiant est key_env, une valeur intégrée api_key ou un key_cmd, et le protocole est transport. La même entrée accepte également name, default_model, models, context_length, discover_models, extra_body, extra_headers, session_affinity_header, ssl_ca_cert / ssl_verify, catalog_provider et enabled: false. Sélectionnez l’entrée avec model.provider: custom:kunavo, ou en cours de session avec /model custom:kunavo:<model-id>.

Deux commandes ne sont pas interchangeables. hermes model, exécutée en dehors d’une session de chat, est l’assistant complet de configuration des fournisseurs et la seule commande capable d’ajouter un fournisseur ou d’accepter une clé. /model à l’intérieur d’une session ne fait que basculer entre les éléments déjà existants. Pour les endpoints d’entreprise qui émettent des tokens à durée de vie courte, key_cmd désigne une commande qui affiche un token sur stdout — brut, ou au format JSON avec un champ access_token — que Hermes exécute et met en cache jusqu’à peu avant son expiration, et qui est préférable à un api_key ou key_env statique dans la même entrée.

Sélectionnez manuellement le transport au lieu de laisser le champ vide

La référence du fournisseur répertorie trois valeurs acceptées pour transport dans une entrée personnalisée. Elle indique également que l'assistant hermes model Custom Endpoint demande désormais explicitement le protocole et enregistre la réponse dans config.yaml, et que la détection automatique fondée sur l'URL « se produit toujours comme solution de repli lorsque le champ est laissé vide ». La seule règle de détection précisée dans la documentation est qu'un chemin /anthropic correspond à anthropic_messages, ce qui ne correspond pas à une URL de base Kunavo ; le reste de l'heuristique n'est détaillé sur aucune page consultée ici, d'où l'intérêt de renseigner le champ plutôt que d'en déduire le comportement. Kunavo fournit /v1/chat/completions, /v1/messages et /v1/responses ; chaque transport dispose donc, sur le papier, d'une route correspondante.

La ligne Anthropic mérite cette réserve plutôt qu'une réponse assurée. Le guide Azure Foundry de Hermes indique que /v1 est supprimé de l'URL de base, car le SDK Anthropic ajoute /v1/messages à chaque requête — mais cette phrase figure sous un titre Azure, et l'exemple de la référence du fournisseur (api: https://proxy.example.com/anthropic) n'indique jamais quel suffixe Hermes ajoute pour un proxy générique. Les deux candidats ci-dessus sont donc plausibles, et l'un d'eux peut produire une erreur 404 avec un double /v1 dans le chemin. Vérifiez le chemin de requête effectivement enregistré lors de votre premier appel ; la documentation de l'URL de base traite de la confusion entre l'origine et /v1 qui explique la plupart des erreurs 404 sur cette connexion API. L'authentification est un problème secondaire : la route Messages de Kunavo accepte à la fois Authorization: Bearer et x-api-key, donc l'en-tête envoyé par le SDK Anthropic pour un proxy générique devrait être accepté — mais Hermes ne documente pas ce choix ; « devrait » est donc le terme honnête.

Une question ouverte à laquelle cette page ne répondra pas non plus. Hermes documente une mise à niveau silencieuse des noms de modèles de la famille GPT-5.x vers codex_responses même lorsque config.yaml indique encore chat_completions — mais cette phrase apparaît sous provider: azure-foundry tout en étant formulée comme une détection de nom de modèle. La documentation n'indique pas si un identifiant GPT sur provider: custom déclenche le même comportement. Si vous choisissez un modèle de classe GPT, notez la route vers laquelle le premier appel a été envoyé.

Ce qu'un endpoint personnalisé n'obtient pas gratuitement, par transport

Aucun de ces éléments ne constitue une restriction de forfait. Hermes Agent est « gratuit et open source sous licence MIT », selon la FAQ de la page d'accueil du projet, et le dictionnaire providers: est documenté comme une configuration ordinaire, non comme une fonctionnalité liée à un niveau. Ce sont des restrictions de capacité, et elles diffèrent selon le circuit.

Deux mécanismes de secours pour une passerelle en particulier. catalog_provider accepte un identifiant de fournisseur Hermes ou un identifiant models.dev et fait hériter les modèles de l'entrée des métadonnées de ce catalogue — uniquement pour les recherches ; les requêtes continuent d'être envoyées à votre URL api avec votre clé. Et discover_models: false ignore entièrement la sonde /models et utilise uniquement les modèles que vous avez listés dans l'entrée ; c'est la solution lorsque la découverte est bruyante ou lente. La réponse /v1/models de Kunavo satisfait-elle la sonde de Hermes ? Cela n'a pas été testé ici ; si ce n'est pas le cas, la détection du contexte aboutit à la valeur par défaut de 128K. Le raisonnement de coût derrière ces réglages — emplacements auxiliaires, workers de délégation et continuité du cache — figure dans les tarifs de Hermes Agent et n'est pas répété ici.

Une échelle de vérification à exécuter avant de déplacer du travail réel

Voici des étapes à exécuter vous-même, avec le résultat attendu ; ce ne sont pas des résultats obtenus par Kunavo. Aucun test Hermes contre Kunavo n'a été effectué, Kunavo ne dispose d'aucun guide de configuration pour Hermes, et rien sur cette page ne doit être considéré comme une intégration testée. Gardez votre route de travail disponible pendant toute l'opération.

1. Ajoutez le fournisseur, puis diagnostiquez. hermes model l'ajoute ; hermes doctor est documenté comme outil de diagnostic des problèmes de configuration et de dépendances, et la référence CLI recense deux contrôles de configuration des endpoints personnalisés — une clé custom_providers qui n'est pas une liste YAML et une entrée de liste héritée sans entrée providers: correspondante. Les deux ne génèrent qu'un avertissement et --fix ne les réécrit pas.
2. Vérifiez que la clé est chargée avant toute dépense. hermes dump affiche un récapitulatif de configuration prêt à copier-coller — version, fournisseur, modèle et présence éventuelle d'une clé API. Attendez-vous à voir votre identifiant de modèle et une clé présente. hermes prompt-size s'exécute hors ligne et affiche la répartition en octets de l'invite système et des schémas d'outils, qui constitue la partie fixe transportée à chaque tour avant tout contenu de conversation.
3. Un tour de texte sans streaming. Attendez-vous à une réponse et vérifiez que la requête a atteint le chemin prévu. Un endpoint personnalisé qui « fonctionne » mais renvoie des données incohérentes figure dans le tableau de dépannage du démarrage rapide de Hermes ; celui-ci cite une URL de base incorrecte, un nom de modèle incorrect ou un endpoint qui n'est pas réellement compatible OpenAI, et recommande de vérifier d'abord l'endpoint dans un client distinct.
4. Un tour en streaming. Attendez-vous à une sortie incrémentielle plutôt qu'à un bloc unique à la fin. Cette page n'a pas testé si le formatage du flux d'un endpoint donné satisfait l'analyse de progression de Hermes.
5. Un tour d'outil. Attendez-vous à ce que l'outil s'exécute. Si l'appel est imprimé sous forme de texte, cela relève de la prise en charge des appels d'outils côté serveur, et non du transport.
6. Lisez le compteur. /usage est le panneau de session qui affiche les tokens, le coût et le contexte. Comparez-le au montant effectivement enregistré sur le compte de votre fournisseur — le calcul effectué par un agent à partir des tokens signalés est une estimation, pas un registre comptable. Consultez la documentation sur l'utilisation.

Coût de l'échelle et coût d'un changement en cours de session

Supposons que les six étapes ci-dessus envoient 26 000 tokens d'entrée et reçoivent au total 1 150 tokens de sortie — une invite système et un schéma d'outils fixes à chacun des trois appels, plus un résultat d'outil renvoyé une fois. Cette hypothèse est donnée à titre d'illustration ; hermes prompt-size indique votre propre invite fixe sous forme de répartition en octets, ce qui est plus proche de la réalité qu'un nombre que cette page pourrait deviner. Les tarifs sont les prix actuels du catalogue Kunavo par million de tokens.

Il s'agit d'un calcul illustratif de tokens aux tarifs du catalogue, non d'une tâche Hermes mesurée et non d'un plafond de facturation. Les écritures de cache, les outils externes et les taxes sont exclus. L'intérêt de ce nombre est sa faiblesse : vérifier une route coûte bien moins cher que découvrir une mauvaise configuration après une semaine de travail planifié.

Le second nombre est celui que la commande /model masque. Les caches d'invites sont indexés sur le modèle qui traite la requête ; tout changement de modèle au milieu d'une conversation oblige donc le message suivant à relire toute la conversation au tarif d'entrée complet, au lieu du tarif de lecture du cache, qu'Hermes décrit comme environ 75 à 90 % moins cher. Pour une conversation de 120 000 tokens avec Claude Sonnet 5, la différence entre $1.40 par million et le tarif de lecture du cache $0.14 est d'environ $0.151 pour ce seul tour — négligeable une fois, mais non négligeable comme habitude. Le montant du catalogue Kunavo constitue un plancher de facturation, pas un plafond : lorsque l'amont indique son coût, la facture correspond au montant le plus élevé entre le coût du catalogue et le coût amont multiplié par la majoration applicable. Le minimum est un rechargement prépayé de $10 sans abonnement. Consultez la facturation.

Annuler la configuration

Hermes documente une procédure d'annulation, ce qui rend un essai peu risqué. enabled: false dans l'entrée la masque sans la supprimer. Des copies datées de config.yaml sont écrites dans backups/config/config.yaml.<reason>.<timestamp> avant que hermes setup ou hermes migrate ne le réécrive et à chaque analyse, les répétitions identiques étant ignorées et seules les cinq plus récentes par motif étant conservées ; si le fichier ne peut plus être analysé par la suite, Hermes sert la copie valide la plus récente plutôt que les valeurs par défaut intégrées. La référence de configuration annote également model.base_url comme étant « effacé lors du changement de fournisseur » ; revenir à un fournisseur intégré est donc documenté comme supprimant l'ancienne URL de base plutôt que de la laisser dans le fichier — vérifiez ensuite la valeur écrite au lieu de le supposer.

Trois pièges proviennent d'anciens tutoriels. La liste custom_providers: de premier niveau héritée fonctionne toujours et hermes update la migre automatiquement vers le dictionnaire providers:, où model devient default_model et api_mode devient transport. LLM_MODEL dans .env a été entièrement supprimé — config.yaml est l'unique source de vérité. Enfin, OPENAI_BASE_URL est documenté de deux façons par deux pages officielles actuelles : la référence du fournisseur indique qu'il n'est respecté que pour le fournisseur openai-api, tandis que la référence des variables d'environnement le répertorie comme l'URL de base d'un endpoint personnalisé. Cette divergence n'est pas résolue ; configurez donc l'endpoint dans config.yaml et ne comptez pas sur cette variable d'environnement comme route.

Si vous choisissez un fournisseur plutôt que d'en configurer un, L'API compatible OpenAI couvre ce que la surface compatible inclut ou non, et Hermes contre OpenClaw compare les deux agents. Lorsque vous êtes prêt à tester cette route avec une clé approvisionnée, créez un compte Kunavo.

Questions fréquentes

Documentation de Hermes Agent — référence des fournisseurs, page du serveur API, page de configuration des modèles, page de configuration, référence CLI, référence des commandes slash, démarrage rapide et page d'accueil du projet — consultée le 21 septembre 2026. L'état du dépôt et la dernière version ont été vérifiés via l'API GitHub le même jour. Les trois routes API de Kunavo ont été confirmées dans son propre code source. Chaque montant en dollars correspond à un calcul illustratif de tokens fondé sur les tarifs actuels du catalogue, et non au coût d'une tâche mesurée. La configuration de Hermes est rapportée à partir de documents sources ; aucun test Hermes contre Kunavo n'a été effectué.