Hermes AI Assistant: installazione, configurazione, flusso di lavoro e risoluzione dei problemi

Hermes Agent è un assistente AI self-hosted, agnostico rispetto al modello, che funziona su un’ macchina locale o su un VPS a basso costo, opera tramite interfacce da terminale e di messaggistica e migliora nel tempo trasformando i task ripetitivi in abilità riutilizzabili.

Funzionalmente è molto simile a OpenClaw, un altro stack di assistente self-hosted costruito attorno a strumenti, memoria e controllo locale. Molti sviluppatori sono arrivati a Hermes dopo che Anthropic ha bloccato l’accesso dell’abbonamento Claude di OpenClaw nell’aprile 2026 — la cronologia della nascita e caduta di OpenClaw spiega perché Hermes sia emerso come la destinazione naturale per gli utenti che cercavano un’automazione persistente e self-hosted senza la dipendenza dal provider.

Se vuoi la prospettiva più ampia sugli assistenti self-hosted, sul retrieval e sull’infrastruttura locale attorno a Hermes, questa panoramica dei sistemi AI collega quei temi agli stessi problemi che Hermes cerca di risolvere. Per il modello a cinque livelli di assistente — LLM, memoria, tooling, routing e osservabilità — con Hermes e OpenClaw come implementazioni di riferimento, consulta [Architettura Assistente AI](https://www.glukhov.org/it/ai-systems/architecture/ai-assistant-architecture/ “Una guida tecnica approfondita all’architettura degli assistenti AI: LLM, memoria, strumenti, routing e osservabilità, con compromessi reali, modalità di fallimento e pattern di progettazione.”}. Per dati concreti sull’adozione — stelle GitHub, volume giornaliero di token su OpenRouter, conteggi di download su PyPI, storico CVE e sentiment della comunità Reddit — OpenClaw vs Hermes Agent: Stelle, Download e Utilizzo 2026} traccia come Hermes si confronta con 19 alternative in ogni segnale misurabile.

Per i compromessi di deployment e le scelte di runtime, [LLM Hosting nel 2026: Infrastruttura Locale, Self-Hosted e Cloud Confrontata](https://www.glukhov.org/it/llm-hosting/ “Guida completa all’hosting LLM nel 2026. Confronta Ollama, vLLM, Docker Model Runner, LocalAI e provider cloud. Scopri costi, prestazioni e compromessi infrastrutturali.”}) fornisce la mappa dell’hosting, mentre [Prestazioni LLM nel 2026: Benchmark, Colli di Bottiglia e Ottimizzazione](https://www.glukhov.org/it/llm-performance/ “Ingegneria delle prestazioni LLM pratica: throughput vs latenza, limiti di VRAM, richieste parallele, allocazione della memoria e benchmark su runtime e hardware.”}) copre gli aspetti di throughput e latenza una volta che Hermes è in esecuzione. Se punti regolarmente Hermes a Qwen o Gemma su runtime locali come Ollama, consolida i preset di temperatura e penalità per l’uso di strumenti multi-passaggio con [Parametri di inferenza LLM agentic per Qwen e Gemma](https://www.glukhov.org/it/llm-performance/benchmarks/agentic-inference-parameters-reference/ “Riferimento curato di parametri di inferenza di vendor e comunità per Qwen 3.6 e Gemma 4, ottimizzato per workflow agentic e sistemi di coding realistici.”}. Per una mappa compatta dei comandi shell (hermes gateway, hermes memory, hermes doctor, scorciatoie slash e altro), usa la [scheda rapida CLI di Hermes Agent](https://www.glukhov.org/it/ai-systems/hermes/hermes-agent-cli-cheatsheet/ “Riferimento rapido per la CLI di Hermes Agent — installazione, hermes chat, gateway, abilità, memoria, diagnostiche e comandi slash.”}. Se il tuo punto di ingresso principale è la messaggistica su mobile, usa [Controllo Vocale Hermes dal Tuo Smartphone](https://www.glukhov.org/it/ai-systems/hermes/hermes-voice-control/ “Configura il controllo vocale di Hermes su Telegram e Discord usando Whisper locale e Edge TTS gratuito. Include configurazione, suggerimenti di tuning, esempi e risoluzione dei problemi.”} per lo stack vocale e la configurazione specifica della piattaforma.

Il mio parere personale: Hermes è più interessante quando viene trattato come infrastruttura, non come una scheda che si apre occasionalmente. Una volta che funziona come servizio e ha una directory home stabile, i tuoi prompt iniziano ad assomigliare meno a “chat” e più a “operazioni”.

Cos’è Hermes Agent e perché è importante

Hermes Agent è un agente AI open source sviluppato da Nous Research. È progettato per funzionare in modo persistente, usare strumenti (terminale, file, web e altro) e migliorare il suo stesso comportamento nel tempo con un sistema di abilità e memoria.

Due scelte di progettazione meritano di essere spiegate perché influenzano tutto il resto in questa guida.

Prima, 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 cambio viene eseguito tramite il comando hermes model piuttosto che con modifiche al codice.

Secondo, Hermes traccia una linea netta tra “conversazione” ed “esecuzione”. L’agente può chattare 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 rinfrescantemente noiosi. Hermes Agent stesso è software gratuito sotto licenza MIT. Se usi modelli hostizzati, il costo ricorrente è ciò che il tuo provider addebita. Se esegui modelli locali, puoi evitare del tutto le fee API.

Se la tua configurazione di Hermes usa Claude attraverso layer di tooling esterni, questo cambiamento nell’abbonamento Anthropic è un riferimento utile sul perché la fatturazione basata su API sia ora la via prevista.

Installa Hermes Agent

Hermes ha un percorso di installazione rapido per Linux, macOS e WSL2. La documentazione ufficiale lo mantiene intenzionalmente semplice.

Installazione Hermes su Linux

sudo apt-get update
sudo apt-get upgrade
sudo apt-get curl git
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Dopo l’installazione, ricarica la shell e avvia la CLI.

source ~/.bashrc   # oppure source ~/.zshrc
hermes

L’installatore non è solo un sottile wrapper. Secondo la guida di installazione, imposta le dipendenze, il repository, un ambiente virtuale e il comando hermes, portandoti a uno stato pronto per la prima chat.

Se stai arrivando da un deployment esistente di OpenClaw invece di iniziare da zero, installa e valida prima un Hermes vuoto, poi segui il passaggio graduale in [Come Migrare da OpenClaw a Hermes Agent in Sicurezza](https://www.glukhov.org/it/ai-systems/hermes/migrate-from-openclaw/ “Migra OpenClaw a Hermes Agent con controlli dry-run, mapping preciso di memoria e abilità, gestione dei segreti, passaggio canali, rollback e correzioni manuali.”} — hermes claw migrate mappa persona, memoria, abilità, provider e server MCP, ma i lavori cron, i plugin e il routing multi-agente devono essere ricostruiti a mano.

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 per Termux. È progettato per rilevare Termux e adattare di conseguenza la configurazione delle dipendenze e dell’ambiente.

Avvio Rapido

L’esecuzione iniziale più veloce è letteralmente solo hermes, ma un avvio rapido significativo comporta due decisioni extra: quale provider di modelli usare 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 un wizard interattivo nelle principali aree di configurazione

Un flusso minimo è questo:

hermes model
hermes tools
hermes

In termini di ciò che è effettivamente supportato, la Quickstart ufficiale elenca una gamma di provider e segnala anche che Hermes funziona con API compatibili con OpenAI. Ciò è importante perché include sia servizi hostizzati che endpoint self-hosted.

Dimostra l’esecuzione degli strumenti precocemente

Prima di creare abitudini attorno a Hermes, vale la pena verificare che l’uso degli strumenti funzioni nel tuo ambiente. La Quickstart suggerisce esplicitamente l’uso del terminale come prima funzione da provare.

Nella pratica, un piccolo prompt di “test di fumo” fa due lavori: verifica lo strumento terminale e valida i prompt di autorizzazione.

Esempio di prompt:

Mostra l'uso del mio disco e le cinque directory più grandi.

Se Hermes non riesce a eseguire lo strumento terminale, salta alla sezione Problemi comuni. La misconfigurazione del backend terminale è una delle cause più comuni e la correzione è di solito ovvia una volta che guardi la configurazione.

Configurazione scalabile

Hermes premia chi comprende dove memorizza lo stato e come risolve la configurazione. È anche qui che nascono molti problemi tipo “funzionava ieri”.

Dove risiedono configurazione e stato

Hermes memorizza le sue impostazioni e lo stato sotto ~/.hermes. La guida di configurazione ufficiale documenta il layout, inclusa config.yaml per le impostazioni, .env per i segreti, auth.json per le credenziali OAuth, SOUL.md per l’identità e cartelle per memorie, abilità, cron, sessioni e log.

Ciò è 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 a cui ti importa.

Precedenza della configurazione e tenuta dei segreti fuori da config.yaml

Hermes risolve la configurazione con un ordine di precedenza. In cima ci sono le override CLI, poi config.yaml, poi .env, con i valori predefiniti integrati in fondo.

Il dettaglio bello è che hermes config set instrada i valori nel file giusto: chiavi API in .env e impostazioni non segrete in 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 dentro config.yaml tramite la sintassi ${VAR_NAME}. Questo è utile quando vuoi mantenere certi valori nell’ambiente facendo comunque riferimento in una configurazione strutturata.

Sandbox e backend di esecuzione

Hermes supporta più backend terminale che definiscono dove i comandi shell vengono effettivamente eseguiti. La guida di configurazione elenca local, docker, ssh, modal, daytona e singularity.

Il modo opinato ma non proselitista per pensarci è:

• local è il più veloce e semplice, ma non è isolato
• docker è un layer pratico di sicurezza e riproducibilità
• ssh è un modo pulito per separare il dispositivo di chat dalla macchina di calcolo
• modal e daytona si adattano a workflow “serverless ma persistenti abbastanza”
• singularity è l’opzione amica dell’HPC

Un esempio minimo 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 l’indurimento della sicurezza per il backend Docker, come la disattivazione delle capacità e la disabilitazione dell’escalation dei privilegi.

Abilità, memoria e profili

Hermes ha due meccanismi correlati per il valore composto.

Le abilità sono memoria procedurale. Hermes può creare, aggiornare ed eliminare le proprie abilità e può offrire di salvare un approccio come abilità dopo aver completato un task complesso.

La memoria integrata è memorizzata come file come MEMORY.md e USER.md sotto ~/.hermes, e Hermes può anche usare provider di memoria esterni per un richiamo più profondo. I documenti sulla memoria elenchano più plugin di provider, e la guida sui provider di memoria documenta un flusso di configurazione interattivo. Per una disamina tecnica completa di come funziona l’architettura di memoria — snapshot congelati, limiti di caratteri, i provider esterni e la filosofia dietro la memoria delimitata — vedi [Sistema di Memoria di Hermes Agent: Come Funziona la Memoria AI Persistente](https://www.glukhov.org/it/ai-systems/hermes/hermes-agent-memory-system/ “Una guida tecnica approfondita all’architettura di memoria di Hermes Agent — dalla memoria di base delimitata a 2 file a 8 provider esterni plug-and-play.”}. Se vuoi un provider locale, self-hosted con un controllo insolitamente granulare su ciò che viene scritto automaticamente, vedi [Mnemosyne per Hermes Agent: Avvio Rapido della Memoria Locale](https://www.glukhov.org/it/ai-systems/hermes/mnemosyne-memory/ “Installa Mnemosyne come provider di memoria locale per Hermes, configura richiamo e ritenzione, ed ispeziona lo store SQLite.”} e [Loop di Memoria Auto-Rinforzanti negli Agenti AI](https://www.glukhov.org/it/ai-systems/memory/self-reinforcing-memory-loops/ “La memoria dell’agente può trasformare le inferenze del modello in prove future.”} per capire perché i predefiniti di scrittura conservativi importano in primo luogo.

Se vuoi più agenti indipendenti sulla stessa macchina, i profili di Hermes forniscono isolamento. Ogni profilo ha la propria directory con la propria configurazione, segreti, memorie, sessioni, abilità, lavori cron e stato del gateway.

Per uno sguardo più approfondito su quali abilità funzionano bene in produzione per ruolo — ingegneri, ricercatori, operatori e flussi di lavoro esecutivi — vedi [Abilità Assistente AI Hermes per Setup di Produzione Reali](https://www.glukhov.org/it/ai-systems/hermes/production-setup/ “Una guida basata sui profili alla configurazione e alle abilità di Hermes Agent per ingegneri, ricercatori, operatori e flussi di lavoro esecutivi in produzione.”}. Quando sei pronto per creare o debuggare i file SKILL.md stessi — metadati YAML, livelli di disclosure progressiva, visibilità condizionale e installazioni hub — usa [Creazione di Abilità per Hermes Agent — Struttura e Best Practice di SKILL.md](https://www.glukhov.org/it/ai-systems/hermes/authoring-hermes-skill/ “Crea abilità Hermes con frontmatter YAML, disclosure progressiva, attivazione condizionale, segreti vs configurazione e risoluzione dei problemi dell’indice.”}.

Workflow tipico

Se tratti Hermes come un agente che terrai a lungo, il workflow inizia ad assomigliare all’ingegneria dei servizi.

Una base stabile

Una base che tende a non marcire è:

1. Installa ed esegui una prima chat nella CLI.
2. Scegli un provider e un modello con hermes model, poi conferma i costi.
3. Configura i set di strumenti e decidi se l’esecuzione del terminale è locale o in sandbox.
4. Fai una rapida modifica a SOUL.md solo dopo aver usato il predefinito per un po’. I cambi di identità contano più di quanto le persone si aspettino perché è il “slot 1” nel prompt di sistema.

Uso quotidiano che compone

Hermes ha un’interfaccia a terminale piuttosto che un’interfaccia web, ed è progettato per sessioni lunghe con comandi slash, sessioni riprendibili e output degli strumenti in streaming. Le flag della shell, i sotto comandi e le scorciatoie slash per quella sessione sono nella [scheda rapida CLI di Hermes Agent](https://www.glukhov.org/it/ai-systems/hermes/hermes-agent-cli-cheatsheet/ “Riferimento rapido per la CLI di Hermes Agent. Percorso di installazione, hermes chat e one-shots con -z, modello, gateway, abilità, memoria, log, profili e scorciatoie slash.”}.

Nella pratica, una cadenza utile è:

• eseguire il lavoro in una sessione nominata per un progetto
• comprimere il contesto quando diventa troppo grande
• lasciare che Hermes trasformi le routine ripetute in abilità
• mantenere un confine mentale tra “chiedere” e “agire” in modo che l’esecuzione degli strumenti resti 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 di 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 CLI documenta sotto comandi del gateway come run, install, start, stop, status e restart. Se vuoi questo modello di gateway funzionante su un server dedicato mentre ti connetti da un client desktop separato, usa [Configurazione Server Headless e Desktop Remoto per Hermes Agent](https://www.glukhov.org/it/ai-systems/hermes/hermes-remote-backend-desktop/ “Esegui Hermes Agent su un server headless con accesso desktop remoto, servizi systemd, separazione del gateway e pattern di esposizione di rete sicura.”}.

Per backlog multi-agente e schedulazione controllata, vedi [Kanban in Hermes Agent per Workflow LLM Self Hosted](https://www.glukhov.org/it/ai-systems/hermes/kanban-in-hermes/ “Configura Hermes Kanban per pianificare in sicurezza task multi agente su LLM self hosted usando un daemon dispatcher, limiti di velocità e batching basato su cron.”}, che copre i limiti del dispatcher, le catene di dipendenza e il batching basato su cron.

La sicurezza per un bot che usa strumenti è importante. I documenti del gateway descrivono allowlist per piattaforme specifiche e un flusso di pairing DM che emette codici di pairing one-time e richiede approvazione tramite hermes pairing approve.

Aggiornamenti senza drama

Gli aggiornamenti di Hermes sono un comando di primo livello. La guida sugli aggiornamenti documenta hermes update, controlli di migrazione della configurazione e una piccola routine di validazione post-aggiornamento inclusa hermes doctor e hermes gateway status.

hermes update
hermes doctor
hermes gateway status

Risoluzione dei problemi e diagnostiche

La maggior parte dei fallimenti di Hermes non è misteriosa. Sembra misteriosa perché le persone controllano solo il layer del modello e ignorano il layer di runtime.

Comandi di triage rapido

Il riferimento CLI posiziona esplicitamente tre comandi come loop di base:

• hermes doctor per diagnostiche interattive
• hermes status per una panoramica rapida
• hermes dump per un riepilogo della configurazione condivisibile e redatto

Per i log, hermes logs fa tail di file memorizzati sotto ~/.hermes/logs.

hermes doctor --fix
hermes status
hermes dump --show-keys
hermes logs errors -f

Fallimenti di installazione comuni

La FAQ e la guida di troubleshooting elenca 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 l’aggiornamento di Python, l’installazione di uv e la reinstallazione di Hermes senza sudo.

Problemi di provider e modello

Quando le chiavi API non funzionano, la FAQ raccomanda di controllare la configurazione, ri-eseguire hermes model o impostare una chiave direttamente tramite hermes config set. Segnala anche un problema comune: le chiavi sono specifiche del provider.

Per problemi di “modello non trovato”, la FAQ rimanda all’uso di hermes model per scegliere un identificatore valido e mostra sia le override di configurazione che quelle per sessione.

Anche i problemi di rate limiting e lunghezza del contesto sono coperti. La FAQ suggerisce di aspettare per errori 429, cambiare provider o modello, e ridurre la pressione sul contesto tramite compressione o una nuova sessione.

Problemi di backend terminale e gateway

Se i comandi del terminale falliscono immediatamente, la guida di configurazione include una sezione “problemi comuni del backend terminale” e punta alle cause tipiche per backend, inclusi Docker non in esecuzione e variabili SSH mancanti. Segnala anche che il fallback su local è una mossa di debugging valida quando la configurazione della sandbox è in discussione.

Per problemi del gateway, la guida sulla 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.

Riferimenti

• Pagina Iniziale di Hermes Agent
• Sistema di Memoria di Hermes Agent: Come Funziona la Memoria AI Persistente
• Abilità Assistente AI Hermes per Setup di Produzione Reali