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

> Despliega NanoClaw, un asistente de IA personal ligero para WhatsApp y Telegram, sobre Venice para un chat y una generación de medios privados y sin censura.

[NanoClaw](https://github.com/qwibitai/nanoclaw) es un asistente de IA ligero y autoalojado que se ejecuta en WhatsApp y Telegram. Este fork añade soporte para Venice AI para que todo se ejecute de forma privada sin una suscripción a Anthropic.

<CardGroup cols={3}>
  <Card title="Pago por token" icon="coins">
    Sin suscripción. Paga solo por lo que uses
  </Card>

  <Card title="Inferencia privada" icon="shield-halved">
    Cero retención de datos en los servidores de Venice
  </Card>

  <Card title="Aislamiento con Docker" icon="cube">
    Cada chat se ejecuta en su propio contenedor seguro
  </Card>
</CardGroup>

***

## ¿Por qué Venice AI?

[Venice](https://venice.ai) es una plataforma de IA centrada en la privacidad. [No almacenan ni registran prompts ni respuestas](https://venice.ai/privacy) en sus servidores — tus conversaciones existen solo en tu dispositivo. Las solicitudes se cifran de extremo a extremo a través de su proxy hacia proveedores de GPU descentralizados, con cero retención de datos. Esto significa que las conversaciones de tu asistente de IA siguen siendo privadas, incluso para Venice.

Venice proporciona acceso anonimizado a modelos de frontera (Claude Opus, Claude Sonnet) y acceso totalmente privado a modelos de código abierto (GLM, Qwen) a través de una sola API — alterna entre ellos en cualquier momento.

|                            | **Venice AI**                                                                                                          | **Proveedores de IA tradicionales**                   |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| **Retención de datos**     | Ninguna — cero logs                                                                                                    | Sí                                                    |
| **Privacidad del prompt**  | Cifrada, nunca almacenada                                                                                              | Almacenada en los servidores del proveedor            |
| **Modelos open-source**    | Sí (GLM, Qwen y otros)                                                                                                 | No                                                    |
| **Modelos frontera**       | Claude, GPT y otros — de forma anónima                                                                                 | Solo mediante suscripciones directas                  |
| **Precios**                | Pago por token, sin suscripción. O hacer staking de [DIEM](https://venice.ai/lp/diem) para créditos diarios renovables | Suscripciones de \$20–200/mes o API de pago por token |
| **Inferencia sin censura** | Sí (modelos open-source)                                                                                               | No                                                    |

***

## ¿Por qué NanoClaw?

NanoClaw es una alternativa limpia y mínima a plataformas más grandes como OpenClaw. Está diseñado para una persona ejecutando un bot.

|                           | **NanoClaw (Venice)**                                                  | **OpenClaw**                                                 |
| ------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------ |
| **Base de código**        | \~2.000 líneas, un puñado de archivos                                  | \~500.000 líneas, 53 archivos de configuración               |
| **Dependencias**          | \~15 paquetes                                                          | 70+ paquetes                                                 |
| **Modelo de seguridad**   | Aislamiento a nivel de SO con contenedores Docker                      | Allowlists y códigos de emparejamiento a nivel de aplicación |
| **Aislamiento por grupo** | Cada grupo tiene su propio contenedor, sistema de archivos y memoria   | Proceso compartido, memoria compartida                       |
| **Configuración**         | Un asistente (`/setup`), \~10 minutos                                  | Configuración manual multi-paso                              |
| **Proveedor de IA**       | Venice AI (privado, sin suscripción)                                   | Anthropic (requiere API key o suscripción)                   |
| **Personalización**       | Edita el código directamente — es lo bastante pequeño como para leerlo | Archivos de configuración y plugins                          |
| **Usuario objetivo**      | Una persona, un bot                                                    | Plataforma multi-usuario                                     |

***

## Lo que obtienes

* Asistente de IA personal en **Telegram** y/o **WhatsApp**
* Impulsado por **Venice AI** — no se necesita cuenta de Anthropic
* El bot se ejecuta en un **contenedor Docker aislado** (en sandbox, no puede acceder a tu sistema)
* **Cambio de modelo** — dile al bot "switch to zai-org-glm-5" o "use opus" en cualquier momento
* **Tareas programadas** — configura recordatorios, tareas recurrentes
* **Búsqueda y navegación web** integradas
* **Formato Markdown** en los mensajes de Telegram

***

## Requisitos previos

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

  <Card title="Docker" icon="docker" href="https://docker.com/products/docker-desktop">
    Instálalo y ábrelo una vez para que esté en ejecución
  </Card>

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

  <Card title="API key de Venice" icon="key" href="https://venice.ai/settings/api">
    Genera desde tu cuenta de Venice
  </Card>
</CardGroup>

**Para Telegram** (recomendado para usuarios nuevos):

1. Abre Telegram y busca **@BotFather**
2. Envía `/newbot` y sigue las indicaciones
3. Guarda el token que te da BotFather (parece `123456789:ABCdef...`)

<Warning>
  **Para WhatsApp — usa un número virtual, NO el personal:**

  NanoClaw se conecta como dispositivo vinculado a tu número de WhatsApp. Eso significa que **el agente puede ver cada mensaje entrante y saliente** — todas tus conversaciones personales, chats de grupo, fotos, todo. Tu teléfono sigue funcionando con normalidad, pero el bot tiene visibilidad completa de toda tu cuenta de WhatsApp.

  **Usa un número de teléfono virtual en su lugar.** Estas apps te dan un segundo número que puedes dedicar por completo al bot:

  | App                                      | Precio    | Notas                                                                             |
  | ---------------------------------------- | --------- | --------------------------------------------------------------------------------- |
  | [Hushed](https://hushed.com)             | \~\$5/mes | Fiable, funciona bien para verificación de WhatsApp                               |
  | [Burner](https://www.burnerapp.com)      | \~\$5/mes | Similar a Hushed, números desechables                                             |
  | [Google Voice](https://voice.google.com) | Gratis    | Solo EE. UU., puede no funcionar para verificación de WhatsApp en todos los casos |

  **Cómo configurarlo:**

  1. Consigue un número virtual de una de las apps anteriores
  2. Instala WhatsApp en un segundo dispositivo (teléfono antiguo, tablet o emulador) usando ese número virtual
  3. Durante la configuración de NanoClaw, escanea el código QR con ese segundo dispositivo, no con tu teléfono personal
</Warning>

***

## Configuración

La configuración tarda unos 10 minutos. Solo necesitas **una ventana de Terminal**.

<Steps>
  <Step title="Clona e instala">
    Abre Terminal y ejecuta:

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

    Espera a que `npm install` termine sin errores.
  </Step>

  <Step title="Lanza Claude Code con Venice">
    Sustituye `your-key` por tu API key de Venice y ejecuta:

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

    Esto inicia el proxy de Venice y lanza Claude Code a través de él en un solo comando.

    <Note>
      Claude Code usa por defecto **GLM 5** (`zai-org-glm-5`) para mantener bajos los costes de configuración. Tras la configuración, escribe `/model` dentro de Claude Code para cambiar a `claude-sonnet-4-6` o `claude-opus-4-6` para el mejor rendimiento.
    </Note>

    Si se te pregunta "Do you want to use this API key?", selecciona **Yes**.
  </Step>

  <Step title="Ejecuta el asistente de configuración">
    En tu terminal de Claude Code, escribe:

    ```
    /setup
    ```

    El asistente te guía por:

    1. **Bootstrap** — comprueba Node.js y dependencias
    2. **API key de Venice** — valida y guarda tu clave
    3. **Elección de canal** — elige WhatsApp, Telegram o ambos
    4. **Build del contenedor** — compila el contenedor Docker (tarda unos minutos la primera vez)
    5. **Auth de WhatsApp** — escanea el código QR con tu teléfono (si aplica)
    6. **Configuración de Telegram** — envía un mensaje a tu bot para que detecte tu chat
    7. **Palabra de activación** — prefijo que activa el bot (por defecto: `@Andy`)
    8. **Directorios montados** — elige "No" por ahora (puedes añadir acceso a archivos más tarde)
    9. **Iniciar servicios** — NanoClaw y el proxy de Venice se inician como servicios en segundo plano

    El asistente instala dos servicios en segundo plano:

    * **NanoClaw** — el propio bot
    * **Proxy de Venice** — un pequeño servidor local (localhost:4001) que traduce entre Claude Code y Venice AI

    Ambos se inician automáticamente al arrancar y se reinician si fallan.

    <Note>
      Si el asistente se detiene entre pasos, escribe "continue" o "next step" para empujarlo hacia adelante.
    </Note>
  </Step>

  <Step title="Empieza a chatear">
    Una vez completada la configuración, abre tu chat (Telegram o WhatsApp) y envía:

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

    El bot debería responder en segundos. En tu canal principal puedes escribir normalmente sin el prefijo `@Andy`.

    **Ya puedes cerrar la ventana del terminal.** Todo se ejecuta como servicios en segundo plano y se inicia automáticamente cuando arranca tu ordenador.
  </Step>
</Steps>

***

## Cómo funciona

Hay dos capas en NanoClaw:

| Capa                | Qué hace                                                           |
| ------------------- | ------------------------------------------------------------------ |
| **Claude Code CLI** | Herramienta admin para configuración, depuración y personalización |
| **El bot**          | IA en tu chat, ejecutándose dentro de un contenedor Docker aislado |

Para abrir Claude Code en cualquier momento:

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

Úsalo para ejecutar `/setup`, `/debug`, `/customize` o hacer cambios en el comportamiento del bot.

***

## Modelos

| Contexto        | Modelo predeterminado   | Cómo cambiar                                          |
| --------------- | ----------------------- | ----------------------------------------------------- |
| Bot (en chat)   | `claude-sonnet-4-6`     | Dile al bot: "switch to opus" o "use zai-org-glm-5"   |
| Claude Code CLI | `zai-org-glm-5` (GLM 5) | Usa `/model` en Claude Code o `claude --model <name>` |

<Tip>
  La CLI usa por defecto GLM 5 para mantener bajos los costes de configuración. Tras la configuración, cambia a `claude-sonnet-4-6` o `claude-opus-4-6` para el mejor rendimiento.
</Tip>

Consulta el [catálogo de modelos](/models/text) para todos los modelos de Venice disponibles.

***

## Resolución de problemas

<AccordionGroup>
  <Accordion title="El proxy no está en ejecución">
    El proxy de Venice se ejecuta como servicio en segundo plano y se reinicia automáticamente. Si no funciona:

    **macOS:**

    ```bash theme={"system"}
    # Comprobar si está corriendo
    launchctl list | grep venice-proxy

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

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

    **Linux:**

    ```bash theme={"system"}
    # Comprobar si está corriendo
    systemctl --user status nanoclaw-venice-proxy

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

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

  <Accordion title="Claude Code muestra error 403 o 'Please run /login'">
    Significa que Claude Code no puede conectar con el proxy de Venice.

    1. **Comprueba que el proxy esté corriendo.** Consulta el paso anterior.
    2. **Asegúrate de estar en la carpeta correcta.** Siempre `cd nanoclaw-venice` primero.
    3. **Empieza de cero:** cierra todos los terminales y ejecuta:
       ```bash theme={"system"}
       cd nanoclaw-venice
       ANTHROPIC_BASE_URL=http://localhost:4001 ANTHROPIC_API_KEY=venice-proxy claude
       ```
  </Accordion>

  <Accordion title="Errores de modelo ('model does not exist')">
    Reinicia el proxy y el 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
    ```

    Comprueba los modelos disponibles en el [catálogo de modelos](/models/text).
  </Accordion>

  <Accordion title="El bot no responde a los mensajes">
    Sigue estos pasos en orden:

    1. **Comprueba tu palabra de activación.** Asegúrate de usar el prefijo correcto (p. ej., `@Andy hello`).
    2. **Comprueba que Docker esté corriendo.** Ejecuta `docker info` — si da error, abre Docker Desktop.
    3. **Comprueba que el proxy esté corriendo.** Consulta "El proxy no está en ejecución" arriba.
    4. **Revisa los logs:** `tail -f logs/nanoclaw.log` en la carpeta del proyecto.
    5. **Revisa los logs del contenedor.** Abre la carpeta `nanoclaw-venice/groups/main/logs/`. Abre el archivo más reciente que empiece por `container-`.
    6. **Reinicia todo:** reinicia tanto proxy como bot (ver arriba).
  </Accordion>

  <Accordion title="El build del contenedor falla durante la configuración">
    Asegúrate de que Docker Desktop esté abierto y corriendo. Espera 10 segundos a que Docker arranque por completo, luego escribe `continue` en el asistente para reintentar.
  </Accordion>

  <Accordion title="WhatsApp desconectado">
    Tu sesión de WhatsApp puede expirar. Para reconectar:

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

    Escanea el código QR con WhatsApp (Settings → Linked Devices → Link a Device) y reinicia el bot:

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

***

## Avanzado

<AccordionGroup>
  <Accordion title="Dale al bot acceso a archivos de tu ordenador">
    Por defecto, el bot está completamente aislado de tu ordenador — solo puede ver su propia memoria y su historial de conversación.

    * **Durante la configuración:** cuando se te pregunte por acceso a directorios, elige "Yes"
    * **Tras la configuración:** ejecuta `/customize` en Claude Code
  </Accordion>

  <Accordion title="Iniciar/detener manualmente el bot">
    NanoClaw ejecuta dos servicios en segundo plano que se inician automáticamente al arrancar.

    **macOS:**

    | Acción          | Comando                                                                   |
    | --------------- | ------------------------------------------------------------------------- |
    | Iniciar bot     | `launchctl load ~/Library/LaunchAgents/com.nanoclaw.plist`                |
    | Detener 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`   |
    | Detener proxy   | `launchctl unload ~/Library/LaunchAgents/com.nanoclaw.venice-proxy.plist` |
    | Reiniciar proxy | `launchctl kickstart -k gui/$(id -u)/com.nanoclaw.venice-proxy`           |

    **Linux:**

    | Acción          | Comando                                          |
    | --------------- | ------------------------------------------------ |
    | Iniciar bot     | `systemctl --user start nanoclaw`                |
    | Detener bot     | `systemctl --user stop nanoclaw`                 |
    | Reiniciar bot   | `systemctl --user restart nanoclaw`              |
    | Iniciar proxy   | `systemctl --user start nanoclaw-venice-proxy`   |
    | Detener proxy   | `systemctl --user stop nanoclaw-venice-proxy`    |
    | Reiniciar proxy | `systemctl --user restart nanoclaw-venice-proxy` |
  </Accordion>

  <Accordion title="Usar Claude Code a través de Venice (sin bot)">
    Si solo quieres Claude Code con Venice y no necesitas WhatsApp/Telegram, el servicio proxy debe estar corriendo. Si ya has ejecutado `/setup`, ya está corriendo como servicio en segundo plano.

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

    **Tip:** añade esto a tu `~/.zshrc` (o `~/.bashrc`) para poder cambiar rápidamente cualquier terminal 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"'
    ```

    Después solo escribe `venice` en cualquier terminal antes de ejecutar `claude` para usar Venice, o `anthropic` para volver.
  </Accordion>

  <Accordion title="Ejecutar varios bots">
    Puedes ejecutar varios bots NanoClaw en la misma máquina (p. ej., uno para uso personal y otro para un equipo). Solo clona el repo en una carpeta diferente y ejecuta la configuración de nuevo. Nota: comparten la misma imagen Docker, así que reconstruir uno afecta a todos.
  </Accordion>

  <Accordion title="Comandos para desarrolladores">
    Para quienes quieran modificar el código de NanoClaw:

    ```bash theme={"system"}
    npm run dev          # Inicia proxy + NanoClaw con hot reload
    npm run proxy        # Inicia solo el proxy de Venice
    npm run build        # Compila TypeScript
    npm test             # Ejecuta tests
    ./container/build.sh # Reconstruye el contenedor del agente
    ```
  </Accordion>
</AccordionGroup>

***

## Arquitectura

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

| Archivo                    | Propósito                                                        |
| -------------------------- | ---------------------------------------------------------------- |
| `proxy/venice-proxy.ts`    | Traduce el formato de Anthropic al formato de OpenAI para Venice |
| `src/index.ts`             | Orquestador principal — bucle de mensajes, invocación de agente  |
| `src/channels/whatsapp.ts` | Conexión a WhatsApp vía baileys                                  |
| `src/channels/telegram.ts` | Bot de Telegram vía grammy                                       |
| `src/container-runner.ts`  | Lanza contenedores aislados de agente                            |

***

## FAQ

<AccordionGroup>
  <Accordion title="¿Por qué necesito un proxy?">
    El Claude Agent SDK habla el formato de mensajes de Anthropic. Venice habla el formato de OpenAI. El proxy traduce entre ambos para que todo funcione sin modificar el SDK.
  </Accordion>

  <Accordion title="¿Puedo usar modelos open-source?">
    Sí. Venice aloja muchos modelos. Dile al bot "switch to zai-org-glm-5" o cualquier ID de modelo de Venice. Consulta el [catálogo de modelos](/models/text).
  </Accordion>

  <Accordion title="¿Es seguro?">
    Los agentes se ejecutan en contenedores Docker con aislamiento real a nivel de SO. La API key de Venice se pasa por stdin, nunca se escribe en disco dentro de los contenedores. Cada grupo obtiene su propio entorno aislado.
  </Accordion>

  <Accordion title="¿Necesito una suscripción a Anthropic?">
    No. Todo se ejecuta a través de Venice AI. Solo necesitas una API key de Venice.
  </Accordion>

  <Accordion title="¿Puedo usar esto en un servidor?">
    Sí. Funciona en cualquier máquina Linux con Docker. Usa el servicio systemd para auto-arranque al iniciar.
  </Accordion>
</AccordionGroup>

***

## Recursos

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

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

  <Card title="Catálogo de modelos de Venice" icon="list" href="/models/text">
    Explora los modelos disponibles
  </Card>

  <Card title="Privacidad de Venice" icon="shield-halved" href="/overview/privacy">
    Cómo Venice protege tus datos
  </Card>
</CardGroup>