Come costruire un agente AI personale come OpenClaw

Che cos'è realmente OpenClaw

OpenClaw è un agente AI personale self-hosted. Lo esegui sul tuo server, lo colleghi alle app 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 più di 380,000 stelle su GitHub; questo lo rende uno dei progetti con più stelle sulla piattaforma. Al di là del rumore, è un insieme piuttosto ridotto di componenti collegati in modo sensato. Questo articolo illustra questi componenti per aiutarti a capire come viene costruito uno strumento di questo tipo e quali sono i punti critici.

È necessaria una premessa importante, perché condiziona ogni scelta progettuale descritta di seguito. Nel marzo 2026 sono state divulgate nove vulnerabilità di sicurezza in OpenClaw nell'arco di quattro giorni, tra cui una vulnerabilità critica di escalation dei privilegi con un punteggio di 9.9 su 10 (CVE-2026-32922). Il progetto presuppone che sia tu, in qualità di operatore, a definirne l'hardening. Un agente che può eseguire qualsiasi comando è sicuro solo quanto il sistema su cui viene eseguito e i limiti che imponi intorno a esso. Tienilo presente durante la lettura.

Il demone gateway: un solo processo, mantenuto privato

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

L’aspetto più importante del gateway è l’indirizzo su cui resta in ascolto. Per impostazione predefinita, OpenClaw lo associa all’indirizzo di loopback, 127.0.0.1, quindi non è raggiungibile da Internet a meno che non venga esposto intenzionalmente. Lascia questa configurazione invariata. Questo è il processo che esegue i comandi, quindi un gateway esposto offre a chiunque lo individui un punto d’accesso remoto al 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 può 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.

Memoria come file di testo

La maggior parte delle persone si aspetta che la memoria di un agent risieda in un database. Quella di OpenClaw non funziona così. Viene archiviata come semplici file Markdown sul disco, ed è una scelta che vale la pena adottare.

I file sono semplici. Non esiste uno schema da migrare, non c'è un servizio da mantenere in esecuzione e non occorre imparare un linguaggio di query. Sono ispezionabili: puoi aprire la directory e leggere esattamente ciò che l'agent ritiene su di te, correggere una nota errata modificando un file oppure eliminare una memoria rimuovendolo. Sono anche portabili, perché spostare l'agent su un nuovo server consiste nel copiare una directory. Per un agent personale usato da 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?

Le singole parti non sono difficili. Un processo gateway, un connettore per chat, un ciclo modello-strumenti e una directory di file sono componenti semplici se considerati separatamente. La parte difficile è realizzare tutto in sicurezza. Un agente che esegue comandi shell ricevuti nei messaggi di chat ha una superficie di attacco rilevante. Configurare correttamente sandbox, permessi e un account utente senza privilegi richiede più lavoro del collegamento delle funzionalità.

Perché OpenClaw archivia la memoria in file Markdown invece di usare 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. Per spostare l'agente su un altro server basta copiare una directory. Un database è giustificato su 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 crea l'agente e anche il motivo per cui può causare danni. L'evento di sicurezza di OpenClaw del March 2026, con nove problemi in quattro giorni tra cui una vulnerabilità critica con valutazione 9.9, dimostra chiaramente che il livello degli strumenti deve essere gestito con attenzione: eseguire l'agente con un account utente senza privilegi, subordinare le azioni distruttive a controlli e usare una sandbox per l'esecuzione.

Devo avere un mio modello linguistico per crearne uno?

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