Hermes Agent

Un provider con nome in ~/.hermes/config.yaml — api https://api.kunavo.com, transport anthropic_messages, selezionato con provider: custom:kunavo — consente a Hermes Agent di usare Claude tramite il protocollo Messages, inviando i propri marcatori di cache e il limite di output.

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

Passo dopo passo

1. Crea una chiave su /app/keys e copiala: viene mostrata una sola volta.
2. Salvala dove Hermes conserva i segreti: hermes config set KUNAVO_API_KEY sk-kn-... la scrive in ~/.hermes/.env. La riga key_env nel blocco indica il nome di questa variabile; la chiave vera e propria non viene mai inserita in config.yaml.
3. Aggiungi il blocco a ~/.hermes/config.yaml — hermes config edit lo apre. Se esiste già una sezione model:, sostituisci i valori default e provider e lascia invariato il resto.
4. In alternativa, lascia che sia la procedura guidata a scriverla: esegui hermes model in un terminale, fuori da qualsiasi sessione di chat, scegli Custom endpoint (self-hosted / VLLM / etc.) e rispondi alle domande: URL di base dell'API, chiave, nome del modello, modalità API e lunghezza del contesto.
5. Avvia hermes e leggi il banner: mostra il modello e la relativa finestra di contesto, che dovrebbero entrambi corrispondere al blocco.
6. Invia due messaggi e apri /usage per vedere le risorse usate dai turni. Per cambiare modello all'interno di una sessione, usa /model custom:kunavo:claude-opus-5-5.

Verificato rispetto a Pagina dei provider IA di Hermes Agent il 5 ottobre 2026. Le impostazioni di terze parti cambiano; se il nome di un campo qui non corrisponde più a quello visualizzato, fa fede quella pagina, non questa.

Verifica prima di eseguire il debug del client

Una sola richiesta stabilisce se il problema riguarda l'endpoint, la chiave o il file di configurazione. Se restituisce JSON, lo stesso base URL e la stessa chiave funzionano in 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"}]}'

Quale model id inserire nel campo

Ogni modello di testo è raggiungibile come model id: l'elenco aggiornato è GET /v1/models e il catalogo con i prezzi è nella pagina dei modelli. Le tariffe sono in USD per 1M di token, input / output.

Il protocollo compatibile con OpenAI

La stessa chiave raggiunge tutte le altre famiglie di modelli tramite /v1/chat/completions, e per questo basta la forma più breve documentata da Hermes — un blocco model: con provider: custom e un base_url, come richiesto anche da 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

L'URL di base mantiene /v1 qui, nella forma usata dalla documentazione di Hermes per gli esempi con server locale, mentre context_length fissa la finestra così che Hermes non debba rilevarla. Per mantenere entrambi i protocolli configurati contemporaneamente, crea per questo una voce dedicata con un proprio nome — transport: chat_completions — e passa da uno all'altro con /model custom:<name>:<model>.

Memorizzazione nella cache dei prompt per ciascun protocollo

Sul protocollo Anthropic, Hermes aggiunge autonomamente gli indicatori della cache. Per un provider personalizzato, la sua pagina sulla configurazione dei modelli documenta l'interruttore usato nel blocco qui sopra — prompt_caching: true sul modello — e specifica che il formato dipende dal protocollo: blocchi nativi su anthropic_messages, formato a involucro sul protocollo compatibile con OpenAI. /v1/messages di Kunavo inoltra il corpo così com'è stato inviato e non aggiunge punti di interruzione propri; quindi su questo protocollo gli indicatori sono quelli di Hermes oppure non ce ne sono.

Per un endpoint personalizzato, la durata è l'aspetto che la documentazione di Hermes lascia in sospeso. prompt_caching.cache_ttl — 5m, 1h o auto — è documentato per Claude tramite l'API Anthropic nativa, OpenRouter e Nous Portal, senza indicazioni sugli altri endpoint. Kunavo inoltra l'indicatore ricevuto e addebita la scrittura alla stessa tariffa; quindi verifica i dati nei tuoi consumi: se un turno dopo una pausa di dieci minuti mostra ancora una lettura dalla cache, significa che la voce era valida per un'ora.

Sul protocollo compatibile con OpenAI, Kunavo inserisce autonomamente i punti di interruzione per i modelli Claude — nel prompt di sistema, nelle definizioni degli strumenti e alla fine della conversazione — non appena il prompt è abbastanza lungo da essere memorizzato nella cache, indipendentemente dal fatto che il client invii o meno un indicatore. I modelli GPT vengono memorizzati implicitamente nella cache dal rispettivo fornitore.

A prescindere da quale componente inserisca i punti di interruzione, il costo è lo stesso. Su Claude Sonnet 5 una lettura dalla cache costa $0.14 per 1M token, rispetto a $1.40 per gli input non memorizzati in cache; una scrittura nella cache costa $1.75: il sovrapprezzo che Claude applica alla scrittura rispetto all'input, addebitato alla stessa tariffa quando la voce richiede una durata di un'ora. Una voce dura cinque minuti e ogni lettura ne rinnova la durata, quindi il costo per un agente dipende meno dal modello che dal fatto che la richiesta successiva arrivi entro questa finestra. Le tariffe della cache per ogni modello sono indicate nella pagina sulla memorizzazione nella cache dei prompt.

Un comportamento di Hermes costa più di qualsiasi tariffa: la sua documentazione segnala che un cambio di modello durante una sessione, un fallback automatico o la rotazione delle credenziali azzera la cache del prompt; di conseguenza, il messaggio successivo rilegge l'intera conversazione alla tariffa di input piena. Scegli il modello prima di avviare una sessione lunga.

Costo giornaliero di un agente sempre attivo

Su Hermes, quando nessuno sta scrivendo, i costi dipendono da ciò che hai pianificato, oltre che dalle attività secondarie avviate da ogni conversazione. La documentazione di cron specifica che ogni esecuzione pianificata avvia una nuova sessione, quindi a ogni attivazione viene addebitato l'intero prompt — istruzioni, schemi degli strumenti e competenze allegate. La dimensione del prompt dipende dalla configurazione; perciò la tabella presenta esplicitamente un'ipotesi: 20.000 token per esecuzione e un'esecuzione ogni 30 minuti, 48 al giorno. Sostituisci entrambi i valori con i tuoi.

Tre impostazioni modificano questa cifra, tutte documentate da Hermes. Un job pianificato usa il modello specificato per quel job, altrimenti cron.model, oppure il modello principale; quindi hermes config set cron.model claude-haiku-4-5 assegna tutti i job senza modello specificato a un livello meno costoso. Uno script di job che stampa {"wakeAgent": false} salta il modello per quell'esecuzione; un job senza agente non ne usa alcuno. Inoltre, le attività secondarie — compressione, titoli e visione — usano il modello principale, a meno che auxiliary non le indirizzi altrove:

# ~/.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 è l'impostazione che conta con una finestra ampia. Per impostazione predefinita, la compattazione inizia a metà della lunghezza del contesto; la documentazione di Hermes indica che questa impostazione consente di fissare un limite massimo al costo di una singola chiamata.

Le ore in cui l’agente è effettivamente al lavoro costituiscono l’altra metà della spesa, e in quel caso è la cache a fare la differenza. Considera 100 richieste consecutive, ognuna delle quali invia nuovamente un contesto di 100.000 token, aggiunge 2000 nuovi token e restituisce 800 token in output. Su Claude Sonnet 5, il costo è di circa $2.31 mentre il contesto viene letto dalla cache e di circa $14.84 quando ogni richiesta lo addebita come input nuovo. Stesso lavoro, stesso modello: la differenza dipende dalla presenza dei breakpoint e dal fatto che le richieste siano distanziate da meno di cinque minuti.

Per avere un riferimento concreto, basato su misurazioni e non su supposizioni: tra gli account Kunavo che eseguono un agente sempre attivo, il costo mediano di una giornata attiva è $12.67 e quello di una giornata al 90° percentile è circa $163. Sono importi fatturati fino a 5 ottobre 2026, alle tariffe in vigore in ciascun giorno. Il gruppo è piccolo: considera questi dati come un’indicazione dell’ampiezza dell’intervallo, non come una previsione per il tuo agente.

Quando il saldo si esaurisce

Kunavo è prepagato: ogni chiamata viene pagata dal portafoglio e un agente che lavora mentre dormi lo svuota mentre dormi. Una richiesta che il portafoglio non può coprire viene rifiutata con HTTP 402 e il codice insufficient_balance, indipendentemente dal protocollo; non viene addebitato alcun importo. Il rifiuto avviene prima che il saldo del portafoglio raggiunga zero: ogni richiesta riserva prima il costo massimo possibile, cioè il prompt più la risposta più lunga che è autorizzata a produrre. Di conseguenza, più alto è il limite di output richiesto da un agente, prima le sue chiamate iniziano a essere rifiutate. L’errore indica l’importo mancante nei campi balance_usd e needed_usd.

Quando un provider dà errore, Hermes Agent ricorre a una catena di fallback: fallback_providers in config.yaml, gestita con hermes fallback e provata turno per turno. La documentazione elenca limiti di frequenza, errori del server, errori di autenticazione e codici 404 tra le condizioni che la attivano per il modello principale, e include HTTP 402 tra gli errori di capacità che fanno passare un'attività secondaria al provider successivo nella catena; non specifica cosa accada a un turno con errore 402 se non è configurato alcun fallback. Preparati all'esito suggerito dall'interpretazione più semplice — il turno non va a buon fine e con esso il job pianificato — e ricorda che un turno che passa effettivamente al fallback inizia con una cache del prompt a freddo.

Due impostazioni impediscono a un agente non presidiato di trovarsi in questa situazione, e svolgono funzioni diverse:

• Ricarica automatica, in Fatturazione. Salva una carta una sola volta e imposta tre importi: il saldo al di sotto del quale ricaricare, l’importo da aggiungere ogni volta e un limite mensile. Il portafoglio si ricarica quindi entro pochi secondi da una chiamata che porta il saldo sotto la soglia. Una richiesta che arriva mentre il saldo del portafoglio è ancora insufficiente attende l’addebito e viene quindi evasa invece di essere rifiutata. Un 402 viene comunque restituito se non è possibile effettuare l’addebito — per una carta rifiutata o perché è stato raggiunto il limite mensile — oppure se una richiesta riserva un importo superiore a quello disponibile nel portafoglio dopo la ricarica. È necessaria una carta o Link: Alipay, WeChat Pay, Pix e gli altri metodi di pagamento locali non possono essere addebitati automaticamente.
• Un limite mensile per la chiave, in Chiavi API. Assegna all’agente una chiave dedicata e imposta la spesa massima consentita a tale chiave in un mese di calendario. Superato tale importo, le sue chiamate vengono rifiutate con un 402 e non viene addebitato nulla, mentre le altre chiavi continuano a funzionare. Questo è il limite massimo necessario per contenere un ciclo incontrollato, che il portafoglio non può fornire perché tutte le chiavi attingono allo stesso portafoglio.

Imposta la soglia di ricarica sopra l'importo riservato da una singola richiesta e scegli l'importo in base a una giornata di attività del tuo agente, non al minimo: la ricarica minima è $10 e la giornata mediana di un agente sempre attivo indicata sopra è $12.67. I limiti della ricarica automatica sono riportati nella pagina di fatturazione e il corpo completo dell'errore nella pagina degli errori.

Guide correlate

• API personalizzata per Hermes Agent: perché il provider in uscita non è il server API in ingresso, spiegazione del campo transport e controlli da eseguire alla prima chiamata.
• Prezzi di Hermes Agent — quanto costa eseguirlo, oltre alle tariffe dei token.
• Timeout durante la compressione del contesto di Hermes — cosa significa l'errore quando il riepilogatore si blocca e come ripristinare il funzionamento.
• Hermes vs OpenClaw — e la stessa configurazione per l'altro agente, nella pagina di OpenClaw.