L’intelligenza artificiale autonoma sta ridefinendo il modo in cui le aziende gestiscono le operazioni quotidiane, e avere un agente locale sempre attivo è diventato un vantaggio competitivo irrinunciabile. Se ti stai chiedendo come installare OpenClaw, sei nel posto giusto. Questo strumento open-source ha rivoluzionato il panorama tech, trasformandosi da semplice esperimento a un vero e proprio ecosistema capace di operare 24 ore su 24 sul tuo computer o server. Per comprendere a fondo le potenzialità di questo strumento prima di procedere al setup, ti consiglio di leggere il nostro approfondimento su OpenClaw: cos’è e come funziona, che ti darà una panoramica chiara della sua architettura a quattro livelli.
A differenza dei classici chatbot che attendono passivamente un tuo input, questo sistema agisce come un assistente proattivo. Può leggere le tue email, organizzare il calendario, eseguire comandi sul terminale e comunicare con te attraverso le app di messaggistica che usi tutti i giorni. Tuttavia, proprio per la sua natura profondamente integrata con il sistema operativo, il processo di setup richiede attenzione. In questa guida tecnica esploreremo ogni singolo passaggio per configurare l’ambiente, installare il core, collegare i modelli linguistici e risolvere qualsiasi intoppo tecnico, garantendoti un’installazione pulita e sicura.
I requisiti di OpenClaw per preparare il tuo ambiente di lavoro
Prima di digitare qualsiasi comando nel terminale, è fondamentale preparare il terreno. L’agente funziona come un demone in background (un processo continuo) che gestisce costantemente connessioni WebSocket, elabora prompt complessi e legge file di testo dal tuo disco. Questo significa che il tuo ambiente di lavoro deve rispettare parametri specifici per evitare colli di bottiglia, crash improvvisi o problemi di latenza durante l’esecuzione dei flussi di lavoro automatizzati.
Hardware necessario per far girare l’agente AI locale
Sebbene il sistema non richieda un supercomputer per le operazioni di base, le specifiche hardware variano drasticamente in base a come intendi utilizzarlo. Il componente principale, noto come Gateway, è estremamente leggero, ma le operazioni di memoria e l’eventuale esecuzione di modelli in locale richiedono risorse adeguate.
Per un’installazione standard in cui l’agente si appoggia a modelli cloud (tramite API), i requisiti minimi e consigliati sono i seguenti:
| Componente | Requisito Minimo | Requisito Consigliato (Uso B2B) |
|---|---|---|
| Processore (CPU) | Dual-core 2.0 GHz | Quad-core o superiore (Apple Silicon M1/M2 o Intel i5/i7 recenti) |
| Memoria RAM | 1 GB (solo per il Gateway) | 4 GB o superiore (per build stabili e gestione plugin) |
| Spazio di Archiviazione | 2 GB di spazio libero | 10 GB su disco SSD (fondamentale per la lettura/scrittura dei log) |
| Sistema Operativo | macOS, Linux, Windows 10/11 | macOS, Linux nativo o Windows tramite WSL2 |
Se utilizzi un ambiente Windows, è strettamente necessario operare tramite WSL2 (Windows Subsystem for Linux). L’architettura del software è ottimizzata per ambienti Unix, e l’esecuzione nativa su PowerShell può portare a problemi di permessi sui file di memoria e conflitti con i percorsi di sistema. Inoltre, se prevedi di ospitare l’infrastruttura su un server remoto per garantire un’operatività ininterrotta, ti suggeriamo di consultare la nostra guida su come configurare OpenClaw su VPS, dove analizziamo la gestione dello swap file e la sicurezza delle porte di rete.
Software indispensabili: Node.js e dipendenze di base
Il cuore dell’applicazione è scritto in TypeScript e viene eseguito su ambiente Node.js. La scelta della versione di Node è forse il passaggio più critico di tutta la preparazione. Il team di sviluppo raccomanda caldamente l’utilizzo di Node.js versione 24, o in alternativa la versione 22.16 o superiore. Versioni precedenti non supportano le API crittografiche moderne richieste dal sistema di autenticazione e causano inevitabilmente errori durante la fase di build.
Ecco i pacchetti software che devi avere installati e aggiornati sul tuo computer:
- Node.js (v24 consigliata): Il motore di runtime. Ti consigliamo di installarlo tramite NVM (Node Version Manager) per poter cambiare versione facilmente senza intaccare i permessi di sistema.
- Gestore di pacchetti: Puoi utilizzare npm (incluso con Node), pnpm (molto più veloce e consigliato per gestire le dipendenze di questo specifico tool) o Bun.
- Git: Indispensabile se decidi di clonare il repository per accedere alle versioni di sviluppo o per ispezionare il codice sorgente.
- Strumenti di compilazione (Build tools): Su macOS avrai bisogno degli Xcode Command Line Tools, mentre su Linux del pacchetto build-essential. Servono per compilare alcune dipendenze native scritte in C++.
Verifica sempre le versioni installate aprendo il terminale e digitando node –version e npm –version. Se i numeri corrispondono ai requisiti, sei pronto per passare all’installazione vera e propria.
OpenClaw: come installare il core del sistema sul tuo computer
Esistono diversi metodi per portare il software sulla tua macchina. Il metodo più rapido è l’utilizzo dello script di installazione automatizzato, ma per gli sviluppatori e i sistemisti B2B è spesso preferibile un approccio manuale tramite terminale, che garantisce il controllo totale su dove e come i file vengono posizionati nel sistema operativo.
Scaricare il repository ufficiale e preparare i file
Se desideri avere accesso diretto al codice sorgente, magari per sviluppare plugin personalizzati o per eseguire un audit di sicurezza prima del deployment aziendale, il primo passo è clonare il repository ufficiale da GitHub. Questo approccio ti permette di esplorare la struttura delle cartelle, che è divisa in moduli logici: il Gateway per il routing dei messaggi, il livello di ragionamento (Brain) e il sistema di memoria basato su file Markdown.
Apri il tuo terminale, naviga nella directory in cui desideri ospitare il progetto e utilizza Git per scaricare i file. Una volta scaricato il pacchetto, dovrai entrare nella cartella principale e installare tutte le dipendenze necessarie. Se utilizzi pnpm, il comando leggerà il file di configurazione e scaricherà esattamente le versioni dei pacchetti testate dagli sviluppatori, riducendo al minimo il rischio di incompatibilità. Durante questa fase, potresti visualizzare dei messaggi di avviso relativi a script di build ignorati; è un comportamento normale legato alla sicurezza dei gestori di pacchetti moderni, che richiedono un’approvazione esplicita per compilare codice nativo.
Come installare OpenClaw passo passo tramite terminale
Per la maggior parte degli utenti, l’installazione globale tramite il gestore di pacchetti npm è la strada più pulita ed efficiente. Questo metodo rende il comando eseguibile da qualsiasi posizione nel tuo terminale, facilitando enormemente la gestione quotidiana dell’agente.
Il processo si divide in due fasi cruciali: il download dei binari e la procedura di onboarding. Inizia digitando il comando di installazione globale. Il sistema scaricherà l’ultima versione stabile. Una volta terminato, non avviare subito l’agente, ma procedi con il comando di configurazione iniziale: openclaw onboard –install-daemon.
L’aggiunta del flag per l’installazione del demone è vitale. Senza di esso, l’agente morirebbe nel momento in cui chiudi la finestra del terminale. Il demone, invece, registra l’applicazione come un servizio di sistema (usando launchd su macOS o systemd su Linux), assicurandosi che l’assistente si riavvii automaticamente in caso di crash o al riavvio del computer. Durante l’onboarding, un’interfaccia interattiva nel terminale ti guiderà attraverso la creazione del tuo spazio di lavoro (workspace), che è la cartella sicura dove l’intelligenza artificiale salverà le tue preferenze, i log delle conversazioni e i file di stato.
La configurazione iniziale di OpenClaw per i modelli LLM
Avere il core installato è solo l’inizio. L’agente, di per sé, è un guscio vuoto: un eccellente orchestratore di messaggi e task, ma privo di un “cervello”. Per renderlo intelligente, devi collegarlo a un Large Language Model (LLM). La bellezza di questa architettura risiede nella sua natura agnostica: non sei vincolato a un singolo fornitore, ma puoi scegliere il motore cognitivo che meglio si adatta al tuo budget e alle tue policy di privacy aziendale.
Collegare le API e impostare i parametri di intelligenza artificiale
Durante la fase di onboarding, o successivamente tramite la dashboard di controllo, ti verrà chiesto di selezionare il provider del modello. Le opzioni più comuni includono OpenAI (GPT-4o), Anthropic (Claude 3.5 Sonnet) o soluzioni locali tramite Ollama o LM Studio, ideali se gestisci dati sensibili che non possono lasciare la tua rete aziendale.
Se opti per un servizio cloud, dovrai generare una chiave API dal pannello sviluppatori del fornitore scelto. Inserisci questa chiave quando richiesto dal terminale. Il sistema salverà la credenziale in modo sicuro all’interno del tuo workspace. È fondamentale configurare anche i parametri di “failover”: puoi istruire il sistema a utilizzare un modello potente e costoso per i task complessi (come la scrittura di codice o l’analisi di documenti) e a scalare automaticamente su un modello più economico e veloce per le semplici risposte conversazionali. Questo approccio ibrido ottimizza i costi operativi in un contesto B2B.
Inoltre, dovrai definire il “System Prompt” o “Megaprompt”. Si tratta di file di testo (spesso nominati USER.md e SOUL.md) in cui descrivi chi sei, qual è il tuo ruolo aziendale e che tono di voce deve usare l’assistente. Più contesto fornisci in questi file, più le risposte dell’agente saranno precise e allineate alle tue aspettative.
Integrare l’assistente con WhatsApp e altre app di messaggistica
Il vero potenziale di questo strumento si sblocca quando smetti di usare il terminale e inizi a comunicare con la tua IA tramite le app che usi abitualmente. Il livello Gateway funge da router universale, capace di tradurre i messaggi in arrivo da diverse piattaforme in un formato standardizzato comprensibile dal modello linguistico.
Per le aziende, l’integrazione con le app di chat è un punto di svolta. Se vuoi approfondire le dinamiche specifiche per il customer care o la gestione interna, ti suggeriamo di leggere il nostro articolo dedicato a OpenClaw e l’automazione su WhatsApp. La configurazione richiede la creazione di un bot sulla piattaforma di destinazione. Ad esempio, per Telegram, dovrai parlare con il BotFather per ottenere un token univoco. Per WhatsApp o Slack, dovrai configurare le credenziali OAuth e i webhook.
Una volta ottenuti i token, inseriscili nella configurazione dei canali (Channels) tramite la Control UI. Il Gateway aprirà una connessione WebSocket sicura. Da quel momento, ogni messaggio inviato al bot sul tuo telefono verrà instradato istantaneamente al tuo computer, elaborato dall’LLM e rispedito indietro sotto forma di risposta naturale o azione eseguita.
Il test del sistema e la verifica dell’installazione di OpenClaw
Dopo aver completato l’installazione e la configurazione delle API, è il momento di verificare che tutti i componenti comunichino correttamente tra loro. Un setup errato potrebbe portare a un consumo anomalo di token API o all’impossibilità di ricevere messaggi. Eseguire test mirati ti farà risparmiare ore di debugging in futuro.
Avviare l’agente per la prima volta e leggere i log
Il primo controllo da effettuare riguarda lo stato del servizio in background. Apri il terminale e digita openclaw gateway status. Se l’installazione del demone è andata a buon fine, vedrai un output che conferma che il processo è “Active” e in esecuzione. Successivamente, è fondamentale monitorare cosa sta succedendo sotto il cofano utilizzando il comando openclaw logs –follow.
Questo comando ti mostrerà un flusso in tempo reale delle operazioni dell’agente. Cerca righe che confermino l’avvio del server WebSocket (solitamente sulla porta 18789) e il caricamento corretto dei file di memoria Markdown. Se vedi messaggi di errore rossi o avvisi di “Access Denied”, fermati immediatamente: significa che c’è un problema di permessi sulle cartelle del workspace o che la porta di rete è occupata da un’altra applicazione.
Puoi anche verificare l’interfaccia grafica digitando openclaw dashboard. Questo aprirà una pagina nel tuo browser web predefinito, mostrandoti un pannello di controllo elegante da cui puoi monitorare l’utilizzo della CPU, il consumo dei token API e lo stato delle connessioni con le app di messaggistica.
Eseguire un prompt di prova per confermare il funzionamento
Con i log aperti in una finestra del terminale, prendi il tuo smartphone e apri l’app di messaggistica che hai collegato (ad esempio, Telegram o WhatsApp). Invia un messaggio semplice, come “Ciao, sei operativo? Qual è il tuo stato attuale?”.
Osserva il terminale: dovresti vedere il Gateway che riceve il payload del messaggio, lo normalizza e lo passa al livello di ragionamento. Subito dopo, vedrai la chiamata API in uscita verso OpenAI o Anthropic, seguita dalla ricezione dei token di risposta. Entro pochi secondi, il tuo telefono dovrebbe vibrare con la risposta dell’assistente.
Per un test più avanzato, chiedi all’agente di compiere un’azione sul tuo computer, ad esempio: “Crea un file di testo sulla mia scrivania chiamato test.txt e scrivici dentro ‘Installazione completata’”. Se l’agente esegue l’azione correttamente e ti conferma l’operazione in chat, significa che non solo il modulo linguistico funziona, ma anche il livello di esecuzione (AgentSkills) ha i permessi corretti per interagire con il tuo file system locale.
Risolvere i principali errori di installazione di OpenClaw
Nonostante l’architettura robusta, lavorare con strumenti open-source che interagiscono profondamente con il sistema operativo può generare imprevisti. La maggior parte degli ostacoli si presenta durante la prima configurazione. Saper leggere gli errori e applicare le giuste correzioni è una competenza fondamentale per chiunque voglia gestire automazioni B2B affidabili.
Problemi comuni con Node.js e conflitti di versione
L’errore più frequente riportato dagli utenti è il temuto messaggio “openclaw: command not found” subito dopo l’installazione. Questo accade quasi sempre perché il percorso (PATH) globale di npm non è configurato correttamente nel profilo del tuo terminale (come .zshrc o .bashrc). Per risolverlo, devi aggiungere la directory bin di npm al tuo PATH di sistema, oppure utilizzare npx per eseguire i comandi bypassando l’installazione globale.
Un altro problema critico riguarda i fallimenti durante la fase di build nativa, spesso accompagnati da errori “EACCES” o “node-gyp rebuild error”. Questo scenario si verifica quando:
- Stai utilizzando una versione di Node.js obsoleta (inferiore alla 22).
- Stai eseguendo l’installazione con privilegi di root (sudo) in modo errato, sballando i permessi dei file.
- Mancano i tool di compilazione C++ sul tuo sistema operativo.
La soluzione migliore è disinstallare completamente Node.js, reinstallarlo tramite NVM assicurandosi di selezionare la versione 24, e ripetere l’installazione dell’agente senza utilizzare il comando sudo, permettendo a npm di gestire i permessi nello spazio utente.
Cosa fare se l’agente non riesce a connettersi alle API
Se il tuo assistente riceve i messaggi ma non risponde, o se nei log visualizzi l’errore “0 tokens used”, il problema risiede nella comunicazione con il provider LLM. Il primo passo è verificare la validità della tua chiave API. Spesso le chiavi appena generate richiedono alcuni minuti per propagarsi, oppure il tuo account sviluppatore ha esaurito il credito prepagato (un problema molto comune con le nuove policy di fatturazione di OpenAI e Anthropic).
Un altro errore bloccante è “RPC probe: failed”. Questo indica che il Gateway non riesce a comunicare con l’interfaccia di controllo perché la porta di rete 18789 è bloccata da un firewall o occupata da un altro processo. Su sistemi Unix, puoi identificare il colpevole eseguendo sudo lsof -i :18789 e terminare il processo in conflitto. Se hai bisogno di una guida visiva e di ulteriori spunti per il troubleshooting, ti invitiamo a consultare il nostro tutorial italiano su OpenClaw, dove affrontiamo casistiche avanzate e configurazioni di rete complesse.
Oltre le basi di OpenClaw: come installare moduli aggiuntivi
Una volta che il sistema base è stabile e funzionante, hai tra le mani un potente motore conversazionale. Tuttavia, il vero valore per un’azienda B2B non risiede nella semplice chat, ma nella capacità dell’agente di eseguire compiti complessi in totale autonomia. Questo è reso possibile dall’architettura modulare del software, che permette di espandere le funzionalità tramite plugin e script personalizzati.
Personalizzare i flussi di lavoro per l’automazione B2B
Il sistema gestisce la memoria in un modo unico, molto simile al Write-Ahead Logging dei database relazionali. Invece di usare complessi database vettoriali, salva tutto in semplici file Markdown. Questo approccio rende estremamente facile per un utente umano ispezionare, correggere o iniettare nuove conoscenze nella mente dell’agente.
Per personalizzare i flussi di lavoro, puoi creare delle “AgentSkills” specifiche. Si tratta di funzioni scritte in TypeScript o Python che l’LLM può decidere di invocare quando necessario. Ad esempio, puoi scrivere uno script che si collega al CRM aziendale, estrae i dati dei lead generati nell’ultima settimana e li formatta in un report PDF. Fornendo all’agente lo schema di questa funzione, lui saprà esattamente quando usarla. Se gli scrivi su Telegram “Preparami il report delle vendite”, l’agente comprenderà l’intento, eseguirà lo script locale, leggerà il risultato e ti invierà il PDF direttamente in chat, tutto senza alcun intervento manuale aggiuntivo.
Estensioni di OpenClaw: come installare plugin per nuove funzionalità
La community open-source ha sviluppato un vasto marketplace di estensioni che permettono all’agente di interfacciarsi con strumenti di terze parti come Google Calendar, Notion, GitHub e suite di posta elettronica. L’installazione di questi plugin avviene solitamente tramite la riga di comando o la dashboard web.
Tuttavia, è fondamentale prestare la massima attenzione alla sicurezza. Poiché l’agente opera con i permessi del tuo utente di sistema, un plugin malevolo potrebbe avere accesso a tutti i tuoi file personali o eseguire comandi distruttivi. Prima di installare qualsiasi estensione di terze parti, utilizza il comando openclaw doctor per verificare l’integrità del tuo ambiente. Inoltre, adotta il principio del privilegio minimo: configura il sistema di approvazione (allowlist) in modo che l’agente debba chiederti esplicitamente il permesso tramite notifica push prima di eseguire comandi shell sensibili o inviare email a tuo nome. Per ambienti di produzione critici, valuta sempre l’esecuzione dell’intero ecosistema all’interno di container Docker isolati, garantendo così che le automazioni B2B avvengano in un perimetro sicuro e controllato.