Migra da OpenClaw a Hermes Agent: Guida Manuale

Hai Deciso. Adesso Viene Il Weekend.

Hai già preso la decisione. Forse hai letto il confronto tra Hermes Agent e OpenClaw e hai concluso che il runtime per agenti focalizzato si adatta meglio al tuo modo di lavorare. Forse l'ha fatto un tuo collega. In ogni caso, la scelta è alle spalle. Quello che ti trovi davanti è un lavoro operativo concreto: prendere un'installazione OpenClaw attiva, con mesi di memoria accumulata e skill affinate, e portarla su una nuova installazione pulita di Hermes Agent senza perdere nulla di importante.

Hermes include un comando di migrazione ufficiale. Il pacchetto hermes-migrate è stato rilasciato il 10 marzo 2026 e il flusso hermes claw migrate è documentato per importare impostazioni, memorie, skill, canali e chiavi API. Questo copre il caso ideale. Quello che non copre è il lavoro attorno: il provisioning dell'host, la traduzione della configurazione del provider dalla forma originale di OpenClaw allo schema snake_case di Hermes, la protezione dei segreti a riposo, la riassociazione del bot Telegram e la verifica end-to-end prima di comunicare al team che il nuovo bot è attivo.

Questa guida percorre tutto il processo manualmente, così sai esattamente cosa ti aspetta. Alla fine c'è un'alternativa in 1 minuto.

Passo 1: Blocca ed Esporta lo Stato di OpenClaw

Non iniziare installando Hermes. Inizia fermando il lato OpenClaw.

La documentazione di migrazione di OpenClaw dice di fermare il gateway prima di copiare lo stato, perché altrimenti la cronologia delle conversazioni e le sessioni dei canali continuano a scrivere sotto i tuoi piedi. La directory di stato predefinita è ~/.openclaw/, che contiene openclaw.json, le impostazioni del gateway, auth-profiles.json, le credenziali del provider, le sessioni, lo stato dei canali per WhatsApp e Telegram, e i file del workspace inclusi MEMORY.md, USER.md, le skill e i prompt.

openclaw gateway stop
cd ~
tar -czf openclaw-state-$(date +%Y%m%d).tgz .openclaw
sha256sum openclaw-state-*.tgz

Se hai impostato un percorso personalizzato con OPENCLAW_STATE_DIR, o se usi profili come ~/.openclaw-work o ~/.openclaw-personal, archivia ognuno separatamente. La migrazione è completa solo quanto le directory che ricordi di catturare, e il rischio di dimenticarne un profilo è silenzioso: Hermes si avvierà correttamente e la tua personalità del weekend sarà semplicemente sparita.

Copia gli archivi sul nuovo host prima di modificare qualsiasi altra cosa. Se salti questo passaggio e l'installazione sul nuovo host fallisce, vuoi avere un percorso di rollback pulito che non dipenda dal fatto che la vecchia macchina sia ancora funzionante.

Passo 2: Provisioning dell'Host e Installazione di Hermes

Hai bisogno di un posto dove far girare Hermes. Le due opzioni realistiche sono un piccolo VPS o un host Docker locale.

Per un VPS, un box da 2 vCPU / 4 GB è un punto di partenza comodo. Passerai la prossima ora sulle parti di cui nessuno scrive post: scegliere una regione vicina agli utenti di messaggistica, proteggere SSH, configurare un firewall che consenta solo le porte di cui hai effettivamente bisogno, impostare gli aggiornamenti di sicurezza automatici e decidere se l'agente gira come root (non dovrebbe) o come utente di servizio dedicato con una home directory protetta.

Per Docker in locale, il lavoro è diverso ma non più breve. Scrivi un file Compose, decidi dove vivono i volumi di stato, decidi come il container si riavvia al reboot dell'host, e capisci come il container raggiunge il mondo esterno senza esporre più del necessario.

Una volta che l'host esiste, installa Hermes:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes setup

hermes setup cercherà ~/.openclaw/ e proporrà di migrare. Se hai caricato il tuo tarball in un percorso diverso, estrailo prima in modo che la procedura guidata lo trovi.

Un terminale che estrae un archivio di stato OpenClaw su un server nuovo

Passo 3: Traduci la Configurazione del Provider

Questo è il passaggio in cui la maggior parte delle migrazioni manuali si rompe silenziosamente.

OpenClaw e Hermes consentono entrambi di puntare l'agente su OpenAI, Anthropic, OpenRouter, vLLM, Ollama o un endpoint compatibile OpenAI personalizzato. I campi sembrano simili. Non hanno la stessa forma.

Hermes riconosce solo snake_case nella configurazione del provider. Un apiKey o baseUrl modificato a mano verrà ignorato silenziosamente. Usa api_key e base_url. Quando base_url è impostato, Hermes ignora il nome del provider e chiama direttamente quell'endpoint usando api_key o la variabile d'ambiente OPENAI_API_KEY per l'autenticazione.

La mappatura manuale minima è questa per ogni provider che porti con te:

Campo OpenClaw	Campo Hermes	Note
`provider`	`provider`	Usa lo slug in minuscolo atteso da Hermes (`openai`, `anthropic`, `openrouter`, `ollama`, `vllm`, `custom`)
`model`	`model`	Stessa stringa, nessuna traduzione
`apiKey`	`api_key`	Lo snake_case è obbligatorio, il camelCase viene ignorato
`baseUrl`	`base_url`	Lo snake_case è obbligatorio, impostalo solo se hai davvero bisogno di un endpoint personalizzato
`apiMode`	`api_mode`	Verifica che Hermes supporti ancora il valore che hai usato

Ripeti questa operazione per ogni provider che hai configurato. Se stai usando catene di fallback (principale più un backup economico), falle una alla volta e testa ognuna prima di passare alla successiva.

Passo 4: Porta Persona, Skill e Memoria

OpenClaw archivia la persona in workspace/SOUL.md e IDENTITY.md, con cartelle opzionali per personalità in personalities/, più USER.md, MEMORY.md e file di memoria giornalieri. Le skill si trovano nella directory delle skill del workspace.

Una porta manuale pulita è una decisione file per file, non una copia di directory. Apri ogni file di persona e verifica:

La voce e i vincoli corrispondono ancora al comportamento desiderato per il nuovo agente.
I riferimenti a strumenti specifici di OpenClaw (Control UI, nomi di plugin, comportamenti del gateway) sono rimossi o riformulati.
I nomi delle skill non collidono con le skill integrate di Hermes, altrimenti la versione importata potrebbe fare shadowing o esserne soggetta senza alcun avviso.

Poi sposta i file nella struttura attesa da Hermes:

~/.hermes/SOUL.md per la persona
~/.hermes/memories/ per MEMORY.md, USER.md e i file giornalieri
~/.hermes/skills/openclaw-imports/ per le skill, con la risoluzione dei conflitti fatta a mano

I file di memoria sono quelli in cui la maggior parte dei team sottovaluta il lavoro. Dopo un anno di utilizzo di OpenClaw, MEMORY.md può contenere centinaia di voci che mescolano contesti di progetto obsoleti con fatti ancora rilevanti. La migrazione è il momento giusto per deduplicare e potare, non per copiare ciecamente.

Passo 5: Proteggi i Segreti

Questo passaggio non ha scorciatoie. Hermes archivia le credenziali in ~/.hermes/, con i token di autenticazione sensibili posti in percorsi come ~/.hermes/auth/google_oauth.json usando chmod 0600, scritture atomiche e lock di file cross-processo. Questo è il minimo, non il massimo.

Una migrazione manuale che prende sul serio i segreti richiede:

Un inventario chiaro di ogni chiave API che stai portando, con la rotazione effettuata al momento della migrazione in modo che le chiavi eventualmente esposte durante il periodo OpenClaw siano invalidate.
Permessi del file ~/.hermes/.env impostati a 0600, di proprietà dell'utente di servizio, mai leggibili da altri account sull'host.
Crittografia a riposo per il volume che contiene ~/.hermes/, specialmente se l'host è un VPS condiviso.
Backup off-host che siano essi stessi crittografati, con una procedura di ripristino testata, perché un backup che non hai mai ripristinato non è davvero un backup.
Liste di accesso consentito documentate su chi e cosa può leggere questi file, in modo che il prossimo che andrà in reperibilità non debba indovinare.

Se salti il passaggio di rotazione, non hai realmente migrato la tua postura di sicurezza, l'hai solo spostata.

Passo 6: Ricollega Telegram e Testa End-to-End

Telegram è il canale Hermes più comune e il più facile da rompere durante il trasferimento. Hai bisogno del token del bot, della lista degli utenti consentiti e di eventuali impostazioni specifiche del canale come gli ID dei gruppi o i flag solo-admin. Hermes legge questi dati dalle variabili d'ambiente in ~/.hermes/.env. Dopo l'importazione, il gateway deve essere riavviato prima che il bot inizi a rispondere.

hermes status
hermes gateway restart

Se non hai mai distribuito Hermes su Telegram, la guida alla configurazione di Hermes Agent su Telegram copre la creazione del bot e i dettagli del webhook. Una volta che il gateway è di nuovo attivo, esegui un test end-to-end dal vero client Telegram, non da hermes status. Invia un messaggio che eserciti il richiamo della memoria, uno che eserciti una skill migrata e uno che eserciti la catena del provider. Se uno qualsiasi dei tre fallisce, sistemalo prima di comunicare a chiunque che la migrazione è completata.

Passo 7: Risoluzione dei Problemi Più Comuni

Realisticamente, incontrerai almeno uno di questi. Mettilo in conto.

Conflitti di porta: il gateway OpenClaw e il gateway Hermes vogliono entrambi una porta. Se li hai co-locati durante i test, ferma prima OpenClaw.
Errori di autenticazione del provider: quasi sempre un errore di snake_case o una chiave scaduta. Ricontrolla api_key e base_url, poi hermes status.
Skill mancanti o incompatibili: le skill importate a volte fanno riferimento a strumenti solo-OpenClaw. Leggi la skill che fallisce e riscrivila o rimuovila.
Codifica della memoria: se il tuo MEMORY.md proviene da un'installazione OpenClaw su Windows con terminazioni di riga CRLF, passalo attraverso dos2unix prima di copiarlo.
Deriva della persona: l'agente si comporta diversamente anche se il file di persona è identico. Verifica di non stare caricando due file di persona contemporaneamente e che nessuna persona predefinita di Hermes stia sovrascrivendo la tua.

Se qualcosa funziona in hermes status ma non in Telegram, il problema è quasi sempre il gateway, non l'agente.

Oppure Fai Tutto Questo in Meno di 1 Minuto con Hermify

Rileggi le ultime sette sezioni. Sono da qualche parte tra un weekend focalizzato e una settimana di serate non focalizzate, a seconda di quanto era pulita la tua configurazione OpenClaw quando hai iniziato.

Hermify include una procedura guidata di migrazione da OpenClaw con un clic all'interno della dashboard che fa lo stesso lavoro senza il weekend. Carichi il tuo export di OpenClaw, la procedura guidata mostra un'anteprima della migrazione con i conteggi per persona, skill, memorie, segreti, provider e Telegram prima di applicare qualsiasi cosa, e il passaggio di applicazione scrive tutto in un'installazione Hermes gestita con i segreti crittografati a riposo. Non c'è nessun host da configurare, nessuna traduzione snake_case da ricordare, nessuno script di backup da scrivere.

L'articolo che hai appena letto è ciò che la procedura guidata esegue sotto il cofano. Se il percorso manuale è l'esperienza che vuoi, i passaggi sopra sono accurati e completi. Se il risultato è quello che vuoi, la procedura guidata ti ci porta in circa un minuto.

Inizia con Hermify e migra da OpenClaw prima del weekend che stavi pianificando di dedicarci.