Assistente AI Hermes - Installazione, configurazione, workflow e risoluzione dei problemi

Hermes Agent è un assistente AI self-hosted e indipendente dal modello che funziona su una macchina locale o su un VPS a basso costo, opera attraverso interfacce terminali e di messaggistica e migliora nel tempo trasformando i compiti ripetitivi in abilità riutilizzabili.

È molto simile per funzionalità a OpenClaw, un altro stack di assistente self-hosted costruito attorno a strumenti, memoria e controllo locale. Molti sviluppatori sono giunti a Hermes dopo che Anthropic ha bloccato l’accesso tramite abbonamento Claude di OpenClaw nell’aprile 2026; la linea temporale dell’ascesa e del declino di OpenClaw spiega perché Hermes sia emersa come destinazione naturale per gli utenti che volevano un’automazione persistente e self-hosted senza dipendenza dal provider.

Se vuoi una visione più ampia degli assistenti self-hosted, della ricerca e dell’infrastruttura locale attorno a Hermes, questa panoramica dei sistemi AI collega quegli argomenti agli stessi problemi che Hermes cerca di risolvere. Per il modello di assistente a cinque livelli — LLM, memoria, strumenti, routing e osservabilità — con Hermes e OpenClaw come implementazioni di riferimento, consulta Architettura degli Assistenti AI. Per dati concreti sull’adozione — stelline GitHub, volume giornaliero di token su OpenRouter, conteggi dei download da PyPI, storico CVE e sentimento della community su Reddit — OpenClaw vs Hermes Agent: Stelline, Download e Utilizzo 2026 traccia come Hermes si confronti con 19 alternative attraverso ogni segnale misurabile.

Per i compromessi di distribuzione e le scelte di runtime, Hosting LLM nel 2026: Infrastruttura Locale, Self-Hosted e Cloud Confrontata 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 VRAM, richieste parallele, allocazione della memoria e benchmark tra runtime e hardware diversi.”} copre il lato throughput e latenza una volta che Hermes è in esecuzione. Se punti frequentemente Hermes verso Qwen o Gemma su runtime locali come Ollama, consolida le preset di temperatura e penalità per l’uso di strumenti in più passaggi con Parametri di inferenza LLM agentica per Qwen e Gemma. Per una mappa compatta dei comandi shell (hermes gateway, hermes memory, hermes doctor, scorciatoie slash, ecc.), usa la scheda rapida CLI di Hermes Agent. Se il tuo punto di ingresso principale è la messaggistica su mobile, usa Controllo Vocale di Hermes dal Telefono per lo stack vocale e la configurazione specifica della piattaforma.

Il mio parere parziale: Hermes è più interessante se trattata come infrastruttura, non come una scheda che apri occasionalmente. Una volta che funziona come servizio e ha un home directory stabile, i tuoi prompt iniziano a sembrare meno come “chat” e più come “operazioni”.

Cos’è Hermes Agent e perché è importante

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

Due scelte di progettazione meritano di essere chiarite perché plasmano tutto il resto in questa guida.

Primo, Hermes non è vincolato a un singolo provider di modelli. Il flusso di installazione ufficiale supporta più provider e qualsiasi endpoint compatibile con OpenAI, e il passaggio viene effettuato tramite il comando hermes model piuttosto che tramite modifiche al codice.

Secondo, Hermes traccia una linea netta tra “conversazione” ed “esecuzione”. L’agente può parlare tutto il giorno, ma quando deve agire, lo fa attraverso strumenti espliciti e un backend di esecuzione configurabile. È lì che risiedono sicurezza, riproducibilità e risoluzione dei problemi.

Costi e licenze sono sorprendentemente noiosi. Hermes Agent stesso è software gratuito sotto licenza MIT. Se usi modelli hostati, il costo ricorrente è ciò che il tuo provider addebita. Se esegui modelli locali, puoi evitare completamente le tasse API.

Se la tua configurazione di Hermes usa Claude attraverso livelli di tooling esterni, questa modifica all’abbonamento Anthropic è un riferimento utile per capire perché la fatturazione basata su API è ora il percorso atteso.

Installazione di Hermes Agent

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

Installazione di 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 il tuo shell e avvia la CLI.

source ~/.bashrc   # oppure 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.

Se arrivi da una distribuzione esistente di OpenClaw piuttosto che da una configurazione pulita, installa e valida prima un Hermes vuoto, quindi segui la migrazione graduale descritta in Come Migrare da OpenClaw a Hermes Agent in Sicurezza — hermes claw migrate mappa persona, memoria, skill, 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 tramite Termux. È progettato per rilevare Termux e adattare di conseguenza la configurazione delle dipendenze e dell’ambiente.

Avvio Rapido

L’esecuzione iniziale più rapida è letteralmente solo hermes, ma un avvio rapido significativo comporta due decisioni aggiuntive: 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 una procedura guidata interattiva attraverso le principali aree di configurazione

Un flusso minimo è questo:

hermes model
hermes tools
hermes

Per quanto riguarda ciò che è effettivamente supportato, l’Avvio Rapido ufficiale elenca una serie di provider e specifica anche che Hermes funziona con API compatibili con OpenAI. Questo è importante perché include sia servizi hostati che endpoint self-hosted.

Verifica l’esecuzione degli strumenti in anticipo

Prima di creare 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 funzione da provare.

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

Esempio di prompt:

Mostrami l'utilizzo del disco e i cinque directory più grandi.

Se Hermes non può eseguire lo strumento terminale, passa avanti alla sezione Risoluzione dei Problemi. La configurazione errata del backend terminale è una delle cause più comuni e la correzione è solitamente ovvia una volta che si guarda alla configurazione.

Configurazione che scala

Hermes ricompensa coloro che capiscono dove conserva lo stato e come risolve la configurazione. È anche da qui che nascono molti problemi del tipo “funzionava ieri”.

Dove risiedono configurazione e stato

Hermes conserva le sue impostazioni e lo stato sotto ~/.hermes. La guida alla configurazione ufficiale documenta la struttura, 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, skill, cron, sessioni e log.

Questo conta per due motivi.

• La diagnostica diventa meccanica perché sai esattamente dove guardare.
• I backup diventano semplici perché un’unica directory cattura la maggior parte dello stato dell’agente che ti interessa.

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 della CLI, poi config.yaml, poi .env, con i valori predefiniti integrati in fondo.

Il bel dettaglio è che hermes config set instrada i valori nel file corretto: le chiavi API in .env e le impostazioni non riservate 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 delle variabili d’ambiente dentro config.yaml tramite la sintassi ${VAR_NAME}. Questo è utile quando vuoi mantenere certi valori nell’ambiente ma vuoi ancora riferirli nella configurazione strutturata.

Sandbox e backend di esecuzione

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

Il modo opinionato ma non evangelico per pensarci è:

• local è il più veloce e semplice, ma non è isolato
• docker è uno strato di sicurezza e riproducibilità pragmatico
• ssh è un modo pulito per separare il dispositivo di chat dalla macchina di calcolo
• modal e daytona si adattano a flussi di lavoro “serverless ma sufficientemente persistenti”
• singularity è l’opzione amichevole per l’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 il disattivare le capability e la disabilitazione dell’elevazione dei privilegi.

Skill, memoria e profili

Hermes ha due meccanismi correlati per accumulare valore.

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

La memoria integrata è conservata come file come MEMORY.md e USER.md sotto ~/.hermes, e Hermes può anche usare provider di memoria esterni per un richiamo più profondo. La documentazione sulla memoria elenca più plugin di provider, e la guida sui provider di memoria documenta un flusso di configurazione interattivo. Per una spiegazione tecnica completa di come funziona l’architettura della memoria — snapshot congelati, limiti di caratteri, i provider esterni e la filosofia dietro la memoria delimitata — consulta Sistema di Memoria di Hermes Agent: Come Funziona Actually la Memoria AI Persistente. Se vuoi un provider locale e self-hosted con un controllo insolitamente granulare su cosa viene scritto automaticamente, vedi Mnemosyne per Hermes Agent: Avvio Rapido Memoria Locale e Loop di Memoria Auto-Rinforzanti negli Agenti AI per capire perché i valori predefiniti di scrittura conservativi contano 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, skill, lavori cron e stato del gateway.

Per uno sguardo più approfondito su quali skill funzionano bene in produzione per ruolo — ingegneri, ricercatori, operatori e flussi di lavoro esecutivi — consulta Skill per Assistenti AI Hermes per Settaggi di Produzione Reali. Quando sei pronto per creare o correggere i file SKILL.md stessi — metadati YAML, livelli di divulgazione progressiva, visibilità condizionale e installazioni hub — usa Creazione di Skill per Hermes Agent — Struttura di SKILL.md e Best Practices.

Flusso di lavoro tipico

Se tratti Hermes come un agente che manterrai, il flusso di lavoro inizia a sembrare ingegneria dei servizi.

Una baseline stabile

Una baseline che tende a non deteriorarsi è:

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 terminale è locale o sandboxed.
4. Fai una rapida modifica a SOUL.md solo dopo aver usato quello predefinito per un po’. I cambiamenti di identità contano più di quanto le persone si aspettino perché è il “slot 1” nel system prompt.

Uso giornaliero che accumula

Hermes ha un’interfaccia a terminale piuttosto che un’interfaccia web, ed è progettata per sessioni lunghe con comandi slash, sessioni riutilizzabili e output degli strumenti in streaming. Le bandiere del shell, i sottomenu e le scorciatoie slash per quella sessione sono nella scheda rapida CLI di Hermes Agent.

Nella pratica, un ritmo utile è:

• eseguire il lavoro in una sessione nominata per un progetto
• comprimere il contesto quando diventa troppo grande
• far trasformare a Hermes le routine ripetute in skill
• mantenere un confine mentale tra “chiedi” e “agisci” affinché l’esecuzione degli strumenti resti auditabile

Gateway di messaggistica per accesso 24/7

Il gateway di messaggistica è la parte che fa sentire Hermes 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ò essere eseguito in primo piano o come servizio utente. Il riferimento CLI documenta sottomenu gateway come run, install, start, stop, status e restart. Se vuoi questo modello di gateway in esecuzione su un server dedicato mentre ti connetti da un client desktop separato, usa Impostazione di Hermes Agent Headless Server e Desktop Remoto.

Per backlog multi-agente e pianificazione controllata, consulta Kanban in Hermes Agent per Flussi di Lavoro LLM Self-Hosted, che copre limiti del dispatcher, catene di dipendenza e batching basato su cron.

La sicurezza per un bot che usa strumenti conta. La documentazione del gateway descrive liste di autorizzazione per piattaforme specifiche e un flusso di accoppiamento DM che emette codici di accoppiamento a tempo unico e richiede approvazione tramite hermes pairing approve.

Aggiornamenti senza drama

Gli aggiornamenti di Hermes sono un comando di prima classe. La guida agli 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 diagnostica

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

Comandi di triage rapido

Il riferimento CLI posiziona esplicitamente tre comandi come il loop centrale:

• hermes doctor per diagnostica interattiva
• hermes status per una panoramica rapida
• hermes dump per un riepilogo configurativo condivisibile e censurato

Per i log, hermes logs fa la coda ai file conservati 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 alla risoluzione dei problemi elencano diversi problemi ricorrenti e le loro correzioni, inclusi problemi di versione di Python, uv non trovato e problemi di permessi causati dalla miscela di installazioni sudo con installazioni utente.

Se incontri questi errori, la documentazione fornisce passi di rimedio specifici come aggiornare Python, installare uv e reinstallare Hermes senza sudo.

Problemi di provider e modello

Quando le chiavi API non funzionano, la FAQ raccomanda di verificare la configurazione, rieseguire hermes model o impostare una chiave direttamente tramite hermes config set. Specifica anche una trappola comune: le chiavi sono specifiche del provider.

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

I limiti di velocità e i problemi di lunghezza del contesto sono anche coperti. La FAQ suggerisce di aspettare per errori 429, cambiare provider o modelli e ridurre la pressione del contesto tramite compressione o una sessione nuova.

Problemi di backend terminale e gateway

Se i comandi terminale falliscono immediatamente, la guida di configurazione include una sezione “problemi comuni di backend terminale” e indica le cause tipiche per backend, incluso Docker non in esecuzione e variabili SSH mancanti. Nota anche che il fallback su local è una mossa di debug valida quando la configurazione sandbox è in discussione.

Per problemi di gateway, la guida di messaggistica evidenzia liste di autorizzazione e accoppiamento come valori predefiniti sicuri, il che significa che molti incidenti del tipo “il bot è silenzioso” sono in realtà l’autorizzazione che fa il suo lavoro.

Riferimenti

• Pagina Principale di Hermes Agent
• Sistema di Memoria di Hermes Agent: Come Funziona Actually la Memoria AI Persistente
• Skill per Assistenti AI Hermes per Settaggi di Produzione Reali