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

> Deploy NanoClaw, a lightweight personal AI assistant for WhatsApp and Telegram, on Venice for private, uncensored chat and media generation.

[NanoClaw](https://github.com/qwibitai/nanoclaw) is a lightweight, self-hosted AI assistant that runs on WhatsApp and Telegram. This fork adds Venice AI support so everything runs privately without an Anthropic subscription.

<CardGroup cols={3}>
  <Card title="Pay Per Token" icon="coins">
    No subscription. Pay only for what you use
  </Card>

  <Card title="Private Inference" icon="shield-halved">
    Zero data retention on Venice servers
  </Card>

  <Card title="Docker Isolation" icon="cube">
    Each chat runs in its own secure container
  </Card>
</CardGroup>

***

## Why Venice AI?

[Venice](https://venice.ai) is a privacy-first AI platform. They [don't store or log any prompts or responses](https://venice.ai/privacy) on their servers — your conversations exist only on your device. Requests are encrypted end-to-end through their proxy to decentralized GPU providers, with zero data retention. This means your AI assistant conversations stay private, even from Venice themselves.

Venice provides anonymized access to frontier models (Claude Opus, Claude Sonnet) and fully private access to open-source models (GLM, Qwen) through a single API — switch between them anytime.

|                          | **Venice AI**                                                                                           | **Traditional AI providers**                   |
| ------------------------ | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| **Data retention**       | None — zero logs                                                                                        | Yes                                            |
| **Prompt privacy**       | Encrypted, never stored                                                                                 | Stored on provider servers                     |
| **Open-source models**   | Yes (GLM, Qwen, and others)                                                                             | No                                             |
| **Frontier models**      | Claude, GPT, and others — anonymously                                                                   | Only through direct subscriptions              |
| **Pricing**              | Pay-per-token, no subscription. Or stake [DIEM](https://venice.ai/lp/diem) for daily refreshing credits | \$20–200/mo subscriptions or pay-per-token API |
| **Uncensored inference** | Yes (open-source models)                                                                                | No                                             |

***

## Why NanoClaw?

NanoClaw is a clean, minimal alternative to larger platforms like OpenClaw. It's designed for one person running one bot.

|                         | **NanoClaw (Venice)**                                     | **OpenClaw**                                   |
| ----------------------- | --------------------------------------------------------- | ---------------------------------------------- |
| **Codebase**            | \~2,000 lines, handful of files                           | \~500,000 lines, 53 config files               |
| **Dependencies**        | \~15 packages                                             | 70+ packages                                   |
| **Security model**      | OS-level Docker container isolation                       | Application-level allowlists and pairing codes |
| **Per-group isolation** | Each group gets its own container, filesystem, and memory | Shared process, shared memory                  |
| **Setup**               | One wizard (`/setup`), \~10 minutes                       | Manual multi-step configuration                |
| **AI provider**         | Venice AI (private, no subscription)                      | Anthropic (requires API key or subscription)   |
| **Customization**       | Edit the code directly — it's small enough to read        | Config files and plugins                       |
| **Target user**         | One person, one bot                                       | Multi-user platform                            |

***

## What You Get

* Personal AI assistant on **Telegram** and/or **WhatsApp**
* Powered by **Venice AI** — no Anthropic account needed
* Bot runs in an **isolated Docker container** (sandboxed, can't access your system)
* **Model switching** — tell the bot "switch to zai-org-glm-5" or "use opus" anytime
* **Scheduled tasks** — set reminders, recurring tasks
* **Web search and browsing** built in
* **Markdown formatting** in Telegram messages

***

## Prerequisites

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

  <Card title="Docker" icon="docker" href="https://docker.com/products/docker-desktop">
    Install and open once so it's running
  </Card>

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

  <Card title="Venice API Key" icon="key" href="https://venice.ai/settings/api">
    Generate from your Venice account
  </Card>
</CardGroup>

**For Telegram** (recommended for first-time users):

1. Open Telegram and search for **@BotFather**
2. Send `/newbot` and follow the prompts
3. Save the token BotFather gives you (looks like `123456789:ABCdef...`)

<Warning>
  **For WhatsApp — use a virtual number, NOT your personal one:**

  NanoClaw connects as a linked device on your WhatsApp number. That means **the agent can see every message coming in and going out** — all your personal conversations, group chats, photos, everything. Your phone still works normally, but the bot has full visibility into your entire WhatsApp account.

  **Use a virtual phone number instead.** These apps give you a second number that you can dedicate entirely to the bot:

  | App                                      | Price    | Notes                                                        |
  | ---------------------------------------- | -------- | ------------------------------------------------------------ |
  | [Hushed](https://hushed.com)             | \~\$5/mo | Reliable, works well for WhatsApp verification               |
  | [Burner](https://www.burnerapp.com)      | \~\$5/mo | Similar to Hushed, disposable numbers                        |
  | [Google Voice](https://voice.google.com) | Free     | US-only, may not work for WhatsApp verification in all cases |

  **How to set it up:**

  1. Get a virtual number from one of the apps above
  2. Install WhatsApp on a second device (old phone, tablet, or emulator) using that virtual number
  3. During NanoClaw setup, scan the QR code with that second device — not your personal phone
</Warning>

***

## Setup

The setup takes about 10 minutes. You only need **one Terminal window**.

<Steps>
  <Step title="Clone and Install">
    Open Terminal and run:

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

    Wait for `npm install` to finish with no errors.
  </Step>

  <Step title="Launch Claude Code with Venice">
    Replace `your-key` with your Venice API key and run:

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

    This starts the Venice proxy and launches Claude Code through it in a single command.

    <Note>
      Claude Code defaults to **GLM 5** (`zai-org-glm-5`) to keep setup costs low. After setup, type `/model` inside Claude Code to switch to `claude-sonnet-4-6` or `claude-opus-4-6` for best performance.
    </Note>

    If prompted "Do you want to use this API key?" — select **Yes**.
  </Step>

  <Step title="Run the Setup Wizard">
    In your Claude Code terminal, type:

    ```
    /setup
    ```

    The wizard walks you through:

    1. **Bootstrap** — checks Node.js and dependencies
    2. **Venice API key** — validates and saves your key
    3. **Channel choice** — pick WhatsApp, Telegram, or both
    4. **Container build** — builds the Docker container (takes a few minutes first time)
    5. **WhatsApp auth** — scan QR code with your phone (if applicable)
    6. **Telegram setup** — send a message to your bot so it detects your chat
    7. **Trigger word** — prefix that activates the bot (default: `@Andy`)
    8. **Mount directories** — pick "No" for now (you can add file access later)
    9. **Start services** — NanoClaw and the Venice proxy both start as background services

    The setup wizard installs two background services:

    * **NanoClaw** — the bot itself
    * **Venice proxy** — a small local server (localhost:4001) that translates between Claude Code and Venice AI

    Both start automatically on boot and restart themselves if they crash.

    <Note>
      If the wizard stops between steps, type "continue" or "next step" to nudge it forward.
    </Note>
  </Step>

  <Step title="Start Chatting">
    Once setup is complete, open your chat (Telegram or WhatsApp) and send:

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

    The bot should respond within seconds. In your main channel, you can type normally without the `@Andy` prefix.

    **You can now close the terminal window.** Everything runs as background services and starts automatically when your computer boots.
  </Step>
</Steps>

***

## How It Works

There are two layers to NanoClaw:

| Layer               | What It Does                                                 |
| ------------------- | ------------------------------------------------------------ |
| **Claude Code CLI** | Admin tool for setup, debugging, and customization           |
| **The Bot**         | AI in your chat, running inside an isolated Docker container |

To open Claude Code anytime:

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

Use it to run `/setup`, `/debug`, `/customize`, or make changes to the bot's behavior.

***

## Models

| Context         | Default Model           | How to Switch                                          |
| --------------- | ----------------------- | ------------------------------------------------------ |
| Bot (in chat)   | `claude-sonnet-4-6`     | Tell the bot: "switch to opus" or "use zai-org-glm-5"  |
| Claude Code CLI | `zai-org-glm-5` (GLM 5) | Use `/model` in Claude Code or `claude --model <name>` |

<Tip>
  The CLI defaults to GLM 5 to keep setup costs low. After setup, switch to `claude-sonnet-4-6` or `claude-opus-4-6` for best performance.
</Tip>

See the [model catalog](/models/text) for all available Venice models.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="The proxy isn't running">
    The Venice proxy runs as a background service and restarts itself automatically. If it's not working:

    **macOS:**

    ```bash theme={"system"}
    # Check if it's running
    launchctl list | grep venice-proxy

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

    # Check logs
    tail -f ~/nanoclaw-venice/logs/venice-proxy.log
    ```

    **Linux:**

    ```bash theme={"system"}
    # Check if it's running
    systemctl --user status nanoclaw-venice-proxy

    # Restart it
    systemctl --user restart nanoclaw-venice-proxy

    # Check logs
    tail -f ~/nanoclaw-venice/logs/venice-proxy.log
    ```
  </Accordion>

  <Accordion title="Claude Code shows 403 error or 'Please run /login'">
    This means Claude Code can't connect to the Venice proxy.

    1. **Check the proxy is running.** See the troubleshooting step above.
    2. **Make sure you're in the right folder.** Always `cd nanoclaw-venice` first.
    3. **Start fresh:** Close all terminals and run:
       ```bash theme={"system"}
       cd nanoclaw-venice
       ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
       ```
  </Accordion>

  <Accordion title="Model errors ('model does not exist')">
    Restart the proxy and the bot:

    **macOS:**

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

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

    **Linux:**

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

    # Restart bot
    systemctl --user restart nanoclaw
    ```

    Check available models at the [model catalog](/models/text).
  </Accordion>

  <Accordion title="Bot doesn't respond to messages">
    Work through these steps in order:

    1. **Check your trigger word.** Make sure you're using the right prefix (e.g., `@Andy hello`).
    2. **Check Docker is running.** Run `docker info` — if it errors, open Docker Desktop.
    3. **Check the proxy is running.** See "The proxy isn't running" above.
    4. **Check logs:** `tail -f logs/nanoclaw.log` in the project folder.
    5. **Check container logs.** Open the `nanoclaw-venice/groups/main/logs/` folder. Open the most recent file that starts with `container-`.
    6. **Restart everything:** Restart both proxy and bot (see above).
  </Accordion>

  <Accordion title="Container build fails during setup">
    Make sure Docker Desktop is open and running. Wait 10 seconds for Docker to fully start, then type `continue` in the wizard to retry.
  </Accordion>

  <Accordion title="WhatsApp disconnected">
    Your WhatsApp session can expire. To reconnect:

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

    Scan the QR code with WhatsApp (Settings → Linked Devices → Link a Device), then restart the bot:

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

***

## Advanced

<AccordionGroup>
  <Accordion title="Give the bot access to files on your computer">
    By default, the bot is completely walled off from your computer — it can only see its own memory and conversation history.

    * **During setup:** When asked about directory access, choose "Yes"
    * **After setup:** Run `/customize` in Claude Code
  </Accordion>

  <Accordion title="Manually start/stop the bot">
    NanoClaw runs two background services that start automatically on boot.

    **macOS:**

    | Action        | Command                                                                   |
    | ------------- | ------------------------------------------------------------------------- |
    | Start bot     | `launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist`                |
    | Stop bot      | `launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist`              |
    | Restart bot   | `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`                        |
    | Start proxy   | `launchctl load ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist`   |
    | Stop proxy    | `launchctl unload ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist` |
    | Restart proxy | `launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy`           |

    **Linux:**

    | Action        | Command                                          |
    | ------------- | ------------------------------------------------ |
    | Start bot     | `systemctl --user start nanoclaw`                |
    | Stop bot      | `systemctl --user stop nanoclaw`                 |
    | Restart bot   | `systemctl --user restart nanoclaw`              |
    | Start proxy   | `systemctl --user start nanoclaw-venice-proxy`   |
    | Stop proxy    | `systemctl --user stop nanoclaw-venice-proxy`    |
    | Restart proxy | `systemctl --user restart nanoclaw-venice-proxy` |
  </Accordion>

  <Accordion title="Using Claude Code through Venice (no bot)">
    If you just want Claude Code with Venice and don't need WhatsApp/Telegram, the proxy service needs to be running. If you've already run `/setup`, it's already running as a background service.

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

    **Tip:** Add this to your `~/.zshrc` (or `~/.bashrc`) so you can quickly switch any terminal to 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"'
    ```

    Then just type `venice` in any terminal before running `claude` to use Venice, or `anthropic` to switch back.
  </Accordion>

  <Accordion title="Running multiple bots">
    You can run multiple NanoClaw bots on the same machine (e.g., one for personal use and one for a team). Just clone the repo into a different folder and run setup again. Note: they share the same Docker image, so rebuilding one affects all of them.
  </Accordion>

  <Accordion title="Developer commands">
    For people who want to modify NanoClaw's code:

    ```bash theme={"system"}
    npm run dev          # Start proxy + NanoClaw with hot reload
    npm run proxy        # Start just the Venice proxy
    npm run build        # Compile TypeScript
    npm test             # Run tests
    ./container/build.sh # Rebuild agent container
    ```
  </Accordion>
</AccordionGroup>

***

## Architecture

```
You (WhatsApp/Telegram)
        ↓
   NanoClaw (Node.js)
        ↓
   Docker Container (isolated sandbox)
        ↓
   Venice Proxy (localhost:4001)
        ↓
   api.venice.ai (private inference)
```

| File                       | Purpose                                                 |
| -------------------------- | ------------------------------------------------------- |
| `proxy/venice-proxy.ts`    | Translates Anthropic format to OpenAI format for Venice |
| `src/index.ts`             | Main orchestrator — message loop, agent invocation      |
| `src/channels/whatsapp.ts` | WhatsApp connection via baileys                         |
| `src/channels/telegram.ts` | Telegram bot via grammy                                 |
| `src/container-runner.ts`  | Spawns isolated agent containers                        |

***

## FAQ

<AccordionGroup>
  <Accordion title="Why do I need a proxy?">
    The Claude Agent SDK speaks Anthropic's message format. Venice speaks OpenAI's format. The proxy translates between them so everything works without modifying the SDK.
  </Accordion>

  <Accordion title="Can I use open-source models?">
    Yes. Venice hosts many models. Tell the bot "switch to zai-org-glm-5" or any Venice model ID. See the [model catalog](/models/text).
  </Accordion>

  <Accordion title="Is it secure?">
    Agents run in Docker containers with real OS-level isolation. The Venice API key is passed via stdin, never written to disk inside containers. Each group gets its own isolated environment.
  </Accordion>

  <Accordion title="Do I need an Anthropic subscription?">
    No. Everything runs through Venice AI. You only need a Venice API key.
  </Accordion>

  <Accordion title="Can I use this on a server?">
    Yes. It works on any Linux machine with Docker. Use the systemd service for auto-start on boot.
  </Accordion>
</AccordionGroup>

***

## Resources

<CardGroup cols={2}>
  <Card title="NanoClaw Venice Repo" icon="github" href="https://github.com/lorenzovenice/nanoclaw-venice">
    Source code and full README
  </Card>

  <Card title="Original NanoClaw" icon="github" href="https://github.com/qwibitai/nanoclaw">
    Upstream project by qwibitai
  </Card>

  <Card title="Venice Model Catalog" icon="list" href="/models/text">
    Browse available models
  </Card>

  <Card title="Venice Privacy" icon="shield-halved" href="/overview/privacy">
    How Venice protects your data
  </Card>
</CardGroup>