Assistente AI Hermes - Installazione, Configurazione, Flusso di Lavoro e Risoluzione dei Problemi
Installazione e avvio rapido di Hermes Agent per gli sviluppatori
Hermes Agent è un assistente AI self-hosted, agnostico rispetto al modello, che gira su una macchina locale o su un VPS a basso costo, opera tramite interfaccia terminale e di messaggistica e migliora nel tempo trasformando i compiti ripetitivi in competenze riutilizzabili.
Per funzionalità è molto simile a OpenClaw, un altro stack di assistenti self-hosted costruito attorno a strumenti, memoria e controllo locale.
Se desideri una visione più ampia degli assistenti self-hosted, del recupero e dell’infrastruttura locale attorno a Hermes, questa panoramica sui sistemi AI collega questi argomenti agli stessi problemi che Hermes cerca di risolvere.
Per quanto riguarda i compromessi di deployment e le scelte runtime, Hosting LLM nel 2026: Locale, Self-Hosted e Confronto Infrastruttura Cloud fornisce la mappa dell’hosting, mentre Prestazioni LLM nel 2026: Benchmark, Colli di Bottiglia e Ottimizzazione copre il lato throughput e latenza una volta che Hermes è in esecuzione.
La mia opinione parziale: Hermes è più interessante se trattato come infrastruttura, non come una scheda che apri occasionalmente. Una volta che gira come servizio e ha un directory home stabile, i tuoi prompt iniziano a sembrare meno come “chat” e più come “ops”.
Cos’è Hermes Agent e perché è importante
Hermes Agent è un agente AI open-source sviluppato da Nous Research. È progettato per eseguire in modo persistente, utilizzare strumenti (terminale, file, web e altro) e migliorare il proprio comportamento nel tempo con un sistema di competenze e memoria.
Due scelte di design meritano di essere spiegate perché plasmano tutto il resto in questa guida.
In primo luogo, Hermes non è bloccato su un singolo provider di modelli. Il flusso di configurazione ufficiale supporta più provider e qualsiasi endpoint compatibile con OpenAI, e il passaggio si effettua tramite il comando hermes model piuttosto che con modifiche al codice.
In secondo luogo, Hermes traccia una linea netta tra “conversazione” ed “esecuzione”. L’agente può chiacchierare tutto il giorno, ma quando deve agire, lo fa attraverso strumenti espliciti e un backend di esecuzione configurabile. È qui che risiedono sicurezza, riproducibilità e risoluzione dei problemi.
Costi e licenze sono piacevolmente noiosi. Hermes Agent stesso è software libero sotto licenza MIT. Se usi modelli ospitati, il costo ricorrente è quello che il tuo provider addebita. Se esegui modelli locali, puoi evitare completamente le tariffe API.
Installa Hermes Agent
Hermes ha un percorso di installazione rapido per Linux, macOS e WSL2. La documentazione ufficiale lo mantiene intenzionalmente semplice.
Installazione in un comando
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Dopo l’installazione, ricarica il tuo shell e avvia la CLI.
source ~/.bashrc # o source ~/.zshrc
hermes
L’installer non è solo un wrapper sottile. Secondo la guida di installazione, configura le dipendenze, il repository, un ambiente virtuale e il comando hermes, portandoti a uno stato pronto per la prima chat.
Note per Windows e Android
Windows nativo non è supportato. La documentazione raccomanda WSL2 e l’esecuzione di Hermes al suo interno.
Per Android, Hermes supporta un percorso di installazione Termux. È progettato per rilevare Termux e adattare di conseguenza la configurazione delle dipendenze e dell’ambiente.
Avvio rapido
Il primo avvio più veloce è letteralmente solo hermes, ma un avvio rapido significativo significa due decisioni extra: quale provider di modello utilizzare e quali strumenti abilitare.
Scegli un provider e un modello
Hermes espone tre punti di ingresso complementari:
- hermes model per scegliere un provider e un modello predefinito
- hermes tools per abilitare o disabilitare set di strumenti
- hermes setup per eseguire una procedura guidata interattiva attraverso le principali aree di configurazione
Un flusso minimale sembra questo:
hermes model
hermes tools
hermes
Per quanto riguarda ciò che è effettivamente supportato, l’avvio rapido ufficiale elenca una gamma di provider e sottolinea anche che Hermes funziona con API compatibili con OpenAI. Questo è importante perché include sia servizi ospitati che endpoint self-hosted.
Prova l’esecuzione degli strumenti presto
Prima di costruire abitudini attorno a Hermes, vale la pena verificare che l’uso degli strumenti funzioni nel tuo ambiente. L’avvio rapido suggerisce esplicitamente l’uso del terminale come prima funzionalità da provare.
In pratica, un piccolo prompt “smoke test” svolge due compiti: controlla lo strumento del terminale e convalida i prompt di autorizzazione.
Esempio di prompt:
Mostra il mio utilizzo del disco e le cinque directory più grandi.
Se Hermes non può eseguire lo strumento del terminale, salta avanti alla Risoluzione dei problemi. La configurazione errata del backend del terminale è una delle cause più comuni e la correzione è solitamente ovvia una volta guardato nella configurazione.
Configurazione che scala
Hermes premia chi capisce dove memorizza lo stato e come risolve la configurazione. È anche dove nascono molti problemi del tipo “funzionava ieri”.
Dove risiedono configurazione e stato
Hermes memorizza le sue impostazioni e lo stato sotto ~/.hermes. La guida alla configurazione ufficiale documenta la struttura, incluso config.yaml per le impostazioni, .env per i segreti, auth.json per le credenziali OAuth, SOUL.md per l’identità e cartelle per memorie, competenze, cron, sessioni e log.
Questo è importante per due motivi.
- Il debugging diventa meccanico perché sai esattamente dove guardare.
- I backup diventano semplici perché una sola directory cattura la maggior parte dello stato dell’agente che ti interessa.
Precedenza della configurazione e mantenimento dei segreti fuori da config.yaml
Hermes risolve la configurazione con un ordine di precedenza. In cima ci sono le sovrascritture CLI, poi config.yaml, poi .env, con i valori predefiniti integrati in fondo.
Il dettaglio positivo è che hermes config set indirizza i valori al file giusto: le chiavi API a .env e le impostazioni non segrete a config.yaml.
hermes config set model openrouter/meta-llama/llama-3.1-70b-instruct
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxx
Hermes supporta anche la sostituzione di variabili d’ambiente all’interno di config.yaml tramite la sintassi ${VAR_NAME}. Questo è utile quando vuoi mantenere certi valori nell’ambiente ma riferirti comunque ad essi in una configurazione strutturata.
Sandbox e backends di esecuzione
Hermes supporta più backends del terminale che definiscono dove i comandi shell vengono effettivamente eseguiti. La guida alla configurazione elenca local, docker, ssh, modal, daytona e singularity.
Il modo opinato ma non evangelico di pensare a questo è:
- local è il più veloce e semplice, ma non è isolato
- docker è uno strato pragmatico di sicurezza e riproducibilità
- ssh è un modo pulito per separare il dispositivo di chat dalla box di calcolo
- modal e daytona si adattano a flussi di lavoro “serverless ma persistenti a sufficienza”
- singularity è l’opzione amichevole per l’HPC
Un esempio minimale di backend Docker:
# ~/.hermes/config.yaml
terminal:
backend: docker
docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
docker_volumes:
- "/home/user/projects:/workspace/projects"
docker_forward_env:
- "GITHUB_TOKEN"
La documentazione descrive anche il rafforzamento della sicurezza per il backend Docker, come la rimozione delle capacità e la disabilitazione dell’escalation dei privilegi.
Competenze, memoria e profili
Hermes ha due meccanismi correlati per accumulare valore.
Le competenze sono memoria procedurale. Hermes può creare, aggiornare ed eliminare le proprie competenze e può offrire di salvare un approccio come competenza dopo aver completato un compito complesso.
La memoria integrata è memorizzata come file come MEMORY.md e USER.md sotto ~/.hermes, e Hermes può anche utilizzare provider di memoria esterni per un recupero più profondo. La documentazione sulla memoria elenca più plugin di provider e la guida sui provider di memoria documenta un flusso di configurazione interattivo.
Se desideri più agenti indipendenti sulla stessa macchina, i profili di Hermes forniscono isolamento. Ogni profilo ottiene la propria directory con la propria configurazione, segreti, memorie, sessioni, competenze, lavori cron e stato del gateway.
Workflow tipico
Se tratti Hermes come un agente che manterrai nel tempo, il workflow inizia a sembrare ingegneria di servizio.
Una linea di base stabile
Una linea di base che tende a non deteriorarsi è:
- Installa ed esegui una prima chat nella CLI.
- Scegli un provider e un modello con hermes model, poi conferma i costi.
- Configura i set di strumenti e decidi se l’esecuzione del terminale è locale o sandboxata.
- Apporta una modifica rapida a SOUL.md solo dopo aver usato le impostazioni predefinite per un po’. I cambiamenti di identità contano più di quanto le persone si aspettino perché è lo “slot 1” nel prompt del sistema.
Uso quotidiano che accumula valore
Hermes ha un’interfaccia utente terminale piuttosto che un’interfaccia web, ed è progettato per sessioni lunghe con comandi con slash, sessioni riprendibili e output degli strumenti in streaming.
In pratica, una cadenza utile è:
- esegui il lavoro in una sessione nominata per un progetto
- comprimi il contesto quando cresce troppo
- lascia che Hermes trasformi le routine ripetute in competenze
- mantieni un confine mentale tra “chiedere” e “agire” affinché l’esecuzione degli strumenti rimanga auditabile
Gateway di messaggistica per accesso 24/7
Il gateway di messaggistica è la parte che fa sentire Hermes come un assistente piuttosto che un’app terminale. La documentazione lo descrive come un singolo processo che si connette a più piattaforme, gestisce sessioni, esegue lavori cron e consegna messaggi.
La configurazione viene invocata tramite hermes gateway setup e il gateway può girare in primo piano o come servizio utente. Il riferimento della CLI documenta i sottocomandi del gateway come run, install, start, stop, status e restart.
La sicurezza per un bot che usa strumenti è importante. La documentazione del gateway descrive allowlist per piattaforme specifiche e un flusso di pairing DM che emette codici di pairing usa-e-getta e richiede approvazione tramite hermes pairing approve.
Aggiornamenti senza dramma
Gli aggiornamenti di Hermes sono un comando di prima classe. La guida agli aggiornamenti documenta hermes update, i controlli di migrazione della configurazione e una piccola routine di convalida post-aggiornamento che include hermes doctor e hermes gateway status.
hermes update
hermes doctor
hermes gateway status
Risoluzione dei problemi e diagnostica
La maggior parte dei fallimenti di Hermes non è misteriosa. Sembrano misteriosi perché le persone controllano solo il livello del modello e ignorano il livello runtime.
Comandi di triage rapido
Il riferimento della CLI posiziona esplicitamente tre comandi come il ciclo principale:
- hermes doctor per la diagnostica interattiva
- hermes status per una panoramica rapida
- hermes dump per un riepilogo della configurazione condivisibile e redatto
Per i log, hermes logs coda i file memorizzati sotto ~/.hermes/logs.
hermes doctor --fix
hermes status
hermes dump --show-keys
hermes logs errors -f
Fallimenti comuni nell’installazione
Il FAQ e la guida alla risoluzione dei problemi elencano diversi problemi ricorrenti e le loro correzioni, inclusi problemi di versione Python, uv non trovato e problemi di permessi causati dalla mescolanza di installazioni sudo con installazioni utente.
Se incontri questi errori, la documentazione fornisce passaggi di rimedio specifici come aggiornare Python, installare uv e reinstallare Hermes senza sudo.
Problemi di provider e modello
Quando le chiavi API non funzionano, il FAQ raccomanda di controllare la configurazione, di rieseguire hermes model o di impostare una chiave direttamente tramite hermes config set. Sottolinea anche un errore comune: le chiavi sono specifiche del provider.
Per i problemi “modello non trovato”, il FAQ rimanda all’uso di hermes model per scegliere un identificatore valido e mostra sia le sovrascritture di configurazione che quelle per sessione.
Sono coperti anche i problemi di limitazione delle richieste e di lunghezza del contesto. Il FAQ suggerisce di aspettare per errori 429, di cambiare provider o modello e di ridurre la pressione sul contesto tramite compressione o una sessione fresca.
Problemi di backend del terminale e gateway
Se i comandi del terminale falliscono immediatamente, la guida alla configurazione include una sezione “problemi comuni del backend del terminale” e indica le cause tipiche per backend, inclusa Docker non in esecuzione e variabili SSH mancanti. Nota anche che tornare a local è una mossa di debug valida quando la configurazione del sandbox è in questione.
Per i problemi del gateway, la guida di messaggistica evidenzia allowlist e pairing come predefiniti sicuri, il che significa che molti incidenti di “bot silenzioso” sono in realtà l’autorizzazione che fa il suo lavoro.
