Hermes

Hermes è un agente open source di Nous Research. La sua procedura guidata integrata hermes model può aggiungere HiAPI come endpoint personalizzato, così non ti serve uno strumento di gestione di terze parti. I passaggi seguenti usano claude-opus-5-5 come esempio; questo tutorial è stato verificato su Windows con Hermes 0.22.5.

1. Installare Hermes

1.1 Requisiti

1.2 Windows (PowerShell)

Salta la procedura guidata e configura il modello solo dopo l’installazione:

& ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -SkipSetup

Installazione standard (apre la procedura guidata):

iex(irm https://hermes-agent.nousresearch.com/install.ps1)

1.3 macOS / Linux

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-setup

1.4 Verificare l’installazione

Riapri il terminale ed esegui:

hermes --version

Basta vedere il numero di versione; prosegui quando c’è un output.

1.5 Altri metodi di installazione

Lo script di installazione e i requisiti di versione seguono la documentazione ufficiale di installazione di Hermes.

2. Configurare l’endpoint HiAPI

Hermes ha due comandi relativi ai modelli con scopi diversi; non confonderli:

Per aggiungere HiAPI usa hermes model, quindi esci prima dalla sessione (Ctrl+C o /quit).

2.1 Eseguire la procedura guidata

hermes model

Scegli Custom endpoint (self-hosted / VLLM / etc.) (alcune versioni mostrano Custom endpoint (enter URL manually)).

2.2 Compilare ogni richiesta

Per i modelli Claude scegli Anthropic Messages come API compatibility mode. Con claude-opus-5-5 come esempio:

In modalità Anthropic Messages imposta l’API base URL sull’indirizzo radice https://api.hiapi.ai senza /v1; Hermes aggiunge /v1/messages da sé. La chiave API HiAPI è nascosta o mostrata come asterischi mentre la digiti; incollala e premi Invio.

2.3 Collegare GPT, DeepSeek e altri modelli

Per GPT, DeepSeek e altri modelli compila le altre voci come nella tabella sopra, cambia solo le due seguenti e sostituisci Model name con il nome del modello corrispondente. Nota che qui l’indirizzo include /v1.

Le combinazioni testate per questo tutorial sono: Anthropic Messages per Claude, Chat Completions per GPT e DeepSeek. Se un modello non supporta il protocollo scelto, ricevi un 400.

2.4 Passare a un altro modello

Per cambiare modello con lo stesso endpoint, digita direttamente in una sessione:

/model custom:<model-id>

Oppure esegui di nuovo hermes model per cambiare il modello predefinito. Quando passi a un altro modello, trova il nome nell’elenco dei modelli testuali e verifica che il contesto sia di almeno 64K. Altre opzioni per gli endpoint personalizzati sono nella documentazione sugli endpoint personalizzati di Hermes.

3. Configurazione manuale (facoltativa)

La configurazione manuale seguente funziona per GPT, DeepSeek e altri modelli che usano Chat Completions; per Claude usa la procedura guidata hermes model qui sopra. Se non puoi usare la procedura guidata, modifica direttamente ~/.hermes/config.yaml (base_url deve includere /v1):

model:
  default: <model-id>
  provider: custom
  base_url: https://api.hiapi.ai/v1
  api_key: YOUR_HIAPI_API_KEY

Puoi anche usare una variabile d’ambiente invece di una chiave in chiaro; key_env è il modo in cui Hermes legge una variabile d’ambiente, quindi lascialo così:

model:
  default: <model-id>
  provider: custom
  base_url: https://api.hiapi.ai/v1
  key_env: HIAPI_API_KEY

Poi scrivi questo in ~/.hermes/.env:

HIAPI_API_KEY=YOUR_HIAPI_API_KEY

Sostituisci YOUR_HIAPI_API_KEY con la tua chiave API HiAPI. Dopo aver modificato la configurazione, avvia una nuova sessione con /new o riavvia Hermes prima di provare.

4. Verificare

4.1 Chat

Apri Hermes, verifica che usi il provider HiAPI e invia “Ciao, presentati in una frase.” Una risposta normale significa che il collegamento funziona.

4.2 Tool calling

Prima crea tool-call-test.txt nella cartella in cui avvii Hermes, scrivi una riga hello hiapi e salva. Poi invia “Chiama lo strumento una sola volta. Leggi l’intero contenuto di tool-call-test.txt e restituiscilo esattamente com’è. Non indovinare il contenuto dal nome del file.” Verifica che compaia una chiamata allo strumento che restituisce hello hiapi.

5. Risoluzione dei problemi

Qui sono elencati solo i problemi specifici di Hermes. Per gli errori comuni come 401, 404 e 429, vedi Errori comuni.

Questa pagina copre solo i modelli testuali; per le capacità degli strumenti vedi la guida MCP.