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

> Deployen Sie NanoClaw, einen leichten KI-Assistenten für WhatsApp und Telegram, auf Venice — für privates, unzensiertes Chatten und Mediengenerierung.

[NanoClaw](https://github.com/qwibitai/nanoclaw) ist ein schlanker, selbstgehosteter KI-Assistent, der auf WhatsApp und Telegram läuft. Dieser Fork ergänzt Venice-AI-Support, sodass alles privat ohne Anthropic-Abo läuft.

<CardGroup cols={3}>
  <Card title="Pay Per Token" icon="coins">
    Kein Abo. Zahle nur, was du nutzt
  </Card>

  <Card title="Private Inferenz" icon="shield-halved">
    Zero Data Retention auf Venice-Servern
  </Card>

  <Card title="Docker-Isolation" icon="cube">
    Jeder Chat läuft in seinem eigenen sicheren Container
  </Card>
</CardGroup>

***

## Warum Venice AI?

[Venice](https://venice.ai) ist eine Privacy-First-KI-Plattform. Sie [speichert oder loggt keine Prompts oder Antworten](https://venice.ai/privacy) auf ihren Servern – deine Gespräche existieren nur auf deinem Gerät. Requests werden Ende-zu-Ende-verschlüsselt über ihren Proxy zu dezentralen GPU-Providern geleitet, mit Zero Data Retention. Das heißt, deine Assistant-Gespräche bleiben privat – selbst gegenüber Venice.

Venice bietet anonymisierten Zugriff auf Frontier-Modelle (Claude Opus, Claude Sonnet) und vollständig privaten Zugriff auf Open-Source-Modelle (GLM, Qwen) über eine einzige API – jederzeit umschaltbar.

|                          | **Venice AI**                                                                                            | **Klassische KI-Provider**                 |
| ------------------------ | -------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| **Datenaufbewahrung**    | Keine – null Logs                                                                                        | Ja                                         |
| **Prompt-Privacy**       | Verschlüsselt, nie gespeichert                                                                           | Auf Provider-Servern gespeichert           |
| **Open-Source-Modelle**  | Ja (GLM, Qwen und andere)                                                                                | Nein                                       |
| **Frontier-Modelle**     | Claude, GPT und andere – anonym                                                                          | Nur über Direkt-Abos                       |
| **Preise**               | Pay-per-Token, kein Abo. Oder [DIEM](https://venice.ai/lp/diem) staken für täglich aufgefrischte Credits | \$20–200/Monat Abos oder Pay-per-Token-API |
| **Unzensierte Inferenz** | Ja (Open-Source-Modelle)                                                                                 | Nein                                       |

***

## Warum NanoClaw?

NanoClaw ist eine schlanke, minimale Alternative zu größeren Plattformen wie OpenClaw. Es ist für eine Person mit einem Bot ausgelegt.

|                          | **NanoClaw (Venice)**                                        | **OpenClaw**                                   |
| ------------------------ | ------------------------------------------------------------ | ---------------------------------------------- |
| **Codebase**             | \~2.000 Zeilen, eine Handvoll Dateien                        | \~500.000 Zeilen, 53 Konfigurationsdateien     |
| **Abhängigkeiten**       | \~15 Pakete                                                  | 70+ Pakete                                     |
| **Sicherheitsmodell**    | OS-level-Docker-Container-Isolation                          | Application-level Allowlists und Pairing-Codes |
| **Per-Gruppe-Isolation** | Jede Gruppe bekommt eigenen Container, Filesystem und Memory | Geteilter Prozess, geteiltes Memory            |
| **Setup**                | Ein Wizard (`/setup`), \~10 Minuten                          | Manuelle Mehrschritt-Konfiguration             |
| **KI-Provider**          | Venice AI (privat, kein Abo)                                 | Anthropic (API-Key oder Abo nötig)             |
| **Anpassbarkeit**        | Code direkt anpassen – klein genug zum Lesen                 | Konfigurationsdateien und Plugins              |
| **Zielnutzer**           | Eine Person, ein Bot                                         | Multi-User-Plattform                           |

***

## Was du bekommst

* Persönlichen KI-Assistenten auf **Telegram** und/oder **WhatsApp**
* Betrieben mit **Venice AI** – kein Anthropic-Konto nötig
* Bot läuft in einem **isolierten Docker-Container** (sandboxed, kein Systemzugriff)
* **Modell-Wechsel** – sag dem Bot „switch to zai-org-glm-5" oder „use opus", jederzeit
* **Geplante Aufgaben** – Erinnerungen, wiederkehrende Tasks
* **Websuche und Browsing** eingebaut
* **Markdown-Formatierung** in Telegram-Nachrichten

***

## Voraussetzungen

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

  <Card title="Docker" icon="docker" href="https://docker.com/products/docker-desktop">
    Installieren und einmal öffnen, damit es läuft
  </Card>

  <Card title="Claude Code CLI" icon="terminal" href="https://claude.ai/download">
    Mit `claude --version` prüfen
  </Card>

  <Card title="Venice API-Schlüssel" icon="key" href="https://venice.ai/settings/api">
    Aus deinem Venice-Konto generieren
  </Card>
</CardGroup>

**Für Telegram** (empfohlen für Erstnutzer):

1. Telegram öffnen und nach **@BotFather** suchen
2. `/newbot` senden und den Anweisungen folgen
3. Den Token, den BotFather dir gibt, speichern (sieht aus wie `123456789:ABCdef...`)

<Warning>
  **Für WhatsApp – verwende eine virtuelle Nummer, NICHT deine persönliche:**

  NanoClaw verbindet sich als verknüpftes Gerät mit deiner WhatsApp-Nummer. Das heißt, **der Agent sieht jede ein- und ausgehende Nachricht** – all deine persönlichen Gespräche, Gruppen-Chats, Fotos, alles. Dein Telefon funktioniert normal weiter, aber der Bot hat vollen Einblick in dein gesamtes WhatsApp-Konto.

  **Nimm stattdessen eine virtuelle Telefonnummer.** Diese Apps geben dir eine Zweitnummer, die du ausschließlich dem Bot widmen kannst:

  | App                                      | Preis       | Anmerkungen                                                           |
  | ---------------------------------------- | ----------- | --------------------------------------------------------------------- |
  | [Hushed](https://hushed.com)             | \~\$5/Monat | Zuverlässig, funktioniert gut für WhatsApp-Verifikation               |
  | [Burner](https://www.burnerapp.com)      | \~\$5/Monat | Ähnlich wie Hushed, Wegwerf-Nummern                                   |
  | [Google Voice](https://voice.google.com) | Kostenlos   | Nur USA, funktioniert nicht in allen Fällen für WhatsApp-Verifikation |

  **So richtest du es ein:**

  1. Hol dir eine virtuelle Nummer von einer der obigen Apps
  2. Installiere WhatsApp auf einem Zweitgerät (altes Handy, Tablet oder Emulator) mit dieser virtuellen Nummer
  3. Scanne im NanoClaw-Setup den QR-Code mit diesem Zweitgerät – nicht mit deinem persönlichen Handy
</Warning>

***

## Einrichtung

Das Setup dauert etwa 10 Minuten. Du brauchst nur **ein Terminal-Fenster**.

<Steps>
  <Step title="Klonen und installieren">
    Terminal öffnen und ausführen:

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

    Warte, bis `npm install` ohne Fehler durchläuft.
  </Step>

  <Step title="Claude Code mit Venice starten">
    Ersetze `your-key` durch deinen Venice API-Schlüssel und führe aus:

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

    Das startet den Venice-Proxy und Claude Code durch ihn in einem Befehl.

    <Note>
      Claude Code nutzt standardmäßig **GLM 5** (`zai-org-glm-5`), um die Setup-Kosten gering zu halten. Nach dem Setup in Claude Code `/model` eingeben, um auf `claude-sonnet-4-6` oder `claude-opus-4-6` für beste Performance umzustellen.
    </Note>

    Falls die Abfrage „Do you want to use this API key?" erscheint, wähle **Yes**.
  </Step>

  <Step title="Setup-Wizard ausführen">
    Tippe im Claude-Code-Terminal:

    ```
    /setup
    ```

    Der Wizard führt dich durch:

    1. **Bootstrap** – prüft Node.js und Abhängigkeiten
    2. **Venice API-Schlüssel** – validiert und speichert deinen Schlüssel
    3. **Kanal-Wahl** – WhatsApp, Telegram oder beides
    4. **Container-Build** – baut den Docker-Container (dauert beim ersten Mal ein paar Minuten)
    5. **WhatsApp-Auth** – QR-Code mit dem Telefon scannen (falls zutreffend)
    6. **Telegram-Setup** – sende eine Nachricht an deinen Bot, damit er deinen Chat erkennt
    7. **Trigger-Wort** – Präfix, das den Bot aktiviert (Default: `@Andy`)
    8. **Verzeichnisse mounten** – wähle vorerst „No" (Dateizugriff kannst du später ergänzen)
    9. **Services starten** – NanoClaw und der Venice-Proxy starten beide als Hintergrund-Services

    Der Setup-Wizard installiert zwei Hintergrund-Services:

    * **NanoClaw** – der Bot selbst
    * **Venice-Proxy** – ein kleiner lokaler Server (localhost:4001), der zwischen Claude Code und Venice AI übersetzt

    Beide starten automatisch beim Booten und starten sich selbst neu, wenn sie abstürzen.

    <Note>
      Wenn der Wizard zwischen Schritten stehen bleibt, tippe „continue" oder „next step", um ihn anzustupsen.
    </Note>
  </Step>

  <Step title="Loschatten">
    Sobald das Setup abgeschlossen ist, öffne deinen Chat (Telegram oder WhatsApp) und sende:

    ```
    @Andy hello, are you there?
    ```

    Der Bot sollte innerhalb von Sekunden antworten. In deinem Hauptkanal kannst du normal tippen, ohne `@Andy`-Präfix.

    **Du kannst das Terminal-Fenster jetzt schließen.** Alles läuft als Hintergrund-Service und startet automatisch beim Booten.
  </Step>
</Steps>

***

## Wie es funktioniert

NanoClaw hat zwei Ebenen:

| Ebene               | Aufgabe                                                       |
| ------------------- | ------------------------------------------------------------- |
| **Claude Code CLI** | Admin-Tool für Setup, Debugging und Anpassung                 |
| **Der Bot**         | KI in deinem Chat, läuft in einem isolierten Docker-Container |

Um Claude Code jederzeit zu öffnen:

```bash theme={"system"}
cd nanoclaw-venice
ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
```

Nutze es, um `/setup`, `/debug`, `/customize` auszuführen oder das Verhalten des Bots zu ändern.

***

## Modelle

| Kontext         | Standardmodell          | Wie wechseln                                                   |
| --------------- | ----------------------- | -------------------------------------------------------------- |
| Bot (im Chat)   | `claude-sonnet-4-6`     | Sag dem Bot: „switch to opus" oder „use zai-org-glm-5"         |
| Claude Code CLI | `zai-org-glm-5` (GLM 5) | `/model` in Claude Code verwenden oder `claude --model <name>` |

<Tip>
  Die CLI nutzt standardmäßig GLM 5, um Setup-Kosten gering zu halten. Nach dem Setup für beste Performance auf `claude-sonnet-4-6` oder `claude-opus-4-6` umstellen.
</Tip>

Alle verfügbaren Venice-Modelle siehe [Modellkatalog](/models/text).

***

## Fehlerbehebung

<AccordionGroup>
  <Accordion title="Der Proxy läuft nicht">
    Der Venice-Proxy läuft als Hintergrund-Service und startet sich automatisch neu. Wenn er nicht funktioniert:

    **macOS:**

    ```bash theme={"system"}
    # Prüfen, ob er läuft
    launchctl list | grep venice-proxy

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

    # Logs prüfen
    tail -f ~/nanoclaw-venice/logs/venice-proxy.log
    ```

    **Linux:**

    ```bash theme={"system"}
    # Prüfen, ob er läuft
    systemctl --user status nanoclaw-venice-proxy

    # Neu starten
    systemctl --user restart nanoclaw-venice-proxy

    # Logs prüfen
    tail -f ~/nanoclaw-venice/logs/venice-proxy.log
    ```
  </Accordion>

  <Accordion title="Claude Code zeigt 403-Fehler oder Please run /login">
    Das bedeutet, Claude Code kann sich nicht mit dem Venice-Proxy verbinden.

    1. **Prüfen, ob der Proxy läuft.** Siehe Schritt oben.
    2. **Sicherstellen, dass du im richtigen Ordner bist.** Immer zuerst `cd nanoclaw-venice`.
    3. **Frisch starten:** Schließe alle Terminals und führe aus:
       ```bash theme={"system"}
       cd nanoclaw-venice
       ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
       ```
  </Accordion>

  <Accordion title="Modellfehler (model does not exist)">
    Proxy und Bot neu starten:

    **macOS:**

    ```bash theme={"system"}
    # Proxy neu starten
    launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy

    # Bot neu starten
    launchctl kickstart -k gui/$(id -u)/com.nanoclaw
    ```

    **Linux:**

    ```bash theme={"system"}
    # Proxy neu starten
    systemctl --user restart nanoclaw-venice-proxy

    # Bot neu starten
    systemctl --user restart nanoclaw
    ```

    Verfügbare Modelle im [Modellkatalog](/models/text) prüfen.
  </Accordion>

  <Accordion title="Bot reagiert nicht auf Nachrichten">
    Arbeite diese Schritte der Reihe nach ab:

    1. **Trigger-Wort prüfen.** Achte darauf, das richtige Präfix zu verwenden (z. B. `@Andy hello`).
    2. **Docker-Lauf prüfen.** `docker info` ausführen – wenn Fehler kommen, Docker Desktop öffnen.
    3. **Proxy-Lauf prüfen.** Siehe „Der Proxy läuft nicht" oben.
    4. **Logs prüfen:** Im Projektordner `tail -f logs/nanoclaw.log`.
    5. **Container-Logs prüfen.** Öffne den Ordner `nanoclaw-venice/groups/main/logs/`. Öffne die neueste Datei, die mit `container-` beginnt.
    6. **Alles neu starten:** Sowohl Proxy als auch Bot neu starten (siehe oben).
  </Accordion>

  <Accordion title="Container-Build schlägt während des Setups fehl">
    Stelle sicher, dass Docker Desktop geöffnet ist und läuft. Warte 10 Sekunden, bis Docker vollständig gestartet ist, dann tippe `continue` im Wizard, um es erneut zu versuchen.
  </Accordion>

  <Accordion title="WhatsApp getrennt">
    Deine WhatsApp-Session kann ablaufen. So verbindest du erneut:

    ```bash theme={"system"}
    cd nanoclaw-venice
    npm run auth
    ```

    Scanne den QR-Code mit WhatsApp (Settings → Linked Devices → Link a Device), dann Bot neu starten:

    * macOS: `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`
    * Linux: `systemctl --user restart nanoclaw`
  </Accordion>
</AccordionGroup>

***

## Fortgeschrittenes

<AccordionGroup>
  <Accordion title="Dem Bot Zugriff auf Dateien auf deinem Computer geben">
    Standardmäßig ist der Bot vollständig von deinem Computer abgeschottet – er sieht nur sein eigenes Memory und die Konversationshistorie.

    * **Während des Setups:** Wenn nach Verzeichniszugriff gefragt wird, wähle „Yes"
    * **Nach dem Setup:** In Claude Code `/customize` ausführen
  </Accordion>

  <Accordion title="Bot manuell starten/stoppen">
    NanoClaw läuft mit zwei Hintergrund-Services, die automatisch beim Booten starten.

    **macOS:**

    | Aktion            | Befehl                                                                    |
    | ----------------- | ------------------------------------------------------------------------- |
    | Bot starten       | `launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist`                |
    | Bot stoppen       | `launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist`              |
    | Bot neu starten   | `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`                        |
    | Proxy starten     | `launchctl load ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist`   |
    | Proxy stoppen     | `launchctl unload ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist` |
    | Proxy neu starten | `launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy`           |

    **Linux:**

    | Aktion            | Befehl                                           |
    | ----------------- | ------------------------------------------------ |
    | Bot starten       | `systemctl --user start nanoclaw`                |
    | Bot stoppen       | `systemctl --user stop nanoclaw`                 |
    | Bot neu starten   | `systemctl --user restart nanoclaw`              |
    | Proxy starten     | `systemctl --user start nanoclaw-venice-proxy`   |
    | Proxy stoppen     | `systemctl --user stop nanoclaw-venice-proxy`    |
    | Proxy neu starten | `systemctl --user restart nanoclaw-venice-proxy` |
  </Accordion>

  <Accordion title="Claude Code über Venice nutzen (ohne Bot)">
    Wenn du nur Claude Code mit Venice willst und kein WhatsApp/Telegram brauchst, muss der Proxy-Service laufen. Wenn du `/setup` ausgeführt hast, läuft er bereits als Hintergrund-Service.

    ```bash theme={"system"}
    cd nanoclaw-venice
    ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
    ```

    **Tipp:** Füge dies zu deiner `~/.zshrc` (oder `~/.bashrc`) hinzu, um jedes Terminal schnell auf Venice umzuschalten:

    ```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"'
    ```

    Dann in jedem Terminal vor `claude` einfach `venice` tippen, um Venice zu nutzen, oder `anthropic` zum Zurückwechseln.
  </Accordion>

  <Accordion title="Mehrere Bots betreiben">
    Du kannst mehrere NanoClaw-Bots auf derselben Maschine betreiben (z. B. einen persönlichen und einen für ein Team). Klon das Repo einfach in einen anderen Ordner und führe das Setup erneut aus. Hinweis: Sie teilen sich dasselbe Docker-Image; ein Rebuild betrifft also alle.
  </Accordion>

  <Accordion title="Entwickler-Befehle">
    Für alle, die den NanoClaw-Code anpassen wollen:

    ```bash theme={"system"}
    npm run dev          # Proxy + NanoClaw mit Hot-Reload starten
    npm run proxy        # Nur den Venice-Proxy starten
    npm run build        # TypeScript kompilieren
    npm test             # Tests ausführen
    ./container/build.sh # Agent-Container neu bauen
    ```
  </Accordion>
</AccordionGroup>

***

## Architektur

```
Du (WhatsApp/Telegram)
        ↓
   NanoClaw (Node.js)
        ↓
   Docker-Container (isolierte Sandbox)
        ↓
   Venice-Proxy (localhost:4001)
        ↓
   api.venice.ai (private Inferenz)
```

| Datei                      | Zweck                                                  |
| -------------------------- | ------------------------------------------------------ |
| `proxy/venice-proxy.ts`    | Übersetzt Anthropic-Format in OpenAI-Format für Venice |
| `src/index.ts`             | Hauptorchestrator – Message-Loop, Agent-Aufruf         |
| `src/channels/whatsapp.ts` | WhatsApp-Verbindung via baileys                        |
| `src/channels/telegram.ts` | Telegram-Bot via grammy                                |
| `src/container-runner.ts`  | Startet isolierte Agent-Container                      |

***

## FAQ

<AccordionGroup>
  <Accordion title="Warum brauche ich einen Proxy?">
    Das Claude Agent SDK spricht Anthropics Message-Format. Venice spricht OpenAIs Format. Der Proxy übersetzt zwischen beiden, sodass alles ohne SDK-Anpassungen funktioniert.
  </Accordion>

  <Accordion title="Kann ich Open-Source-Modelle nutzen?">
    Ja. Venice hostet viele Modelle. Sag dem Bot „switch to zai-org-glm-5" oder eine beliebige Venice-Modell-ID. Siehe [Modellkatalog](/models/text).
  </Accordion>

  <Accordion title="Ist es sicher?">
    Agenten laufen in Docker-Containern mit echter OS-level-Isolation. Der Venice-API-Schlüssel wird per stdin übergeben und nie auf Disk in Containern geschrieben. Jede Gruppe hat ihre eigene isolierte Umgebung.
  </Accordion>

  <Accordion title="Brauche ich ein Anthropic-Abo?">
    Nein. Alles läuft über Venice AI. Du brauchst nur einen Venice-API-Schlüssel.
  </Accordion>

  <Accordion title="Kann ich das auf einem Server nutzen?">
    Ja. Es läuft auf jedem Linux-Rechner mit Docker. Nutze den systemd-Service für Autostart beim Booten.
  </Accordion>
</AccordionGroup>

***

## Ressourcen

<CardGroup cols={2}>
  <Card title="NanoClaw Venice Repo" icon="github" href="https://github.com/lorenzovenice/nanoclaw-venice">
    Quellcode und vollständige README
  </Card>

  <Card title="Original-NanoClaw" icon="github" href="https://github.com/qwibitai/nanoclaw">
    Upstream-Projekt von qwibitai
  </Card>

  <Card title="Venice-Modellkatalog" icon="list" href="/models/text">
    Verfügbare Modelle durchsuchen
  </Card>

  <Card title="Venice Privacy" icon="shield-halved" href="/overview/privacy">
    Wie Venice deine Daten schützt
  </Card>
</CardGroup>