Assistente AI Hermes - Installazione, Configurazione, Flusso di Lavoro e Risoluzione dei Problemi

Hermes Agent è un assistente AI auto-gestito e indipendente dal modello, che gira su una macchina locale o su un VPS a basso costo, opera tramite interfacce a riga di comando e di messaggistica e migliora nel tempo trasformando le attività ripetitive in abilità riutilizzabili.

Per funzionalità è molto simile a OpenClaw, un altro stack di assistenti auto-gestiti costruito attorno a strumenti, memoria e controllo locale. Molti sviluppatori hanno scoperto 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 desideravano un’automazione persistente e auto-gestita senza dipendenze dal fornitore.

Se desideri una visione più ampia degli assistenti auto-gestiti, del recupero informazioni e dell’infrastruttura locale intorno a Hermes, questa panoramica dei sistemi AI collega questi argomenti agli stessi problemi che Hermes cerca di risolvere.

Per le scelte di distribuzione e le opzioni di runtime, LLM Hosting nel 2026: Infrastruttura Locale, Auto-gestita e Cloud Confrontata fornisce la mappa dell’hosting, mentre Prestazioni LLM nel 2026: Benchmark, Colli di Bottiglia e Ottimizzazione copre gli aspetti di throughput e latenza una volta che Hermes è in esecuzione. Per una mappa compatta dei comandi shell (hermes gateway, hermes memory, hermes doctor, scorciatoie slash e altro), utilizza il Cheat sheet della CLI di Hermes Agent.

La mia opinione, con i miei pregiudizi: Hermes è più interessante quando viene trattato come infrastruttura, non come una scheda che apri occasionalmente. Una volta che gira come un servizio e ha una directory home stabile, i tuoi prompt iniziano a somigliare meno a una “chat” e più a “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 proprio comportamento nel tempo grazie a un sistema di abilità 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 fornitore di modelli. Il flusso di configurazione ufficiale supporta più fornitori e qualsiasi endpoint compatibile con OpenAI, e il passaggio da uno all’altro avviene tramite il comando hermes model piuttosto che modificando il codice.

In secondo luogo, Hermes traccia una linea netta tra “conversazione” e “esecuzione”. L’agente può chiacchierare tutto il giorno, ma quando ha bisogno di 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 piacevolmente noiosi. Hermes Agent stesso è software gratuito sotto licenza MIT. Se utilizzi modelli ospitati, il costo continuativo è quello che il tuo fornitore addebita. Se esegui modelli locali, puoi evitare completamente le spese per le API.

Se la tua configurazione Hermes utilizza Claude attraverso livelli di strumentazione esterni, questo cambiamento nell’abbonamento Anthropic è un utile riferimento per capire perché la fatturazione basata sulle API è ora la via prevista.

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 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

L’installer non è solo un involucro sottile. Secondo la guida all’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 consiglia WSL2 ed eseguire 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.

Inizio Rapido

L’esecuzione iniziale più veloce è letteralmente solo hermes, ma un inizio rapido significativo comporta due decisioni aggiuntive: quale fornitore di modelli utilizzare e quali strumenti abilitare.

Scegli un fornitore e un modello

Hermes espone tre punti di ingresso complementari:

• hermes model per scegliere un fornitore e un modello predefiniti
• hermes tools per abilitare o disabilitare set di strumenti
• hermes setup per eseguire un wizard interattivo nelle principali aree di configurazione

Un flusso minimale appare così:

hermes model
hermes tools
hermes

Per quanto riguarda ciò che è effettivamente supportato, l’Inizio Rapido ufficiale elenca una gamma di fornitori e sottolinea anche che Hermes funziona con API compatibili con OpenAI. Questo è importante perché include sia servizi ospitati che endpoint auto-gestiti.

Verifica l’esecuzione degli strumenti presto

Prima di creare abitudini attorno a Hermes, vale la pena verificare che l’uso degli strumenti funzioni nel tuo ambiente. L’Inizio Rapido suggerisce esplicitamente l’uso del terminale come prima funzionalità da provare.

In pratica, un piccolo prompt di “test fumi” svolge due compiti: verifica lo strumento del terminale e convalida le richieste di autorizzazione.

Prompt di esempio:

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

Se Hermes non riesce a eseguire lo strumento del terminale, salta alla sezione Risoluzione dei problemi. La configurazione errata del backend del terminale è una delle cause più comuni e la correzione è solitamente ovvia una volta esaminata la configurazione.

Configurazione scalabile

Hermes premia chi comprende dove memorizza lo stato e come risolve la configurazione. Questo è anche il punto da cui derivano molti problemi “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, 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.

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 dettaglio positivo è 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 delle variabili d’ambiente all’interno di config.yaml tramite la sintassi ${VAR_NAME}. Questo è utile quando si desidera mantenere certi valori nell’ambiente facendoli comunque riferimento in una 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 opinabile ma non evangelico a riguardo è:

• locale è il più veloce e semplice, ma non è isolato
• docker è uno strato 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 flussi di lavoro “serverless ma sufficientemente persistenti”
• 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 l’indurimento della sicurezza per il backend Docker, come l’abbandono delle capacità e la disabilitazione dell’escalation dei privilegi.

Abilità, memoria e profili

Hermes ha due meccanismi correlati per accumulare valore.

Le abilità sono memoria procedurale. Hermes può creare, aggiornare e eliminare le proprie abilità e può offrire di salvare un approccio come abilità 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 fornitori di memoria esterni per un richiamo più profondo. La documentazione sulla memoria elenca più plugin per i fornitori e la guida ai fornitori 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 fornitori esterni e la filosofia dietro la memoria limitata — vedi Sistema di Memoria di Hermes Agent: Come Funziona Realmente 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, abilità, lavori cron e stato del gateway.

Per un’analisi più approfondita di quali abilità funzionano bene in produzione per ruolo — ingegneri, ricercatori, operatori e flussi di lavoro esecutivi — vedi Abilità dell’Assistente AI Hermes per Configurazioni di Produzione Reali. Quando sei pronto a creare o debuggare i file SKILL.md stessi — metadati YAML, livelli di divulgazione progressiva, visibilità condizionale e installazioni hub — usa Creazione di Abilità per Hermes Agent — Struttura e Best Practice di SKILL.md.

Flusso di lavoro tipico

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

Una linea di base stabile

Una linea di base che tende a non decomporsi è:

1. Installa ed esegui una prima chat nella CLI.
2. Scegli un fornitore 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 sandboxed.
4. Apporta una modifica rapida a SOUL.md solo dopo aver usato il predefinito per un po’. I cambiamenti di identità contano più di quanto le persone si aspettano perché è il “slot 1” nel prompt del sistema.

Uso quotidiano che si accumula

Hermes ha un’interfaccia utente a terminale piuttosto che una web, ed è progettato per sessioni lunghe con comandi slash, sessioni riprendibili e output degli strumenti in streaming.

In pratica, una cadenza utile è:

• eseguire il lavoro in una session nominata per un progetto
• comprimere il contesto quando diventa troppo grande
• lasciare che Hermes trasformi le routine ripetitive in abilità
• mantenere un confine mentale tra “chiedere” e “agire” in modo che 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’applicazione 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 un 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-gestiti, 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 allowlist per piattaforme specifiche e un flusso di accoppiamento DM che emette codici di accoppiamento monouso e richiede approvazione tramite hermes pairing approve.

Aggiornamenti senza drammi

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 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. Sembrano misteriosi 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 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 fa il tail dei file memorizzati 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 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 rimedi specifici come l’aggiornamento di Python, l’installazione di uv e la reinstallazione di Hermes senza sudo.

Problemi di fornitori e modelli

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 fornitore.

Per i problemi di “modello non trovato”, la FAQ rimanda a usare hermes model per scegliere un identificatore valido e mostra sia le sovrascritture della configurazione che quelle per sessione.

Sono coperti anche i problemi di limitazione della frequenza e della lunghezza del contesto. La FAQ suggerisce di attendere per gli errori 429, cambiare fornitore o modello e ridurre la pressione del contesto tramite compressione o una nuova sessione.

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 questione.

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

Riferimenti

• Homepage di Hermes Agent
• Sistema di Memoria di Hermes Agent: Come Funziona Realmente la Memoria AI Persistente
• Abilità dell’Assistente AI Hermes per Configurazioni di Produzione Reali