Hermes Agent

Un proveedor con nombre en ~/.hermes/config.yaml — api https://api.kunavo.com, transport anthropic_messages, seleccionado con provider: custom:kunavo — conecta Hermes Agent a Claude mediante el protocolo Messages, donde envía sus propios marcadores de caché y límite de salida.

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com        # origin — the Anthropic SDK adds /v1/messages
    key_env: KUNAVO_API_KEY            # the variable's NAME; the key goes in ~/.hermes/.env
    transport: anthropic_messages
    models:
      claude-sonnet-5:
        context_length: 1000000
        prompt_caching: true
      claude-haiku-4-5:
        context_length: 200000
        prompt_caching: true

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

Paso a paso

1. Cree una clave en /app/keys y cópiela: se muestra una sola vez.
2. Guárdala donde Hermes almacena los secretos: hermes config set KUNAVO_API_KEY sk-kn-... la escribe en ~/.hermes/.env. La línea key_env del bloque indica el nombre de esa variable; la clave en sí nunca se guarda en config.yaml.
3. Añade el bloque a ~/.hermes/config.yaml; hermes config edit lo abre. Si ya hay una sección model:, sustituye sus valores default y provider y conserva el resto.
4. O deja que el asistente de configuración lo escriba: ejecuta hermes model en una terminal, fuera de cualquier sesión de chat, elige Custom endpoint (self-hosted / VLLM / etc.) y responde a sus indicaciones: URL base de la API, clave, nombre del modelo, modo de API y longitud del contexto.
5. Inicia hermes y lee el banner: allí aparecen el modelo y su ventana de contexto; ambos deberían coincidir con los del bloque.
6. Envía dos mensajes y abre /usage para ver qué usaron los turnos. Para cambiar de modelo dentro de una sesión, usa /model custom:kunavo:claude-opus-5-5.

Comprobado con Página de proveedores de IA de Hermes Agent el 5 de octubre de 2026. La configuración de terceros puede cambiar; si el nombre de un campo ya no coincide con lo que ves, esa página es la autoridad, no esta.

Verifica antes de depurar el cliente

Una solicitud determina si el fallo está en el endpoint, la clave o el archivo de configuración. Si devuelve JSON, la misma URL base y la misma clave funcionan en Hermes Agent.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Qué ID de modelo introducir en el campo

Todos los modelos de texto están disponibles mediante un ID de modelo; la lista activa está en GET /v1/models, y el catálogo con precios está en la página de modelos. Las tarifas son USD por 1M de tokens, entrada / salida.

El protocolo compatible con OpenAI

La misma clave permite acceder a todas las demás familias de modelos mediante /v1/chat/completions, y para eso basta con la forma más breve que documenta Hermes: un bloque model: con provider: custom y base_url, que también es lo que requiere hermes model:

# ~/.hermes/config.yaml — the bare form, for an OpenAI-compatible endpoint
model:
  default: gpt-6-sol
  provider: custom
  base_url: https://api.kunavo.com/v1    # this wire keeps /v1
  key_env: KUNAVO_API_KEY
  context_length: 1050000

La URL base conserva aquí /v1, el formato que la documentación de Hermes usa en sus ejemplos de servidores locales, y context_length fija la ventana para que Hermes no tenga que detectarla. Para mantener configuradas ambas conexiones a la vez, asigna a esta una entrada con nombre propio: transport: chat_completions; luego, cambia con /model custom:<name>:<model>.

Almacenamiento en caché de prompts en cada protocolo

En la conexión de Anthropic, Hermes añade los marcadores de caché por sí mismo. Para un proveedor personalizado, su página de configuración de modelos documenta el ajuste que se usa en el bloque anterior: prompt_caching: true en el modelo. También indica que la estructura depende del transporte: bloques nativos en anthropic_messages y la estructura envolvente en la conexión compatible con OpenAI. El /v1/messages de Kunavo reenvía el cuerpo tal como se envió y no añade ningún punto de interrupción propio, así que en esta conexión los marcadores los aporta Hermes o no hay marcadores.

La documentación de Hermes deja sin especificar la duración para un endpoint personalizado. prompt_caching.cache_ttl —5m, 1h o auto— está descrito para Claude mediante la API nativa de Anthropic, OpenRouter y Nous Portal, pero no se dice nada sobre otros endpoints. Kunavo reenvía el marcador que reciba y factura la escritura a la misma tarifa, así que puedes deducir la duración a partir de tu propio uso: si después de una pausa de diez minutos un turno sigue mostrando una lectura de caché, se estaba usando una entrada de una hora.

En la conexión compatible con OpenAI, Kunavo coloca por sí mismo los puntos de interrupción para los modelos Claude —en el prompt del sistema, las definiciones de herramientas y el final de la conversación— una vez que el prompt alcanza la longitud necesaria para almacenarse en caché, tanto si el cliente envía un marcador como si no. Los modelos GPT usan la caché implícita de su proveedor.

Independientemente de qué lado coloque los puntos de corte, la factura es la misma. En Claude Sonnet 5, leer de la caché cuesta $0.14 por cada millón de tokens, frente a $1.40 por la entrada nueva, y escribir en la caché cuesta $1.75: la prima que Claude aplica a la escritura sobre la entrada, cobrada a esa misma tarifa cuando la entrada solicita una duración de una hora. Cada entrada dura cinco minutos y cada lectura la renueva, así que lo que paga un agente depende menos del modelo que de si su siguiente solicitud llega dentro de esa ventana. Las tarifas de caché de cada modelo están en la página sobre el almacenamiento en caché de prompts.

Hay un comportamiento de Hermes que cuesta más que cualquier tarifa: su documentación señala que cambiar de modelo a mitad de una sesión, pasar automáticamente a un proveedor alternativo o rotar las credenciales restablece la caché del prompt, por lo que el mensaje siguiente vuelve a leer toda la conversación al precio completo de entrada. Elige el modelo antes de iniciar una sesión larga.

Coste diario de un agente siempre activo

En Hermes, mientras nadie escribe, se factura lo que hayas programado, además de las tareas secundarias que inicia cada conversación. La documentación de cron indica que cada ejecución programada inicia una sesión nueva, así que cada vez que se ejecuta factura el prompt completo: instrucciones, esquemas de herramientas y habilidades adjuntas. El tamaño del prompt depende de tu configuración; por eso, la tabla presenta claramente una suposición: 20.000 tokens por ejecución y una ejecución cada 30 minutos, es decir, 48 al día. Sustituye ambas cifras por las tuyas.

Tres ajustes modifican esa cifra, todos documentados por Hermes. Una tarea programada se ejecuta con el modelo asignado a esa tarea; si no, usa cron.model; y, si tampoco está configurado, usa el modelo principal. Así que hermes config set cron.model claude-haiku-4-5 quita todas las tareas sin un modelo asignado del nivel caro. Un script de tarea que imprime {"wakeAgent": false} omite el modelo en esa ejecución, y una tarea sin agente no llama a ningún modelo. Además, las tareas secundarias —compresión, títulos y visión— se ejecutan en el modelo principal, salvo que auxiliary las dirija a otro:

# ~/.hermes/config.yaml — what decides the cost of an unattended day
compression:
  threshold_tokens: 256000         # compact here, not at half of a 1M window

auxiliary:
  compression:
    provider: kunavo               # the named entry above
    model: claude-haiku-4-5        # summaries on the cheapest tier
  title_generation:
    provider: kunavo
    model: claude-haiku-4-5

threshold_tokens es el ajuste que importa cuando la ventana es grande. De forma predeterminada, la compactación comienza al alcanzar la mitad de la longitud del contexto, y la documentación de Hermes presenta este ajuste como la forma de establecer un límite fijo al coste de cada llamada.

Las horas en que el agente está trabajando realmente son la otra mitad de la factura, y ahí es donde la caché marca la diferencia. Supongamos 100 solicitudes consecutivas, cada una reenviando un contexto de 100.000 tokens, con 2000 tokens nuevos adicionales y devolviendo 800 tokens de salida. En Claude Sonnet 5, eso cuesta aproximadamente $2.31 cuando el contexto se lee de la caché, y aproximadamente $14.84 cuando en cada solicitud el contexto se factura como entrada nueva. El mismo trabajo, el mismo modelo: la diferencia está en si se colocan los puntos de ruptura y si las solicitudes se realizan con menos de cinco minutos de diferencia.

Para tener una referencia basada en mediciones, no en suposiciones: entre las cuentas de Kunavo que ejecutan un agente siempre activo, el coste de un día activo mediano es de $12.67 y el de un día en el percentil 90 es de aproximadamente $163. Son importes facturados hasta 5 de octubre de 2026, según las tarifas vigentes cada día. Es un grupo pequeño, así que interprétalo como la amplitud del intervalo, no como una previsión para tu agente.

Cuando se agota el saldo

Kunavo es de prepago: cada llamada se paga con el saldo de la cartera, y un agente que trabaja mientras duermes lo consume mientras duermes. Si el saldo no alcanza para cubrir una solicitud, esta se rechaza con HTTP 402 y el código insufficient_balance, en cualquiera de los dos protocolos, y no se cobra nada. El rechazo se produce antes de que el saldo de la cartera llegue a cero: cada solicitud primero reserva su costo máximo, es decir, el de su prompt más el de la respuesta más larga que tiene permitido generar. Por eso, cuanto mayor sea el límite de salida que solicite un agente, antes empezarán a rechazarse sus llamadas. El error indica cuánto faltaba, en balance_usd y needed_usd.

La respuesta de Hermes Agent ante un proveedor que falla es una cadena de alternativas: fallback_providers en config.yaml, administrada con hermes fallback y probada turno por turno. La documentación enumera los límites de frecuencia, los errores del servidor, los fallos de autenticación y los errores 404 como causas que la activan para el modelo principal, e incluye HTTP 402 entre los errores de capacidad que hacen avanzar una tarea secundaria en su cadena. No especifica qué hace un turno ante un 402 si no hay ninguna alternativa configurada. Cuenta con la interpretación más directa: el turno falla, y la tarea programada también; recuerda que un turno que sí recurre a una alternativa empieza con la caché del prompt vacía.

Dos ajustes mantienen a un agente desatendido lejos de esa situación, y cumplen funciones distintas:

• Recarga automática, en Facturación. Guarda una tarjeta una sola vez y configura tres cifras: el saldo por debajo del cual se recargará la cuenta, el importe que se añadirá cada vez y un límite mensual. A partir de entonces, la billetera se recarga en cuestión de segundos cuando una llamada hace que el saldo caiga por debajo del umbral. Si llega una solicitud mientras el saldo sigue siendo insuficiente, espera a que se complete el cargo y luego se atiende en lugar de rechazarse. Aun así, se devuelve un 402 si no se puede realizar el cargo —por ejemplo, si se rechaza la tarjeta o se alcanza el límite mensual—, o si una solicitud reserva más de lo que contiene la billetera después de la recarga. Se necesita una tarjeta o Link; no se pueden realizar cargos automáticos mediante Alipay, WeChat Pay, Pix ni los demás métodos de pago locales.
• Un límite mensual para la clave, en Claves API. Asigna al agente una clave propia y establece el importe máximo que podrá gastar esa clave durante un mes natural. Al superar esa cifra, sus llamadas se rechazan con un 402 y no se cobra nada, mientras que las demás claves siguen funcionando. Ese es el límite que necesita un bucle descontrolado y que la billetera no puede ofrecer, porque todas las claves utilizan la misma billetera.

Establece el umbral de recarga por encima de lo que reserva una solicitud y calcula el importe según el gasto diario de tu agente, no según el mínimo: la recarga mínima es $10 y el gasto mediano de un día de funcionamiento continuo indicado arriba es $12.67. Los límites de la recarga automática están en la página de facturación, y el cuerpo completo del error, en la página de errores.

Guías relacionadas

• API personalizada de Hermes Agent: por qué el proveedor de salida no es el servidor de la API de entrada, explicación del campo transport y comprobaciones que se deben realizar en la primera llamada.
• Precios de Hermes Agent: cuánto cuesta ejecutarlo, además de las tarifas por token.
• Se agotó el tiempo de espera de la compresión del contexto de Hermes: qué significa el error cuando se atasca el generador de resúmenes y cómo recuperarse.
• Hermes frente a OpenClaw, y la misma configuración para el otro agente en la página de OpenClaw.