Come configurare Hermes Agent con OmniaKey: endpoint OpenAI-compatible

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

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

Configurazione in config.yaml

Per una configurazione persistente con più modelli, usa ~/.hermes/config.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 elenca tutti gli id che puoi impostare, e i prezzi mostrano la tariffa per token di ciascuno. La stessa chiave funziona anche in altri agent; vedi le guide per configurare OpenClaw, la chiave API personalizzata in Cline e configurare Claude Code.

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 e dalla referenza di configurazione.

/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:<model ID>, 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
• Nous Research: configurazione di Hermes Agent

La guida agli agenti di coding copre gli altri strumenti.