Tutorial NanoClaw: crea un agente leggero e local-first

Gli agenti IA autonomi stanno cambiando il modo in cui si lavora con il software. Invece di passare da un’app all’altra, puoi dare un semplice comando testuale e lasciare che l’agente gestisca il compito per te. Questo può includere impostare promemoria, aiutare con le email, supportare il project management o assistere con codice e scrittura.

Strumenti come OpenClaw hanno reso questa idea molto più pratica. Mostrano cosa è possibile quando un agente IA è sempre disponibile sul tuo laptop o telefono. Allo stesso tempo, sistemi di agenti più grandi possono sembrare pesanti, complessi e difficili da gestire. Possono introdurre problemi di sicurezza, richiedere più configurazione ed essere più di quanto serve per un flusso di lavoro personale in locale.

Ed è qui che entra in gioco NanoClaw. NanoClaw è un’alternativa più leggera, local-first, più facile da eseguire e con cui sperimentare sulla tua macchina. È anche pensato con la sicurezza in mente, usando l’isolamento basato su Docker per mantenere il tuo ambiente contenuto e proteggere i tuoi dati.

In questo tutorial, configurerai NanoClaw su Windows usando WSL e preparerai l’ambiente passo dopo passo. Installerai gli strumenti di sistema richiesti, imposterai Node.js, clonerai il repository NanoClaw, collegherai l’autenticazione e avvierai il progetto in locale.

Per un confronto tra i due strumenti agentici, ti consiglio di leggere la nostra guida NanoClaw vs OpenClaw.

1. Configura WSL e l’ambiente Linux

Prima di iniziare, ti serve un PC Windows 10/11 abbastanza recente che supporti WSL 2 e la virtualizzazione hardware, con sufficiente RAM (almeno 4 GB, idealmente 8 GB o più) e spazio su disco (circa 20–30 GB liberi) per eseguire Docker Desktop e un ambiente Ubuntu WSL.

Inizia installando WSL su Windows. Apri PowerShell come Amministratore ed esegui:

wsl --install

Dopo l’installazione, riavvia se necessario, poi verifica la configurazione:

wsl --status

Vuoi che la tua distribuzione giri su WSL 2. Questo è importante perché Claude Code supporta WSL su Windows, e Anthropic segnala che il sandboxing funziona con WSL 2 mentre WSL 1 non è supportato.

Quando WSL è pronto, avvia Ubuntu:

wsl

Dentro Ubuntu, aggiorna il sistema e installa gli strumenti di sviluppo di base:

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential curl git wget

Questo ti fornisce un ambiente Linux pulito con gli strumenti core necessari per il resto della configurazione.

2. Installa Node.js, Docker e Claude Code

Prima di installare NanoClaw, devi preparare gli strumenti da cui dipende. 

In questa parte installerai Node.js per eseguire il tooling JavaScript del progetto, ti assicurerai che Docker sia disponibile dentro WSL così che NanoClaw possa usare container isolati, e installerai Claude Code, che userai per eseguire il setup guidato di NanoClaw.

Installa Node.js con NVM

Il modo più semplice per installare Node.js in WSL è con NVM, il Node Version Manager. Ti dà un modo pulito e flessibile per gestire le versioni di Node senza affidarti al gestore pacchetti di sistema.

Esegui i seguenti comandi nel terminale di Ubuntu:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
\. "$HOME/.nvm/nvm.sh"
nvm install 24
node -v
npm -v

Dopo questo, dovresti vedere un output simile a:

v24.14.1
11.11.0

Node.js è necessario perché NanoClaw usa un setup e un flusso di dipendenze basati su JavaScript. Installarlo tramite NVM è utile perché mantiene il tuo ambiente più facile da gestire in seguito. Se mai dovessi cambiare versione o reinstallare Node, puoi farlo senza influenzare il resto della tua configurazione Linux.

Assicurati che Docker funzioni dentro WSL

NanoClaw gira in modo più sicuro e controllato usando l’isolamento dei container basato su Docker. Questo significa che Docker deve essere installato su Windows e collegato correttamente al tuo ambiente WSL.

Per prima cosa, scarica Docker Desktop dal sito di Docker e installalo su Windows. Poi apri Docker Desktop, vai su Settings, assicurati che l’opzione Use the WSL 2-based engine sia attivata e, sotto Resources → WSL Integration, abilita l’integrazione per la tua distro Ubuntu.

Fatto ciò, torna al terminale Ubuntu ed esegui:

docker --version
docker ps

Dovresti vedere un output simile a questo:

Docker version 29.1.3, build f52814d
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

È un buon segno. Significa che Docker è disponibile dentro WSL ed è pronto per essere usato da NanoClaw.

Installa Claude Code in Ubuntu

Con Node e Docker pronti, il passo successivo è installare Claude Code dentro WSL. Questa è l’interfaccia che userai per completare il setup guidato di NanoClaw.

Esegui:

curl -fsSL https://claude.ai/install.sh | bash

Questo installa Claude Code direttamente nel tuo ambiente Ubuntu.

3. Installa NanoClaw dal sorgente

Ora che il tuo ambiente è pronto, è il momento di scaricare NanoClaw e aprirlo in Claude Code.

Inizia clonando il repository ed entrando nella cartella del progetto:

git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw

Se prevedi di personalizzare NanoClaw in seguito, puoi prima fare un fork del repository e clonare la tua copia. Per un primo setup, clonare il repository principale va benissimo.

Una volta dentro la cartella nanoclaw, esegui:

claude

Al primo avvio, Claude Code ti guiderà nel flusso iniziale di accesso e configurazione. Puoi accedere con un account Claude.ai oppure usare l’accesso diretto all’API Anthropic con una chiave API.

Se hai già un abbonamento Claude Pro o Max, l’accesso è di solito il percorso più semplice. Se lavori invece con fatturazione via API, Claude Code può anche essere configurato per usare la tua chiave API Anthropic.

Una volta completato l’accesso, Claude Code si aprirà dentro il tuo progetto NanoClaw e sarai pronto a proseguire con la configurazione.

4. Configura NanoClaw

Con Claude Code aperto dentro la cartella nanoclaw, puoi avviare il setup completo.

Esegui:

/setup

Questo avvia il flusso di setup guidato di NanoClaw.

Cosa succede durante il setup

Una volta eseguito /setup, Claude Code inizia a preparare NanoClaw per te. Questa parte può richiedere un po’ di tempo, quindi lascialo lavorare fase per fase.

Per prima cosa, installa le dipendenze del progetto e verifica che il tuo ambiente locale sia pronto. 

Dopodiché passa alla fase di setup del container, dove esegue i comandi Docker necessari per creare il container personalizzato di NanoClaw e verificare che si avvii correttamente.

Una volta costruito e verificato il container, il setup prosegue installando OneCLI. È una parte importante dello stack NanoClaw perché aiuta a gestire in modo più sicuro i segreti e l’accesso ai container.

Al termine, puoi aprire la dashboard di Docker Desktop e confermare che i container siano in esecuzione. A questo punto dovresti vedere comparire i servizi NanoClaw, incluso l’app container e i servizi di supporto come PostgreSQL.

Imposta il token Claude per OneCLI

Anche se Claude Code è già connesso dentro WSL, il container di NanoClaw ha bisogno di un proprio modo sicuro per accedere a Claude. Per farlo, devi generare un token e registrarlo con OneCLI.

Apri un nuovo terminale ed esegui:

claude setup-token

Questo comando genererà un link da aprire nel browser. Accedi, approva la richiesta e poi incolla il codice restituito nel terminale. Dopodiché, Claude Code ti fornirà un token.

Copia quel token, poi esegui il seguente comando nel terminale, sostituendo YOUR_TOKEN con il token appena generato:

onecli secrets create --name Anthropic --type anthropic --value YOUR_TOKEN --host-pattern api.anthropic.com

Questo passaggio dà al container NanoClaw un accesso sicuro a Claude senza esporre direttamente le tue credenziali dentro il container. Una volta fatto, il setup è pronto per la fase successiva.

5. Configura WhatsApp per NanoClaw

Dopo il completamento del setup principale, Claude Code passerà alla fase di configurazione dei canali. Qui scegli come vuoi interagire con NanoClaw.

Genera il QR code per WhatsApp

Seleziona WhatsApp (puoi anche selezionare altri canali supportati come Discord, Telegram o Slack per dopo, ma ora ci concentriamo su WhatsApp), poi continua.

Per qualche motivo, il QR code nel browser non ha funzionato per me. Sembrava causato da un problema di rete tra WSL e il browser, probabilmente legato a come veniva accessata la porta locale. Per questo useremo invece l’opzione del QR code nel terminale.

Claude Code proverà a mostrare un QR code nel terminale. In alcuni casi, questo QR può risultare tagliato o non visualizzato correttamente.

Per risolvere, apri un nuovo terminale ed esegui:

cd nanoclaw
npm run auth

Questo genererà un QR code pulito nel tuo terminale.

Collega WhatsApp dal tuo telefono

Ora apri WhatsApp sul tuo telefono e segui questi passaggi:

• Vai su Impostazioni
• Tocca Dispositivi collegati
• Tocca Collega un dispositivo
• Scansiona il QR code mostrato nel terminale

Quando la scansione va a buon fine, il tuo account WhatsApp sarà collegato a NanoClaw.

Dopo l’associazione, dovresti vedere un messaggio di successo nel terminale.

Completa la configurazione dei canali in Claude Code

Torna al terminale originale di Claude Code e prosegui con il setup.

Ti verranno poste alcune domande di configurazione. Per ora puoi scegliere le opzioni consigliate.

• Lascia la parola di attivazione predefinita
• Lascia il nome dell’assistente predefinito
• Seleziona la modalità self-chat

La modalità self-chat significa che NanoClaw risponderà solo a te nella tua chat WhatsApp. È utile per i test, perché nessun altro può interagire con il tuo agente.

Finalizza il setup e testa

Quando tutto è configurato, NanoClaw ricostruirà il container con le nuove impostazioni. Potrebbe richiedere qualche istante.

Dopodiché vedrai le istruzioni su come usare NanoClaw.

Per testarlo:

• Apri WhatsApp
• Cerca il tuo numero (la tua self chat)
• Invia un messaggio tipo:

@Andy hello

Se tutto funziona correttamente, NanoClaw risponderà nella chat.

6. Testa NanoClaw con WhatsApp

Ora che è tutto configurato, puoi testare NanoClaw direttamente da WhatsApp.

Apri WhatsApp sul telefono e vai sulla tua chat personale. Apparirà come il tuo numero con “(Tu)” tra parentesi. Inizia con un messaggio semplice, ad esempio:

@Andy how are you?

Entro pochi secondi, NanoClaw dovrebbe rispondere in chat. Questo conferma che il setup funziona correttamente e che l’agente è connesso a WhatsApp.

Puoi anche testare come funziona il trigger. Prova a inviare un messaggio senza la parola di attivazione, ad esempio:

How are you?

Noterai che NanoClaw non risponde. È il comportamento atteso. La parola di attivazione garantisce che l’agente si attivi solo quando lo chiami esplicitamente.

Quando i messaggi di base funzionano, puoi provare un’attività più avanzata. Per esempio, chiedi:

@Andy Tell me the latest gold and silver prices and should i buy it or not

NanoClaw eseguirà l’attività e restituirà una risposta strutturata. Questo mostra che il tuo agente non sta solo rispondendo ai messaggi, ma può anche svolgere attività multi‑step e fornire output utili quando è configurato con gli strumenti giusti, come la ricerca sul web.

A questo punto, la tua configurazione di NanoClaw è pienamente operativa e pronta per casi d’uso più avanzati.

I prezzi dell’oro e dell’argento erano errati, il che suggerisce che in realtà non ha effettuato una ricerca sul web e si è invece basato su informazioni obsolete presenti nella knowledge base del modello.

Considerazioni finali

Configurare NanoClaw ha richiesto molto più tempo del previsto, soprattutto su Windows con WSL. Tra Docker, setup dei container, molteplici servizi di supporto e il numero di permessi che ho dovuto continuare ad approvare dentro Claude Code, il processo è sembrato più pesante di quanto ci si aspetterebbe da un agente locale leggero. Dopo un po’, i prompt e le approvazioni costanti sono diventati stancanti, e l’esperienza complessiva di setup non è risultata adatta ai principianti.

Anche il flusso di installazione non è stato fluido come speravo. In diversi punti, Claude Code mi ha chiesto di aprire nuovi terminali, eseguire comandi aggiuntivi di autenticazione, generare token e registrarli manualmente con OneCLI. Se sei nuovo agli strumenti di IA, ai container o ai flussi di lavoro da riga di comando, questa parte può diventare rapidamente confusa. È fattibile, ma richiede più sforzo manuale di quanto penso molti utenti si aspettino.

Per questo motivo, personalmente ho preferito Nanobot. Mi sono bastati pochi minuti per iniziare a scrivere al mio agente da WhatsApp, e l’esperienza è sembrata molto più rapida e diretta. Con NanoClaw, il rapporto sforzo/risultato non mi è sembrato così favorevole.

Anche l’esperienza su WhatsApp necessita di miglioramenti. Le risposte funzionavano, ma l’interazione è sembrata grezza. Non c’era un chiaro indicatore di digitazione o risposta e la bolla del messaggio aveva lo stesso aspetto dei miei messaggi, cosa che ha reso la conversazione meno naturale. Una distinzione visiva più chiara e qualche feedback che l’agente sta lavorando farebbero una grande differenza, soprattutto quando le risposte richiedono tempo.

Nel complesso, penso ancora che l’idea alla base di NanoClaw sia valida. Un agente sicuro, local-first e leggero è una direzione molto utile. Ma in pratica, il setup è stato più complesso del previsto e l’esperienza finale è risultata un po’ deludente rispetto alla quantità di sforzo necessaria per arrivarci.