Come creare un agente AI tipo OpenClaw

Cos'è effettivamente OpenClaw

OpenClaw è un agente AI personale self-hosted. Viene eseguito sul proprio server, si collega alle app di chat già in uso e può eseguire comandi shell, controllare un browser, leggere e scrivere file ed agire sui messaggi inviati. È distribuito con licenza MIT, è local-first e ha superato le 380.000 stelle su GitHub a metà del 2026, rendendolo uno dei progetti più popolari della piattaforma. Sotto la superficie è un insieme relativamente piccolo di componenti collegati in modo logico. Questo post analizza tali componenti per comprendere come viene costruito uno strumento simile e quali sono i suoi punti critici.

Un avvertimento preliminare, poiché influenza ogni scelta progettuale descritta di seguito. Nel marzo 2026 OpenClaw ha avuto nove vulnerabilità di sicurezza scoperte nell'arco di quattro giorni, inclusa una falla critica di privilege-escalation con un punteggio di 9.9 su 10 (CVE-2026-32922). Il progetto è progettato per essere messo in sicurezza dall'operatore. Un agente capace di eseguire qualsiasi comando è sicuro solo quanto il sistema su cui gira e i limiti che gli vengono imposti. Tenete presente questo concetto durante la lettura.

Il daemon gateway: un singolo processo, protetto

Al centro opera un singolo processo a lunga esecuzione, solitamente chiamato gateway. È il piano di controllo. Riceve i messaggi, decide cosa fare, esegue gli strumenti e invia le risposte. Tutto il resto si collega ad esso.

Il dettaglio più importante riguarda l'indirizzo di ascolto del gateway. Di default OpenClaw lo vincola all'indirizzo loopback, 127.0.0.1, quindi non è raggiungibile da internet a meno che non si decida esplicitamente di esporlo. Lasciatelo così. Questo è l'unico processo che esegue comandi per gestire il sistema; un gateway esposto concede a chiunque lo trovi un accesso remoto al proprio server. Quando è necessario raggiungerlo dal proprio laptop, farlo tramite una VPN o un tunnel SSH invece di aprire una porta. Nessuno può attaccare una porta che non può raggiungere.

Channel connectors: ricevere un messaggio e inviare una risposta

Un agente personale è utile solo se è possibile comunicare con esso tramite le app già utilizzate. Questo è il compito dei channel connectors. Ognuno comunica con una singola piattaforma, come Telegram, WhatsApp, Slack o Discord, utilizzando la bot API o i webhook di tale piattaforma.

La struttura è identica per tutti. Il connettore registra un bot sulla piattaforma, riceve il messaggio in entrata (tramite polling o tramite un webhook inviato dalla piattaforma), passa 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 per l'agente" e viceversa. Costruirene uno proprio consiste principalmente nel leggere la documentazione bot di una piattaforma e mappare il suo formato di messaggio su quello del gateway.

Il cervello e il tool loop

All'interno del gateway risiede la parte che lo rende un agente piuttosto che un chatbot. Si tratta di un ciclo (loop).

Arriva un messaggio. Il gateway lo inviola a un modello linguistico insieme a un elenco di strumenti che il modello è autorizzato a usare. Il modello legge il messaggio e decide: rispondere direttamente o chiamare uno strumento. Se chiama uno strumento, il gateway esegue lo strumento, cattura il risultato e lo invia nuovamente al modello. Il modello analizza il risultato e decide di nuovo. Questo processo si ripete finché il modello non ha più operazioni da eseguire e produce una risposta finale.

Questo ciclo è il concetto fondamentale di un agente, ed è lo stesso sia che l'agente risieda in un'app di chat che in un terminale. Per comprendere come gli strumenti vengono collegati a questo ciclo in modo standard, connettere gli strumenti tramite il Model Context Protocol è una lettura consigliata; per quanto riguarda il lato del modello, eseguire il modello su hardware proprio completa l'altra metà.

L'insieme degli strumenti è il punto centrale, e il pericolo

Gli strumenti sono ciò che rende potente OpenClaw. Uno strumento che esegue un comando shell, uno strumento che controlla un browser, uno strumento che legge e scrive file. Fornendo al ciclo sopra descritto l'accesso a questi strumenti, l'agente può fare quasi tutto ciò che è possibile fare tramite tastiera. Questa capacità è l'intero prodotto, ma rappresenta anche l'intero rischio.

Un agente che può eseguire qualsiasi comando, agendo su istruzioni provenienti da un'app di chat, rappresenta una vasta superficie di attacco. Un'istruzione errata, un attacco di prompt-injection nascosto in una pagina web visitata dal connettore browser, o un bug come quelli del marzo 2026 possono trasformare "leggi il mio calendario" in "cancella i miei file". Pertanto, i limiti non sono opzioni facoltative. Eseguite l'agente come utente dedicato e senza privilegi, senza permessi sudo, in modo che un compromesso non possa scalare i privilegi. Limitatene l'accesso agli strumenti pericolosi tramite un passaggio di approvazione, così l'agente chiederà conferma prima di eseguire azioni distruttive. Utilizzate il sandboxing per l'esecuzione degli strumenti, in modo che un comando fuori controllo rimanga isolato. Isolate la chiave API del modello per evitare che una fuga di dati conceda un account all'attaccante.

Prima di esporre qualsiasi elemento che esegue comandi shell, completate deliberatamente le operazioni di base. Generatene una checklist per il proprio sistema qui, quindi seguite i punti dall'alto verso il basso:

La gestione dell'utente senza privilegi è trattata in dettaglio in eseguire servizi come utente senza privilegi, mentre la guida completa alla configurazione sicura per il progetto reale si trova in eseguire OpenClaw in sicurezza su un VPS.

La memoria come file semplici

Molti si aspettano che la memoria di un agente risieda in un database. La memoria di OpenClaw no. Memorizza la memoria come semplici file Markdown su disco; questa scelta è consigliabile.

I file sono semplici. Non c'è bisogno di migrare schemi, non serve mantenere attivo un servizio e non serve imparare un linguaggio di interrogazione. Sono ispezionabili: è possibile aprire la cartella e leggere esattamente cosa l'agente sa di voi, correggere una nota errata modificando un file o eliminare una memoria rimuovendo un file. Sono inoltre portatili, poiché spostare l'agente su un nuovo server consiste nel copiare una directory. Per un agente personale a utente singolo, una cartella di file di testo è sufficiente e mantiene l'intero sistema facile da gestire.

Skill: un modo portatile per aggiungere capacità

Oltre agli strumenti integrati, OpenClaw utilizza un formato skill portatile, in modo che la community possa estendere le sue capacità senza modificare il core. Una skill è un pacchetto autonomo di istruzioni e, talvolta, codice che insegna all'agente un nuovo compito. L'agente carica una skill quando il compito lo richiede.

Il valore di un formato simile è che le capacità diventano condivisibili. Qualcuno scrive una skill per un compito specifico, la pubblica e altri possono aggiungerla. Se costruite il vostro agente, definire precocemente un formato di estensione piccolo e chiaro vi eviterà di dover codificare ogni singola capacità nel core in seguito.

Portate il vostro modello

OpenClaw è agnostico rispetto al modello. Non include il proprio modello linguistico. Si collega invece a un modello scelto dall'utente, che può essere un'API ospitata o un modello eseguito localmente.

Questa distinzione è importante per costi, privacy e controllo. Un'API ospitata fornisce i modelli più potenti senza dover gestire l'hardware, con un costo per token e con i prompt che lasciano il server. Un modello self-hosted, servito con strumenti come Ollama, mantiene ogni messaggio sul proprio server e costa solo per l'hardware e l'energia, a fronte dell'uso di un modello più piccolo o più lento. Molti utenti utilizzano un sistema misto. Se si desidera mantenere un agente completamente privato, eseguire il modello su proprio VPS è l'elemento che colma l'ultimo divario; Hermes Agent è un altro agente self-hosted da confrontare.

Dovreste costruirne uno?

È possibile costruire tutto questo. I componenti non sono esotici: un daemon, alcuni connettori chat, un ciclo modello-strumenti, una cartella di file Markdown e un formato plugin. Comprenderli è utile, poiché demistifica ogni agente che utilizzerete e indica esattamente dove risiede il pericolo.

Tuttavia, per la maggior parte delle persone, la risposta onesta è eseguire il software reale e metterlo in sicurezza, piuttosto che reinventarlo. OpenClaw ha già risolto la questione dei connettori, del ciclo e del formato delle skill, ed è stato sottoposto a verifiche di sicurezza reali. Il vostro sforzo è meglio investito nella parte che spetta effettivamente a voi: la configurazione e la messa in sicurezza sul vostro server. Costruitene uno piccolo per imparare. Eseguite e blindate quello reale per usarlo.

Le fondamenta generali si trovano in costruire il proprio agente AI su un VPS, mentre costruire un agente con Claude mostra gli stessi concetti utilizzando un modello specifico come cervello.

FAQ

È difficile costruire un agente come OpenClaw?

I singoli componenti non sono difficili. Un processo gateway, un connettore chat, un ciclo modello-strumenti e una cartella di file sono ciascuno semplici di per sé. La parte difficile è farlo in modo sicuro. Un agente che esegue comandi shell da messaggi chat rappresenta una seria superficie di attacco; configurare correttamente il sandboxing, i permessi e l'utente senza privilegi richiede più lavoro rispetto al collegamento delle funzioni.

Perché OpenClaw memorizza la memoria come file Markdown invece di un database?

Perché per un agente personale a utente singolo i file sono sufficienti e molto più semplici. Non c'è un servizio database da eseguire, la memoria è facile da leggere e correggere manualmente e spostare l'agente su un altro server richiede solo la copia di una directory. Un database è utile su scala maggiore, non in questo caso.

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

Gli strumenti che gli permettono di agire: eseguire comandi shell, controllare un browser e scrivere file. Questi sono il motivo per cui si costruisce un agente e il motivo per cui può causare danni. L'evento di sicurezza di OpenClaw del marzo 2026, con nove problemi in quattro giorni inclusa una falla critica con valutazione 9.9, è l'argomento più chiaro per trattare lo strato degli strumenti con cautela: eseguite come utente senza privilegi, limitate le azioni distruttive e utilizzate il sandboxing per l'esecuzione.

Ho bisogno di un mio modello linguistico per costruirne uno?

No. Gli agenti come OpenClaw sono agnostici rispetto al modello, quindi è possibile collegarne uno scelto dall'utente. Può trattarsi di un'API ospitata per i modelli più potenti, o di un modello eseguito localmente per la massima privacy. L'auto-hosting con Ollama mantiene ogni messaggio sul proprio server, al costo di utilizzare un modello più piccolo.