API personalizada de Hermes Agent: proveedores, transportes y comprobaciones de la primera llamada

Un endpoint personalizado de Hermes Agent se configura de forma saliente, como una entrada con nombre bajo providers: en ~/.hermes/config.yaml, donde api es la URL base y transport es el protocolo de comunicación. Esto es distinto del propio servidor API de Hermes, que apunta en la dirección contraria. Ambos aparecen como «la API personalizada de Hermes» en los resultados de búsqueda, y las páginas de documentación oficiales de cada uno posicionan para las mismas consultas; por eso, determine primero la dirección.

Esta página trata sobre Hermes Agent, el agente de código abierto de Nous Research. Una consulta a la API de GitHub el 21 de septiembre de 2026 devolvió archived: false, disabled: false, una licencia MIT y un push ese mismo día; la versión publicada más reciente es Hermes Agent v0.21.3, etiquetada como v2026.9.14 el 14 de septiembre de 2026, no una versión preliminar. Las superficies de las que esta página obtiene la configuración son ese repositorio y hermes-agent.nousresearch.com. hermes-agent.org trata el mismo proyecto desde un dominio externo a nousresearch.com y carga análisis de Microsoft Clarity (comprobado el 21 de septiembre de 2026); no es una superficie propia del proyecto, así que no obtenga configuración de allí. Tampoco se trata de Hermes 3 o Hermes 4, la familia de modelos de pesos abiertos de Nous, ni del motor de JavaScript del mismo nombre.

Dos cosas opuestas llamadas la API personalizada de Hermes

Ambas filas están tomadas de las propias páginas de Hermes, consultadas el 21 de septiembre de 2026: la referencia de proveedores y la página del servidor API. Hay un detalle de nomenclatura que conviene comprobar en su propia instalación: la página del servidor API documenta hermes gateway como el comando que lo ejecuta, mientras que la referencia de la CLI describe hermes gateway como el administrador del servicio de mensajería, con los subcomandos run, start, stop y status. Ejecute hermes gateway --help en lugar de adivinar. Todo lo que sigue corresponde a la parte saliente.

La configuración mínima de salida

# ~/.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

Campo por campo, según la referencia del proveedor: la clave de configuración es providers.<name>, el campo de URL base es api (con base_url y url aceptados como alias), la credencial es key_env, un api_key insertado directamente o un key_cmd, y el protocolo es transport. La misma entrada también acepta name, default_model, models, context_length, discover_models, extra_body, extra_headers, session_affinity_header, ssl_ca_cert / ssl_verify, catalog_provider y enabled: false. Selecciona la entrada con model.provider: custom:kunavo, o durante la sesión con /model custom:kunavo:<model-id>.

Dos comandos no son intercambiables. hermes model, ejecutado fuera de una sesión de chat, es el asistente completo de configuración del proveedor y la única opción que puede añadir un proveedor o aceptar una clave. /model dentro de una sesión solo cambia entre lo que ya existe. Para endpoints empresariales que emiten tokens de corta duración, key_cmd designa un comando que imprime un token en stdout —sin formato o como JSON con un campo access_token—, que Hermes ejecuta y almacena en caché hasta poco antes de que caduque, y que tiene prioridad sobre un api_key o key_env estático en la misma entrada.

Elige manualmente el transporte en lugar de dejar el campo vacío

La referencia del proveedor enumera tres valores aceptados para transport en una entrada personalizada. También indica que el asistente hermes model Custom Endpoint ahora solicita explícitamente el protocolo y guarda la respuesta en config.yaml, y que la autodetección basada en la URL «sigue ocurriendo como alternativa cuando el campo se deja vacío». La única regla de detección que especifica la documentación es que una ruta /anthropic se asigna a anthropic_messages, algo que una URL base de Kunavo no cumple; el resto de la heurística no se enumera en ninguna página consultada aquí, por lo que conviene escribir el campo en lugar de inferir qué haría. Kunavo ofrece /v1/chat/completions, /v1/messages y /v1/responses, de modo que, en principio, cada transporte tiene una ruta correspondiente.

La fila de Anthropic merece una salvedad, no una respuesta categórica. La guía de Azure Foundry de Hermes afirma que /v1 se elimina de la URL base porque el SDK de Anthropic añade /v1/messages a cada solicitud, pero esa frase aparece bajo un encabezado de Azure, y el propio ejemplo de la referencia del proveedor (api: https://proxy.example.com/anthropic) nunca indica qué sufijo añade Hermes para un proxy genérico. Por tanto, ambos candidatos son plausibles y uno de ellos podría producir un 404 por /v1 duplicado. Comprueba la ruta de solicitud que registre realmente tu primera llamada; la documentación de la URL base explica la trampa entre origen y /v1 que está detrás de la mayoría de los 404 en este canal. La autenticación es una preocupación menor: la ruta Messages de Kunavo acepta tanto Authorization: Bearer como x-api-key, por lo que debería aceptar cualquiera de los encabezados que el SDK de Anthropic envíe para un proxy genérico, pero Hermes no documenta esa elección; por eso «debería» es la palabra honesta.

Otra pregunta abierta que esta página tampoco puede responder. Hermes documenta una actualización silenciosa de los nombres de modelos de la familia GPT-5.x a codex_responses incluso cuando config.yaml sigue indicando chat_completions, pero esa frase aparece bajo provider: azure-foundry y está formulada como detección del nombre del modelo. No está documentado si un identificador GPT en provider: custom activa el mismo cambio. Si eliges un modelo de clase GPT, registra a qué ruta fue la primera llamada.

Lo que un endpoint personalizado no obtiene automáticamente, según el transporte

Ninguno de estos elementos está limitado por el plan. Hermes Agent es «gratuito y de código abierto bajo la licencia MIT», según la propia sección de preguntas frecuentes de la página principal del proyecto, y providers: está documentado como configuración ordinaria, no como una función por nivel. Son límites de capacidad y varían según el canal.

Dos mecanismos de escape para un gateway específicamente. catalog_provider acepta un ID de proveedor de Hermes o un ID de models.dev y hace que los modelos de la entrada hereden los metadatos de ese catálogo; solo realiza consultas, las solicitudes siguen yendo a tu URL api con tu clave. Y discover_models: false omite por completo la comprobación /models y utiliza únicamente los modelos que hayas indicado en la entrada, lo que soluciona los casos en que el descubrimiento es ruidoso o lento. Aquí no se ha probado si la respuesta /v1/models de Kunavo satisface la comprobación de Hermes; si no lo hace, la detección del contexto termina en el valor predeterminado de 128K. El razonamiento de costes detrás de estos ajustes —ranuras auxiliares, trabajadores de delegación y continuidad de la caché— se explica en los precios de Hermes Agent, por lo que no se repite aquí.

Una escalera de verificación que debes ejecutar antes de trasladar trabajo real

Estos son pasos que debes ejecutar tú, junto con lo que debes observar; no son resultados obtenidos por Kunavo. No se ha ejecutado Hermes contra Kunavo, no existe una guía de configuración de Kunavo para Hermes y nada de esta página debe interpretarse como una integración probada. Mantén disponible tu ruta de trabajo durante todo el proceso.

1. Añade el proveedor y después diagnostica. hermes model lo añade; hermes doctor está documentado para diagnosticar problemas de configuración y dependencias, y la referencia de la CLI registra dos comprobaciones de configuración de endpoints personalizados que ejecuta: una clave custom_providers que no es una lista YAML y una entrada de lista heredada sin una entrada providers: correspondiente. Ambas solo generan advertencias y --fix no las reescribe.
2. Confirma que la clave se ha cargado antes de gastar nada. hermes dump imprime un resumen de configuración que se puede copiar y pegar: versión, proveedor, modelo y si hay una clave de API presente. Debes esperar tu ID de modelo y una clave presente. hermes prompt-size se ejecuta sin conexión e informa del desglose en bytes del prompt del sistema y de los esquemas de herramientas, que es la parte fija que cada turno transporta antes de cualquier contenido de la conversación.
3. Un turno de texto sin streaming. Debes esperar una respuesta y que la solicitud haya llegado a la ruta prevista. Un endpoint personalizado que «funciona» pero devuelve contenido basura aparece como caso en la tabla de resolución de problemas de inicio rápido de Hermes, que menciona una URL base incorrecta, un nombre de modelo incorrecto o un endpoint que en realidad no es compatible con OpenAI, y recomienda verificar primero el endpoint en un cliente independiente.
4. Un turno con streaming. Debes esperar una salida incremental, no un único bloque al final. Esta página no ha probado si el encuadre del stream de un endpoint determinado satisface el análisis de progreso de Hermes.
5. Una ronda de herramientas. Debes esperar que la herramienta se ejecute. Si la llamada se imprime como texto, se trata de una limitación de la compatibilidad con llamadas a herramientas del servidor, no del transporte.
6. Lee el medidor. /usage es el panel de tokens, costes y contexto dentro de la sesión. Compáralo con el cargo que realmente haya registrado tu cuenta del proveedor: el cálculo propio de un agente sobre los tokens informados es una estimación, no un libro contable. Consulta la documentación de uso.

Cuánto cuesta la escalera y cuánto cuesta cambiar a mitad de una sesión

Supón que los seis pasos anteriores envían 26.000 tokens de entrada y reciben 1.150 tokens de salida en total: un prompt del sistema y un esquema de herramientas fijos en cada una de las tres llamadas, más un resultado de herramienta reenviado una vez. Es una suposición ilustrativa; hermes prompt-size informa del prompt fijo real como un desglose en bytes, más cercano a la realidad que una cifra que esta página pueda adivinar. Las tarifas son precios activos del catálogo de Kunavo por millón de tokens.

Esto es un cálculo ilustrativo de tokens a precios de catálogo, no una tarea de Hermes medida ni un límite máximo de facturación. Excluye escrituras en caché, herramientas externas e impuestos. La cifra pretende mostrar que es pequeña: verificar una ruta cuesta mucho menos que descubrir una configuración incorrecta después de una semana de trabajo programado.

La segunda cifra es la que oculta el comando /model. Las cachés de prompts se asocian al modelo que sirve la solicitud, por lo que cualquier cambio de modelo a mitad de la conversación hace que el siguiente mensaje vuelva a leer toda la conversación al precio de entrada completo, en lugar de aplicar la tarifa de caché, que Hermes describe como aproximadamente entre un 75 % y un 90 % más barata. En una conversación de 120.000 tokens con Claude Sonnet 5, la diferencia entre $1.40 por millón y la tarifa de lectura de caché $0.14 es de aproximadamente $0.151 para ese único turno: insignificante una vez, pero no como práctica habitual. El importe del catálogo de Kunavo es un mínimo de facturación, no un límite: cuando el upstream informa de su cargo, la factura es el mayor valor entre el coste de catálogo y el coste del upstream multiplicado por el recargo aplicable. El mínimo es una recarga prepaga de $10 sin suscripción. Consulta facturación.

Revertir la configuración

Hermes documenta un procedimiento de deshacer, por lo que una prueba implica poco riesgo. enabled: false en la entrada la oculta sin eliminarla. Las copias puntuales de config.yaml se escriben en backups/config/config.yaml.<reason>.<timestamp> antes de que hermes setup o hermes migrate la reescriban y cada vez que la analiza; se omiten las repeticiones idénticas y solo se conservan las cinco más recientes por motivo. Si el archivo deja de poder analizarse posteriormente, Hermes sirve la copia válida más reciente en lugar de los valores predeterminados integrados. La referencia de configuración también marca model.base_url como «se borra al cambiar de proveedor», por lo que cambiar de nuevo a un proveedor integrado está documentado como la eliminación de la URL base obsoleta, no como su permanencia en el archivo; comprueba después el valor escrito en lugar de darlo por supuesto.

Tres trampas proceden de tutoriales antiguos. La lista heredada de nivel superior custom_providers: sigue funcionando y hermes update la migra automáticamente al diccionario providers:, donde el model heredado se convierte en default_model y el api_mode heredado en transport. LLM_MODEL en .env se ha eliminado por completo: config.yaml es la única fuente de verdad. Y OPENAI_BASE_URL aparece documentado de dos formas en dos páginas oficiales actuales: la referencia del proveedor dice que solo se respeta para el proveedor openai-api, mientras que la referencia de variables de entorno lo enumera como la URL base de un endpoint personalizado. Esa discrepancia no está resuelta, así que configura el endpoint en config.yaml y no dependas de esa variable de entorno como ruta.

Si estás eligiendo un proveedor en lugar de conectarlo, API compatible con OpenAI explica qué incluye y qué no incluye la superficie compatible, y Hermes frente a OpenClaw compara ambos agentes. Cuando estés listo para probar esta ruta con una clave con fondos, crea una cuenta de Kunavo.

Preguntas frecuentes

Documentación de Hermes Agent —la referencia del proveedor, la página del servidor de API, la página de configuración de modelos, la página de configuración, la referencia de la CLI, la referencia de comandos con barra, el inicio rápido y la página principal del proyecto— consultada el 21 de septiembre de 2026. El estado del repositorio y la versión más reciente se comprobaron contra la API de GitHub ese mismo día. Las tres rutas de API de Kunavo se confirmaron en su propio código fuente. Todas las cifras en dólares son cálculos ilustrativos de tokens basados en tarifas activas del catálogo, no costes medidos de una tarea. La configuración de Hermes se ha extraído de documentos fuente; no se ha ejecutado Hermes contra Kunavo.