Installazione di Hermes e configurazione di OmniProxy

Hermes è un assistente in grado di conservare le conversazioni e l’esperienza acquisita nelle attività, organizzando ciò che ha già fatto in competenze riutilizzabili in seguito. Tramite lo stesso Gateway può inoltre collegarsi a Telegram, Discord, Slack, WhatsApp, Signal e al terminale; il Gateway può essere considerato un punto di ingresso unificato che riceve e inoltra i messaggi. Puoi affidargli revisioni del codice, registri degli incidenti o materiali dei clienti dal tuo strumento di chat abituale, per poi farlo continuare a lavorare nel repository.

Preparazione all’installazione

Scegli innanzitutto il metodo di installazione in base al sistema operativo del computer. Su macOS e Windows puoi usare direttamente il pacchetto di installazione con interfaccia grafica; su Linux, macOS e WSL2 puoi utilizzare lo script da terminale. WSL2 è una funzionalità che consente di eseguire un ambiente Linux in Windows. Sono disponibili metodi di installazione specifici anche per Termux su telefoni Android e per Docker, ma questa guida tratta soltanto l’installazione sui normali computer.

Vuoi una finestra

macOS、Windows

macOS: apri il DMG
Windows: apri il pacchetto di installazione
Sposta l'app nel sistema

Solo terminale

Linux、macOS、WSL2

Un unico install.sh
Su Windows usa install.ps1
Al termine inserisci hermes

Non usarli per ora

pip、brew、AUR

Questi metodi di installazione non sono supportati ufficialmente
Anche gli aggiornamenti successivi sono difficili
Usa invece le due opzioni a sinistra

Questa guida utilizza due metodi: il pacchetto di installazione con interfaccia grafica e lo script da terminale. pip, brew e AUR non rientrano tra i metodi di installazione supportati ufficialmente.

Prima di iniziare, prepara un computer macOS, Windows o Linux e verifica che possa aprire il terminale e accedere a GitHub. Se intendi eseguire l’installazione su un disco esterno, collegalo prima e assicurati che disponga di spazio sufficiente.

Installazione e primo avvio

Se vuoi un’interfaccia grafica

Vai alla sezione Download del sito di Hermes e scarica il pacchetto di installazione adatto al tuo sistema. Il pacchetto include già l’ambiente di esecuzione, quindi al primo avvio non è necessario compilare il programma sul computer.

macOS: apri il DMG e sposta Hermes.app in «Applicazioni». Un DMG è un file immagine di installazione usato comunemente su macOS. Questo pacchetto supporta soltanto i Mac con chip Apple; i Mac Intel non sono supportati.
Windows: apri il file .appinstaller con il programma di installazione applicazioni di Windows. Verrà installato un MSIX firmato, ossia un tipo di pacchetto di installazione usato da Windows.
Linux: il pacchetto desktop è destinato a macOS e Windows. Su Linux usa il comando da terminale indicato di seguito; al termine dell’installazione potrai eseguire hermes desktop.

Se ti serve soltanto il terminale

Se usi Linux, macOS o WSL2, esegui nel terminale:

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

Se usi PowerShell incluso in Windows, esegui:

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

Il programma di installazione scaricherà il codice di Hermes e i programmi necessari per eseguirlo. Se il download si interrompe, esegui nuovamente lo stesso comando. Al termine dell’installazione, chiudi il terminale corrente, apri una nuova finestra e digita:

hermes

Se compare il prompt di Hermes, il comando è disponibile. Puoi quindi eseguire hermes doctor, uno strumento di verifica dell’installazione che segnala gli eventuali componenti ancora mancanti.

Installazione del programma su un disco esterno

Il 9 ottobre 2026, Hermes Agent v0.21.6 è stato installato su un disco esterno collegato a un Mac. Il programma si trova in /Volumes/AItools/tools/hermes-agent, il comando di avvio in ~/.local/bin/hermes, mentre la configurazione e le conversazioni restano in ~/.hermes.

Se il tuo disco ha un nome diverso, sostituisci il percorso dopo --dir con quello della tua cartella. Il disco deve rimanere collegato mentre Hermes è in esecuzione.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o install.sh
bash install.sh --dir /Volumes/AItools/tools/hermes-agent --non-interactive

Programma

Disco rigido esterno

tools/hermes-agent
Metti qui il codice

Comando

~/.local/bin/hermes

Inserisci hermes nel terminale
Diventa effettivo dopo aver aperto una nuova finestra

Configurazione e conversazioni

~/.hermes

Qui si trova config.yaml
Esci prima di scollegare il disco rigido

Questa è la suddivisione usata su quel Mac. L'installazione predefinita colloca il programma nella directory dell'utente, con lo stesso risultato: dopo aver aperto un nuovo terminale, digita hermes.

Ottenere i parametri di connessione da OmniProxy

In questa configurazione Hermes si collega a OmniProxy, non direttamente a Grok o Gemini. Gli indirizzi dei servizi Grok e Gemini vengono configurati in OmniProxy e non devono essere inseriti direttamente in Hermes.

Il tuo computer

Hermes

Gateway locale

OmniProxy

Imposta l'indirizzo fino a /v1

Grok

grok-4.7

Gemini

gemini-3.8-flash

Hermes vede OmniProxy. Le richieste verso Grok e Gemini vengono inoltrate da OmniProxy.

L’ID modello è il nome esatto usato dall’API per identificare il modello. Per i due modelli usa i nomi seguenti:

Per Grok inserisci grok-4.7. L’interfaccia di xAI è https://api.x.ai/v1 e le richieste di chat usano /v1/chat/completions. Consulta la documentazione dei modelli Grok.
Per Gemini inserisci gemini-3.8-flash. L’interfaccia di Google compatibile con OpenAI è https://generativelanguage.googleapis.com/v1beta/openai/. Consulta le informazioni sulla compatibilità di Gemini con OpenAI.

Per passare a Gemini in Hermes, basta sostituire il nome del modello con gemini-3.8-flash; come indirizzo dell’interfaccia devi continuare a usare quello di OmniProxy.

Copia da OmniProxy l’indirizzo dell’interfaccia e la chiave, quindi inserisci l’ID modello corrispondente:

Base URL: https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: grok-4.7

Base URL è l’indirizzo dell’interfaccia al quale Hermes invia le richieste; in questo caso deve terminare con /v1. API Key è la chiave fornita da OmniProxy a Hermes: sostituiscila con la tua e non pubblicarla su pagine accessibili pubblicamente.

Se OmniProxy in esecuzione sul computer locale non richiede una chiave, puoi lasciare vuoto API Key; se l’indirizzo è accessibile da altre persone, devi impostare una chiave. Verifica inoltre che l’indirizzo sia raggiungibile dall’ambiente in cui viene eseguito Hermes. Se Hermes e OmniProxy si trovano sullo stesso computer, puoi usare un indirizzo locale.

Inserire la configurazione dello strumento

Esci prima dalla chat in corso, quindi esegui nel terminale:

hermes model

Seleziona Custom endpoint (self-hosted / VLLM / etc.). Custom endpoint indica un endpoint personalizzato e consente a Hermes di collegarsi all’indirizzo del servizio specificato, invece di usare un provider preimpostato.

La procedura guidata chiederà, nell’ordine, l’indirizzo dell’interfaccia, la chiave e il nome del modello. Inserisci i tre valori indicati nella sezione precedente. Per usare Gemini, inserisci gemini-3.8-flash come nome del modello.

Puoi anche modificare direttamente ~/.hermes/config.yaml. YAML è un formato di testo che rappresenta le relazioni di configurazione tramite l’indentazione. Questa è la configurazione per Grok:

model:
  default: grok-4.7
  provider: custom
  base_url: https://your-omniproxy-origin.example/v1
  api_key: <YOUR_OMNIPROXY_API_KEY>

Per usare Gemini, sostituisci default con gemini-3.8-flash e lascia invariate le altre tre voci:

model:
  default: gemini-3.8-flash
  provider: custom
  base_url: https://your-omniproxy-origin.example/v1
  api_key: <YOUR_OMNIPROXY_API_KEY>

Dopo aver salvato, esegui nuovamente hermes e avvia una chat. In una sessione già aperta, /model consente soltanto di passare da un provider salvato a un altro e non può essere usato per aggiungere questa configurazione.

Verificare un’attività reale

hermes doctor

Il controllo dell'installazione è riuscito

Invia una frase breve

Visualizza la risposta di Hermes

Apri il registro delle chiamate

Verifica il nome del modello

La configurazione può essere considerata utilizzabile soltanto dopo aver completato tutti e tre i passaggi.

Esegui hermes doctor per verificare che l’installazione sia completa.
Esegui hermes e chiedigli di spiegare in una frase cosa può fare. Dovresti ricevere una risposta.
Apri i registri delle chiamate di OmniProxy, verifica che la richiesta provenga da Hermes e controlla che il nome del modello sia grok-4.7 oppure gemini-3.8-flash.

Il semplice fatto che la procedura guidata abbia salvato correttamente la configurazione, o che l’interfaccia abbia restituito una risposta positiva, non dimostra ancora che Hermes possa completare attività per tuo conto. Il nome del modello nei registri delle chiamate deve corrispondere a quello inserito.

Per usare la chat nel browser, esegui sul computer locale:

hermes dashboard --no-open --host 127.0.0.1 --port 9119

Apri quindi http://127.0.0.1:9119. Questo indirizzo funziona soltanto sul computer corrente.

Errori comuni

Se digitando hermes viene segnalato che il comando non è stato trovato, chiudi il terminale e apri una nuova finestra. Se il comando non viene ancora trovato, verifica che ~/.local/bin sia incluso in PATH; PATH è l’elenco delle directory in cui il sistema cerca i comandi. Su Windows, verifica invece che la directory di avvio aggiunta dal programma di installazione sia inclusa in PATH.
Se il download dell’installazione si interrompe a metà, esegui nuovamente lo stesso comando di installazione: le parti già scaricate verranno riutilizzate.
Se Hermes non risponde o segnala che non riesce a connettersi, verifica che OmniProxy sia in esecuzione e che Base URL termini con /v1. Se Hermes viene eseguito in Docker e OmniProxy si trova nel sistema host, non usare 127.0.0.1, che è valido soltanto all’interno del container.
Se viene segnalata una chiave errata, aggiorna la chiave di OmniProxy e modifica quindi api_key in config.yaml. Le chiavi di xAI o Google appartengono alle impostazioni dei provider di OmniProxy e non devono essere inserite in questo campo di Hermes.
Se viene segnalato che il modello non esiste, apri l’elenco corrente dei modelli di OmniProxy e copia grok-4.7 o gemini-3.8-flash esattamente come appare nell’elenco.
Se Hermes risponde ma non riesce a svolgere operazioni come leggere file o eseguire comandi, passa a un altro modello di OmniProxy dotato di queste capacità e avvia una nuova sessione di Hermes.
Se il programma è installato su un disco esterno e hermes doctor segnala un errore di archiviazione dopo che il disco è stato scollegato, ricollega prima il disco. Non lasciare che Hermes scriva una configurazione separata mentre il disco non è collegato.

Riferimenti ufficiali

Per i passaggi di installazione, consulta la documentazione sull’installazione di Hermes e le informazioni sulle piattaforme supportate. Per la configurazione di Custom endpoint, consulta la documentazione sui provider di Hermes. Per gli ID modello, consulta rispettivamente la documentazione dei modelli Grok e le informazioni sulla compatibilità di Gemini con OpenAI.

L’installazione su macOS è stata completata il 2026-10-09 usando Hermes Agent v0.21.6. grok-4.7 e gemini-3.8-flash erano gli ID modello standard riportati quel giorno nella documentazione di xAI e Google. Quando inserisci i valori effettivi, usa come riferimento i nomi visualizzati in OmniProxy.

Sostituisci ogni segnaposto con valori dalla tua configurazione OmniProxy personale. Non pubblicare mai una chiave reale.

Un risultato salvato o HTTP 200 da soli non provano la piena compatibilità con l'Agente. Controlla l'origine e il modello nel registro delle chiamate di OmniProxy.

Fonti ufficiali · Hermes ↗