Hermes Agent y suscripción a Codex: configuración OAuth, cuotas y API

La integración de Hermes Agent permite canalizar solicitudes hacia modelos de OpenAI utilizando una suscripción de consumo de ChatGPT o Codex mediante el flujo OAuth Device Code. Este método elimina la necesidad de configurar claves de API estáticas, pero introduce incertidumbres tanto técnicas como financieras. Completar con éxito el protocolo de autenticación únicamente valida las credenciales de la cuenta desde una perspectiva técnica; no define ni garantiza las reglas de facturación aplicadas a las solicitudes posteriores.

Alcance y límites: hechos confirmados, vacíos documentales y verificación

Al utilizar Hermes Agent con cuentas de Codex, las interacciones del sistema se dividen en tres categorías bien diferenciadas:

Categoría	Estado documental	Implementación técnica y alcance de control
Confirmado	Documentado oficialmente	Autorización mediante el flujo Device Code. Almacenamiento local de tokens en ~/.hermes/auth.json. Importación de credenciales desde ~/.codex/auth.json (sin necesidad de instalar Codex CLI de forma independiente). Cuarentena automática de tokens revocados.
No documentado	No revelado oficialmente	Planes de suscripción compatibles y reglas de consumo de cuotas. La documentación oficial no especifica los niveles admitidos ni cómo se deducen los límites.
Requiere verificación	Responsabilidad del usuario	Cotejo de las métricas en el panel del proveedor antes y después de ejecutar el agente, contemplando la posible latencia de telemetría, y separación entre la facturación de la suscripción y las claves de API independientes.

La documentación de Nous Research describe exclusivamente el protocolo de conexión de red y los mecanismos de renovación de sesiones. Las fuentes oficiales no detallan qué planes de suscripción califican ni el modo en que se descuentan las cuotas de uso; los desarrolladores deben comprobar de forma independiente las métricas de su cuenta en el panel de control antes de ejecutar cargas de trabajo reales. Cualquier afirmación que sostenga que acceder a los modelos de Codex a través de un agente es «gratuito», «ilimitado» o que está incluido sin restricciones en los planes de consumo base carece de fundamento técnico.

Procedimiento de configuración y gestión de sesiones

La arquitectura de Hermes divide estrictamente la configuración inicial del entorno del cambio de modelos en tiempo de ejecución:

• hermes model — Se ejecuta directamente en la terminal, fuera de cualquier sesión activa del agente. Es el asistente de configuración inicial encargado de registrar nuevos proveedores, iniciar la autorización OAuth en el navegador y guardar los parámetros de configuración.
• /model — Comando interno de la sesión de chat interactiva. Funciona exclusivamente para alternar entre proveedores y modelos previamente configurados. No permite registrar nuevos servicios ni iniciar flujos OAuth desde dentro de la conversación.

La configuración inicial del proveedor comienza en la terminal seleccionando la opción ChatGPT or Codex Subscription en el menú interactivo:

hermes model

Al elegir esta opción, la consola muestra una URL de verificación de un solo uso junto con un código alfanumérico único para el dispositivo. El usuario debe abrir dicho enlace en el navegador, iniciar sesión en su cuenta de OpenAI y autorizar la vinculación. Tras la confirmación, Hermes almacena los tokens de acceso y actualización recibidos en la ruta local ~/.hermes/auth.json. Si en el equipo ya existían credenciales activas procedentes de Codex CLI, el agente las importa automáticamente desde ~/.codex/auth.json, eliminando la necesidad de instalar el paquete Codex CLI por separado.

Gestión de errores de autenticación y cuarentena de tokens

Si el servidor devuelve un error fatal de autenticación (como una respuesta HTTP 4xx, el estado invalid_grant o la revocación de permisos por parte del usuario), Hermes detiene los reintentos automáticos para no saturar los registros de la terminal. El token de actualización no válido pasa de inmediato a un estado de cuarentena local. En cualquier intento posterior de ejecutar el agente, el sistema emite una notificación estructurada solicitando iniciar sesión de nuevo.

Para restablecer el estado de cuarentena y completar nuevamente el flujo de autenticación, se utiliza el siguiente comando:

hermes auth add openai-codex

Como alternativa, es posible volver a ejecutar el asistente hermes model y seleccionar nuevamente el proveedor de suscripción. Al actualizar con éxito las credenciales, el estado de cuarentena se elimina de manera automática.

API dedicada frente a acceso por suscripción

La conexión mediante OAuth basada en suscripción y la conexión directa a la API mediante claves estáticas operan en circuitos financieros y de infraestructura completamente aislados:

1. Suscripción: Vinculada de forma directa a una cuenta de usuario de ChatGPT. La documentación oficial no define la lista de planes compatibles ni aclara cómo las solicitudes vía OAuth se descuentan del balance de cuotas. Es imprescindible verificar el estado de la cuenta y los contadores de facturación antes de iniciar las tareas del agente.
2. Clave de API: Se configura al seleccionar el proveedor openai-api (a través de la variable OPENAI_API_KEY en ~/.hermes/.env) o mediante pasarelas de terceros. Los costes se rigen por las tablas de tarifas del proveedor específico seleccionado y no siempre se limitan al volumen estricto de tokens procesados.

Si el despliegue del agente exige una facturación predecible y desglosada por cada petición, o bien acceso a modelos abiertos alternativos, la vía por suscripción puede complementarse o reemplazarse por una pasarela independiente. Como ejemplo de arquitectura desacoplada, puede consultarse la documentación de BetterToken, que ofrece puntos de conexión compatibles con el estándar de OpenAI, claves de acceso individuales y supervisión del consumo desde el panel de control. El acceso mediante API de terceros funciona como un circuito independiente: no convierte una suscripción existente de ChatGPT/Codex, no consume de sus cuotas y no garantiza la disponibilidad del mismo catálogo de modelos.

Lista de verificación y resolución de incidencias

Dado que el mecanismo exacto de deducción de cuotas bajo suscripciones de consumo no está documentado por los desarrolladores, se recomienda establecer una línea base de control antes de ejecutar tareas habituales siguiendo este protocolo:

1. Parámetros de la cuenta: Anote y documente el plan de suscripción activo y el estado de las cuotas disponibles en la interfaz web del proveedor (la lista oficial de planes admitidos sigue sin revelarse).
2. Marca de tiempo y línea base: Registre los contadores de uso iniciales junto con la marca de tiempo (timestamp) exacta de inicio de la prueba.
3. Petición mínima: Inicie una sesión del agente y envíe una solicitud de prueba breve sin ejecución de herramientas externas (por ejemplo: Calcula 256 * 4).
4. Cotejo de balance: Revise el panel de facturación de la cuenta tras un tiempo de espera prudencial, ya que la latencia de reporte de telemetría no está especificada. Si el contador no se actualiza al instante, no significa que la petición haya sido gratuita.
5. Higiene de seguridad: Nunca comparta el contenido de ~/.hermes/auth.json con terceros ni publique registros de terminal que contengan fragmentos de tokens.

Si tras completar la autenticación Hermes devuelve un error HTTP 403 o informa de permisos insuficientes, la causa raíz específica vinculada a Codex no está documentada. Se recomienda revisar el mensaje de error recibido, comprobar la elegibilidad del plan y los privilegios de la cuenta, verificar la ruta y el identificador de modelo seleccionados, y consultar la documentación oficial o los canales de soporte del proveedor. En caso necesario, configurar un proveedor de API dedicado con una clave de acceso personal ofrece una ruta alternativa.