Come configurare Hermes Agent con OpenRouter

OpenRouter è il punto di partenza consigliato per Hermes

Quando configuri Hermes Agent per la prima volta, devi puntarlo su un provider LLM. La quickstart ufficiale supporta Nous Portal, OpenRouter, OpenAI, Anthropic e qualsiasi endpoint compatibile con OpenAI. In pratica, OpenRouter è la scelta migliore per la maggior parte degli utenti, soprattutto alla prima distribuzione.

Il motivo è semplice: OpenRouter è una singola chiave API che ti dà accesso a centinaia di modelli di provider diversi. Invece di gestire account separati su OpenAI, Anthropic e Nous Portal, hai un'unica interfaccia di fatturazione, un'unica chiave API e un selettore di modelli che non richiede di riconfigurare Hermes ogni volta che vuoi provare qualcosa di diverso.

Per un agente in continuo miglioramento come Hermes, progettato per diventare più capace nel tempo, poter cambiare modello senza modifiche all'infrastruttura è molto utile. Puoi iniziare con un modello più economico per l'uso quotidiano e passare a uno più potente per attività complesse senza toccare la tua installazione di Hermes.

Come ottenere la tua chiave API OpenRouter

La configurazione è rapida:

1. Vai su openrouter.ai e crea un account.
2. Vai su Settings → API Keys e genera una nuova chiave.
3. Copia la chiave: inizia con sk-or-.
4. Aggiungi crediti al tuo account. OpenRouter supporta la fatturazione a consumo, quindi puoi partire con una piccola somma.

La chiave che copi è quella che fornirai a Hermes (o a Hermify se usi l'hosting gestito) come OPENROUTER_API_KEY.

Configurare Hermes per usare OpenRouter

Se esegui Hermes in locale, la configurazione avviene nel file config.yaml. La sezione rilevante è questa:

provider: openrouter
model: anthropic/claude-3-5-sonnet
openrouter_api_key: sk-or-your-key-here

Puoi anche usare il comando di configurazione interattiva:

hermes setup

Questo ti guida nella scelta del provider e del modello, e scrive la configurazione per te. Se vuoi cambiare il modello in seguito senza eseguire di nuovo l'intera configurazione, puoi usare:

hermes model

Questo apre un selettore di modelli senza reimpostare il resto della tua configurazione.

Scegliere il modello giusto su OpenRouter

OpenRouter espone centinaia di modelli. La scelta giusta dipende dal tuo caso d'uso e dal budget. Ecco le opzioni pratiche per Hermes:

I migliori modelli per uso generale su OpenRouter:

• anthropic/claude-3-5-sonnet: ragionamento solido, segue bene le istruzioni multi-step, ottimo per workflow complessi. È il modello con cui inizia la maggior parte degli utenti di Hermes.
• openai/gpt-4o: veloce, capace, ottimo per codice e attività strutturate.
• meta-llama/llama-3.1-70b-instruct: pesi aperti, costo per token più basso, adatto per workflow ad alto volume.
• nousresearch/hermes-3-llama-3.1-405b: il modello della famiglia Hermes di Nous. Si adatta naturalmente ai prompt di sistema di Hermes Agent, dato che entrambi provengono dallo stesso laboratorio.
• google/gemini-2.0-flash: veloce ed economico, adatto per applicazioni sensibili alla latenza.

Approccio economico: inizia con llama-3.1-70b-instruct per l'uso quotidiano. Passa a Claude o GPT-4o per attività che richiedono un ragionamento più potente o finestre di contesto più ampie.

L'approccio con il modello Nous: nousresearch/hermes-3-llama-3.1-405b vale la pena testarlo proprio perché il runtime dell'agente Hermes è stato costruito attorno ai modelli Nous. L'allineamento tra lo stile di prompting dell'agente e il training del modello tende a essere più stretto rispetto ai modelli di terze parti.

Consigli di configurazione specifici per OpenRouter

Alcune cose importanti specificamente per OpenRouter con Hermes:

Imposta una preferenza di provider. OpenRouter instrada le richieste verso più provider di infrastruttura. Se usi modelli Anthropic, puoi fissare l'infrastruttura di Anthropic impostando provider_order nella tua configurazione. Questo riduce la varianza della latenza.

Configura i modelli di fallback. Hermes supporta provider ausiliari in config.yaml. Questo significa che se il tuo modello principale non è disponibile, Hermes può ricorrere a uno secondario. Con OpenRouter, puoi specificare più modelli come fallback in auxiliary_providers.

Tieni d'occhio la finestra di contesto. Hermes usa la memoria persistente e i file di contesto, il che significa che i prompt possono essere lunghi. I modelli con finestre di contesto più piccole (meno di 32k token) possono raggiungere i limiti più in fretta del previsto. Se noti risposte che sembrano ignorare il contesto recente, il modello potrebbe stare troncando il tuo file di memoria. Passa a un modello con una finestra di contesto più ampia: Claude e Gemini offrono entrambi 128k+.

Errori di configurazione comuni

Usare il base URL sbagliato. Hermes si aspetta un endpoint compatibile con OpenAI. Il base URL di OpenRouter è https://openrouter.ai/api/v1. Alcuni utenti usano per errore l'URL di OpenAI, il che causa errori di autenticazione con le chiavi OpenRouter.

Dimenticare l'header HTTP-Referer. OpenRouter richiede un header HTTP-Referer nelle richieste API per identificare la tua applicazione. Hermes lo gestisce automaticamente quando configuri openrouter come provider, ma se usi una configurazione con endpoint personalizzato, devi aggiungere questo header manualmente.

Esaurimento della quota a sessione in corso. OpenRouter blocca le richieste quando i tuoi crediti si esauriscono, e Hermes lo segnala come errore nel terminale o nell'interfaccia di messaggistica. Aggiungere una piccola soglia di ricarica automatica nelle impostazioni di OpenRouter evita che questo interrompa workflow lunghi.

Scegliere un modello che non supporta le chiamate agli strumenti. Hermes si affida all'uso degli strumenti per molte delle sue funzionalità (scrittura di file, fetch web, attività pianificate). Alcuni modelli più economici su OpenRouter non supportano il tool calling. Controlla i flag delle funzionalità del modello nella pagina del modello su OpenRouter prima di cambiare.

Cosa cambia se usi l'hosting gestito

Se distribuisci Hermes tramite Hermify, la configurazione del provider funziona allo stesso modo, ma inserisci la tua chiave API OpenRouter attraverso la dashboard di onboarding invece di modificare un file di configurazione. Hermify la archivia in modo crittografato e la inietta nel runtime all'avvio.

Puoi anche aggiornare la chiave del provider o cambiare modello dalla dashboard di Hermify senza riavviare il container manualmente. Questa è la principale differenza operativa: invece di accedere via SSH per modificare config.yaml, usi l'interfaccia delle impostazioni, avvii un riavvio e la modifica diventa effettiva in pochi secondi.

Il piano Starter è progettato specificamente attorno al BYOK con OpenRouter: porti tu la chiave, Hermify si occupa di tutto il resto. Se vuoi saltare completamente l'account OpenRouter, i piani Pro e Dedicated includono l'accesso ai modelli, quindi non devi configurare alcun provider di terze parti.

Una configurazione di partenza pratica

Se vuoi un'impostazione predefinita solida e non vuoi perdere tempo a confrontare modelli, questa è la configurazione che funziona bene per la maggior parte degli utenti di Hermes su OpenRouter:

• Provider: OpenRouter
• Modello: anthropic/claude-3-5-sonnet per l'uso principale
• Fallback: meta-llama/llama-3.1-70b-instruct
• Finestra di contesto: 200k token (Claude lo supporta)
• Carico iniziale di crediti: $10-$20 (in genere dura diverse settimane di utilizzo regolare)

Da lì puoi calibrare il modello man mano che capisci meglio i tuoi pattern di utilizzo. Hermes è progettato per sessioni di lunga durata, quindi il modello che scegli influisce sulla qualità della memoria e sull'affidabilità degli strumenti, non solo sulla velocità delle risposte.

Se vuoi saltare il lavoro di configurazione e arrivare più velocemente a una distribuzione funzionante di Hermes, Hermify gestisce il collegamento al provider per te. Puoi anche leggere di più sulla differenza di costo reale tra distribuzioni self-hosted e gestite di Hermes prima di decidere.