Assistente AI Hermes - Installazione, Configurazione, Flusso di Lavoro e Risoluzione dei Problemi
Installazione e avvio rapido dell'Agente Hermes per sviluppatori
Hermes Agent è un assistente AI auto-ospitato e indipendente dal modello che gira su un computer locale o su un VPS a basso costo, funziona tramite interfaccia terminale e di messaggistica e migliora nel tempo trasformando i compiti ripetitivi in competenze riutilizzabili.
È molto simile per funzionalità a OpenClaw, un altro stack di assistenti auto-ospitati costruiti attorno a strumenti, memoria e controllo locale. Molti sviluppatori hanno trovato la strada verso Hermes dopo che Anthropic ha bloccato l’accesso agli abbonamenti Claude di OpenClaw nell’aprile 2026 — la cronologia dell’ascesa e della caduta di OpenClaw spiega perché Hermes è emerso come la destinazione naturale per gli utenti che volevano un’automazione persistente e auto-ospitata senza dipendere dal provider.
Se desideri una visione più ampia degli assistenti auto-ospitati, del recupero e dell’infrastruttura locale attorno a Hermes, questa panoramica dei sistemi AI collega quegli argomenti agli stessi problemi che Hermes sta cercando di risolvere.
Per gli compromessi di distribuzione e le scelte di runtime, Hosting LLM nel 2026: Infrastruttura Locale, Auto-ospitata e Cloud Confrontata fornisce la mappa dell’hosting, mentre Prestazioni LLM nel 2026: Benchmark, Colli di Bottiglia & Ottimizzazione copre l’aspetto del throughput e della latenza una volta che Hermes è in esecuzione. Per una mappa compatta dei comandi shell (hermes gateway, hermes memory, hermes doctor, scorciatoie slash e altro), usa il [vademecum 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, competenze, memoria, diagnostica e comandi slash.”}). Se il tuo punto di ingresso principale è la messaggistica su mobile, usa [Controllo Vocale Hermes dal Tuo Telefono](https://www.glukhov.org/it/ai-systems/hermes/hermes-voice-control/ “Configura il controllo vocale Hermes su Telegram e Discord usando Whisper locale e Edge TTS gratuito. Include configurazione, suggerimenti di regolazione, esempi e risoluzione dei problemi.”}) per lo stack vocale e la configurazione specifica della piattaforma.
Il mio punto di vista parziale: Hermes è più interessante quando viene trattato come infrastruttura, non come una scheda che apri occasionalmente. Una volta che gira come servizio e ha una directory home 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 girare in modo persistente, utilizzare strumenti (terminale, file, web e altro) e migliorare il suo comportamento nel tempo con un sistema di competenze e memoria.
Due scelte di progettazione meritano di essere esplicitate perché modellano tutto il resto di questa guida.
In primo luogo, Hermes non è vincolato a un singolo provider di modelli. Il flusso di configurazione ufficiale supporta più provider e qualsiasi endpoint compatibile con OpenAI, e il passaggio avviene tramite il comando hermes model piuttosto che tramite modifiche al codice.
In secondo luogo, Hermes traccia una linea netta tra “conversazione” e “esecuzione”. L’agente può parlare tutto il giorno, ma quando ha bisogno di agire, lo fa tramite strumenti espliciti e un backend di esecuzione configurabile. È lì che risiedono sicurezza, riproducibilità e risoluzione dei problemi.
Costi e licenze sono piacevolmente noiosi. Hermes Agent stesso è software gratuito sotto licenza MIT. Se utilizzi modelli ospitati, il costo ricorrente è quello che il tuo provider addebita. Se esegui modelli locali, puoi evitare completamente le tariffe API.
Se la tua configurazione Hermes utilizza Claude attraverso layer di strumentazione esterni, questo cambiamento nell’abbonamento Anthropic è un riferimento utile su perché la fatturazione basata su API è ora il percorso previsto.
Installazione di Hermes Agent
Hermes ha un percorso di installazione rapido per Linux, macOS e WSL2. La documentazione ufficiale lo mantiene intenzionalmente semplice.
Installazione di Hermes su Linux
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install curl git
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Dopo l’installazione, ricarica la tua shell e avvia la CLI.
source ~/.bashrc # oppure source ~/.zshrc
hermes
Il programmatore di installazione non è solo un semplice wrapper. Secondo la guida di installazione, configura le dipendenze, la 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 consiglia WSL2 e l’esecuzione di Hermes al suo interno.
Per Android, Hermes supporta un percorso di installazione su 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 implica due decisioni aggiuntive: quale provider di modelli utilizzare e quali strumenti abilitare.
Scegli un provider e un modello
Hermes espone tre punti di ingresso complementari:
hermes modelper scegliere un provider e un modello predefinitohermes toolsper abilitare o disabilitare set di strumentihermes setupper eseguire un wizard interattivo attraverso le aree di configurazione principali
Un flusso minimale è simile a questo:
hermes model
hermes tools
hermes
In termini di 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 auto-ospitati.
Verifica 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. L’Avvio Rapido suggerisce esplicitamente l’uso del terminale come prima funzionalità da provare.
In pratica, un piccolo prompt di “test di fumo” svolge due compiti: controlla lo strumento del terminale e convalida i prompt di autorizzazione.
Esempio di prompt:
Mostra l'utilizzo del mio disco e le cinque directory più grandi.
Se Hermes non può eseguire lo strumento del terminale, passa alla Risoluzione dei Problemi. La configurazione errata del backend del terminale è una delle cause più comuni e la soluzione è di solito ovvia una volta che si guarda alla configurazione.
Configurazione che scala
Hermes premia chi comprende dove archivia lo stato e come risolve la configurazione. È anche qui che nascono molti problemi “funzionava ieri”.
Dove risiedono configurazione e stato
Hermes archivia 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, competenze, cron, sessioni e log.
Questo è importante per due motivi.
- Il debug diventa meccanico perché sai esattamente dove guardare.
- I backup diventano semplici perché una singola 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 della CLI, poi config.yaml, poi .env, con i valori predefiniti integrati in fondo.
Il bello è che hermes config set indirizza i valori al file corretto: le chiavi API in .env e le 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 all’interno di config.yaml tramite la sintassi ${VAR_NAME}. Questo è utile quando si desidera mantenere determinati valori nell’ambiente mentre li si riferisce ancora nella configurazione strutturata.
Sandbox e backend di esecuzione
Hermes supporta più backend del terminale che definiscono dove i comandi shell vengono effettivamente eseguiti. La guida alla configurazione elenca locale, docker, ssh, modal, daytona e singularity.
Il modo di pensare opinione ma non evangelico è:
localeè il più veloce e semplice, ma non è isolatodockerè uno strato pragmatico di sicurezza e riproducibilitàsshè un modo pulito per separare il tuo dispositivo di chat dalla tua macchina di calcolomodaledaytonasi adattano a flussi di lavoro “serverless ma sufficientemente persistenti”singularityè l’opzione amichevole per l’HPC (High Performance Computing)
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 l’indurimento 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 e eliminare le proprie competenze e può offrire di salvare un approccio come competenza dopo aver completato un compito complesso.
La memoria integrata è archiviata 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 ai provider di memoria documenta un flusso di configurazione interattivo. Per un’analisi tecnica completa di come funziona l’architettura della memoria — snapshot congelati, limiti di caratteri, gli otto provider esterni e la filosofia dietro la memoria limitata — vedi Sistema di Memoria di Hermes Agent: Come Funziona Really la Memoria AI Persistente.
Se desideri più agenti indipendenti sulla stessa macchina, i profili Hermes forniscono isolamento. Ogni profilo ottiene la propria directory con la propria configurazione, segreti, memorie, sessioni, competenze, lavori cron e stato del gateway.
Per un’analisi più approfondita su quali competenze funzionano bene in produzione per ruolo — ingegneri, ricercatori, operatori e flussi di lavoro esecutivi — vedi [Competenze dell’Assistente AI Hermes per Configurazioni di Produzione Reali](https://www.glukhov.org/it/ai-systems/hermes/production-setup/ “Una guida incentrata sui profili alla configurazione e alle competenze di Hermes Agent per ingegneri, ricercatori, operatori e flussi di lavoro esecutivi in produzione.”}). Quando sei pronto a creare o debuggare i file SKILL.md stessi — metadati YAML, livelli di disclosure progressiva, visibilità condizionale e installazioni hub — usa [Creazione di Competenze per Hermes Agent — Struttura e Best Practices di SKILL.md](https://www.glukhov.org/it/ai-systems/hermes/authoring-hermes-skill/ “Crea competenze Hermes con frontmatter YAML, disclosure progressiva, attivazione condizionale, segreti vs configurazione e risoluzione dei problemi dell’indice.”}).
Flusso di lavoro tipico
Se tratti Hermes come un agente che manterrai, il flusso di lavoro inizia a sembrare ingegneria dei servizi.
Una base stabile
Una base che tende a non degradarsi è:
- 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 in sandbox.
- Effettua una modifica rapida a
SOUL.mdsolo dopo aver usato quello predefinito per un po’. I cambiamenti di identità contano più di quanto le persone si aspettano perché è la “slot 1” nel prompt del sistema.
Utilizzo quotidiano che si accumula
Hermes ha un’interfaccia utente del terminale piuttosto che un’interfaccia web, ed è progettata per sessioni lunghe con comandi slash, sessioni riprendibili e output degli strumenti in streaming.
In 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 competenze
- mantenere 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 sembrare 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ò girare in primo piano o come servizio utente. Il riferimento CLI documenta i sottocomandi del gateway come run, install, start, stop, status e restart.
Per code multi-agente e pianificazione controllata, vedi Kanban in Hermes Agent per Flussi di Lavoro LLM Auto-ospitati, che copre limiti del dispatcher, catene di dipendenze e batching basato su cron.
La sicurezza per un bot che usa strumenti è importante. La documentazione del gateway descrive liste bianche per piattaforme specifiche e un flusso di abbinamento DM che emette codici di abbinamento monouso e richiede approvazione tramite hermes pairing approve.
Aggiornamenti senza drammi
Gli aggiornamenti 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 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 sono misteriosi. Sembra misterioso perché le persone controllano solo il layer del modello e ignorano il layer di runtime.
Comandi di triage rapidi
Il riferimento CLI posiziona esplicitamente tre comandi come il ciclo principale:
hermes doctorper la diagnostica interattivahermes statusper una panoramica rapidahermes dumpper un riepilogo configurabile e anonimizzato
Per i log, hermes logs segue i file archiviati sotto ~/.hermes/logs.
hermes doctor --fix
hermes status
hermes dump --show-keys
hermes logs errors -f
Fallimenti comuni di installazione
La FAQ e la guida alla risoluzione dei problemi elencano diversi problemi ricorrenti e le loro soluzioni, inclusi problemi di versione Python, uv non trovato e problemi di autorizzazione 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 consiglia di controllare la configurazione, rieseguire hermes model o 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”, la 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 della frequenza e della lunghezza del contesto. La FAQ suggerisce di aspettare per gli errori 429, cambiare provider o modelli e ridurre la pressione del contesto tramite compressione o una sessione fresca.
Problemi del backend del terminale e del gateway
Se i comandi del terminale falliscono immediatamente, la guida alla configurazione include una sezione “problemi comuni del backend del terminale” e punta alle cause tipiche per backend, inclusi Docker non in esecuzione e variabili SSH mancanti. Nota anche che tornare al locale è una mossa di debug valida quando la configurazione della sandbox è in discussione.
Per i problemi del gateway, la guida alla messaggistica evidenzia liste bianche e abbinamento come i valori predefiniti sicuri, il che significa che molti incidenti “il bot è silenzioso” sono in realtà l’autorizzazione che fa il suo lavoro.
