WhatsApp è dove avvengono le conversazioni. Non Slack, non Discord, non Telegram — per la maggior parte del mondo, WhatsApp è il default. Due miliardi di utenti attivi mensili, dominante in Europa, America Latina, Asia meridionale e Africa. Se vuoi un assistente AI che faccia davvero parte della tua vita quotidiana, deve essere dove le tue conversazioni quotidiane già avvengono.
Il problema è che WhatsApp non offre un'API bot per i privati. L'API WhatsApp Business esiste, ma richiede un account business, l'approvazione di Meta e una struttura di costi per messaggio pensata per il servizio clienti, non per assistenti personali. Per uno sviluppatore che vuole un bot AI personale nel proprio WhatsApp — uno che risponda nelle chat di gruppo, ricordi il contesto e giri sul proprio hardware — il percorso ufficiale è un vicolo cieco.
NanoClaw risolve questo con Baileys, una libreria open-source per WhatsApp Web che si connette ai server di WhatsApp nello stesso modo del client WhatsApp Web. Scansioni un codice QR, la connessione viene stabilita, e NanoClaw può inviare e ricevere messaggi come il tuo account WhatsApp. Nessuna API business, nessuna approvazione Meta, nessun costo per messaggio.
L'architettura: perché WhatsApp è speciale
L'integrazione WhatsApp di NanoClaw non è solo un bridge per messaggi — è il canale principale attorno al quale l'intera architettura è progettata. Mentre gli altri canali (Telegram, Discord, Slack) vengono aggiunti tramite Claude Code skills, WhatsApp è integrato nel core. Non è favoritismo; è un riflesso di come il modello a gruppi di WhatsApp si mappa naturalmente sul modello di sicurezza di NanoClaw.
I gruppi WhatsApp sono il confine di isolamento. Ogni gruppo ottiene il proprio container, il proprio file di memoria CLAUDE.md e il proprio workspace scrivibile. Quando qualcuno invia un messaggio in un gruppo familiare, l'agente che risponde ha accesso solo alla cronologia e alla memoria di quel gruppo. Non può vedere i messaggi del tuo gruppo di lavoro, non può accedere alla cronologia delle tue chat private e non può leggere file che appartengono ad altri gruppi. L'isolamento è garantito dai mount dei container, non dalla logica applicativa.
Questo isolamento per gruppo è ciò che rende NanoClaw sicuro per il modo in cui le persone usano davvero WhatsApp. Il tuo gruppo familiare discute questioni personali. Il tuo gruppo di lavoro discute progetti proprietari. Il tuo gruppo di amici condivide cose che non condividerebbe pubblicamente. Ciascuno di questi contesti deve essere separato, e NanoClaw lo garantisce — non attraverso liste di controllo degli accessi che potrebbero avere bug, ma attraverso la separazione fisica dei container che non può essere aggirata da exploit a livello applicativo.
La configurazione
Il processo di setup richiede circa dieci minuti, la maggior parte dei quali in attesa di npm install.
Clona il repository e installa le dipendenze:
```bash git clone https://github.com/qwibitai/NanoClaw.git cd NanoClaw npm install ```
Configura il tuo ambiente. La configurazione minima è solo una chiave API Anthropic:
```bash echo 'ANTHROPIC_API_KEY=sk-ant-your-key-here' > .env ```
Esegui il pairing WhatsApp:
```bash npm run auth ```
Questo mostra un codice QR nel tuo terminale. Apri WhatsApp sul telefono, vai su Dispositivi collegati e scansiona il codice. La connessione viene stabilita, e NanoClaw è ora in ascolto per i messaggi.
Avvia l'agente:
```bash npm start ```
Tutto qui. Invia un messaggio a qualsiasi gruppo WhatsApp dove vuoi che il bot sia attivo, menziona il nome dell'assistente (configurabile tramite ASSISTANT_NAME nel file .env), e risponde. La prima risposta richiede qualche secondo mentre il container si avvia; i messaggi successivi nella stessa sessione sono più veloci perché il container resta attivo.
Come fluiscono i messaggi
Comprendere il flusso dei messaggi aiuta a spiegare perché NanoClaw risulta reattivo nonostante l'overhead dei container. Quando arriva un messaggio su WhatsApp, il processo host — il core TypeScript di NanoClaw da circa 500 righe — lo riceve tramite Baileys. Verifica se il messaggio è indirizzato all'assistente (per menzione del nome o messaggio diretto). Se lo è, l'host cerca lo stato del container del gruppo.
Se un container è già in esecuzione per quel gruppo (da una conversazione recente), il messaggio viene instradato ad esso tramite IPC. L'agente all'interno del container riceve il messaggio, lo elabora con Claude Agent SDK e rimanda la risposta tramite IPC. L'host inoltra la risposta a WhatsApp. Latenza aggiuntiva totale: pochi millisecondi per l'IPC, più il tempo di risposta dell'API di Claude.
Se nessun container è in esecuzione, l'host ne avvia uno. Su macOS con Apple Container, questo richiede 200-400ms. Su Linux con Docker, 1-2 secondi. Il container riceve il file di memoria CLAUDE.md del gruppo, la cronologia della conversazione da SQLite e la chiave API tramite stdin. Elabora il messaggio e risponde. Il container resta attivo per un timeout configurabile (default: 30 minuti) per gestire i messaggi di follow-up senza l'overhead di avvio.
Il risultato è che la maggior parte dei messaggi — quelli che arrivano durante una conversazione attiva — sembrano istantanei. Il tempo di risposta dell'AI è dominato dalla latenza dell'API di Claude, non dall'infrastruttura di NanoClaw. Solo il primo messaggio dopo un lungo silenzio ha l'overhead di avvio del container, e anche quello è abbastanza veloce da passare raramente inosservato.
Memoria per gruppo: la funzionalità che lo rende utile
Il file CLAUDE.md per gruppo è ciò che trasforma un chatbot stateless in un assistente genuinamente utile. Il file di memoria di ogni gruppo accumula contesto nel tempo — preferenze, progetti in corso, argomenti ricorrenti, battute interne. L'agente legge questo file all'inizio di ogni turno di conversazione, il che significa che ricorda ciò che gli hai detto la settimana scorsa senza che tu debba ripeterlo.
In un gruppo familiare, la memoria potrebbe annotare preferenze alimentari, orari scolastici e attività ricorrenti. In un gruppo di lavoro, potrebbe tracciare scadenze di progetto, preferenze del team e decisioni tecniche. In un gruppo di amici, potrebbe ricordare piani di viaggio, raccomandazioni di ristoranti e interessi condivisi.
La memoria è modificabile. Puoi chiedere all'agente di ricordare qualcosa di specifico ("ricorda che la mamma è allergica ai crostacei") o di dimenticare qualcosa ("dimentica quello che ho detto sulla festa a sorpresa"). Puoi anche modificare il file CLAUDE.md direttamente — è un file di testo semplice sul tuo filesystem, non chiuso dentro un database.
La realtà sulla privacy
Gestire un bot AI su WhatsApp solleva legittime domande sulla privacy, e vale la pena essere diretti. I messaggi che NanoClaw elabora vengono inviati all'API di Anthropic affinché Claude generi le risposte. Questo significa che i tuoi messaggi WhatsApp — o almeno quelli indirizzati all'assistente — lasciano il tuo dispositivo e vengono elaborati dai server di Anthropic.
NanoClaw mitiga questo in diversi modi. Solo i messaggi esplicitamente indirizzati all'assistente vengono inviati all'API — il bot non elabora né archivia messaggi che non gli sono diretti. La cronologia delle conversazioni archiviata in SQLite resta sulla tua macchina. I file di memoria CLAUDE.md restano sulla tua macchina. E se configuri NanoClaw per usare Ollama invece di Anthropic, l'elaborazione AI avviene localmente — nulla lascia la tua rete.
Per la maggior parte degli utenti, la postura pratica sulla privacy è: i tuoi messaggi WhatsApp restano sul tuo dispositivo tranne quando chiedi esplicitamente una domanda all'assistente AI, nel qual caso quel messaggio specifico viene inviato ad Anthropic (o elaborato localmente con Ollama). È una storia sulla privacy significativamente migliore rispetto ai servizi AI cloud che elaborano e archiviano tutto ciò che digiti.
WhatsApp è dove avviene la tua vita. NanoClaw ci mette un assistente AI — con l'isolamento, la memoria e il modello di privacy che lo rendono sicuro da usare nei gruppi dove discuti cose che contano davvero.