# Come configurare Hermes Agent con OmniaKey: endpoint OpenAI-compatible > Collega Hermes Agent a un endpoint OmniaKey compatibile con OpenAI. Usa hermes model o config.yaml, cambia modello e risolvi gli errori 404. - Canonical HTML: https://omniakey.com/it/blog/hermes-setup - Markdown: https://omniakey.com/it/blog/hermes-setup.md - Published: 2026-05-24 (updated 2026-10-30) - Author: Kiki, COO at OmniaKey - Language: it - Category: Guide - Reading time: 4 min - All posts: https://omniakey.com/blog/llms.txt --- Aggiornato il 30 ottobre 2026: quattro errori di configurazione comuni di Hermes ora riportano sintomo, causa e soluzione, presi dalla documentazione ufficiale di Hermes Agent. Per **configurare Hermes Agent API** basta aggiungere un endpoint personalizzato OpenAI-compatible. Hermes Agent di Nous Research può passare da Claude a GPT, Gemini o Grok usando il model ID. ## Metodo rapido: `hermes model` ```bash hermes model ``` Scegli **Custom endpoint (self-hosted / VLLM / etc.)** e inserisci: - **Base URL:** `https://api.omniakey.com/v1` - **API key:** la tua chiave OmniaKey - **Model:** ad esempio `claude-opus-4-8` > Termina la Base URL con `/v1`. Hermes aggiunge `/chat/completions`; un percorso completo o una barra finale causa spesso un 404. ## Configurazione in `config.yaml` Per una configurazione persistente con più modelli, usa `~/.hermes/config.yaml`: ```yaml model: provider: custom base_url: https://api.omniakey.com/v1 api_key: your-omniakey-api-key default: claude-opus-4-8 models: - claude-opus-4-8 - gpt-5.5 - gemini-3.1-pro-preview - grok-4.5 ``` `provider: custom` dice a Hermes di chiamare direttamente il tuo endpoint. La lista `models:` alimenta il selettore `/model`; riavvia Hermes dopo la modifica e passa tra `claude-opus-4-8`, `gpt-5.5`, `gemini-3.1-pro-preview` e `grok-4.5` senza uscire dalla sessione. ## Una chiave, quattro famiglie OmniaKey sceglie il modello per ID sul suo endpoint compatibile con OpenAI. Un solo endpoint copre le quattro famiglie, con tariffazione a token da un saldo prepagato. L'ID configurato è quello eseguito, senza fallback silenziosi. Il [catalogo dei modelli](https://omniakey.com/it/models) elenca tutti gli id che puoi impostare, e [i prezzi](https://omniakey.com/it/pricing) mostrano la tariffa per token di ciascuno. La stessa chiave funziona anche in altri agent; vedi le guide per [configurare OpenClaw](https://omniakey.com/it/blog/openclaw-setup), [la chiave API personalizzata in Cline](https://omniakey.com/it/blog/cline-custom-api-key) e [configurare Claude Code](https://omniakey.com/it/blog/claude-code-setup). - **OpenAI-compatible**: - **Anthropic-native**: - **Gemini-native**: ## Errori di configurazione comuni Questi quattro capitano spesso quando Hermes punta a un endpoint personalizzato. La causa e la soluzione vengono dalla [documentazione sui provider di Hermes](https://hermes-agent.nousresearch.com/docs/integrations/providers) e dalla [referenza di configurazione](https://hermes-agent.nousresearch.com/docs/user-guide/configuration). ### `/model` non propone l'endpoint personalizzato Sintomo: digiti `/model` in una sessione attiva e OmniaKey non compare nell'elenco. Causa: `/model` dentro una sessione cambia solo tra i provider che hai già configurato. Non può aggiungere un provider, avviare OAuth o chiedere una chiave API. Soluzione: esci dalla sessione, esegui `hermes model` nel terminale, configura lì l'endpoint personalizzato e avvia una nuova sessione. ### Una chiave in `.env` viene ignorata e le richieste vanno a un altro provider Sintomo: metti la base URL o la chiave in `~/.hermes/.env` e Hermes continua a chiamare un provider integrato. Causa: `LLM_MODEL` in `.env` è stato rimosso, `config.yaml` è l'unica fonte per modello ed endpoint, e `OPENAI_BASE_URL` vale solo per il provider `openai-api`. Soluzione: metti `base_url` e `api_key` nel blocco `model:` di `~/.hermes/config.yaml`, oppure punta `key_env` alla variabile che contiene la chiave. Con `base_url` impostato, Hermes chiama quell'endpoint direttamente e si autentica con `api_key` o `OPENAI_API_KEY`. ### Hermes non parte con `provider: main` Sintomo: l'avvio fallisce, o il selettore dei modelli resta vuoto, dopo che hai messo `provider: main` nel blocco `model:` di primo livello. Causa: `main` significa "usa il provider del mio agente principale" e vale solo dentro `auxiliary:`, `compression:` o una voce di fallback. Soluzione: metti `provider: custom` in `model:`, accanto alla `base_url` e alla chiave OmniaKey. ### `/model custom` finisce sul modello sbagliato Sintomo: `/model custom` sceglie un modello che non hai chiesto, o dà errore. Causa: `/model custom` senza nome interroga l'API `/models` dell'endpoint e sceglie da solo solo quando è caricato esattamente un modello; OmniaKey ne serve diversi. Soluzione: indica il modello, per esempio `/model custom:claude-opus-4-8`. ## Domande frequenti ### Come collego Hermes Agent a OmniaKey? Esegui `hermes model`, scegli Custom endpoint (self-hosted / VLLM / etc.) e inserisci `https://api.omniakey.com/v1` come base URL, la tua chiave OmniaKey e un model ID come `claude-opus-4-8`. Gli stessi tre valori in `~/.hermes/config.yaml` bastano se preferisci modificare il file. ### Perché Hermes restituisce 404 con la mia base URL OmniaKey? La base URL deve fermarsi a `/v1`. Hermes aggiunge `/chat/completions` da sé, quindi una URL che contiene già quel percorso, o con uno slash finale, è la causa abituale del 404. ### Una sola chiave OmniaKey copre Claude, GPT, Gemini e Grok? Sì. OmniaKey sceglie il modello per ID sul suo endpoint compatibile con OpenAI, quindi un solo endpoint copre le quattro famiglie: cambi l'ID, non il blocco provider. Aggiungi gli ID che vuoi alla lista `models:` e compaiono nel selettore `/model`. ### Come cambio modello a metà sessione? Digita `/model custom:`, per esempio `/model custom:gpt-5.5`. Dopo aver modificato la lista `models:` riavvia Hermes una volta: selettore e `/model` vedono i nuovi ID. ## Fonti verificate - [Nous Research: provider LLM e modelli](https://hermes-agent.nousresearch.com/docs/integrations/providers) - [Nous Research: configurazione di Hermes Agent](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) La [guida agli agenti di coding](https://docs.omniakey.com/en/coding) copre gli altri strumenti.