nanoclaw v2.1.54

Un assistente AI che esegue agenti in modo sicuro nei propri contenitori. Leggero, progettato per essere facilmente compreso e completamente personalizzato per le tue esigenze.

nanoclaw.dev  •   documentazione  •   中文  •   日本語  •   한국어  •     •  

Perché ho creato NanoClaw

OpenClaw è un progetto impressionante, ma non sarei riuscito a dormire se avessi dato a un software complesso che non capivo accesso completo alla mia vita. OpenClaw ha quasi mezzo milione di righe di codice, 53 file di configurazione e oltre 70 dipendenze. La sua sicurezza è a livello applicativo (liste bianche, codici di abbinamento) piuttosto che un vero isolamento a livello di sistema operativo. Tutto gira in un unico processo Node con memoria condivisa.

NanoClaw offre la stessa funzionalità principale, ma in una base di codice abbastanza piccola da essere compresa: un processo e una manciata di file. Gli agenti girano nei propri contenitori Linux con isolamento del filesystem, non solo dietro a controlli di permessi.

Avvio rapido

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash nanoclaw.sh

nanoclaw.sh ti guida da una macchina appena configurata a un agente nominato a cui puoi inviare messaggi. Installa Node, pnpm e Docker se mancanti, registra la tua credenziale Anthropic con OneCLI, costruisce il contenitore dell'agente e abbina il tuo primo canale (Telegram, Discord, WhatsApp o una CLI locale). Se un passaggio fallisce, Claude Code viene invocato automaticamente per diagnosticare e riprendere dal punto in cui si è interrotto.

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash migrate-v2.sh

Filosofia

Abbastanza piccolo da essere compreso. Un processo, pochi file sorgente e nessun microservizio. Se vuoi capire l'intera base di codice di NanoClaw, chiedi semplicemente a Claude Code di guidarti.

Sicuro tramite isolamento. Gli agenti girano in contenitori Linux e possono vedere solo ciò che è montato esplicitamente. L'accesso Bash è sicuro perché i comandi girano all'interno del contenitore, non sul tuo host.

Progettato per l'utente singolo. NanoClaw non è un framework monolitico; è un software che si adatta alle esatte esigenze di ogni utente. Invece di diventare un bloatware, NanoClaw è progettato per essere su misura. Crei il tuo fork e fai in modo che Claude Code lo modifichi per adattarlo alle tue necessità.

Personalizzazione = modifiche al codice. Nessuna proliferazione di configurazioni. Vuoi un comportamento diverso? Modifica il codice. La base di codice è abbastanza piccola da rendere sicure le modifiche.

AI-nativo, ibrido per progettazione. Il flusso di installazione e onboarding è un percorso scriptato ottimizzato, veloce e deterministico. Quando un passaggio richiede giudizio — che sia un'installazione fallita, una decisione guidata o una personalizzazione — il controllo passa senza soluzione di continuità a Claude Code. Oltre all'impostazione non c'è alcun pannello di monitoraggio o interfaccia di debug: descrivi il problema in chat e Claude Code se ne occupa.

Skill sopra funzionalità. Il trunk contiene il registro e l'infrastruttura, non adattatori di canale specifici o provider agenti alternativi. I canali (Discord, Slack, Telegram, WhatsApp, …) vivono su un ramo channels a lunga durata; i provider alternativi (OpenCode, Ollama) su providers. Esegui /add-telegram, /add-opencode, ecc. e la skill copia esattamente i moduli di cui hai bisogno nel tuo fork. Nessuna funzionalità che non hai richiesto.

Miglior cablaggio, miglior modello. NanoClaw utilizza nativamente Claude Code tramite il Claude Agent SDK ufficiale di Anthropic, quindi ottieni gli ultimi modelli Claude e il set completo di strumenti di Claude Code, inclusa la capacità di modificare ed espandere il tuo fork di NanoClaw. Altri provider sono opzioni pronte all'uso: /add-codex per OpenAI Codex (abbonamento ChatGPT o chiave API), /add-opencode per OpenRouter, Google, DeepSeek e altro tramite OpenCode, e /add-ollama-provider per modelli locali open-weight. Il provider è configurabile per gruppo di agenti.

Cosa supporta

• Messaggistica multi-canale — WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat ed email tramite Resend. Installati su richiesta con skill /add-<canale>. Eseguine uno o molti contemporaneamente.
• Isolamento flessibile — collega ogni canale al proprio agente per la massima privacy, condividi un agente tra molti canali per memoria unificata con conversazioni separate, o riunisci più canali in un'unica sessione condivisa in modo che una conversazione si estenda su più superfici. Scegli per canale tramite /manage-channels. Vedi docs/isolation-model.md.
• Area di lavoro per agente — ogni gruppo di agenti ha il proprio CLAUDE.md, la propria memoria, il proprio contenitore e solo i mount che autorizzi. Niente attraversa il confine a meno che tu non lo colleghi.
• Attività pianificate: job ricorrenti eseguiti dall'agente, con gate script opzionali che evitano di risvegliarlo quando non c'è lavoro.
• Accesso web — cerca e recupera contenuti dal web.
• Isolamento in contenitori — gli agenti sono in sandbox in contenitori Docker (macOS/Linux/WSL2).
• Sicurezza delle credenziali — gli agenti non possiedono mai chiavi API in chiaro. Le richieste in uscita passano attraverso OneCLI Agent Vault, che inietta le credenziali al momento della richiesta e applica policy per agente e limiti di frequenza.
• Modelli di agente: stampa un agente pronto all'uso (istruzioni + strumenti MCP + skill, nessun segreto) da un bundle riutilizzabile tramite ncl groups create --template <ref>. I modelli vengono caricati dalla cartella locale templates/; popolala manualmente o copiandoli dalla libreria pubblica. Vedi docs/templates.md.

Utilizzo

Parla con il tuo assistente usando la parola di attivazione (predefinita: @Andy):

@Andy invia ogni mattina dei giorni feriali alle 9 un riepilogo del pipeline di vendita (ha accesso alla mia cartella Obsidian)
@Andy ogni venerdì rivedi la cronologia git dell'ultima settimana e aggiorna il README se c'è deriva
@Andy ogni lunedì alle 8, compila notizie sugli sviluppi dell'IA da Hacker News e TechCrunch e inviami un briefing

Da un canale di tua proprietà o che amministri, puoi gestire gruppi e attività:

@Andy elenca tutte le attività pianificate in tutti i gruppi
@Andy metti in pausa l'attività del briefing del lunedì
@Andy unisciti al gruppo Famiglia

Personalizzazione

NanoClaw non utilizza file di configurazione. Per apportare modifiche, basta dire a Claude Code cosa vuoi:

• "Cambia la parola di attivazione in @Bob"
• "Ricorda in futuro di rendere le risposte più brevi e dirette"
• "Aggiungi un saluto personalizzato quando dico buongiorno"
• "Salva i riepiloghi delle conversazioni settimanalmente"

Oppure esegui /customize per modifiche guidate.

La base di codice è abbastanza piccola da permettere a Claude di modificarla in sicurezza.

Contribuire

Non aggiungere funzionalità. Aggiungi skill.

Se vuoi aggiungere un nuovo canale o provider di agenti, non aggiungerlo al trunk. I nuovi adattatori di canale vanno sul ramo channels; i nuovi provider di agenti vanno su providers. Gli utenti li installano nel proprio fork con skill /add-<nome>, che copiano i moduli rilevanti nei percorsi standard, collegano la registrazione e fissano le dipendenze.

Questo mantiene il trunk come puro registro e infrastruttura, e ogni fork rimane snello — gli utenti ottengono solo i canali e i provider che hanno richiesto, niente di più.

RFS (Richiesta di Skill)

Nessuna skill per canali o provider è attualmente richiesta — proponila tramite un issue.

Requisiti

• macOS o Linux (Windows tramite WSL2)
• Node.js 20+ e pnpm 10+ (l'installer installerà entrambi se mancanti)
• Docker Desktop (macOS/Windows) o Docker Engine (Linux)
• Claude Code per /customize, /debug, recupero errori durante l'installazione e tutte le skill /add-<canale>

Architettura

app di messaggistica → processo host (router) → inbound.db → contenitore (Bun, Claude Agent SDK) → outbound.db → processo host (consegna) → app di messaggistica

Un singolo host Node orchestra contenitori di agenti per sessione. Quando arriva un messaggio, l'host lo instrada tramite il modello entità (utente → gruppo di messaggistica → gruppo di agenti → sessione), lo scrive in inbound.db della sessione e risveglia il contenitore. L'agente-runner all'interno del contenitore interroga inbound.db, esegue l'agente e scrive le risposte in outbound.db. L'host interroga outbound.db e consegna tramite l'adattatore di canale.

Due file SQLite per sessione, ognuno con un singolo scrittore — nessuna contesa cross-mount, nessuna IPC, nessun piping su stdin. Canali e provider alternativi si auto-registrano all'avvio; il trunk contiene il registro e il bridge Chat SDK, mentre gli adattatori stessi sono installati come skill per fork.

Per la descrizione completa dell'architettura vedi docs/architecture.md; per il modello di isolamento a tre livelli vedi docs/isolation-model.md.

File chiave:

• src/index.ts — punto di ingresso: init DB, adattatori di canale, polling di consegna, sweep
• src/router.ts — instradamento in ingresso: gruppo di messaggistica → gruppo di agenti → sessione → inbound.db
• src/delivery.ts — interroga outbound.db, consegna tramite adattatore, gestisce azioni di sistema
• src/host-sweep.ts — sweep ogni 60s: rilevamento sessioni stale, risveglio per messaggi in scadenza, ricorrenza
• src/session-manager.ts — risolve le sessioni, apre inbound.db / outbound.db
• src/container-runner.ts — avvia contenitori per gruppo di agenti, iniezione credenziali OneCLI
• src/db/ — database centrale (utenti, ruoli, gruppi di agenti, gruppi di messaggistica, cablaggio, migrazioni)
• src/channels/ — infrastruttura adattatori di canale (adattatori installati tramite skill /add-<canale>)
• src/providers/ — configurazione provider lato host (claude preinstallato; altri tramite skill)
• container/agent-runner/ — agente-runner Bun: ciclo di polling, strumenti MCP, astrazione provider
• groups/<cartella>/ — filesystem per gruppo di agenti (CLAUDE.md, skill, configurazione contenitore)

FAQ

Perché Docker?

Docker offre supporto multipiattaforma (macOS, Linux e Windows tramite WSL2) e un ecosistema maturo.

Posso eseguirlo su Linux o Windows?

Sì. Docker è il runtime predefinito e funziona su macOS, Linux e Windows (tramite WSL2). Basta eseguire bash nanoclaw.sh.

È sicuro?

Gli agenti girano in contenitori, non dietro a controlli di permessi a livello applicativo. Possono accedere solo a directory montate esplicitamente. Le credenziali non entrano mai nel contenitore — le richieste API in uscita passano attraverso OneCLI Agent Vault, che inietta l'autenticazione a livello proxy e supporta limiti di frequenza e politiche di accesso. Dovresti comunque rivedere cosa stai eseguendo, ma la base di codice è abbastanza piccola da permetterlo davvero. Vedi la documentazione sulla sicurezza per il modello di sicurezza completo.

Perché nessun file di configurazione?

Non vogliamo proliferazione di configurazioni. Ogni utente dovrebbe personalizzare NanoClaw in modo che il codice faccia esattamente ciò che vuole, piuttosto che configurare un sistema generico. Se preferisci avere file di configurazione, puoi dire a Claude di aggiungerli.

Posso usare modelli di terze parti o open-source?

Sì. Il percorso supportato è /add-opencode (OpenRouter, OpenAI, Google, DeepSeek e altro tramite configurazione OpenCode) oppure /add-ollama-provider (modelli locali open-weight tramite Ollama). Entrambi sono configurabili per gruppo di agenti, quindi agenti diversi possono girare su backend differenti nella stessa installazione.

Per esperimenti singoli, qualsiasi endpoint compatibile con l'API Claude funziona anche tramite .env:

ANTHROPIC_BASE_URL=https://tuo-endpoint-api.com
ANTHROPIC_AUTH_TOKEN=il-tuo-token

Come faccio a fare debug di problemi?

Chiedi a Claude Code. "Perché lo scheduler non sta girando?" "Cosa c'è nei log recenti?" "Perché questo messaggio non ha ricevuto risposta?" Questo è l'approccio AI-nativo che sta alla base di NanoClaw.

Perché l'installazione non funziona per me?

Se un passaggio fallisce, nanoclaw.sh passa a Claude Code per diagnosticare e riprendere. Se non si risolve, esegui claude, poi /debug. Se Claude identifica un problema che probabilmente colpisce altri utenti, apri una PR sul relativo passo di installazione o skill.

Come disinstallo NanoClaw?

bash nanoclaw.sh --uninstall

Ogni installazione è taggata con un ID per checkout, quindi il disinstallatore rimuove solo ciò che appartiene a quella copia: il servizio in background, i contenitori e l'immagine, i dati dell'app e i log, i file dei tuoi agenti e gli agenti OneCLI di questa copia. Le cose condivise — l'app OneCLI e le tue credenziali, altre copie di NanoClaw sulla macchina — vengono lasciate intatte. Mostra esattamente cosa ha trovato e chiede conferma per ogni gruppo; nulla viene cancellato finché non dici di sì. Usa --dry-run per vedere l'anteprima senza modificare nulla, oppure --yes per saltare i prompt. Il tuo .env viene salvato prima della rimozione. Per finire, elimina la cartella del checkout.

Quali modifiche verranno accettate nella base di codice?

Solo correzioni di sicurezza, bug fix e miglioramenti chiari verranno accettati nella configurazione base. Tutto qui.

Tutto il resto (nuove capacità, compatibilità OS, supporto hardware, miglioramenti) dovrebbe essere contribuito come skill: codice di canali e provider sui rami del registro channels/providers, tutto il resto come skill autonoma. Vedi docs/customizing.md e CONTRIBUTING.md.

Questo mantiene il sistema base minimale e permette a ogni utente di personalizzare la propria installazione senza ereditare funzionalità indesiderate.

Community

Domande? Idee? Unisciti al Discord.

Changelog

Vedi CHANGELOG.md per modifiche sostanziali, oppure la cronologia completa delle release sul sito di documentazione.

Licenza

MIT