> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# NanoClaw

> Distribuisci NanoClaw, un assistente AI personale leggero per WhatsApp e Telegram, su Venice per chat e generazione di media privata e senza censura.

[NanoClaw](https://github.com/qwibitai/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.

<CardGroup cols={3}>
  <Card title="Paga per token" icon="coins">
    Nessun abbonamento. Paghi solo per ciò che usi
  </Card>

  <Card title="Inferenza privata" icon="shield-halved">
    Zero data retention sui server di Venice
  </Card>

  <Card title="Isolamento Docker" icon="cube">
    Ogni chat viene eseguita nel suo container sicuro
  </Card>
</CardGroup>

***

## Perché Venice AI?

[Venice](https://venice.ai) è una piattaforma AI privacy-first. [Non memorizza né registra alcun prompt o risposta](https://venice.ai/privacy) 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](https://venice.ai/lp/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

<CardGroup cols={2}>
  <Card title="Node.js 20+" icon="node-js" href="https://nodejs.org/">
    Verifica con `node --version`
  </Card>

  <Card title="Docker" icon="docker" href="https://docker.com/products/docker-desktop">
    Installa e aprilo una volta in modo che sia in esecuzione
  </Card>

  <Card title="Claude Code CLI" icon="terminal" href="https://claude.ai/download">
    Verifica con `claude --version`
  </Card>

  <Card title="Venice API Key" icon="key" href="https://venice.ai/settings/api">
    Generala dal tuo account Venice
  </Card>
</CardGroup>

**Per Telegram** (consigliato per chi inizia):

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

<Warning>
  **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](https://hushed.com)             | \~5\$/mese | Affidabile, funziona bene per la verifica WhatsApp                         |
  | [Burner](https://www.burnerapp.com)      | \~5\$/mese | Simile a Hushed, numeri usa e getta                                        |
  | [Google Voice](https://voice.google.com) | Gratis     | Solo USA, potrebbe non funzionare per la verifica WhatsApp in tutti i casi |

  **Come configurarlo:**

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

***

## Setup

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

<Steps>
  <Step title="Clona e installa">
    Apri Terminal ed esegui:

    ```bash theme={"system"}
    git clone https://github.com/lorenzovenice/nanoclaw-venice.git
    cd nanoclaw-venice
    npm install
    ```

    Attendi che `npm install` termini senza errori.
  </Step>

  <Step title="Avvia Claude Code con Venice">
    Sostituisci `your-key` con la tua Venice API key ed esegui:

    ```bash theme={"system"}
    VENICE_API_KEY=your-key npm run venice
    ```

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

    <Note>
      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.
    </Note>

    Se ti viene chiesto "Do you want to use this API key?" — seleziona **Yes**.
  </Step>

  <Step title="Esegui la procedura guidata di setup">
    Nel tuo terminale Claude Code, digita:

    ```
    /setup
    ```

    La procedura guidata ti accompagna in:

    1. **Bootstrap** — verifica Node.js e dipendenze
    2. **Venice API key** — valida e salva la tua chiave
    3. **Scelta del canale** — scegli WhatsApp, Telegram o entrambi
    4. **Build del container** — costruisce il container Docker (richiede qualche minuto la prima volta)
    5. **Autenticazione WhatsApp** — scansiona il QR code con il tuo telefono (se applicabile)
    6. **Setup Telegram** — invia un messaggio al tuo bot per fargli rilevare la tua chat
    7. **Trigger word** — il prefisso che attiva il bot (default: `@Andy`)
    8. **Directory da montare** — scegli "No" per ora (puoi aggiungere l'accesso ai file in seguito)
    9. **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.

    <Note>
      Se la procedura guidata si ferma tra un passo e l'altro, digita "continue" o "next step" per farla proseguire.
    </Note>
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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:

```bash theme={"system"}
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>` |

<Tip>
  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.
</Tip>

Consulta il [catalogo dei modelli](/models/text) per tutti i modelli Venice disponibili.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Il proxy non è in esecuzione">
    Il proxy Venice gira come servizio in background e si riavvia automaticamente. Se non funziona:

    **macOS:**

    ```bash theme={"system"}
    # 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:**

    ```bash theme={"system"}
    # 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
    ```
  </Accordion>

  <Accordion title="Claude Code mostra errore 403 o 'Please run /login'">
    Significa che Claude Code non riesce a connettersi al proxy Venice.

    1. **Verifica che il proxy sia in esecuzione.** Consulta il passo di troubleshooting precedente.
    2. **Assicurati di essere nella cartella corretta.** Esegui sempre prima `cd nanoclaw-venice`.
    3. **Riparti da zero:** Chiudi tutti i terminali ed esegui:
       ```bash theme={"system"}
       cd nanoclaw-venice
       ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
       ```
  </Accordion>

  <Accordion title="Errori del modello ('model does not exist')">
    Riavvia il proxy e il bot:

    **macOS:**

    ```bash theme={"system"}
    # 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:**

    ```bash theme={"system"}
    # Riavvia il proxy
    systemctl --user restart nanoclaw-venice-proxy

    # Riavvia il bot
    systemctl --user restart nanoclaw
    ```

    Controlla i modelli disponibili nel [catalogo dei modelli](/models/text).
  </Accordion>

  <Accordion title="Il bot non risponde ai messaggi">
    Esegui questi passi nell'ordine:

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

  <Accordion title="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.
  </Accordion>

  <Accordion title="WhatsApp disconnesso">
    La tua sessione WhatsApp può scadere. Per riconnetterti:

    ```bash theme={"system"}
    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`
  </Accordion>
</AccordionGroup>

***

## Avanzato

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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` |
  </Accordion>

  <Accordion title="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.

    ```bash theme={"system"}
    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:

    ```bash theme={"system"}
    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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Comandi per sviluppatori">
    Per chi vuole modificare il codice di NanoClaw:

    ```bash theme={"system"}
    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
    ```
  </Accordion>
</AccordionGroup>

***

## 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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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](/models/text).
  </Accordion>

  <Accordion title="È 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.
  </Accordion>

  <Accordion title="Mi serve un abbonamento Anthropic?">
    No. Tutto passa attraverso Venice AI. Ti serve solo una Venice API key.
  </Accordion>

  <Accordion title="Posso usarlo su un server?">
    Sì. Funziona su qualsiasi macchina Linux con Docker. Usa il servizio systemd per l'auto-avvio al boot.
  </Accordion>
</AccordionGroup>

***

## Risorse

<CardGroup cols={2}>
  <Card title="Repository NanoClaw Venice" icon="github" href="https://github.com/lorenzovenice/nanoclaw-venice">
    Codice sorgente e README completo
  </Card>

  <Card title="NanoClaw originale" icon="github" href="https://github.com/qwibitai/nanoclaw">
    Progetto upstream di qwibitai
  </Card>

  <Card title="Catalogo modelli Venice" icon="list" href="/models/text">
    Sfoglia i modelli disponibili
  </Card>

  <Card title="Privacy di Venice" icon="shield-halved" href="/overview/privacy">
    Come Venice protegge i tuoi dati
  </Card>
</CardGroup>