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

> Implante o NanoClaw, um assistente de IA pessoal leve para WhatsApp e Telegram, na Venice para chat privado e sem censura e geração de mídia.

O [NanoClaw](https://github.com/qwibitai/nanoclaw) é um assistente de IA leve e auto-hospedado que roda no WhatsApp e Telegram. Este fork adiciona suporte à Venice AI para que tudo rode privadamente sem uma assinatura da Anthropic.

<CardGroup cols={3}>
  <Card title="Pagamento por token" icon="coins">
    Sem assinatura. Pague apenas pelo que usar
  </Card>

  <Card title="Inferência privada" icon="shield-halved">
    Zero retenção de dados nos servidores Venice
  </Card>

  <Card title="Isolamento Docker" icon="cube">
    Cada chat roda em seu próprio container seguro
  </Card>
</CardGroup>

***

## Por que Venice AI?

A [Venice](https://venice.ai) é uma plataforma de IA focada em privacidade. Ela [não armazena nem registra prompts ou respostas](https://venice.ai/privacy) em seus servidores — suas conversas existem apenas no seu dispositivo. As requisições são criptografadas ponta a ponta através de seu proxy para provedores de GPU descentralizados, com zero retenção de dados. Isso significa que as conversas com seu assistente de IA permanecem privadas, até mesmo da própria Venice.

A Venice oferece acesso anonimizado a modelos de fronteira (Claude Opus, Claude Sonnet) e acesso totalmente privado a modelos de código aberto (GLM, Qwen) por meio de uma única API — alterne entre eles a qualquer momento.

|                              | **Venice AI**                                                                                               | **Provedores tradicionais de IA**            |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **Retenção de dados**        | Nenhuma — zero logs                                                                                         | Sim                                          |
| **Privacidade dos prompts**  | Criptografados, nunca armazenados                                                                           | Armazenados nos servidores do provedor       |
| **Modelos de código aberto** | Sim (GLM, Qwen e outros)                                                                                    | Não                                          |
| **Modelos de fronteira**     | Claude, GPT e outros — anonimamente                                                                         | Apenas via assinaturas diretas               |
| **Preço**                    | Pague por token, sem assinatura. Ou faça staking de [DIEM](https://venice.ai/lp/diem) para créditos diários | Assinaturas de \$20–200/mês ou API por token |
| **Inferência sem censura**   | Sim (modelos de código aberto)                                                                              | Não                                          |

***

## Por que NanoClaw?

O NanoClaw é uma alternativa limpa e minimalista a plataformas maiores como o OpenClaw. É projetado para uma pessoa executando um único bot.

|                          | **NanoClaw (Venice)**                                               | **OpenClaw**                                             |
| ------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------- |
| **Base de código**       | \~2.000 linhas, alguns arquivos                                     | \~500.000 linhas, 53 arquivos de configuração            |
| **Dependências**         | \~15 pacotes                                                        | Mais de 70 pacotes                                       |
| **Modelo de segurança**  | Isolamento por container Docker no nível do SO                      | Allowlists e códigos de pareamento no nível da aplicação |
| **Isolamento por grupo** | Cada grupo tem seu próprio container, sistema de arquivos e memória | Processo compartilhado, memória compartilhada            |
| **Configuração**         | Um assistente (`/setup`), \~10 minutos                              | Configuração manual em múltiplas etapas                  |
| **Provedor de IA**       | Venice AI (privada, sem assinatura)                                 | Anthropic (requer chave de API ou assinatura)            |
| **Customização**         | Edite o código diretamente — é pequeno o suficiente para ler        | Arquivos de configuração e plugins                       |
| **Usuário-alvo**         | Uma pessoa, um bot                                                  | Plataforma multiusuário                                  |

***

## O que você obtém

* Assistente de IA pessoal no **Telegram** e/ou **WhatsApp**
* Impulsionado por **Venice AI** — sem necessidade de conta Anthropic
* O bot roda em um **container Docker isolado** (sandbox, não pode acessar seu sistema)
* **Troca de modelo** — diga ao bot "switch to zai-org-glm-5" ou "use opus" a qualquer momento
* **Tarefas agendadas** — defina lembretes e tarefas recorrentes
* **Busca na web e navegação** integradas
* Formatação **Markdown** em mensagens do Telegram

***

## Pré-requisitos

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

  <Card title="Docker" icon="docker" href="https://docker.com/products/docker-desktop">
    Instale e abra uma vez para que esteja rodando
  </Card>

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

  <Card title="Chave de API Venice" icon="key" href="https://venice.ai/settings/api">
    Gere a partir da sua conta Venice
  </Card>
</CardGroup>

**Para Telegram** (recomendado para usuários de primeira viagem):

1. Abra o Telegram e pesquise por **@BotFather**
2. Envie `/newbot` e siga as instruções
3. Salve o token que o BotFather te der (parece com `123456789:ABCdef...`)

<Warning>
  **Para WhatsApp — use um número virtual, NÃO o seu pessoal:**

  O NanoClaw se conecta como um dispositivo vinculado no seu número de WhatsApp. Isso significa que **o agente pode ver todas as mensagens entrando e saindo** — todas as suas conversas pessoais, chats em grupo, fotos, tudo. Seu telefone continua funcionando normalmente, mas o bot tem visibilidade total da sua conta inteira do WhatsApp.

  **Use um número de telefone virtual em vez disso.** Esses aplicativos oferecem um segundo número que você pode dedicar inteiramente ao bot:

  | App                                      | Preço     | Notas                                                                         |
  | ---------------------------------------- | --------- | ----------------------------------------------------------------------------- |
  | [Hushed](https://hushed.com)             | \~\$5/mês | Confiável, funciona bem para verificação do WhatsApp                          |
  | [Burner](https://www.burnerapp.com)      | \~\$5/mês | Similar ao Hushed, números descartáveis                                       |
  | [Google Voice](https://voice.google.com) | Grátis    | Apenas EUA, pode não funcionar para verificação do WhatsApp em todos os casos |

  **Como configurar:**

  1. Obtenha um número virtual de um dos apps acima
  2. Instale o WhatsApp em um segundo dispositivo (telefone antigo, tablet ou emulador) usando esse número virtual
  3. Durante a configuração do NanoClaw, escaneie o QR code com esse segundo dispositivo — não com seu telefone pessoal
</Warning>

***

## Configuração

A configuração leva cerca de 10 minutos. Você só precisa de **uma janela de Terminal**.

<Steps>
  <Step title="Clone e instale">
    Abra o Terminal e execute:

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

    Espere o `npm install` terminar sem erros.
  </Step>

  <Step title="Inicie o Claude Code com Venice">
    Substitua `your-key` pela sua chave de API Venice e execute:

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

    Isso inicia o proxy Venice e lança o Claude Code através dele em um único comando.

    <Note>
      O Claude Code usa por padrão o **GLM 5** (`zai-org-glm-5`) para manter os custos de configuração baixos. Após a configuração, digite `/model` dentro do Claude Code para trocar para `claude-sonnet-4-6` ou `claude-opus-4-6` para melhor desempenho.
    </Note>

    Se for perguntado "Do you want to use this API key?" — selecione **Yes**.
  </Step>

  <Step title="Execute o assistente de configuração">
    No seu terminal do Claude Code, digite:

    ```
    /setup
    ```

    O assistente te guia por:

    1. **Bootstrap** — verifica Node.js e dependências
    2. **Chave de API Venice** — valida e salva sua chave
    3. **Escolha do canal** — escolha WhatsApp, Telegram ou ambos
    4. **Build do container** — constrói o container Docker (leva alguns minutos na primeira vez)
    5. **Autenticação do WhatsApp** — escaneie o QR code com seu telefone (se aplicável)
    6. **Configuração do Telegram** — envie uma mensagem ao seu bot para que ele detecte seu chat
    7. **Palavra-chave de gatilho** — prefixo que ativa o bot (padrão: `@Andy`)
    8. **Diretórios montados** — escolha "Não" por enquanto (você pode adicionar acesso a arquivos depois)
    9. **Iniciar serviços** — NanoClaw e o proxy Venice iniciam ambos como serviços em segundo plano

    O assistente de configuração instala dois serviços em segundo plano:

    * **NanoClaw** — o bot em si
    * **Proxy Venice** — um pequeno servidor local (localhost:4001) que traduz entre o Claude Code e a Venice AI

    Ambos iniciam automaticamente no boot e se reiniciam se travarem.

    <Note>
      Se o assistente parar entre etapas, digite "continue" ou "next step" para fazê-lo avançar.
    </Note>
  </Step>

  <Step title="Comece a conversar">
    Quando a configuração estiver completa, abra seu chat (Telegram ou WhatsApp) e envie:

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

    O bot deve responder em segundos. No seu canal principal, você pode digitar normalmente sem o prefixo `@Andy`.

    **Você agora pode fechar a janela do terminal.** Tudo roda como serviços em segundo plano e inicia automaticamente quando seu computador é ligado.
  </Step>
</Steps>

***

## Como funciona

Existem duas camadas no NanoClaw:

| Camada                 | O que faz                                                             |
| ---------------------- | --------------------------------------------------------------------- |
| **CLI do Claude Code** | Ferramenta administrativa para configuração, depuração e customização |
| **O Bot**              | IA no seu chat, rodando dentro de um container Docker isolado         |

Para abrir o Claude Code a qualquer momento:

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

Use-o para executar `/setup`, `/debug`, `/customize` ou fazer alterações no comportamento do bot.

***

## Modelos

| Contexto        | Modelo padrão           | Como trocar                                            |
| --------------- | ----------------------- | ------------------------------------------------------ |
| Bot (no chat)   | `claude-sonnet-4-6`     | Diga ao bot: "switch to opus" ou "use zai-org-glm-5"   |
| CLI Claude Code | `zai-org-glm-5` (GLM 5) | Use `/model` no Claude Code ou `claude --model <name>` |

<Tip>
  O CLI usa por padrão o GLM 5 para manter os custos de configuração baixos. Após a configuração, troque para `claude-sonnet-4-6` ou `claude-opus-4-6` para melhor desempenho.
</Tip>

Veja o [catálogo de modelos](/models/text) para todos os modelos Venice disponíveis.

***

## Solução de problemas

<AccordionGroup>
  <Accordion title="O proxy não está rodando">
    O proxy Venice roda como um serviço em segundo plano e se reinicia automaticamente. Se não estiver funcionando:

    **macOS:**

    ```bash theme={"system"}
    # Verifique se está rodando
    launchctl list | grep venice-proxy

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

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

    **Linux:**

    ```bash theme={"system"}
    # Verifique se está rodando
    systemctl --user status nanoclaw-venice-proxy

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

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

  <Accordion title="O Claude Code mostra erro 403 ou 'Please run /login'">
    Isso significa que o Claude Code não consegue se conectar ao proxy Venice.

    1. **Verifique se o proxy está rodando.** Veja o passo de solução de problemas acima.
    2. **Certifique-se de estar na pasta certa.** Sempre faça `cd nanoclaw-venice` primeiro.
    3. **Comece do zero:** Feche todos os terminais e execute:
       ```bash theme={"system"}
       cd nanoclaw-venice
       ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
       ```
  </Accordion>

  <Accordion title="Erros de modelo ('model does not exist')">
    Reinicie o proxy e o bot:

    **macOS:**

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

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

    **Linux:**

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

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

    Confira os modelos disponíveis no [catálogo de modelos](/models/text).
  </Accordion>

  <Accordion title="O bot não responde a mensagens">
    Siga esses passos na ordem:

    1. **Verifique sua palavra-chave de gatilho.** Confirme se está usando o prefixo correto (ex.: `@Andy hello`).
    2. **Verifique se o Docker está rodando.** Execute `docker info` — se der erro, abra o Docker Desktop.
    3. **Verifique se o proxy está rodando.** Veja "O proxy não está rodando" acima.
    4. **Verifique os logs:** `tail -f logs/nanoclaw.log` na pasta do projeto.
    5. **Verifique os logs do container.** Abra a pasta `nanoclaw-venice/groups/main/logs/`. Abra o arquivo mais recente que começa com `container-`.
    6. **Reinicie tudo:** Reinicie tanto o proxy quanto o bot (veja acima).
  </Accordion>

  <Accordion title="O build do container falha durante a configuração">
    Certifique-se de que o Docker Desktop está aberto e em execução. Aguarde 10 segundos para o Docker iniciar completamente, depois digite `continue` no assistente para tentar de novo.
  </Accordion>

  <Accordion title="WhatsApp desconectado">
    Sua sessão do WhatsApp pode expirar. Para reconectar:

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

    Escaneie o QR code com o WhatsApp (Configurações → Dispositivos conectados → Conectar um dispositivo), depois reinicie o bot:

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

***

## Avançado

<AccordionGroup>
  <Accordion title="Dê ao bot acesso a arquivos no seu computador">
    Por padrão, o bot está totalmente isolado do seu computador — ele só pode ver sua própria memória e histórico de conversas.

    * **Durante a configuração:** Quando perguntado sobre acesso a diretórios, escolha "Sim"
    * **Após a configuração:** Execute `/customize` no Claude Code
  </Accordion>

  <Accordion title="Iniciar/parar o bot manualmente">
    O NanoClaw roda dois serviços em segundo plano que iniciam automaticamente no boot.

    **macOS:**

    | Ação            | Comando                                                                   |
    | --------------- | ------------------------------------------------------------------------- |
    | Iniciar bot     | `launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist`                |
    | Parar bot       | `launchctl unload ~/Library/LaunchAgents/com.nanoclaw.plist`              |
    | Reiniciar bot   | `launchctl kickstart -k gui/$(id -u)/com.nanoclaw`                        |
    | Iniciar proxy   | `launchctl load ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist`   |
    | Parar proxy     | `launchctl unload ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist` |
    | Reiniciar proxy | `launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy`           |

    **Linux:**

    | Ação            | Comando                                          |
    | --------------- | ------------------------------------------------ |
    | Iniciar bot     | `systemctl --user start nanoclaw`                |
    | Parar bot       | `systemctl --user stop nanoclaw`                 |
    | Reiniciar bot   | `systemctl --user restart nanoclaw`              |
    | Iniciar proxy   | `systemctl --user start nanoclaw-venice-proxy`   |
    | Parar proxy     | `systemctl --user stop nanoclaw-venice-proxy`    |
    | Reiniciar proxy | `systemctl --user restart nanoclaw-venice-proxy` |
  </Accordion>

  <Accordion title="Usar o Claude Code através da Venice (sem bot)">
    Se você só quer o Claude Code com Venice e não precisa do WhatsApp/Telegram, o serviço de proxy precisa estar rodando. Se já executou `/setup`, ele já está rodando como serviço em segundo plano.

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

    **Dica:** Adicione isto ao seu `~/.zshrc` (ou `~/.bashrc`) para alternar qualquer terminal para Venice rapidamente:

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

    Em seguida, basta digitar `venice` em qualquer terminal antes de executar `claude` para usar a Venice, ou `anthropic` para voltar.
  </Accordion>

  <Accordion title="Rodando múltiplos bots">
    Você pode rodar múltiplos bots NanoClaw na mesma máquina (por exemplo, um para uso pessoal e outro para uma equipe). Basta clonar o repositório em uma pasta diferente e executar o setup novamente. Observação: eles compartilham a mesma imagem Docker, então reconstruir um afeta todos.
  </Accordion>

  <Accordion title="Comandos de desenvolvedor">
    Para pessoas que querem modificar o código do NanoClaw:

    ```bash theme={"system"}
    npm run dev          # Inicia proxy + NanoClaw com hot reload
    npm run proxy        # Inicia apenas o proxy Venice
    npm run build        # Compila TypeScript
    npm test             # Executa testes
    ./container/build.sh # Reconstrói container do agente
    ```
  </Accordion>
</AccordionGroup>

***

## Arquitetura

```
Você (WhatsApp/Telegram)
        ↓
   NanoClaw (Node.js)
        ↓
   Container Docker (sandbox isolada)
        ↓
   Proxy Venice (localhost:4001)
        ↓
   api.venice.ai (inferência privada)
```

| Arquivo                    | Finalidade                                                      |
| -------------------------- | --------------------------------------------------------------- |
| `proxy/venice-proxy.ts`    | Traduz formato Anthropic para formato OpenAI para a Venice      |
| `src/index.ts`             | Orquestrador principal — loop de mensagens, invocação de agente |
| `src/channels/whatsapp.ts` | Conexão com WhatsApp via baileys                                |
| `src/channels/telegram.ts` | Bot do Telegram via grammy                                      |
| `src/container-runner.ts`  | Cria containers de agente isolados                              |

***

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Por que preciso de um proxy?">
    O SDK Claude Agent fala o formato de mensagens da Anthropic. A Venice fala o formato da OpenAI. O proxy traduz entre eles para que tudo funcione sem modificar o SDK.
  </Accordion>

  <Accordion title="Posso usar modelos de código aberto?">
    Sim. A Venice hospeda muitos modelos. Diga ao bot "switch to zai-org-glm-5" ou qualquer ID de modelo Venice. Veja o [catálogo de modelos](/models/text).
  </Accordion>

  <Accordion title="É seguro?">
    Os agentes rodam em containers Docker com isolamento real no nível do SO. A chave de API Venice é passada via stdin, nunca escrita em disco dentro dos containers. Cada grupo tem seu próprio ambiente isolado.
  </Accordion>

  <Accordion title="Preciso de uma assinatura da Anthropic?">
    Não. Tudo roda via Venice AI. Você só precisa de uma chave de API Venice.
  </Accordion>

  <Accordion title="Posso usar isso em um servidor?">
    Sim. Funciona em qualquer máquina Linux com Docker. Use o serviço systemd para auto-iniciar no boot.
  </Accordion>
</AccordionGroup>

***

## Recursos

<CardGroup cols={2}>
  <Card title="Repositório NanoClaw Venice" icon="github" href="https://github.com/lorenzovenice/nanoclaw-venice">
    Código-fonte e README completo
  </Card>

  <Card title="NanoClaw original" icon="github" href="https://github.com/qwibitai/nanoclaw">
    Projeto upstream por qwibitai
  </Card>

  <Card title="Catálogo de modelos Venice" icon="list" href="/models/text">
    Navegue pelos modelos disponíveis
  </Card>

  <Card title="Privacidade Venice" icon="shield-halved" href="/overview/privacy">
    Como a Venice protege seus dados
  </Card>
</CardGroup>