Hermes Agent et abonnement Codex : OAuth, gestion des quotas et API

L’intégration de Hermes Agent permet aux développeurs d’acheminer des requêtes vers les modèles d’OpenAI à l’aide d’un abonnement grand public ChatGPT ou Codex via le flux OAuth Device Code. Cette approche élimine le besoin de clés API statiques, mais introduit des incertitudes techniques et financières. La réussite de la procédure d’authentification valide uniquement la conformité technique du compte, sans définir ni garantir les règles de facturation des requêtes ultérieures.

Périmètre et limites : faits confirmés, lacunes documentaires et vérifications

Lors de l’utilisation de Hermes Agent avec des comptes Codex, les interactions système se divisent en trois catégories distinctes :

Catégorie	Statut documentaire	Implémentation technique et périmètre de contrôle
Confirmé	Officiellement documenté	Authentification via le flux Device Code. Stockage local des tokens dans ~/.hermes/auth.json. Importation des identifiants depuis ~/.codex/auth.json (sans exiger l’installation préalable de Codex CLI). Mise en quarantaine automatique des tokens révoqués.
Non documenté	Non divulgué officiellement	Liste des forfaits d’abonnement éligibles et règles de consommation des quotas. La documentation officielle ne précise ni les formules prises en charge ni le mode de déduction des limites.
À vérifier	Responsabilité de l’utilisateur	Rapprochement des métriques sur le tableau de bord du fournisseur avant et après l’exécution de l’agent, prise en compte de la latence potentielle de télémétrie et dissociation entre facturation de l’abonnement et clés API indépendantes.

La documentation de Nous Research décrit uniquement le protocole réseau d’échange de clés et les mécanismes de renouvellement de session. Les sources officielles ne précisent ni les formules d’abonnement compatibles ni les modalités de décompte des quotas ; les développeurs doivent donc vérifier eux-mêmes l’état de leur compte dans la console du fournisseur avant d’exécuter des tâches de production. Toute affirmation prétendant que l’accès aux modèles Codex via l’agent serait « gratuit », « illimité » ou inclus sans restriction dans les forfaits grand public de base est techniquement infondée.

Procédure de configuration et gestion des sessions

L’architecture de Hermes sépare strictement la configuration persistante de l’environnement du basculement de modèle à l’exécution :

• hermes model — S’exécute directement dans le terminal en dehors de toute session active de l’agent. Cet assistant gère l’enregistrement initial des fournisseurs, déclenche l’autorisation OAuth dans le navigateur et enregistre les paramètres de configuration fondamentaux.
• /model — Commande interne à la session de discussion. Elle sert exclusivement à basculer entre des fournisseurs et modèles déjà configurés. L’enregistrement d’un nouveau service ou le déroulement d’un flux OAuth est impossible au sein du chat interactif.

La configuration initiale du fournisseur s’effectue dans le terminal en sélectionnant l’option ChatGPT or Codex Subscription dans le menu interactif :

hermes model

Après avoir sélectionné cette option, la console affiche une URL à usage unique accompagnée d’un code d’appareil alphanumérique exclusif. Ouvrez ce lien dans votre navigateur, connectez-vous à votre compte OpenAI et validez l’association. Une fois la confirmation effectuée, Hermes enregistre les tokens d’accès et de rafraîchissement obtenus dans son stockage local sous ~/.hermes/auth.json. Si la machine utilisait déjà l’utilitaire Codex CLI, l’agent importe automatiquement les identifiants existants depuis ~/.codex/auth.json, ce qui évite d’avoir à installer séparément le paquet Codex CLI.

Gestion des erreurs d’authentification et mise en quarantaine des tokens

Si le serveur renvoie une erreur d’authentification fatale (telle qu’une réponse HTTP 4xx, un statut invalid_grant ou une révocation des autorisations par l’utilisateur), Hermes interrompt immédiatement les tentatives en boucle afin d’éviter la saturation des journaux du terminal. Le refresh token invalide est aussitôt placé dans un état de quarantaine local. Lors de la tentative suivante, l’agent affiche une notification système explicite invitant à renouveler l’authentification.

Pour réinitialiser l’état de quarantaine et relancer la procédure d’authentification, utilisez la commande :

hermes auth add openai-codex

Une autre solution consiste à relancer l’assistant hermes model en sélectionnant à nouveau le fournisseur d’abonnement. L’actualisation réussie des identifiants lève automatiquement le statut de quarantaine.

API dédiée contre accès par abonnement

La connexion OAuth adossée à un abonnement grand public et l’accès direct par API via des clés statiques fonctionnent dans des circuits financiers et techniques rigoureusement cloisonnés :

1. Abonnement : Rattaché directement au compte utilisateur ChatGPT. La documentation officielle ne mentionne pas la liste des formules compatibles ni la façon dont les requêtes effectuées via OAuth viennent décréter les quotas disponibles. Il est indispensable de contrôler l’état du compte et la facturation avant de démarrer vos tâches.
2. Clé API : Utilisée lors de la sélection du fournisseur openai-api (via la variable OPENAI_API_KEY dans ~/.hermes/.env) ou de plateformes tierces. Les dépenses sont régies par la grille tarifaire du prestataire choisi et ne se résument pas nécessairement au seul volume de tokens consommés.

Si le déploiement d’un agent exige une facturation prévisible avec le détail de chaque requête ou un accès à des modèles ouverts alternatifs, l’accès par abonnement peut être complété ou remplacé par une passerelle dédiée. À titre d’exemple d’architecture indépendante, vous pouvez consulter la documentation de BetterToken, qui propose des endpoints standards compatibles OpenAI, des clés d’accès personnelles et un suivi de consommation depuis l’espace client. Cet accès API tiers fonctionne comme un canal isolé : il ne convertit pas un abonnement ChatGPT/Codex existant, n’hérite pas de ses quotas et ne garantit pas la disponibilité d’un catalogue de modèles identique.

Protocole de vérification et résolution des pannes

Dans la mesure où les mécanismes de déduction des quotas sous abonnement ne sont pas précisés par les développeurs, il est vivement recommandé d’établir une vérification de contrôle empirique avant toute utilisation opérationnelle :

1. Paramètres du compte : Relevez la formule d’abonnement active et l’état des quotas disponibles dans l’interface web du fournisseur (la liste officielle des forfaits pris en charge n’étant pas divulguée).
2. Horodatage et référence : Notez les compteurs d’utilisation initiaux ainsi que l’horodatage exact de début du test.
3. Requête minimale : Démarrez une session d’agent et soumettez une requête brève sans appel d’outil externe (par exemple : Calcule 256 * 4).
4. Rapprochement du solde : Vérifiez les métriques sur le tableau de bord de facturation après un délai raisonnable, le temps de latence de la télémétrie n’étant pas communiqué. L’absence d’actualisation immédiate du compteur ne signifie nullement que l’appel a été gratuit.
5. Hygiène de sécurité : Ne transmettez jamais le contenu de ~/.hermes/auth.json à des tiers et ne publiez aucun journal de terminal laissant apparaître des fragments de tokens.

Si l’agent renvoie une erreur HTTP 403 ou signale des autorisations insuffisantes après une connexion réussie, la cause exacte propre à Codex n’est pas précisée dans la documentation. Il convient d’analyser le message d’erreur, de contrôler l’adéquation du forfait et des permissions du compte, de vérifier le routage et le modèle sélectionnés, puis de consulter la documentation officielle ou le support du fournisseur. En cas de besoin, basculer vers un fournisseur d’API dédié muni de clés d’accès personnelles constitue une alternative.