Come creare un agente AI personale in stile OpenClaw

Che cos’è realmente OpenClaw

OpenClaw è un agente AI personale self-hosted. Lo esegui sul tuo server, lo colleghi alle applicazioni di chat che già utilizzi e può eseguire comandi shell, controllare un browser, leggere e scrivere i tuoi file e agire sui messaggi che gli invii. È distribuito con licenza MIT, segue un approccio local-first e, a metà del 2026, ha oltre 380,000 stelle su GitHub, risultando così uno dei progetti con più stelle sulla piattaforma. Al di là del clamore, è composto da un insieme piuttosto ridotto di componenti collegati in modo sensato. Questo articolo esamina tali componenti per spiegare come viene realizzato uno strumento di questo tipo e quali sono i principali rischi.

È necessaria una premessa, perché condiziona ogni scelta progettuale descritta di seguito. A marzo 2026 i manutentori di OpenClaw hanno pubblicato una grande quantità di avvisi di sicurezza: 22 solo il 13 marzo e altri cinque il 16 marzo, mentre il National Vulnerability Database ha registrato 199 CVE di OpenClaw pubblicati nello stesso mese. Il gruppo del 13 marzo includeva due vulnerabilità critiche con una valutazione di 9.9 su 10. Una di queste era una vulnerabilità di escalation dei privilegi (CVE-2026-32922) che consentiva a un dispositivo con i soli diritti di pairing di generare token di amministrazione completi. Il progetto è pensato per essere messo in sicurezza dall’operatore. Un agente che può eseguire qualsiasi comando è sicuro solo quanto il sistema su cui viene eseguito e quanto i limiti che gli imponi. Tienilo presente durante la lettura.

Il demone gateway: un solo processo, mantenuto privato

Al centro del sistema c’è un unico processo a esecuzione prolungata, generalmente chiamato gateway. È il control plane. Riceve i messaggi, decide cosa fare, esegue gli strumenti e invia le risposte. Tutto il resto si collega a questo processo.

Il fatto più importante riguardo al gateway è l’indirizzo su cui resta in ascolto. In un’installazione su un host standard, OpenClaw lo associa all’indirizzo di loopback, 127.0.0.1, quindi non è raggiungibile da Internet a meno che non si scelga esplicitamente di esporlo. Le immagini container fanno eccezione: la documentazione di sicurezza di OpenClaw indica che, per impostazione predefinita, utilizzano un bind esposto. Se esegui il container, mantieni attiva l’autenticazione e non pubblicare la sua porta su Internet. In ogni caso, mantienilo privato. Questo è il processo che esegue i comandi, quindi un gateway esposto offre a chiunque lo individui un punto d’appoggio remoto nel server. Quando devi raggiungerlo dal laptop, usa una VPN o un tunnel SSH invece di aprire una porta. Nessuno può attaccare una porta che non è in grado di raggiungere.

Connettori dei canali: ricevere un messaggio e inviare una risposta

Un agente personale è utile solo se puoi interagire con esso dalle applicazioni che già usi. Questo è il compito dei connettori dei canali. Ogni connettore comunica con una piattaforma, ad esempio Telegram, WhatsApp, Slack o Discord, usando l'API bot o i webhook della piattaforma.

La struttura è la stessa per tutti. Il connettore registra un bot sulla piattaforma, riceve il messaggio in ingresso, tramite polling della piattaforma oppure tramite un webhook inviato dalla piattaforma, inoltra il messaggio al gateway e pubblica la risposta del gateway tramite la stessa API. Il connettore è un sottile livello di traduzione. Converte "è arrivato un messaggio Telegram" in "ecco il testo da passare all'agente" e svolge poi la conversione inversa. Per crearne uno autonomamente, è sufficiente consultare la documentazione bot di una piattaforma e associare il relativo formato dei messaggi a quello del gateway.

Il cervello e il ciclo degli strumenti

All'interno del gateway si trova il componente che lo rende un agente anziché un chatbot. È un ciclo.

Arriva un messaggio. Il gateway lo invia a un modello linguistico insieme all'elenco degli strumenti che il modello può usare. Il modello legge il messaggio e decide se rispondere direttamente oppure chiamare uno strumento. Se chiama uno strumento, il gateway lo esegue, acquisisce il risultato e lo invia nuovamente al modello. Il modello analizza il risultato e decide di nuovo. Il ciclo continua finché il modello non ha più operazioni da eseguire e produce una risposta finale.

Questo ciclo è il concetto alla base di un agente. È lo stesso sia che l'agente operi in un'applicazione di chat sia che operi in un terminale. Per vedere come collegare gli strumenti a questo ciclo in modo standard, collegare gli strumenti tramite il Model Context Protocol è una buona lettura successiva. Per il componente relativo al modello, eseguire il modello direttamente sul proprio hardware completa l'altra metà.

L’insieme degli strumenti è il punto di forza, ma anche il pericolo

Gli strumenti sono ciò che rende OpenClaw potente. Uno strumento può eseguire un comando shell, un altro può controllare un browser e un altro ancora può leggere e scrivere file. Se si concede al ciclo descritto sopra l’accesso a questi strumenti, può fare quasi tutto ciò che si può fare con una tastiera. Questa capacità costituisce l’intero prodotto, ma anche l’intero rischio.

Un agente in grado di eseguire qualsiasi comando sulla base di istruzioni ricevute da un’applicazione di chat presenta un’ampia superficie di attacco. Un’istruzione dannosa, un attacco di prompt injection nascosto in una pagina web visitata dallo strumento browser oppure un bug come quelli delle vulnerabilità di marzo 2026 possono trasformare “leggi il mio calendario” in “elimina i miei file”. I limiti, quindi, non sono funzionalità opzionali. Eseguire l’agente con un utente dedicato e senza privilegi, privo di accesso a sudo, in modo che una compromissione non possa portare a un’escalation dei privilegi. Proteggere gli strumenti pericolosi con un passaggio di approvazione, così l’agente deve chiedere conferma prima di eseguire un’azione distruttiva. Eseguire gli strumenti in una sandbox, in modo che un comando fuori controllo resti confinato. Isolare la chiave API del modello, così una fuga di dati non consegna a un attaccante l’accesso al proprio account. Considerare anche gli altri secret presenti sullo stesso host: i veri punti deboli di Vaultwarden sono il token amministrativo e il file di backup, non la crittografia, e un agente con accesso alla shell può raggiungere entrambi.

Prima di esporre qualsiasi componente in grado di eseguire comandi shell, verificare con metodo gli aspetti fondamentali. Generare qui una checklist per il proprio host, quindi seguirla dall’inizio alla fine:

La configurazione dell’utente senza privilegi è descritta in dettaglio in eseguire i servizi con un utente senza privilegi, mentre la procedura completa per configurare in sicurezza il progetto reale è disponibile in eseguire OpenClaw in sicurezza su un VPS.

La memoria come file di testo

La maggior parte delle persone si aspetta che la memoria di un agente risieda in un database. Quella di OpenClaw no. Viene memorizzata in normali file Markdown sul disco, una scelta che vale la pena adottare. I file sono la fonte autorevole dei dati; il motore di memoria predefinito mantiene accanto a essi un indice di ricerca SQLite, che può essere ricostruito a partire dai file.

I file sono semplici. Non è necessario migrare uno schema, mantenere in esecuzione un servizio o imparare un linguaggio di query. Sono ispezionabili: puoi aprire la directory e leggere esattamente ciò che l’agente ritiene di sapere su di te, correggere una nota errata modificando un file oppure eliminare una memoria rimuovendone uno. Sono anche portabili, perché trasferire l’agente su un nuovo server consiste nel copiare una directory. Per un agente personale destinato a un singolo utente, una directory di file di testo è sufficiente e mantiene l’intero sistema facile da comprendere.

Competenze: un modo portabile per aggiungere funzionalità

Oltre agli strumenti integrati, OpenClaw usa un formato portabile per le competenze, così la community può estenderne le funzionalità senza modificare il core. Una competenza è un insieme autonomo di istruzioni e, in alcuni casi, codice, che insegna all'agente a svolgere una nuova attività. L'agente carica una competenza quando l'attività lo richiede. La ricerca sul Web è la prima competenza che molti aggiungono e indirizzarla alla propria istanza SearXNG mantiene le query al di fuori delle API dei motori di ricerca commerciali e rende molto chiaro il perimetro di attendibilità della competenza, perché tutto ciò che restituisce è testo scritto da terzi.

Il valore di un formato di questo tipo è che le funzionalità possono essere condivise. Una persona scrive una competenza per un'attività specifica, la pubblica e altri utenti la installano. Questa comodità ha anche un rovescio della medaglia: una competenza è codice scritto da terzi che l'agente eseguirà senza esitazione. Per questo è opportuno sottoporre a uno scanner di sicurezza ospitato autonomamente tutto ciò che non è stato scritto internamente, prima di caricarlo. Se sviluppi un agente personalizzato, definire fin dall'inizio un formato di estensione piccolo e chiaro evita di dover incorporare in seguito ogni funzionalità nel core.

Scegli il tuo modello

OpenClaw è indipendente dal modello. Non include un proprio modello linguistico. Si connette invece al modello scelto, che può essere disponibile tramite un'API ospitata oppure eseguito autonomamente.

Questa separazione incide su costi, privacy e controllo. Un'API ospitata consente di usare i modelli più avanzati senza gestire hardware, pagando in base ai token e inviando i prompt al di fuori del proprio server. Un modello self-hosted, fornito tramite strumenti come Ollama, mantiene ogni messaggio sul proprio server e comporta soltanto i costi dell'hardware e dell'energia, ma richiede di usare un modello più piccolo o più lento. Molti utenti combinano le due opzioni. Per mantenere un agent completamente privato, eseguire il modello in modalità self-hosted sul proprio VPS elimina anche quest'ultima esposizione, mentre Hermes Agent è un altro agent self-hosted che vale la pena confrontare.

Dovresti crearne uno?

Puoi creare tutto questo. I componenti non sono esotici: un daemon, alcuni connettori per chat, un ciclo modello-strumenti, una directory di file Markdown e un formato per i plugin. Comprenderli è davvero utile, perché chiarisce il funzionamento di ogni agente che utilizzerai e indica esattamente dove si annidano i rischi.

Per la maggior parte delle persone, però, la risposta corretta è eseguire il software reale e configurarlo in modo sicuro, invece di reinventarlo. OpenClaw ha già risolto la gestione dei connector, del loop e del formato delle skill, ed è stato sottoposto a verifiche di sicurezza reali. È più utile concentrare il lavoro sulla parte di cui siete effettivamente responsabili: configurare e mettere in sicurezza il vostro server. Se preferite iniziare dal percorso di apprendimento, studiare i concetti gradualmente è più efficace che leggere direttamente il codice sorgente dell’agente, perché ogni fase vi lascia qualcosa che avete effettivamente realizzato. Costruite un agente di piccole dimensioni per imparare. Eseguite quello reale e configuratelo in modo sicuro per utilizzarlo.

Le basi generali sono descritte in creare il proprio agente AI su un VPS, mentre creare un agente con Claude presenta gli stessi concetti usando un modello specifico come componente centrale.

FAQ

È difficile creare un agente come OpenClaw?

I singoli componenti non sono difficili. Un processo gateway, un connettore per la chat, un ciclo modello-strumenti e una directory di file sono elementi semplici se considerati separatamente. La parte difficile è realizzarli in sicurezza. Un agente che esegue comandi shell a partire dai messaggi di chat espone una superficie di sicurezza significativa, e configurare correttamente sandboxing, permessi e un utente non privilegiato richiede più lavoro del semplice collegamento delle funzionalità.

Perché OpenClaw memorizza la memoria in file Markdown invece che in un database?

Perché, per un agente personale destinato a un singolo utente, i file sono sufficienti e molto più semplici. Non è necessario eseguire un servizio database, la memoria è facile da leggere e correggere manualmente e trasferire l’agente su un altro server significa soltanto copiare una directory. Un database è giustificato su una scala maggiore, non in questo caso.

Qual è la parte più pericolosa di un agente AI personale?

Gli strumenti che gli consentono di agire: eseguire comandi shell, controllare un browser e scrivere file. Sono il motivo per cui si costruisce l’agente e anche il motivo per cui può causare danni. L’ondata di avvisi di sicurezza di OpenClaw di marzo 2026, con 27 avvisi pubblicati tra il 13 e il 16 marzo, inclusi due avvisi critici con valutazione 9.9, è l’argomento più chiaro per trattare con attenzione il livello degli strumenti: esegui l’agente con un utente non privilegiato, limita le azioni distruttive e utilizza il sandboxing per l’esecuzione.

Mi serve un modello linguistico proprietario per crearne uno?

No. Gli agenti come OpenClaw sono indipendenti dal modello, quindi puoi collegare quello che preferisci. Può essere un’API hosted per i modelli più potenti oppure un modello eseguito autonomamente per ottenere la massima privacy. Il self-hosting con Ollama mantiene ogni messaggio sul tuo server, al costo di utilizzare un modello più piccolo.