NanoClaw with Venice | Venice API Docs

NanoClaw è un assistente AI leggero e self-hosted che funziona su WhatsApp e Telegram. Questo fork aggiunge il supporto a Venice AI, in modo che tutto funzioni privatamente senza un abbonamento Anthropic.

Paga per token

Nessun abbonamento. Paghi solo per ciò che usi

Inferenza privata

Zero data retention sui server di Venice

Isolamento Docker

Ogni chat viene eseguita nel suo container sicuro

Perché Venice AI?

Venice è una piattaforma AI privacy-first. Non memorizza né registra alcun prompt o risposta sui propri server: le tue conversazioni esistono solo sul tuo dispositivo. Le richieste sono cifrate end-to-end tramite il loro proxy verso provider GPU decentralizzati, con zero data retention. Questo significa che le conversazioni con il tuo assistente AI rimangono private, anche nei confronti di Venice stessa. Venice fornisce accesso anonimizzato a modelli frontier (Claude Opus, Claude Sonnet) e accesso completamente privato a modelli open-source (GLM, Qwen) tramite una singola API: passa dall’uno all’altro in qualsiasi momento.

	Venice AI	Provider AI tradizionali
Data retention	Nessuna — zero log	Sì
Privacy del prompt	Cifrato, mai memorizzato	Memorizzato sui server del provider
Modelli open-source	Sì (GLM, Qwen e altri)	No
Modelli frontier	Claude, GPT e altri — in modo anonimo	Solo tramite abbonamenti diretti
Prezzi	Pay-per-token, nessun abbonamento. Oppure metti in staking DIEM per crediti giornalieri rinnovabili	Abbonamenti da 20–200$/mese o API pay-per-token
Inferenza non censurata	Sì (modelli open-source)	No

Perché NanoClaw?

NanoClaw è un’alternativa pulita e minimale a piattaforme più grandi come OpenClaw. È progettato per una sola persona che gestisce un solo bot.

	NanoClaw (Venice)	OpenClaw
Codebase	~2.000 righe, una manciata di file	~500.000 righe, 53 file di configurazione
Dipendenze	~15 pacchetti	70+ pacchetti
Modello di sicurezza	Isolamento container Docker a livello OS	Allowlist e codici di accoppiamento a livello applicativo
Isolamento per gruppo	Ogni gruppo ha il proprio container, filesystem e memoria	Processo condiviso, memoria condivisa
Setup	Una procedura guidata (`/setup`), ~10 minuti	Configurazione manuale multi-step
Provider AI	Venice AI (privato, nessun abbonamento)	Anthropic (richiede API key o abbonamento)
Personalizzazione	Modifica direttamente il codice — è abbastanza piccolo da leggere	File di configurazione e plugin
Utente target	Una persona, un bot	Piattaforma multi-utente

Cosa ottieni

Assistente AI personale su Telegram e/o WhatsApp
Alimentato da Venice AI — nessun account Anthropic necessario
Il bot gira in un container Docker isolato (sandboxed, non può accedere al tuo sistema)
Cambio di modello — di’ al bot “switch to zai-org-glm-5” o “use opus” in qualsiasi momento
Task pianificati — imposta promemoria, task ricorrenti
Ricerca web e browsing integrati
Formattazione Markdown nei messaggi Telegram

Prerequisiti

Node.js 20+

Verifica con node --version

Docker

Installa e aprilo una volta in modo che sia in esecuzione

Claude Code CLI

Verifica con claude --version

Venice API Key

Generala dal tuo account Venice

Per Telegram (consigliato per chi inizia):

Apri Telegram e cerca @BotFather
Invia /newbot e segui le istruzioni
Salva il token che BotFather ti fornisce (è simile a 123456789:ABCdef...)

Per WhatsApp — usa un numero virtuale, NON il tuo personale:NanoClaw si connette come dispositivo collegato al tuo numero WhatsApp. Questo significa che l’agente può vedere ogni messaggio in entrata e in uscita — tutte le tue conversazioni personali, chat di gruppo, foto, tutto. Il telefono continua a funzionare normalmente, ma il bot ha piena visibilità sull’intero account WhatsApp.Usa invece un numero di telefono virtuale. Queste app ti forniscono un secondo numero che puoi dedicare interamente al bot:

App	Prezzo	Note
Hushed	~5$/mese	Affidabile, funziona bene per la verifica WhatsApp
Burner	~5$/mese	Simile a Hushed, numeri usa e getta
Google Voice	Gratis	Solo USA, potrebbe non funzionare per la verifica WhatsApp in tutti i casi

Come configurarlo:

Ottieni un numero virtuale da una delle app sopra
Installa WhatsApp su un secondo dispositivo (vecchio telefono, tablet o emulatore) usando quel numero virtuale
Durante il setup di NanoClaw, scansiona il QR code con quel secondo dispositivo — non con il tuo telefono personale

Setup

Il setup richiede circa 10 minuti. Hai bisogno di una sola finestra di Terminal.

Clona e installa

Apri Terminal ed esegui:

git clone https://github.com/lorenzovenice/nanoclaw-venice.git
cd nanoclaw-venice
npm install

Attendi che npm install termini senza errori.

Avvia Claude Code con Venice

Sostituisci your-key con la tua Venice API key ed esegui:

VENICE_API_KEY=your-key npm run venice

Questo avvia il proxy Venice e lancia Claude Code attraverso di esso con un singolo comando.

Claude Code usa di default GLM 5 (zai-org-glm-5) per mantenere bassi i costi di setup. Dopo il setup, digita /model in Claude Code per passare a claude-sonnet-4-6 o claude-opus-4-6 per le migliori prestazioni.

Se ti viene chiesto “Do you want to use this API key?” — seleziona Yes.

Esegui la procedura guidata di setup

Nel tuo terminale Claude Code, digita:

/setup

La procedura guidata ti accompagna in:

Bootstrap — verifica Node.js e dipendenze
Venice API key — valida e salva la tua chiave
Scelta del canale — scegli WhatsApp, Telegram o entrambi
Build del container — costruisce il container Docker (richiede qualche minuto la prima volta)
Autenticazione WhatsApp — scansiona il QR code con il tuo telefono (se applicabile)
Setup Telegram — invia un messaggio al tuo bot per fargli rilevare la tua chat
Trigger word — il prefisso che attiva il bot (default: @Andy)
Directory da montare — scegli “No” per ora (puoi aggiungere l’accesso ai file in seguito)
Avvio dei servizi — NanoClaw e il proxy Venice si avviano entrambi come servizi in background

La procedura guidata installa due servizi in background:

NanoClaw — il bot vero e proprio
Venice proxy — un piccolo server locale (localhost:4001) che fa da traduttore tra Claude Code e Venice AI

Entrambi si avviano automaticamente all’avvio del sistema e si riavviano da soli in caso di crash.

Se la procedura guidata si ferma tra un passo e l’altro, digita “continue” o “next step” per farla proseguire.

Inizia a chattare

Una volta completato il setup, apri la tua chat (Telegram o WhatsApp) e invia:

@Andy hello, are you there?

Il bot dovrebbe rispondere in pochi secondi. Nel tuo canale principale puoi scrivere normalmente senza il prefisso @Andy.Puoi ora chiudere la finestra del terminale. Tutto gira come servizi in background e si avvia automaticamente all’accensione del computer.

Come funziona

NanoClaw ha due livelli:

Livello	Cosa fa
Claude Code CLI	Strumento di amministrazione per setup, debug e personalizzazione
Il Bot	L’AI nella tua chat, in esecuzione all’interno di un container Docker isolato

Per aprire Claude Code in qualsiasi momento:

cd nanoclaw-venice
ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude

Usalo per eseguire /setup, /debug, /customize o per modificare il comportamento del bot.

Modelli

Contesto	Modello di default	Come cambiarlo
Bot (in chat)	`claude-sonnet-4-6`	Di’ al bot: “switch to opus” o “use zai-org-glm-5”
Claude Code CLI	`zai-org-glm-5` (GLM 5)	Usa `/model` in Claude Code o `claude --model <name>`

La CLI usa di default GLM 5 per mantenere bassi i costi di setup. Dopo il setup, passa a claude-sonnet-4-6 o claude-opus-4-6 per le migliori prestazioni.

Consulta il catalogo dei modelli per tutti i modelli Venice disponibili.

Troubleshooting

Il proxy non è in esecuzione

Il proxy Venice gira come servizio in background e si riavvia automaticamente. Se non funziona:macOS:

# Verifica se è in esecuzione
launchctl list | grep venice-proxy

# Riavvialo
launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy

# Controlla i log
tail -f ~/nanoclaw-venice/logs/venice-proxy.log

Linux:

# Verifica se è in esecuzione
systemctl --user status nanoclaw-venice-proxy

# Riavvialo
systemctl --user restart nanoclaw-venice-proxy

# Controlla i log
tail -f ~/nanoclaw-venice/logs/venice-proxy.log

Significa che Claude Code non riesce a connettersi al proxy Venice.

Verifica che il proxy sia in esecuzione. Consulta il passo di troubleshooting precedente.
Assicurati di essere nella cartella corretta. Esegui sempre prima cd nanoclaw-venice.

Riparti da zero: Chiudi tutti i terminali ed esegui:

cd nanoclaw-venice
ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude

Errori del modello ('model does not exist')

Riavvia il proxy e il bot:macOS:

# Riavvia il proxy
launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy

# Riavvia il bot
launchctl kickstart -k gui/$(id -u)/com.nanoclaw

Linux:

# Riavvia il proxy
systemctl --user restart nanoclaw-venice-proxy

# Riavvia il bot
systemctl --user restart nanoclaw

Controlla i modelli disponibili nel catalogo dei modelli.

Il bot non risponde ai messaggi

Esegui questi passi nell’ordine:

Controlla la tua trigger word. Assicurati di usare il prefisso corretto (es. @Andy hello).
Verifica che Docker sia in esecuzione. Esegui docker info — se restituisce errore, apri Docker Desktop.
Verifica che il proxy sia in esecuzione. Vedi “Il proxy non è in esecuzione” sopra.
Controlla i log: tail -f logs/nanoclaw.log nella cartella del progetto.
Controlla i log del container. Apri la cartella nanoclaw-venice/groups/main/logs/. Apri il file più recente che inizia con container-.
Riavvia tutto: Riavvia sia il proxy che il bot (vedi sopra).

La build del container fallisce durante il setup

Assicurati che Docker Desktop sia aperto e in esecuzione. Attendi 10 secondi affinché Docker sia completamente avviato, poi digita continue nella procedura guidata per riprovare.

WhatsApp disconnesso

La tua sessione WhatsApp può scadere. Per riconnetterti:

cd nanoclaw-venice
npm run auth

Scansiona il QR code con WhatsApp (Impostazioni → Dispositivi collegati → Collega un dispositivo), poi riavvia il bot:

macOS: launchctl kickstart -k gui/$(id -u)/com.nanoclaw
Linux: systemctl --user restart nanoclaw

Avanzato

Dare al bot accesso ai file sul tuo computer

Di default, il bot è completamente isolato dal tuo computer — può vedere solo la propria memoria e la cronologia delle conversazioni.

Durante il setup: Quando ti viene chiesto dell’accesso alle directory, scegli “Yes”
Dopo il setup: Esegui /customize in Claude Code

Avviare/arrestare manualmente il bot

NanoClaw esegue due servizi in background che si avviano automaticamente all’avvio del sistema.macOS:

Azione	Comando
Avvia bot	`launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist`
Arresta bot	`launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist`
Riavvia bot	`launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
Avvia proxy	`launchctl load ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist`
Arresta proxy	`launchctl unload ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist`
Riavvia proxy	`launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy`

Linux:

Azione	Comando
Avvia bot	`systemctl --user start nanoclaw`
Arresta bot	`systemctl --user stop nanoclaw`
Riavvia bot	`systemctl --user restart nanoclaw`
Avvia proxy	`systemctl --user start nanoclaw-venice-proxy`
Arresta proxy	`systemctl --user stop nanoclaw-venice-proxy`
Riavvia proxy	`systemctl --user restart nanoclaw-venice-proxy`

Usare Claude Code tramite Venice (senza bot)

Se vuoi semplicemente usare Claude Code con Venice e non ti servono WhatsApp/Telegram, il servizio proxy deve essere in esecuzione. Se hai già eseguito /setup, è già in esecuzione come servizio in background.

cd nanoclaw-venice
ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude

Suggerimento: Aggiungi questo al tuo ~/.zshrc (o ~/.bashrc) in modo da poter passare rapidamente qualsiasi terminale a Venice:

alias venice='export ANTHROPIC_BASE_URL=http://localhost:4001 && export ANTHROPIC_API_KEY=venice-proxy && echo "Using Venice API"'
alias anthropic='unset ANTHROPIC_BASE_URL && unset ANTHROPIC_API_KEY && echo "Using Anthropic API"'

Poi basta digitare venice in qualsiasi terminale prima di eseguire claude per usare Venice, oppure anthropic per tornare indietro.

Eseguire più bot

Puoi eseguire più bot NanoClaw sulla stessa macchina (es. uno per uso personale e uno per un team). Basta clonare il repository in una cartella diversa ed eseguire di nuovo il setup. Nota: condividono la stessa immagine Docker, quindi ricostruirne una influisce su tutte.

Comandi per sviluppatori

Per chi vuole modificare il codice di NanoClaw:

npm run dev          # Avvia proxy + NanoClaw con hot reload
npm run proxy        # Avvia solo il proxy Venice
npm run build        # Compila TypeScript
npm test             # Esegue i test
./container/build.sh # Ricostruisce il container dell'agente

Architettura

Tu (WhatsApp/Telegram)
        ↓
   NanoClaw (Node.js)
        ↓
   Docker Container (sandbox isolato)
        ↓
   Venice Proxy (localhost:4001)
        ↓
   api.venice.ai (inferenza privata)

File	Scopo
`proxy/venice-proxy.ts`	Traduce il formato Anthropic in formato OpenAI per Venice
`src/index.ts`	Orchestratore principale — loop dei messaggi, invocazione dell’agente
`src/channels/whatsapp.ts`	Connessione WhatsApp tramite baileys
`src/channels/telegram.ts`	Bot Telegram tramite grammy
`src/container-runner.ts`	Crea container isolati per l’agente

FAQ

Perché ho bisogno di un proxy?

Il Claude Agent SDK parla il formato di messaggi Anthropic. Venice parla il formato OpenAI. Il proxy traduce tra i due in modo che tutto funzioni senza modificare l’SDK.

Posso usare modelli open-source?

Sì. Venice ospita molti modelli. Di’ al bot “switch to zai-org-glm-5” o qualsiasi ID di modello Venice. Vedi il catalogo dei modelli.

È sicuro?

Gli agenti girano in container Docker con un vero isolamento a livello OS. La Venice API key viene passata tramite stdin, mai scritta su disco all’interno dei container. Ogni gruppo ha il proprio ambiente isolato.

Mi serve un abbonamento Anthropic?

No. Tutto passa attraverso Venice AI. Ti serve solo una Venice API key.

Posso usarlo su un server?

Sì. Funziona su qualsiasi macchina Linux con Docker. Usa il servizio systemd per l’auto-avvio al boot.

Risorse

Repository NanoClaw Venice

Codice sorgente e README completo

NanoClaw originale

Progetto upstream di qwibitai

Catalogo modelli Venice

Sfoglia i modelli disponibili

Privacy di Venice

Come Venice protegge i tuoi dati

Guides

Getting Started

Text & Chat

Image & Video

Agents & Integrations

Agent Tooling

Coding Tools

SDKs & Frameworks

Projects

NanoClaw

Paga per token

Inferenza privata

Isolamento Docker

Perché Venice AI?

Perché NanoClaw?

Cosa ottieni

Prerequisiti

Node.js 20+

Docker

Claude Code CLI

Venice API Key

Setup

Come funziona

Modelli

Troubleshooting

Avanzato

Architettura

FAQ

Risorse

Repository NanoClaw Venice

NanoClaw originale

Catalogo modelli Venice

Privacy di Venice

Paga per token

Inferenza privata

Isolamento Docker

​Perché Venice AI?

​Perché NanoClaw?

​Cosa ottieni

​Prerequisiti

Node.js 20+

Docker

Claude Code CLI

Venice API Key

​Setup

​Come funziona

​Modelli

​Troubleshooting

​Avanzato

​Architettura

​FAQ

​Risorse

Repository NanoClaw Venice

NanoClaw originale

Catalogo modelli Venice

Privacy di Venice

Perché Venice AI?

Perché NanoClaw?

Cosa ottieni

Prerequisiti

Setup

Come funziona

Modelli

Troubleshooting

Avanzato

Architettura

FAQ

Risorse