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

L’agente Hermes è un assistente AI ospitato in modo self-hosted e indipendente dal modello, che gira su una macchina locale o su un VPS a basso costo, opera attraverso interfacce terminal e di messaggistica e migliora nel tempo trasformando le attività ripetute in competenze riutilizzabili.

È molto simile per funzionalità a OpenClaw, un altro stack di assistenti self-hosted costruito 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 di ascesa e caduta di OpenClaw spiega perché Hermes è emerso come la destinazione naturale per gli utenti che volevano automazione persistente e self-hosted senza dipendere dai provider.

Se vuoi una visione più ampia degli assistenti self-hosted, del recupero e dell’infrastruttura locale intorno a Hermes, questa panoramica dei sistemi AI collega quegli argomenti agli stessi problemi che Hermes sta cercando di risolvere. Per dati concreti sull’adozione — stelle su GitHub, volume giornaliero di token su OpenRouter, conteggi dei download su PyPI, storia delle CVE e sentiment della comunità su Reddit — OpenClaw vs Hermes Agent: Stelle, Download & Utilizzo 2026 traccia come Hermes si confronta con 19 alternative attraverso ogni segnale misurabile.

Per compromessi di deployment e scelte di runtime, Hosting LLM nel 2026: Locale, Self-Hosted & Infrastruttura Cloud Confrontati fornisce la mappa dell’hosting, mentre Prestazioni LLM nel 2026: Benchmark, Colli di Bottiglia & Ottimizzazione copre il lato throughput e latenza una volta che Hermes è in esecuzione. Se punti regolarmente Hermes su Qwen o Gemma su runtime locali come Ollama, consolida i preset di temperatura e penalità per l’uso di strumenti multi-step con Parametri di inferenza Agentic LLM per Qwen e Gemma. Per una mappa compatta dei comandi shell (hermes gateway, hermes memory, hermes doctor, scorciatoie slash e altro), usa il Cheat sheet CLI di Hermes Agent. Se il tuo punto di ingresso principale è il messaggistica su mobile, usa Controllo Vocale Hermes dal tuo Telefono} 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 ad assomigliare meno a una “chat” e più a “ops”.

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 (terminal, file, web e altro) e migliorare il proprio 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.

Primo, 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 cambio avviene tramite il comando hermes model piuttosto che modifiche al codice.

Secondo, Hermes traccia una linea dura tra “conversazione” ed “esecuzione”. L’agente può parlare 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 sorprendentemente noiosi. Hermes Agent stesso è software gratuito sotto licenza MIT. Se usi modelli ospitati, il costo ricorrente è quanto addebita il tuo provider. Se esegui modelli locali, puoi evitare completamente le tariffe API.

Se la tua configurazione Hermes usa Claude attraverso layer di strumentazione esterni, questo cambiamento negli abbonamenti Anthropic è un riferimento utile su perché la fatturazione basata su API è ora il percorso previsto.

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

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

L’installatore non è solo un wrapper sottile. Secondo la guida di installazione, configura le dipendenze, la repo, 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.

Quickstart

L’esecuzione iniziale più rapida è letteralmente solo hermes, ma un quickstart significativo significa due decisioni extra: quale provider di modello 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 attraverso le principali aree di configurazione

Un flusso minimale appare così:

hermes model
hermes tools
hermes

In termini di cosa è effettivamente supportato, il Quickstart 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.

Verifica l’esecuzione degli strumenti presto

Prima di costruire abitudini intorno a Hermes, vale la pena verificare che l’uso degli strumenti funzioni nel tuo ambiente. Il Quickstart suggerisce esplicitamente l’uso del terminal come prima funzionalità da provare.

In pratica, un piccolo prompt di “smoke test” svolge due compiti: controlla lo strumento terminal 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 terminal, salta avanti alla Risoluzione dei problemi. La configurazione errata del backend del terminal è una delle cause più comuni, e la soluzione è solitamente ovvia una volta che si guarda la configurazione.

Configurazione che scala

Hermes premia coloro che capiscono dove memorizza lo stato e come risolve la configurazione. Questo è anche da dove provengono molti problemi “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, includendo 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 ragioni.

• Il debugging 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 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: chiavi API a .env e 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 mentre li riferisci ancora nella configurazione strutturata.

Sandbox e backends di esecuzione

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

Il modo di pensare opinabile ma non evangelico è:

• local è il più veloce e semplice, ma non è isolato
• docker è un layer pragmatico di sicurezza e riproducibilità
• ssh è un modo pulito per separare il tuo dispositivo di chat dalla tua macchina di calcolo
• modal e daytona si adattano a flussi di lavoro “serverless ma sufficientemente persistenti”
• singularity è l’opzione amichevole per 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 il rilascio 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 richiamo più profondo. La documentazione della memoria elenca più plugin di provider, e la guida sui 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 Hermes Agent: Come Funziona Realmente la Memoria AI Persistente.

Se vuoi 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 di quali competenze funzionano bene in produzione per ruolo — ingegneri, ricercatori, operatori e flussi di lavoro esecutivi — vedi Competenze Assistente AI Hermes per Setup di Produzione Reali. Quando sei pronto a scrivere o debuggare i file SKILL.md stessi — metadati YAML, livelli di disclosure progressiva, visibilità condizionale e installazioni hub — usa Autore di Competenze Hermes Agent — Struttura SKILL.md e Best Practices.

Flusso di lavoro tipico

Se tratti Hermes come un agente che terrai intorno, il flusso di lavoro inizia ad assomigliare all’ingegneria dei servizi.

Una baseline stabile

Una baseline che tende a non degradarsi è:

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 terminal è locale o sandboxed.
4. Fai 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é è la “slot 1” nel system prompt.

Utilizzo quotidiano che si accumula

Hermes ha un’interfaccia UI del terminal piuttosto che un’interfaccia web, ed è progettato per sessioni lunghe con comandi slash, sessioni riprendibili e output streaming degli strumenti.

In pratica, una cadenza utile è:

• eseguire il lavoro in una sessione nominata per un progetto
• comprimere il contesto quando cresce troppo
• lasciare che Hermes trasformi le routine ripetute in competenze
• mantenere un confine mentale tra “chiedere” e “agire” così l’esecuzione degli strumenti rimane 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 servizio utente. Il riferimento CLI documenta i sottocomandi del gateway come run, install, start, stop, status e restart.

Per backlog multi-agente e pianificazione controllata, vedi 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 è importante. La documentazione del gateway descrive allowlist per piattaforme specifiche e un flusso di pairing DM che emette codici di pairing una-tantum 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 includendo 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 rapido

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

• hermes doctor per la diagnostica interattiva
• hermes status per una panoramica rapida
• hermes dump per un riepilogo dell’setup 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 dal mescolare 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. 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 della configurazione che quelle per sessione.

Anche i limiti di frequenza e i problemi di lunghezza del contesto sono coperti. 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 terminal e del gateway

Se i comandi del terminal falliscono immediatamente, la guida di configurazione include una sezione “problemi comuni del backend del terminal” e punta alle cause tipiche per backend, includendo Docker non in esecuzione e variabili SSH mancanti. Nota anche che ricadere su locale è una mossa di debug valida quando la configurazione della sandbox è in dubbio.

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

Riferimenti

• Homepage Hermes Agent
• Sistema di Memoria Hermes Agent: Come Funziona Realmente la Memoria AI Persistente
• Competenze Assistente AI Hermes per Setup di Produzione Reali