Tutorial de NanoClaw: crea un agente ligero y local-first

Los agentes de IA autónomos están cambiando la forma en que trabajamos con el software. En lugar de saltar entre apps y herramientas, puedes dar una orden de texto sencilla y dejar que el agente haga el trabajo por ti. Esto puede incluir crear recordatorios, ayudarte con el correo, apoyar la gestión de proyectos o echarte una mano con programación y redacción.

Herramientas como OpenClaw han hecho esta idea mucho más práctica. Demuestran lo que es posible cuando un agente de IA está siempre disponible en tu portátil o móvil. Al mismo tiempo, los sistemas de agentes más grandes pueden sentirse pesados, complejos y difíciles de gestionar. Pueden introducir problemas de seguridad, requerir más configuración y ser más de lo que necesitas para un flujo de trabajo personal y local.

Ahí es donde entra NanoClaw. NanoClaw es una alternativa más ligera y local-first, más fácil de ejecutar y de experimentar en tu propia máquina. También está diseñado pensando en la seguridad, usando aislamiento basado en Docker para mantener tu entorno contenido y tus datos protegidos.

En este tutorial, vas a configurar NanoClaw en Windows usando WSL y a preparar el entorno paso a paso. Instalarás las herramientas de sistema necesarias, configurarás Node.js, clonarás el repositorio de NanoClaw, conectarás la autenticación y pondrás el proyecto en marcha en local.

Para comparar estas dos herramientas de agentes, te recomiendo leer nuestra guía NanoClaw vs OpenClaw.

1. Configura WSL y tu entorno Linux

Antes de empezar, necesitas un PC con Windows 10/11 relativamente reciente que admita WSL 2 y virtualización por hardware, con suficiente RAM (al menos 4 GB, idealmente 8 GB o más) y espacio en disco (unos 20–30 GB libres) para ejecutar Docker Desktop y un entorno Ubuntu en WSL.

Empieza instalando WSL en Windows. Abre PowerShell como administrador y ejecuta:

wsl --install

Tras la instalación, reinicia si hace falta y comprueba tu configuración:

wsl --status

Tu distribución debe ejecutarse en WSL 2. Esto es importante porque Claude Code admite WSL en Windows, y Anthropic indica que el sandboxing funciona con WSL 2 mientras que WSL 1 no es compatible.

Cuando WSL esté listo, inicia Ubuntu:

wsl

Dentro de Ubuntu, actualiza el sistema e instala las herramientas básicas de desarrollo:

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential curl git wget

Con esto tendrás un entorno Linux limpio con las herramientas esenciales para el resto de la configuración.

2. Instala Node.js, Docker y Claude Code

Antes de instalar NanoClaw, necesitas preparar sus dependencias. 

En esta parte, instalarás Node.js para poder ejecutar las herramientas JavaScript del proyecto, te asegurarás de que Docker esté disponible dentro de WSL para que NanoClaw use contenedores aislados e instalarás Claude Code, que utilizarás para ejecutar la configuración guiada de NanoClaw.

Instala Node.js con NVM

La forma más sencilla de instalar Node.js en WSL es con NVM, el gestor de versiones de Node. Te da una manera limpia y flexible de gestionar versiones de Node sin depender del gestor de paquetes del sistema.

Ejecuta estos comandos en tu terminal de Ubuntu:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
\. "$HOME/.nvm/nvm.sh"
nvm install 24
node -v
npm -v

Después deberías ver una salida similar a:

v24.14.1
11.11.0

Node.js es necesario porque NanoClaw usa una configuración y flujo de dependencias basados en JavaScript. Instalarlo con NVM es útil porque mantiene tu entorno más fácil de gestionar. Si en algún momento necesitas cambiar de versión o reinstalar Node, podrás hacerlo sin afectar al resto de tu sistema Linux.

Asegúrate de que Docker funciona dentro de WSL

NanoClaw se ejecuta de forma más segura y controlada usando aislamiento por contenedores con Docker. Eso significa que Docker debe estar instalado en Windows y correctamente conectado a tu entorno WSL.

Primero, descarga Docker Desktop desde la web de Docker e instálalo en Windows. Luego abre Docker Desktop, ve a Settings, asegúrate de que la opción Use the WSL 2-based engine esté activada y, en Resources → WSL Integration, habilita la integración para tu distro de Ubuntu.

Cuando termines, vuelve a tu terminal de Ubuntu y ejecuta:

docker --version
docker ps

Deberías ver una salida parecida a esta:

Docker version 29.1.3, build f52814d
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Buena señal: significa que Docker está disponible dentro de WSL y listo para que NanoClaw lo use.

Instala Claude Code en Ubuntu

Con Node y Docker listos, el siguiente paso es instalar Claude Code dentro de WSL. Esta es la interfaz que usarás para completar la configuración guiada de NanoClaw.

Ejecuta:

curl -fsSL https://claude.ai/install.sh | bash

Esto instala Claude Code directamente en tu entorno de Ubuntu.

3. Instala NanoClaw desde su código fuente

Con el entorno listo, toca descargar NanoClaw y abrirlo en Claude Code.

Empieza clonando el repositorio y accediendo a la carpeta del proyecto:

git clone https://github.com/qwibitai/nanoclaw.git
cd nanoclaw

Si planeas personalizar NanoClaw más adelante, puedes hacer un fork del repositorio primero y clonar tu propia copia. Para una primera configuración, clonar el repositorio principal es totalmente válido.

Una vez dentro de la carpeta nanoclaw, ejecuta:

claude

La primera vez que inicies Claude Code, te guiará por el flujo inicial de acceso y configuración. Puedes iniciar sesión con una cuenta de Claude.ai o usar acceso directo a la API de Anthropic con una clave de API.

Si ya tienes una suscripción a Claude Pro o Max, iniciar sesión suele ser la vía más simple. Si trabajas con facturación por API, también puedes configurar Claude Code para que use tu clave de la API de Anthropic.

Cuando completes el acceso, Claude Code se abrirá dentro de tu proyecto NanoClaw y podrás continuar con la configuración.

4. Configura NanoClaw

Con Claude Code abierto dentro de la carpeta nanoclaw, ya puedes iniciar la configuración completa.

Ejecuta:

/setup

Esto inicia el asistente de configuración de NanoClaw.

Qué ocurre durante la configuración

En cuanto ejecutes /setup, Claude Code empezará a preparar NanoClaw por ti. Esta parte puede tardar un poco, así que deja que complete cada fase.

Primero, instala las dependencias del proyecto y comprueba que tu entorno local está listo. 

Después pasa a la fase de configuración de contenedores, donde ejecuta los comandos de Docker necesarios para construir el contenedor personalizado de NanoClaw y comprobar que arranca correctamente.

Una vez construido y verificado el contenedor, el asistente continúa instalando OneCLI. Esta es una parte importante de la pila de NanoClaw porque ayuda a gestionar secretos y el acceso a contenedores de forma más segura.

Cuando termine, puedes abrir el panel de Docker Desktop y confirmar que los contenedores están en ejecución. A estas alturas deberías ver allí los servicios de NanoClaw, incluido el contenedor de la app y servicios de soporte como PostgreSQL.

Configura el token de Claude para OneCLI

Aunque Claude Code ya haya iniciado sesión dentro de WSL, el contenedor de NanoClaw necesita su propia forma segura de acceder a Claude. Para ello, debes generar un token y registrarlo en OneCLI.

Abre un terminal nuevo y ejecuta:

claude setup-token

Este comando generará un enlace para abrir en tu navegador. Inicia sesión, aprueba la solicitud y pega el código devuelto en el terminal. Después, Claude Code te dará un token.

Copia ese token y ejecuta el siguiente comando en tu terminal, sustituyendo YOUR_TOKEN por el token que acabas de generar:

onecli secrets create --name Anthropic --type anthropic --value YOUR_TOKEN --host-pattern api.anthropic.com

Este paso da al contenedor de NanoClaw acceso seguro a Claude sin exponer directamente tus credenciales dentro del contenedor. Con esto listo, la configuración está preparada para la siguiente fase.

5. Configura WhatsApp para NanoClaw

Tras completar la configuración principal, Claude Code pasará a la fase de configuración de canales. Aquí eliges cómo quieres interactuar con NanoClaw.

Genera el código QR para WhatsApp

Selecciona WhatsApp (también puedes marcar otros canales compatibles como Discord, Telegram o Slack para más adelante, pero ahora nos centraremos en WhatsApp) y continúa.

Por alguna razón, el código QR en el navegador no me funcionó. Parecía un problema de red entre WSL y el navegador, probablemente relacionado con cómo se accedía al puerto local. Por eso, usaremos la opción de generar el código QR en el terminal.

Claude Code intentará mostrar un código QR en el terminal. En algunos casos, puede cortarse o no mostrarse correctamente.

Para solucionarlo, abre un nuevo terminal y ejecuta:

cd nanoclaw
npm run auth

Esto generará un código QR limpio en tu terminal.

Conecta WhatsApp en tu móvil

Ahora abre WhatsApp en tu teléfono y sigue estos pasos:

• Ve a Ajustes
• Toca Dispositivos vinculados
• Toca Vincular un dispositivo
• Escanea el código QR que aparece en tu terminal

Cuando el escaneo se complete, tu cuenta de WhatsApp quedará conectada a NanoClaw.

Tras el emparejamiento, deberías ver un mensaje de éxito en el terminal.

Completa la configuración del canal en Claude Code

Vuelve a tu terminal original de Claude Code y continúa con la configuración.

Se te harán algunas preguntas de configuración. Por ahora, puedes elegir las opciones recomendadas.

• Mantén la palabra de activación por defecto
• Mantén el nombre del asistente por defecto
• Selecciona el modo self-chat

El modo self-chat hace que NanoClaw solo te responda a ti en tu propio chat de WhatsApp. Es útil para pruebas, ya que nadie más puede interactuar con tu agente.

Finaliza la configuración y haz una prueba

Cuando todo esté configurado, NanoClaw recompilará el contenedor con tus nuevos ajustes. Puede tardar unos minutos.

Después verás instrucciones sobre cómo usar NanoClaw.

Para probarlo:

• Abre WhatsApp
• Busca tu propio número (tu self-chat)
• Envía un mensaje como:

@Andy hello

Si todo funciona correctamente, NanoClaw responderá en tu chat.

6. Prueba NanoClaw con WhatsApp

Ahora que todo está configurado, puedes probar NanoClaw directamente desde WhatsApp.

Abre WhatsApp en tu teléfono y ve a tu propio chat. Aparecerá como tu número con “(Tú)” entre paréntesis. Empieza con un mensaje sencillo como:

@Andy how are you?

En unos segundos, NanoClaw debería responder en el chat. Esto confirma que tu configuración funciona correctamente y que el agente está conectado a WhatsApp.

También puedes probar cómo funciona el disparador. Intenta enviar un mensaje sin la palabra de activación, por ejemplo:

How are you?

Verás que NanoClaw no responde. Es el comportamiento esperado: la palabra de activación garantiza que el agente solo se active cuando lo invoques explícitamente.

Cuando la mensajería básica funcione, prueba una tarea más avanzada. Por ejemplo, pide:

@Andy Tell me the latest gold and silver prices and should i buy it or not

NanoClaw realizará la tarea y devolverá una respuesta estructurada. Así verás que tu agente no solo responde mensajes, sino que también puede ejecutar tareas de varios pasos y ofrecer resultados útiles cuando está configurado con las herramientas adecuadas, como la búsqueda web.

A estas alturas, tu configuración de NanoClaw está completamente operativa y lista para casos de uso más avanzados.

Los precios del oro y la plata eran incorrectos, lo que sugiere que no realizó realmente una búsqueda web y se basó en información desactualizada del conocimiento interno del modelo.

Reflexiones finales

Configurar NanoClaw me llevó bastante más tiempo del esperado, especialmente en Windows con WSL. Entre Docker, la configuración de contenedores, varios servicios de soporte y la cantidad de permisos que tuve que ir aprobando en Claude Code, el proceso se sintió más pesado de lo que debería para un agente local ligero. Al cabo de un rato, los avisos y aprobaciones constantes resultaron cansinos, y la experiencia general de instalación no me pareció amigable para principiantes.

El flujo de instalación tampoco fue tan fluido como esperaba. En varios momentos, Claude Code me pidió abrir nuevos terminales, ejecutar comandos extra de autenticación, generar tokens y registrarlos manualmente en OneCLI. Si eres nuevo en herramientas de IA, contenedores o flujos de trabajo por línea de comandos, esta parte puede volverse confusa rápidamente. Se puede hacer, pero exige más esfuerzo manual del que muchos usuarios seguramente esperan.

Por eso, personalmente preferí Nanobot. Tardé solo unos minutos en empezar a enviar mensajes a mi agente desde WhatsApp, y la experiencia fue mucho más rápida y directa. Con NanoClaw, la relación esfuerzo‑resultado no me pareció tan buena.

La experiencia en WhatsApp también necesita mejoras. Las respuestas funcionaban, pero la interacción fue tosca. No había un indicador claro de escritura o de que estuviera respondiendo, y la burbuja de respuesta se veía igual que mis propios mensajes, lo que hacía la conversación menos natural. Una distinción visual más clara y alguna señal de que el agente está trabajando marcarían una gran diferencia, especialmente cuando las respuestas tardan.

En general, sigo pensando que la idea detrás de NanoClaw es sólida. Un agente seguro, local-first y ligero es una dirección muy útil. Pero en la práctica, la configuración fue más compleja de lo esperado y la experiencia final se sintió algo decepcionante en comparación con el esfuerzo necesario para llegar hasta ahí.