Brancher Hermes Agent sur son abonnement Claude Pro ou Max avec le plugin DirectSDK

Vous payez un abonnement Claude Pro ou Max, vous travaillez avec Hermes Agent, l'agent IA open source de Nous Research, et depuis le printemps vos requêtes Claude y échouent avec un message d'extra usage épuisé, ou vous obligent à passer par une clé API facturée à part. Le plugin officiel Claude Subscription DirectSDK (Experimental), publié par Nous Research, remet l'abonnement dans la boucle : au lieu de réutiliser un token, il pilote le CLI Claude Code officiel, connecté par vous, sur votre propre machine.

À la fin de ce pas-à-pas, Hermes utilise votre abonnement Claude comme provider par défaut, vous avez vérifié que la consommation part bien sur votre quota, et vous savez ce que ce chemin coûte en limites d'usage. Le périmètre est volontairement serré : un poste, un compte Claude, le provider DirectSDK. Les versions visées sont celles de septembre 2026 : plugin 0.3.0, Hermes Agent 0.21.4 au minimum et Claude Code 2.1.263 (la version qualifiée par l'auteur du plugin).

Prérequis

L'installation de Hermes elle-même n'est pas refaite ici : si ce n'est pas déjà fait, suivez d'abord notre tutoriel installation et configuration de Hermes Agent. Il vous faut ensuite :

• Hermes Agent 0.21.4 ou plus récent, ou la branche main à partir du commit 118984d7a02f. Sur une version plus ancienne, le plugin refuse de se charger avec un avertissement explicite.
• Python 3.10 ou plus récent, sous Linux, macOS ou Windows.
• Un abonnement Claude Pro ou Max : ce sont les seuls plans que citent le README, le manifeste plugin.yaml et la documentation Hermes du plugin, dont l'auteur n'a pas qualifié Team ni Enterprise. Le plan gratuit de claude.ai n'inclut pas Claude Code, et un compte Console (facturation API) ne sert à rien ici.
• Le CLI Claude Code officiel installé, que l'on vérifie à l'étape 1.
• Un terminal interactif pour la connexion OAuth au compte Claude.
• Aucune variable ANTHROPIC_API_KEY ni endpoint Anthropic personnalisé actif dans le shell qui lance Hermes.

Pourquoi l'abonnement Claude ne marchait plus dans Hermes

Le blocage ne vient pas de Hermes, mais d'une série de décisions d'Anthropic, l'éditeur de Claude, étalées sur l'année 2026. Le 9 janvier 2026, Thariq Shihipar, de l'équipe Claude Code chez Anthropic, annonce sur X que les protections contre l'usurpation du harness Claude Code ont été durcies la veille, après des bannissements de comptes déclenchés par les filtres anti-abus sur des harness tiers utilisant un abonnement. Il rappelle dans la foulée que ces harness sont interdits par les conditions d'utilisation et qu'ils génèrent un trafic inhabituel, privé de la télémétrie que fournit le client officiel.

Le 20 février 2026, le média tech britannique The Register rapporte qu'Anthropic a clarifié sa page de conformité. La version citée alors indiquait qu'utiliser les tokens OAuth d'un compte Claude Free, Pro ou Max dans tout autre produit, outil ou service, « including the Agent SDK », n'était pas permis et violait les conditions d'utilisation grand public. Cette phrase ne figure plus dans la version actuelle de la page, présentée plus bas.

Le 4 avril 2026, le cran suivant tombe. Comme le rapporte le média tech TechCrunch, les abonnés ne peuvent plus consommer les limites de leur abonnement dans des harness tiers comme OpenClaw : cet usage se paie désormais à part, en paiement à l'usage. Boris Cherny, responsable de Claude Code chez Anthropic, le justifie ainsi : « subscriptions weren't built for the usage patterns of these third-party tools ».

Anthropic a ensuite annoncé, pour le 15 juin 2026, de sortir l'usage de l'Agent SDK et de claude -p des limites d'abonnement au profit de crédits mensuels dédiés, avant de suspendre ce changement. La page d'aide Anthropic sur l'Agent SDK l'écrit noir sur blanc : « For now, nothing has changed: Claude Agent SDK, `claude -p`, and third-party app usage still draw from your subscription's usage limits. » C'est cette voie que le plugin emprunte.

Hermes a bien été touché. Son provider natif anthropic en OAuth n'a pas été retiré, mais la documentation des providers Hermes précise qu'il ne fonctionne que sur un plan Max avec des crédits d'extra usage achetés, qu'il consomme ces crédits et non l'allocation incluse, et que les abonnés Pro doivent passer par une clé API. L'issue #15080 du 24 avril 2026 en montre le symptôme : un abonné Max voit ses requêtes avec outils échouer en HTTP 400 (« You're out of extra usage ») alors que 97 % de son abonnement reste disponible. Le 13 mai 2026, l'issue #25267 demande un provider Agent SDK branché sur l'OAuth d'abonnement, sur le modèle de Codex. Toujours ouverte, cette demande a nourri la réflexion. Le plugin lui-même est extrait, d'après son README, de la pull request #105863 de teknium1 et unsupportedpastels, ouverte le 8 septembre 2026 et refermée sans fusion le 20 septembre, quand le provider a été sorti du cœur de Hermes pour devenir un plugin autonome.

Comprendre ce que fait le plugin (et ce qu'il ne fait pas)

Deux mécanismes s'opposent. Le provider OAuth natif réutilise un token pour appeler l'API directement, et tombe donc dans l'extra usage. Le plugin DirectSDK, lui, lance le binaire claude officiel, non modifié, en mode non interactif (-p), pour chaque requête de Hermes. Malgré son nom, il parle directement le protocole stream-json du CLI et n'a pas besoin du paquet Python de l'Agent SDK.

Ce que le plugin ne fait jamais compte autant. D'après sa page de documentation Hermes, il n'a aucun identifiant propre : il n'ouvre, ne copie, ne rafraîchit ni n'affiche les fichiers d'identifiants du CLI, et n'envoie aucune clé API. Une nuance compte pourtant : pour garantir une seule requête vers Anthropic par appel, le plugin lance pour chaque requête un relais local sur l'interface loopback (127.0.0.1, port éphémère, route aléatoire) et y fait pointer le CLI via ANTHROPIC_BASE_URL. Les en-têtes d'autorisation du CLI transitent donc par ce relais, en mémoire, avant de partir vers Anthropic ; d'après la documentation, ils ne sont ni journalisés ni conservés, et le relais disparaît à la fin de la requête. Le client Hermes refuse, avant même de lancer le processus, les variables de clé API héritées, les endpoints Anthropic personnalisés et les surcharges de backend cloud : il n'existe pas de repli silencieux vers l'API. Chaque requête tourne dans un répertoire temporaire privé, avec les outils natifs et les skills de Claude Code désactivés. Le serveur MCP interne n'annonce que les outils de Hermes, renommés avec le préfixe mcp__hermes__ : Hermes garde sa boucle d'agent, ses approbations et sa compaction.

Côté règles d'Anthropic, la page Legal and compliance de Claude Code a deux faces. D'un côté, elle interdit aux développeurs tiers de proposer le login Claude.ai ou de router des requêtes via les identifiants d'abonnement de leurs utilisateurs : « Anthropic does not permit third-party developers to offer Claude.ai login into their own applications, or to route requests through Free, Pro, or Max plan credentials on behalf of their users ». Elle ajoute que ces développeurs ne doivent ni collecter, ni stocker, ni faire transiter (« intermediate ») les identifiants ou tokens de session Claude.ai. De l'autre, elle précise que cette règle n'empêche pas un utilisateur final de se connecter lui-même au binaire officiel : « Nor does it prevent an end user from signing in to the unmodified Claude Code binary with their own Claude subscription ». L'overview de l'Agent SDK rappelle de son côté que, sauf accord préalable, un produit tiers bâti sur l'Agent SDK ne doit pas proposer le login claude.ai. Le plugin s'appuie sur une lecture de cette seconde phrase (binaire officiel non modifié, connexion faite par vous), non validée nommément par Anthropic : aucune source Anthropic ne se prononce sur Hermes ni sur ce plugin, et ces textes ne disent pas si un relais local qui fait transiter en mémoire les en-têtes d'autorisation du CLI reste dans ce cadre.

Étape 1 : vérifier et préparer le CLI Claude Code

Commencez par confirmer que le CLI est installé et sain. claude doctor affiche un diagnostic en lecture seule (santé de l'installation, erreurs de settings) sans ouvrir de session.

claude --version
claude doctor

Si la commande claude est introuvable, installez-la. La documentation d'installation de Claude Code recommande l'installeur natif sur macOS, Linux et WSL :

curl -fsSL https://claude.ai/install.sh | bash

Sous Windows, dans PowerShell :

irm https://claude.ai/install.ps1 | iex

La documentation du plugin cite aussi npm install -g @anthropic-ai/claude-code. Depuis Claude Code 2.1.198, ce paquet npm demande Node.js 22 ou plus récent ; sur un Node plus ancien, npm affiche un simple avertissement EBADENGINE et l'installation aboutit quand même, car le paquet télécharge un binaire natif qui n'utilise pas Node à l'exécution. Ouvrez un nouveau terminal après l'installation, puis relancez claude --version : la commande doit afficher un numéro de version suivi de (Claude Code).

Nettoyez ensuite l'environnement du shell qui lancera Hermes. Une clé API ou un endpoint personnalisé hérité bloque le provider, qui affiche une erreur nommant les variables en conflit (sans leur valeur).

env | grep -E 'ANTHROPIC|CLAUDE_CODE_USE'
unset ANTHROPIC_API_KEY ANTHROPIC_BASE_URL

Si la première commande affiche aussi une variable qui bascule Claude Code vers un backend cloud (CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX ou CLAUDE_CODE_USE_FOUNDRY), retirez-la de la même façon ; les autres variables du même préfixe, comme CLAUDE_CODE_USE_POWERSHELL_TOOL, ne choisissent pas de backend et peuvent rester. Si ces variables sont définies dans votre ~/.zshrc, ~/.bashrc ou un fichier .env chargé au démarrage, retirez-les aussi à la source, sinon elles reviendront au prochain terminal. Enfin, si le binaire n'est pas dans le PATH du processus Hermes (l'installeur natif place le lanceur dans ~/.local/bin, qui n'y figure pas toujours), indiquez son chemin absolu au plugin :

export CLAUDE_SUBSCRIPTION_DIRECTSDK_COMMAND="$HOME/.local/bin/claude"

Étape 2 : se connecter avec son compte Claude

La connexion appartient entièrement au CLI officiel. Dans un vrai terminal, lancez la connexion navigateur avec le compte qui porte votre abonnement, puis contrôlez le résultat. D'après la référence CLI de Claude Code, claude auth status renvoie du JSON par défaut, un affichage lisible avec --text, et sort avec le code 0 si vous êtes connecté, 1 sinon.

claude auth login
claude auth status --text

N'utilisez pas claude auth login --console : cette option connecte le CLI à Anthropic Console avec une facturation API, exactement ce que l'on cherche à éviter. Les options --email (pré-remplir l'adresse) et --sso (forcer le SSO) restent utilisables.

Si vous voulez isoler le compte utilisé par Hermes de votre Claude Code habituel, connectez le CLI dans un répertoire de configuration séparé et pointez le plugin dessus. Une variable CLAUDE_CONFIG_DIR héritée fonctionne aussi.

CLAUDE_CONFIG_DIR="$HOME/.claude-hermes" claude auth login
export CLAUDE_SUBSCRIPTION_DIRECTSDK_CONFIG_DIR="$HOME/.claude-hermes"

Étape 3 : installer le plugin dans Hermes

L'entrée du catalogue de plugins Hermes est la voie recommandée : elle est épinglée sur une version relue. La documentation des plugins Hermes décrit les commandes hermes plugins.

hermes plugins install claude-subscription-directsdk
hermes plugins list

hermes plugins list confirme l'installation ; la vraie vérification viendra à l'étape suivante, quand le provider apparaîtra dans hermes model. Deux alternatives existent : installer depuis GitHub, ce qui suit la branche main et que Hermes signale comme source personnalisée non relue (--ref suivi du SHA complet de 40 caractères épingle un commit précis), ou cloner le dépôt à la main. Pour une installation par profil, le dossier cible devient ~/.hermes/profiles/<profile>/plugins/.

# depuis GitHub (suit main)
hermes plugins install NousResearch/hermes-plugin-claude-subscription-directsdk

# ou à la main
git clone https://github.com/NousResearch/hermes-plugin-claude-subscription-directsdk \
    ~/.hermes/plugins/claude-subscription-directsdk-experimental

Aucun hermes plugins enable n'est nécessaire : le plugin déclare kind: model-provider, et la découverte des providers de Hermes l'importe directement. Attention aux trois noms, qui ne sont pas interchangeables :

• claude-subscription-directsdk : le nom du plugin dans le catalogue, pour install, update et remove.
• claude-subscription-directsdk-experimental : l'identifiant du provider, pour --provider et le fichier de configuration (c'est aussi le nom du dossier en installation manuelle).
• « Claude Subscription DirectSDK (Experimental) » : le libellé affiché dans hermes model.

Étape 4 : sélectionner le provider et choisir son modèle

Lancez le sélecteur de modèle de Hermes et choisissez « Claude Subscription DirectSDK (Experimental) ».

hermes model

Avant d'enregistrer quoi que ce soit, le flux interroge le CLI local (jamais Anthropic directement). Si claude est introuvable, il s'arrête avec un conseil d'installation sans toucher à la configuration. Si vous n'êtes pas connecté et que vous êtes dans un terminal interactif, il lance claude auth login en ligne, puis reprend ; sans terminal interactif, il affiche la consigne et s'arrête. Il récupère ensuite la liste des modèles proposés à votre compte par le CLI, et retombe sur le catalogue épinglé du plugin si cette découverte échoue. Sur une installation existante, l'action Refresh models efface l'ancienne liste en cache.

Pour un essai ponctuel sans rien enregistrer, passez le provider et le modèle en ligne de commande :

hermes --provider claude-subscription-directsdk-experimental -m sonnet

Voici le catalogue du plugin 0.3.0 au commit ef73726, celui qu'installe le catalogue Hermes (re-épinglé le 27 septembre 2026). Les alias courts pointent vers les routes natives correspondantes, d'après la table d'alias du code (model_catalog.py) ; la documentation se contente d'écrire qu'ils « resolve to the corresponding pinned routes ». Attention à opus : il pointe vers Opus 5.5 depuis le commit 815c05e du 22 septembre 2026, et pointait vers Opus 5 auparavant, sans changement du numéro de version 0.3.0. Sur une installation antérieure ou en cas de doute, passez la route complète (-m claude-opus-5-5[1m] ou -m claude-opus-5[1m]) plutôt que l'alias.

Modèle	Route native	Contexte (tokens)	Alias
Sonnet 5	claude-sonnet-5[1m]	1 000 000	sonnet
Haiku 4.5	claude-haiku-4-5-20251001	200 000	haiku
Opus 5.5	claude-opus-5-5[1m]	1 000 000	opus
Opus 5	claude-opus-5[1m]	1 000 000	aucun
Opus 4.8	claude-opus-4-8[1m]	1 000 000	aucun
Fable 5.1	claude-fable-5-1[1m]	1 000 000	fable

Tous les modèles ne sont pas pris sur le quota inclus. Le plugin signale que la découverte native marque Opus en contexte 1M comme puisant dans les crédits d'usage sur un plan Pro, et les modèles concernés portent une mention « usage credits » dans le sélecteur. Pour Fable 5.1, la règle d'Anthropic est détaillée à la section quota plus bas. Pour démarrer, sonnet est le modèle que l'auteur du plugin a utilisé pour ses mesures de quota et de cache.

Étape 5 : rendre la configuration persistante

Une fois le choix fait, fixez-le dans ~/.hermes/config.yaml pour ne plus avoir à le passer à chaque lancement :

model:
  provider: claude-subscription-directsdk-experimental
  default: sonnet

Ce bloc ne concerne que le modèle principal. Les routes auxiliaires et de repli (fallback) restent gérées par Hermes : si elles doivent aussi passer par l'abonnement, configurez-les explicitement, le plugin ne modifie pas en douce les autres providers sélectionnés. Si vous souhaitez un budget de compaction plus petit que la fenêtre du modèle, la clé Hermes model.context_length garde la priorité.

Vérifier que ça tourne sur l'abonnement, et connaître les limites

Lancez hermes et envoyez un message simple. Demandez ensuite une action qui déclenche un outil Hermes, par exemple lire un fichier du projet courant : c'est ce qui valide le relais des outils via mcp__hermes__. Ouvrez en parallèle la jauge d'usage de votre compte Claude (claude.ai/settings/usage) : c'est elle qui doit bouger, pas une facture API.

Le coût que Hermes enregistre pour chaque requête est un équivalent prix catalogue de l'API, remonté par le CLI, et non une facture ni la preuve d'un débit sur l'abonnement. Si la consommation vous paraît élevée, la documentation du plugin conseille de comparer /usage dans Hermes avec /cost dans Claude Code sur une même tâche.

Les messages d'erreur prévus sont explicites. Un Hermes trop ancien affiche l'avertissement Failed to load user provider plugin. Un claude absent fait échouer la requête immédiatement avec le conseil d'installation, au lieu d'une trace Python. Une variable de clé API héritée est nommée dans l'erreur. Un modèle non inclus dans votre plan remonte l'erreur native telle quelle (par exemple Fable 5.1 requires usage credits), sans basculer vers un autre modèle.

Côté fonctionnalités, le plugin prend en charge le texte, les images (base64 ou natives), les documents, les outils et leurs résultats, les limites de tokens de sortie, les séquences d'arrêt, le raisonnement et son niveau d'effort, la projection de réponse en JSON-schema, le streaming, l'annulation (qui tue tout l'arbre de processus) et la commande /steer en cours de tour. En revanche, il ne gère pas :

• le prefill de la réponse de l'assistant ;
• le mode strict des fonctions et le tool choice forcé ;
• parallel_tool_calls=False et n>1 ;
• le mode JSON-object seul, les en-têtes ou champs de requête arbitraires ;
• le téléchargement d'images distantes ;
• la parité d'historique signé entre modèles.

Un paramètre inconnu échoue explicitement. Le délai d'inactivité en lecture est de 180 secondes par défaut, remis à zéro à chaque sortie du CLI. Les très gros prompts restent soumis aux limites du CLI et du système d'exploitation.

Ce que coûte le plugin en quota

Les chiffres qui suivent sont des mesures publiées par l'auteur du plugin dans sa documentation et le README du dépôt GitHub, pas des chiffres d'Anthropic. Elles ont été relevées le 9 septembre 2026 sur un plan Pro, avec Sonnet 5 en contexte 1M, environ 500 000 tokens d'entrée frais par essai, et la jauge de session de claude.ai lue avant et après chaque essai.

Chemin	Coût catalogue API poussé	Hausse de la jauge de session
claude -p (deux fenêtres)	2,12 $ / 1,94 $	+19 / +17 points
Plugin DirectSDK	2,36 $	+21 points
Claude Code interactif (deux essais)	2,22 $ / 2,25 $	+12 / +11 points

Lecture de l'auteur : le plugin consomme l'abonnement exactement au tarif de claude -p et de l'Agent SDK, sans pénalité propre à Hermes. C'est le Claude Code interactif qui est décompté moins cher, à environ 0,58 fois ce tarif. Autrement dit, le plugin coûte environ 1,7 fois le Claude Code interactif, et il faut compter sur à peu près 60 % du débit du terminal interactif par fenêtre de 5 heures. Les compteurs d'usage transmis étant identiques d'un chemin à l'autre, l'auteur en déduit que la pondération est appliquée côté serveur, à tout usage -p ou SDK. À tâche de code identique, il mesure par ailleurs que Hermes envoie environ 0,6 fois les tokens de Claude Code natif, ce qui peut compenser une partie de l'écart sur un vrai travail.

Gardez en tête que l'échantillon est minuscule : un à deux essais par chemin (deux pour claude -p et pour le Claude Code interactif, un seul pour le plugin), des jauges lues en points entiers, un seul plan (Pro) et une sortie forcée à « Hello! », si bien que le test mesure surtout le coût des tokens d'entrée. Le 1,7 est un ordre de grandeur, pas une constante.

Le cas de Fable 5.1 est à part. La page d'aide Anthropic sur les modèles Fable indique que Fable 5 et Fable 5.1 ne sont pas inclus dans les limites du plan Pro ni des sièges Team Standard : il faut des crédits d'usage. Les plans Max, les sièges Team Premium et les sièges Enterprise Premium les incluent, jusqu'à 50 % des limites hebdomadaires. Les sièges Enterprise Standard n'y accèdent que si l'organisation a activé les crédits d'usage, et les contrats Enterprise facturés à l'usage les paient au tarif standard de l'API. Fable 5.1 demande Claude Code 2.1.255 ou plus récent. Sur le compte de qualification de l'auteur du plugin, Fable 5.1 a d'ailleurs été refusé faute de crédits (Fable 5.1 requires usage credits) ; le README ne précise pas le plan de ce compte, seules les mesures de quota étant explicitement relevées sur un plan Pro.

Deux réflexes à prendre. Surveillez la jauge d'usage de votre compte les premiers jours, le temps de voir comment vos sessions Hermes la font bouger. Et si vous refusez tout dépassement payant, désactivez l'extra usage dans les réglages de votre compte Claude : la documentation du plugin rappelle que ce réglage appartient au compte, pas au plugin. Gardez enfin en tête que le plugin est expérimental et que le régime de l'Agent SDK a déjà été modifié puis suspendu en juin 2026 : il peut encore évoluer.

Plugin Claude ou provider openai-codex : les différences

Les abonnés ChatGPT ont, eux, un provider intégré au cœur de Hermes, openai-codex, libellé « ChatGPT or Codex Subscription » dans hermes model. Le tableau ci-dessous s'en tient aux faits documentés des deux côtés.

Critère	Plugin Claude DirectSDK	Provider openai-codex
Intégration	Plugin externe à installer	Intégré au core de Hermes, rien à installer
Statut	Expérimental, version 0.3.0, « review build »	Documenté parmi les providers standard, sans mention expérimentale
Connexion	Via le CLI officiel (claude auth login)	OAuth ChatGPT par device code, ou hermes auth add openai-codex --browser
Identifiants	Fichiers gérés par le CLI claude, jamais ouverts par le plugin ; en-têtes d'autorisation relayés en mémoire par son relais local	Stockés dans ~/.hermes/auth.json, import possible depuis ~/.codex/auth.json
Dépendance externe	Binaire claude installé à côté	Aucune, le CLI Codex n'est pas requis
Quota	Environ 1,7 fois le Claude Code interactif, mesuré par l'auteur du plugin sur un petit échantillon	Aucune donnée comparable publiée

Côté provider openai-codex, le flux navigateur écoute sur http://localhost:1455/auth/callback et peut être rendu permanent par la clé auth.codex_login_flow: browser dans config.yaml, d'après la documentation des providers Hermes. La posture des éditeurs diffère aussi : Tibo Sottiaux, de l'équipe Codex d'OpenAI, a encouragé publiquement l'usage de l'abonnement ChatGPT dans d'autres outils dans un post X du 23 mai 2026 (« Reminder you can use your ChatGPT account in a flourishing set of other tools »), quand Anthropic a restreint cet usage en avril avant de l'encadrer via l'Agent SDK. Côté quota, la documentation Hermes indique que la façon dont l'usage est décompté sur un plan ChatGPT n'est pas encore documentée : aucune comparaison chiffrée entre les deux abonnements n'est donc possible à ce jour.

Pour aller plus loin

• Installer et configurer Hermes Agent pas à pas
• Notre accompagnement sur Hermes Agent
• Claude Mythos 5.1 et Claude Fable 5.1 : ce qui change
• Notre offre de déploiement d'agents IA
• Notre expertise automatisation et IA