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

Hermes Agent è un assistente AI auto-ospitato e agnostico rispetto al modello che si esegue su una macchina locale o su un VPS a basso costo, opera tramite interfacce a terminale e di messaggistica e migliora nel tempo trasformando i compiti ripetitivi in competenze riutilizzabili.

Presenta funzionalità molto simili a quelle di OpenClaw, un altro stack di assistenti auto-ospitati costruito attorno a strumenti, memoria e controllo locale.

Se desideri una visione più ampia degli assistenti auto-ospitati, del retrieval e dell’infrastruttura locale attorno a Hermes, questa panoramica sui sistemi AI collega questi argomenti agli stessi problemi che Hermes cerca di risolvere.

Per quanto riguarda i compromessi di deployment e le scelte runtime, LLM Hosting nel 2026: Infrastruttura Locale, Auto-ospitata e Cloud Confrontata fornisce la mappa dell’hosting, mentre LLM Performance nel 2026: Benchmark, Colli di Bottiglia & Ottimizzazione copre gli aspetti di throughput e latenza una volta che Hermes è in esecuzione.

La mia opinione di parte: Hermes è più interessante quando viene trattato come infrastruttura, non come una scheda che si apre occasionalmente. Una volta che esegue come servizio e ha una directory home stabile, i tuoi prompt iniziano a sembrare meno come “chat” e più come “ops”.

Cos’è Hermes Agent e perché è importante

Hermes Agent è un agente AI open-source sviluppato da Nous Research. È progettato per eseguirsi in modo persistente, utilizzare strumenti (terminale, file, web e altro) e migliorare il proprio comportamento nel tempo grazie a un sistema di competenze e memoria.

Due scelte di progettazione meritano di essere specificate perché definiscono tutto il resto di questa guida.

Prima di tutto, 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 modificando il codice.

In secondo luogo, Hermes traccia una linea netta tra “conversazione” ed “esecuzione”. L’agente può chiacchierare tutto il giorno, ma quando deve agire, lo fa attraverso strumenti espliciti e un backend di esecuzione configurabile. È qui che risiedono sicurezza, riproducibilità e troubleshooting.

Costi e licenze sono piacevolmente noiosi. Hermes Agent stesso è software gratuito sotto licenza MIT. Se utilizzi modelli ospitati, il costo ricorrente è quello addebitato dal tuo provider. Se esegui modelli locali, puoi evitare completamente le tariffe API.

Se la tua configurazione di Hermes utilizza Claude tramite layer esterni di strumenti, questa modifica all’abbonamento Anthropic è un riferimento utile per capire 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 mantiene le cose intenzionalmente semplici.

Installazione in un comando

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.

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

Quickstart

La prima esecuzione più rapida è letteralmente solo hermes, ma un quickstart significativo implica due decisioni extra: quale provider di modelli utilizzare 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 su aree di configurazione principali

Un flusso minimale sembra questo:

hermes model
hermes tools
hermes

Per quanto riguarda ciò che è effettivamente supportato, il Quickstart ufficiale elenca una gamma di provider e segnala anche che Hermes funziona con API compatibili con OpenAI. Questo è importante perché include sia servizi ospitati che endpoint auto-ospitati.

Prova 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. Il Quickstart suggerisce esplicitamente l’uso del terminale come prima funzionalità da provare.

In pratica, un piccolo prompt “smoke test” svolge due compiti: verifica lo strumento del terminale e valida i prompt di autorizzazione.

Esempio di prompt:

Mostra la mia utilizzazione del disco e le cinque directory più grandi.

Se Hermes non riesce a eseguire lo strumento del terminale, passa direttamente al Troubleshooting. La configurazione errata del backend del terminale è una delle cause più comuni e la soluzione è solitamente evidente una volta che si guarda la configurazione.

Configurazione scalabile

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

Dove risiedono configurazione e stato

Hermes archivia le sue impostazioni e lo stato sotto ~/.hermes. La guida di configurazione ufficiale documenta la struttura, inclusi 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 debugging diventa meccanico perché sai esattamente dove guardare.
• I backup diventano lineari 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 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 all’interno di config.yaml tramite la sintassi ${VAR_NAME}. Questo è utile quando vuoi mantenere certi valori nell’ambiente mentre li fai 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 di configurazione elenca local, docker, ssh, modal, daytona e singularity.

Il modo opinato ma non evangelico per pensare a questo è:

• local è il più veloce e semplice, ma non è isolato
• docker è uno strato pragmatico per 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 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 il rafforzamento 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 comporre 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 è memorizzata come file come MEMORY.md e USER.md sotto ~/.hermes, e Hermes può anche utilizzare provider di memoria esterni per un ricordo più profondo. La documentazione sulla memoria elenca più plugin di provider e la guida sui provider di memoria documenta un flusso di configurazione interattivo.

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

Per uno sguardo più approfondito su quali competenze funzionano bene in produzione per ruolo — ingegneri, ricercatori, operatori e flussi di lavoro esecutivi — vedi Hermes AI Assistant Skills per Configurazioni di Produzione Reali.

Flusso di lavoro tipico

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

Una baseline stabile

Una baseline che tende a non decomporsi è:

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 sandboxata.
4. Apporta una modifica rapida a SOUL.md solo dopo aver usato le impostazioni predefinite per un po’. I cambiamenti di identità contano più di quanto si pensi perché sono “slot 1” nel prompt del sistema.

Uso quotidiano che compone valore

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

In pratica, una cadenza utile è:

• esegui il lavoro in una sessione nominata per un progetto
• comprimi il contesto quando cresce troppo
• lascia che Hermes trasformi le routine ripetitive in competenze
• mantieni 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’app a 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ò eseguire in primo piano o come servizio utente. Il riferimento CLI documenta sottocomandi del gateway come run, install, start, stop, status e restart.

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

Aggiornamenti senza dramma

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

Troubleshooting e diagnostica

La maggior parte dei fallimenti di Hermes non è misteriosa. Sembra misteriosa perché le persone controllano solo il layer del modello e ignorano il layer 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 oscurato

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 di installazione comuni

La FAQ e la guida al troubleshooting elencano diversi problemi ricorrenti e le loro correzioni, inclusi problemi di versione Python, uv non trovato e problemi di permessi causati dalla miscela di installazioni sudo con installazioni utente.

Se incontri questi errori, la documentazione fornisce passaggi 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 consiglia di controllare la configurazione, rieseguire hermes model o impostare una chiave direttamente tramite hermes config set. Segnala anche un tranello 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.

Anche i problemi di limitazione delle velocità e 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 di backend del terminale e gateway

Se i comandi del terminale falliscono immediatamente, la guida di 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 fare fallback su local è una mossa di debugging valida quando la configurazione del sandbox è in discussione.

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

Riferimenti

• Homepage di Hermes Agent
• Hermes AI Assistant Skills per Configurazioni di Produzione Reali