API personalizzata di Hermes Agent: provider, trasporti e verifiche della prima chiamata

Un endpoint personalizzato di Hermes Agent viene configurato in uscita, come voce nominata in providers: all'interno di ~/.hermes/config.yaml, dove api è l'URL di base e transport è il protocollo di rete. È diverso dal server API di Hermes, che punta nella direzione opposta. Nei risultati di ricerca entrambi vengono chiamati «API personalizzata di Hermes» e le pagine di documentazione ufficiale di ciascuno si posizionano per le stesse query — quindi verificate prima la direzione.

Questa pagina riguarda Hermes Agent, l'agent open source di Nous Research. Un controllo dell'API di GitHub il 21 settembre 2026 ha restituito archived: false, disabled: false, una licenza MIT e un push effettuato lo stesso giorno; la release pubblicata più recente è Hermes Agent v0.21.3, contrassegnata con v2026.9.14 il 14 settembre 2026, non una prerelease. Le superfici da cui questa pagina ricava la configurazione sono quel repository e hermes-agent.nousresearch.com. hermes-agent.org tratta lo stesso progetto da un dominio esterno a nousresearch.com e carica le analisi di Microsoft Clarity (verificato il 21 settembre 2026); non è una delle superfici proprie del progetto, quindi non ricavate la configurazione da lì. Non si tratta neppure di Hermes 3 o Hermes 4, la famiglia di modelli open-weight di Nous, né del motore JavaScript omonimo.

Le due cose opposte chiamate API personalizzata di Hermes

Entrambe le righe sono citate dalle pagine ufficiali di Hermes, consultate il 21 settembre 2026: il riferimento dei provider e la pagina del server API. C'è una particolarità nei nomi che vale la pena verificare nella vostra installazione: la pagina del server API documenta hermes gateway come comando per avviarlo, mentre il riferimento della CLI descrive hermes gateway come gestore del servizio di messaggistica con i sottocomandi run, start, stop e status. Eseguite hermes gateway --help invece di procedere per supposizioni. Tutto ciò che segue riguarda la parte in uscita.

La configurazione minima in uscita

# ~/.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 per campo, dal riferimento dei provider: la chiave di configurazione è providers.<name>, il campo dell'URL di base è api (con base_url e url accettati come alias), la credenziale è key_env, un api_key inline oppure un key_cmd, e il protocollo è transport. La stessa voce accetta anche name, default_model, models, context_length, discover_models, extra_body, extra_headers, session_affinity_header, ssl_ca_cert / ssl_verify, catalog_provider e enabled: false. Selezionate la voce con model.provider: custom:kunavo, oppure durante la sessione con /model custom:kunavo:<model-id>.

Due comandi non sono intercambiabili. hermes model, eseguito al di fuori di una sessione chat, è la procedura guidata completa per la configurazione dei provider e l'unico comando che può aggiungere un provider o acquisire una chiave. /model all'interno di una sessione si limita a passare tra ciò che esiste già. Per gli endpoint aziendali che emettono token di breve durata, key_cmd indica un comando che stampa un token su stdout — semplice oppure in JSON con un campo access_token — che Hermes esegue e memorizza nella cache fino a poco prima della scadenza, e che è preferibile a un api_key o key_env statico nella stessa voce.

Scegli manualmente il trasporto invece di lasciare vuoto il campo

Il riferimento del provider elenca tre valori accettati per transport in una voce personalizzata. Specifica inoltre che la procedura guidata hermes model Custom Endpoint ora richiede esplicitamente il protocollo e salva la risposta in config.yaml, e che il rilevamento automatico basato sull'URL «avviene ancora come fallback quando il campo viene lasciato vuoto». L'unica regola di rilevamento esplicitata nella documentazione è una mappatura del percorso /anthropic a anthropic_messages, che un URL di base Kunavo non soddisfa; il resto dell'euristica non è elencato in nessuna pagina consultata qui, motivo per cui conviene compilare il campo invece di dedurre quale comportamento avrebbe. Kunavo espone /v1/chat/completions, /v1/messages e /v1/responses, quindi sulla carta ogni trasporto ha una route corrispondente.

La riga Anthropic merita una precisazione, non una risposta categorica. La guida Azure Foundry di Hermes afferma che /v1 viene rimosso dall'URL di base perché l'SDK Anthropic aggiunge /v1/messages a ogni richiesta — ma la frase compare sotto un'intestazione Azure, e l'esempio del riferimento del provider (api: https://proxy.example.com/anthropic) non dice mai quale suffisso Hermes aggiunga per un proxy generico. Entrambi i candidati sopra sono quindi plausibili e uno dei due potrebbe produrre un 404 con doppio-/v1. Controlla il percorso della richiesta registrato dalla prima chiamata; la documentazione sull'URL di base tratta il problema origine-versus-/v1 alla base della maggior parte dei 404 su questo canale. L'autenticazione è la preoccupazione minore: la route Messages di Kunavo accetta sia Authorization: Bearer sia x-api-key, quindi qualunque intestazione invii l'SDK Anthropic per un proxy generico dovrebbe essere accettata — ma Hermes non documenta questa scelta, quindi «dovrebbe» è il termine più corretto.

Una domanda aperta a cui neppure questa pagina darà risposta. Hermes documenta un aggiornamento silenzioso dei nomi dei modelli della famiglia GPT-5.x a codex_responses anche quando config.yaml continua a indicare chat_completions — ma la frase compare sotto provider: azure-foundry pur essendo formulata come rilevamento del nome del modello. Non è documentato se uno slug GPT su provider: custom attivi lo stesso passaggio. Se scegli un modello della classe GPT, registra la route raggiunta dalla prima chiamata.

Cosa un endpoint personalizzato non ottiene automaticamente, per trasporto

Nessuno di questi è un limite di piano. Secondo la FAQ della homepage del progetto, Hermes Agent è «gratuito e open source con licenza MIT», e il dict providers: è documentato come configurazione ordinaria, non come funzione riservata a un livello. Sono limiti di capacità e differiscono a seconda del canale.

Due vie di fuga specifiche per un gateway. catalog_provider accetta un ID provider Hermes o un ID models.dev e fa ereditare ai modelli della voce i metadati di quel catalogo — solo per le ricerche; le richieste continuano a essere inviate al tuo URL api con la tua chiave. Inoltre discover_models: false salta completamente la sonda /models e usa solo i modelli elencati nella voce, soluzione quando il rilevamento è rumoroso o lento. Qui non è stato verificato se la risposta /v1/models di Kunavo soddisfi la sonda di Hermes; in caso contrario, il rilevamento del contesto ricade sul valore predefinito di 128K. Il ragionamento sui costi alla base di queste impostazioni — slot ausiliari, worker di delega e continuità della cache — è riportato in Prezzi di Hermes Agent e non viene ripetuto qui.

Una sequenza di verifica da eseguire prima di affidarle lavoro reale

Questi sono passaggi da eseguire con l'osservazione attesa, non risultati ottenuti da Kunavo. Non è stata eseguita alcuna sessione Hermes contro Kunavo, non esiste una guida di configurazione Kunavo per Hermes e nulla in questa pagina deve essere interpretato come un'integrazione testata. Mantieni disponibile la route di lavoro per tutta la procedura.

1. Aggiungi il provider, poi esegui la diagnosi. hermes model lo aggiunge; hermes doctor è documentato come strumento per diagnosticare problemi di configurazione e dipendenze, e il riferimento CLI registra due controlli di configurazione per endpoint personalizzati — una chiave custom_providers che non è un elenco YAML e una voce di elenco legacy senza una voce providers: corrispondente. Entrambi producono solo avvisi e --fix non li riscrive.
2. Verifica che la chiave sia stata caricata prima di spendere. hermes dump stampa un riepilogo della configurazione copiabile e incollabile — versione, provider, modello e presenza o assenza di una chiave API. Aspettati il tuo ID modello e una chiave presente. hermes prompt-size funziona offline e restituisce una suddivisione in byte del prompt di sistema e degli schemi degli strumenti, la parte fissa trasmessa in ogni turno prima di qualsiasi contenuto della conversazione.
3. Un turno di testo non in streaming. Aspettati una risposta e che la richiesta sia stata inviata al percorso previsto. Un endpoint personalizzato che «funziona» ma restituisce dati senza senso è una voce della tabella di risoluzione dei problemi del quickstart di Hermes, che indica un URL di base errato, un nome di modello errato o un endpoint non realmente compatibile con OpenAI e consiglia di verificare prima l'endpoint in un client separato.
4. Un turno in streaming. Aspettati un output incrementale invece di un unico blocco finale. Questa pagina non ha verificato se la struttura dello streaming di uno specifico endpoint soddisfi l'analisi dell'avanzamento di Hermes.
5. Un ciclo di strumenti. Aspettati che lo strumento venga eseguito. Se invece la chiamata viene stampata come testo, si tratta del supporto al tool calling sul lato del servizio, non del trasporto.
6. Leggi il contatore. /usage è il pannello dei token, dei costi e del contesto nella sessione. Confrontalo con l'addebito effettivamente registrato dal tuo account provider — il calcolo autonomo di un agente sui token riportati è una stima, non un registro contabile. Consulta la documentazione sull'utilizzo.

Quanto costa la sequenza e quanto costa un cambio a metà sessione

Supponi che i sei passaggi sopra inviino 26.000 token di input e ricevano complessivamente 1.150 token di output — un prompt di sistema e uno schema degli strumenti fissi in ciascuna delle tre chiamate, più un risultato dello strumento reinviato una volta. Questa ipotesi è illustrativa; hermes prompt-size riporta il tuo prompt fisso come suddivisione in byte, più vicina alla realtà di un numero che questa pagina può stimare. Le tariffe sono i prezzi correnti del catalogo Kunavo per milione di token.

Si tratta di un calcolo illustrativo dei token alle tariffe di catalogo, non di un'attività Hermes misurata né di un limite massimo di fatturazione. Esclude scritture nella cache, strumenti esterni e imposte. Il punto del numero è la sua esiguità: verificare una route costa molto meno che scoprire una configurazione errata dopo una settimana di lavoro pianificato.

Il secondo numero è quello nascosto dal comando /model. Le cache dei prompt sono associate al modello che serve la richiesta, quindi qualsiasi cambio di modello a metà conversazione fa rileggere al messaggio successivo l'intera conversazione alla tariffa piena dell'input invece della tariffa della cache, che Hermes descrive come più economica di circa il 75-90 percento. In una conversazione di 120.000 token con Claude Sonnet 5, la differenza tra $1,40 per milione e la tariffa di lettura della cache $0,14 è di circa $0,151 per quel singolo turno — trascurabile una volta, ma non come abitudine. L'importo del catalogo Kunavo è un minimo di fatturazione, non un tetto: quando l'upstream comunica il proprio addebito, il conto è il maggiore tra il costo di catalogo e il costo upstream moltiplicato per il markup applicabile. Il minimo è una ricarica prepagata di $10 senza abbonamento. Consulta fatturazione.

Come annullare nuovamente la configurazione

Hermes documenta una procedura di annullamento, motivo per cui una prova comporta un rischio ridotto. enabled: false nella voce la nasconde senza eliminarla. Copie puntuali di config.yaml vengono scritte in backups/config/config.yaml.<reason>.<timestamp> prima che hermes setup o hermes migrate lo riscrivano e ogni volta che viene analizzato, saltando le ripetizioni identiche e conservando solo le cinque più recenti per motivo; se in seguito il file non può essere analizzato, Hermes serve la copia valida più recente invece dei valori predefiniti incorporati. Il riferimento della configurazione annota inoltre model.base_url come «cancellato al cambio di provider», quindi il ritorno a un provider incorporato è documentato come rimozione dell'URL di base obsoleto invece di lasciarlo nel file — controlla il valore scritto in seguito invece di darlo per scontato.

Tre insidie provengono dai tutorial più vecchi. L'elenco legacy custom_providers: di primo livello continua a funzionare e hermes update lo migra automaticamente nel dict providers:, dove il vecchio model diventa default_model e il vecchio api_mode diventa transport. LLM_MODEL in .env è stato rimosso completamente — config.yaml è l'unica fonte di verità. Inoltre, OPENAI_BASE_URL è documentato in due modi da due pagine ufficiali attuali: il riferimento del provider afferma che viene rispettato solo per il provider openai-api, mentre il riferimento delle variabili d'ambiente lo elenca come URL di base per un endpoint personalizzato. La discrepanza non è risolta, quindi configura l'endpoint in config.yaml e non affidarti a quella variabile d'ambiente come route.

Se stai scegliendo un provider invece di collegarne uno, API compatibile con OpenAI descrive cosa include e cosa non include la superficie compatibile, mentre Hermes rispetto a OpenClaw confronta i due agenti. Quando sei pronto a testare questa route con una chiave finanziata, crea un account Kunavo.

Domande frequenti

Documentazione di Hermes Agent — il riferimento del provider, la pagina del server API, la pagina di configurazione dei modelli, la pagina di configurazione, il riferimento CLI, il riferimento dei comandi slash, il quickstart e la homepage del progetto — consultata il 21 settembre 2026. Lo stato del repository e l'ultima release sono stati verificati tramite l'API GitHub lo stesso giorno. Le tre route API di Kunavo sono state confermate nel relativo codice sorgente. Ogni importo in dollari è un calcolo illustrativo dei token sulle tariffe correnti del catalogo, non il costo di un'attività misurata. La configurazione di Hermes è riportata dai documenti sorgente; non è stata eseguita alcuna sessione Hermes contro Kunavo.