Tutorial NanoClaw: construa um agente leve com foco no local

Agentes autônomos de IA estão mudando a forma como trabalhamos com software. Em vez de alternar entre apps e ferramentas, você pode dar um comando de texto simples e deixar o agente executar a tarefa para você. Isso pode incluir definir lembretes, ajudar com e-mails, apoiar o gerenciamento de projetos ou auxiliar em código e escrita.

Ferramentas como o OpenClaw tornaram essa ideia muito mais prática. Elas mostram o que é possível quando um agente de IA está sempre disponível no seu laptop ou celular. Ao mesmo tempo, sistemas de agentes maiores podem parecer pesados, complexos e difíceis de gerenciar. Eles podem introduzir preocupações de segurança, exigir mais configuração e ir além do necessário para um fluxo de trabalho pessoal e local.

É aí que entra o NanoClaw. O NanoClaw é uma alternativa mais leve, com foco no local, mais fácil de rodar e de experimentar na sua própria máquina. Ele também foi projetado com segurança em mente, usando isolamento baseado em Docker para manter seu ambiente contido e seus dados protegidos.

Neste tutorial, você vai configurar o NanoClaw no Windows usando WSL e preparar o ambiente passo a passo. Vai instalar as ferramentas de sistema necessárias, configurar o Node.js, clonar o repositório do NanoClaw, conectar a autenticação e colocar o projeto para rodar localmente.

Para uma comparação entre as duas ferramentas de agentes, recomendo ler nosso guia NanoClaw vs OpenClaw.

1. Configure o WSL e seu ambiente Linux

Antes de começar, você vai precisar de um PC Windows 10/11 relativamente recente que suporte o WSL 2 e virtualização por hardware, tenha memória suficiente (mínimo de 4 GB, idealmente 8 GB ou mais) e espaço em disco (cerca de 20–30 GB livres) para rodar o Docker Desktop e um ambiente Ubuntu no WSL.

Comece instalando o WSL no Windows. Abra o PowerShell como Administrador e execute:

wsl --install

Depois da instalação, reinicie se necessário e verifique sua configuração:

wsl --status

Você quer que sua distribuição esteja rodando no WSL 2. Isso é importante porque o Claude Code oferece suporte ao WSL no Windows, e a Anthropic informa que o sandbox funciona com WSL 2, enquanto o WSL 1 não é suportado.

Quando o WSL estiver pronto, inicie o Ubuntu:

wsl

Dentro do Ubuntu, atualize o sistema e instale as ferramentas básicas de desenvolvimento:

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

Isso garante um ambiente Linux limpo com as ferramentas essenciais para o restante da configuração.

2. Instale Node.js, Docker e Claude Code

Antes de instalar o próprio NanoClaw, você precisa preparar as ferramentas das quais ele depende. 

Nesta parte, você vai instalar o Node.js para que o projeto rode suas ferramentas em JavaScript, garantir que o Docker esteja disponível dentro do WSL para que o NanoClaw use contêineres isolados, e instalar o Claude Code, que será usado para executar a configuração guiada do NanoClaw.

Instale o Node.js com NVM

A forma mais simples de instalar o Node.js no WSL é com o NVM, o Node Version Manager. Ele oferece uma maneira limpa e flexível de gerenciar versões do Node sem depender do gerenciador de pacotes do sistema.

Execute os comandos abaixo dentro do seu terminal do 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

Depois disso, você deve ver uma saída semelhante a:

v24.14.1
11.11.0

O Node.js é necessário porque o NanoClaw usa um fluxo de configuração e dependências baseado em JavaScript. Instalá-lo via NVM é útil porque mantém seu ambiente mais fácil de gerenciar depois. Se um dia você precisar trocar de versão ou reinstalar o Node, poderá fazê-lo sem afetar o restante do seu setup Linux.

Verifique se o Docker funciona dentro do WSL

O NanoClaw roda de forma mais segura e controlada usando isolamento por contêineres via Docker. Isso significa que o Docker precisa estar instalado no Windows e corretamente integrado ao seu ambiente WSL.

Primeiro, baixe o Docker Desktop no site da Docker e instale no Windows. Depois, abra o Docker Desktop, vá em Settings, garanta que a opção Use the WSL 2-based engine esteja habilitada e, em Resources → WSL Integration, ative a integração para a sua distro Ubuntu.

Feito isso, volte ao terminal do Ubuntu e execute:

docker --version
docker ps

Você deve ver uma saída semelhante a:

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

Ótimo sinal. Isso indica que o Docker está disponível dentro do WSL e pronto para ser usado pelo NanoClaw.

Instale o Claude Code no Ubuntu

Com Node e Docker prontos, o próximo passo é instalar o Claude Code dentro do WSL. Essa é a interface que você usará para concluir a configuração guiada do NanoClaw.

Execute:

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

Isso instala o Claude Code diretamente no seu ambiente Ubuntu.

3. Instale o NanoClaw a partir do código-fonte

Com o ambiente pronto, é hora de baixar o NanoClaw e abri-lo no Claude Code.

Comece clonando o repositório e entrando na pasta do projeto:

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

Se você pretende personalizar o NanoClaw depois, pode fazer um fork do repositório primeiro e clonar a sua própria cópia. Para uma primeira configuração, clonar o repositório principal é totalmente aceitável.

Quando estiver dentro da pasta nanoclaw, execute:

claude

Na primeira execução, o Claude Code vai orientar você pelo fluxo inicial de login e configuração. Você pode entrar com uma conta do Claude.ai ou usar acesso direto à API da Anthropic com uma chave de API.

Se você já tem uma assinatura Claude Pro ou Max, o login costuma ser o caminho mais simples. Se estiver trabalhando com cobrança por API, o Claude Code também pode ser configurado para usar sua chave de API da Anthropic.

Concluída a autenticação, o Claude Code abrirá dentro do seu projeto NanoClaw e você estará pronto para continuar a configuração.

4. Configure o NanoClaw

Com o Claude Code aberto dentro da pasta nanoclaw, você já pode iniciar a configuração completa.

Execute:

/setup

Isso inicia o fluxo de configuração guiada do NanoClaw.

O que acontece durante a configuração

Assim que você roda /setup, o Claude Code começa a preparar o NanoClaw para você. Essa etapa pode levar um tempo, então deixe que ele conclua cada fase.

Primeiro, ele instala as dependências do projeto e verifica se o seu ambiente local está pronto. 

Depois, segue para a etapa de configuração do contêiner, executando os comandos do Docker necessários para compilar o contêiner customizado do NanoClaw e testar se ele inicia corretamente.

Com o contêiner compilado e verificado, a configuração continua instalando o OneCLI. Essa é uma parte importante da stack do NanoClaw porque ajuda a gerenciar segredos e o acesso ao contêiner com mais segurança.

Depois disso, você pode abrir o painel do Docker Desktop e confirmar que os contêineres estão rodando. Neste ponto, você deve ver os serviços do NanoClaw por lá, incluindo o contêiner do app e serviços de suporte como o PostgreSQL.

Configure o token do Claude para o OneCLI

Mesmo que o Claude Code já esteja autenticado dentro do WSL, o contêiner do NanoClaw precisa de uma forma própria e segura para acessar o Claude. Para isso, você precisa gerar um token e registrá-lo no OneCLI.

Abra um novo terminal e execute:

claude setup-token

Esse comando vai gerar um link para você abrir no navegador. Faça login, aprove a solicitação e depois cole o código retornado no terminal. Em seguida, o Claude Code vai fornecer um token.

Copie esse token e execute o seguinte comando no terminal, substituindo YOUR_TOKEN pelo token que você acabou de gerar:

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

Essa etapa concede ao contêiner do NanoClaw acesso seguro ao Claude sem expor diretamente suas credenciais dentro do contêiner. Concluído isso, o setup está pronto para a próxima fase.

5. Configure o WhatsApp para o NanoClaw

Depois que a configuração principal termina, o Claude Code avança para a etapa de configuração de canais. É aqui que você escolhe como quer interagir com o NanoClaw.

Gere o QR Code para o WhatsApp

Selecione WhatsApp (você também pode selecionar outros canais compatíveis como Discord, Telegram ou Slack para depois, mas vamos focar no WhatsApp por agora) e continue.

Por algum motivo, o QR code no navegador não funcionou para mim. Parece ter sido causado por um problema de rede entre o WSL e o navegador, provavelmente relacionado à forma como a porta local estava sendo acessada. Por isso, vamos usar a opção de QR code direto no terminal.

O Claude Code vai tentar exibir um QR code no terminal. Em alguns casos, esse QR pode ficar cortado ou não aparecer corretamente.

Para corrigir, abra um novo terminal e execute:

cd nanoclaw
npm run auth

Isso vai gerar um QR code limpo no seu terminal.

Conecte o WhatsApp no seu celular

Agora, abra o WhatsApp no seu celular e siga estes passos:

• Vá em Configurações
• Toque em Aparelhos conectados
• Toque em Conectar um aparelho
• Escaneie o QR code exibido no seu terminal

Quando a leitura for concluída com sucesso, sua conta do WhatsApp estará conectada ao NanoClaw.

Após o pareamento, você deve ver uma mensagem de sucesso no terminal.

Conclua a configuração de canais no Claude Code

Volte ao terminal original do Claude Code e continue a configuração.

Algumas perguntas de configuração serão feitas. Por enquanto, você pode escolher as opções recomendadas.

• Mantenha a palavra de ativação padrão
• Mantenha o nome do assistente padrão
• Selecione o modo de autochat

O modo autochat significa que o NanoClaw só vai responder a você no seu próprio chat do WhatsApp. Isso é útil para testes, já que ninguém mais poderá interagir com o seu agente.

Finalize a configuração e teste

Quando tudo estiver configurado, o NanoClaw vai recompilar o contêiner com as suas novas definições. Isso pode levar alguns instantes.

Em seguida, você verá instruções de como usar o NanoClaw.

Para testar:

• Abra o WhatsApp
• Procure pelo seu próprio número (seu autochat)
• Envie uma mensagem como:

@Andy hello

Se tudo estiver funcionando, o NanoClaw vai responder no seu chat.

6. Teste o NanoClaw com o WhatsApp

Agora que está tudo configurado, você pode testar o NanoClaw direto pelo WhatsApp.

Abra o WhatsApp no seu celular e vá ao seu próprio chat. Ele aparece como o seu número com “(Você)” entre parênteses. Comece com uma mensagem simples como:

@Andy how are you?

Em poucos segundos, o NanoClaw deve responder no chat. Isso confirma que sua configuração está correta e que o agente está conectado ao WhatsApp.

Você também pode testar como funciona a palavra de ativação. Tente enviar uma mensagem sem a palavra de ativação, como:

How are you?

Você deve notar que o NanoClaw não responde. Isso é o comportamento esperado. A palavra de ativação garante que o agente só entre em ação quando você chamá-lo explicitamente.

Quando as mensagens básicas estiverem funcionando, tente uma tarefa mais avançada. Por exemplo, peça:

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

O NanoClaw vai executar a tarefa e retornar uma resposta estruturada. Isso mostra que o seu agente não está apenas respondendo mensagens, mas também consegue realizar tarefas em múltiplas etapas e entregar resultados úteis quando configurado com as ferramentas certas, como busca na web.

Neste ponto, sua configuração do NanoClaw está totalmente funcional e pronta para casos de uso mais avançados.

Os preços do ouro e da prata estavam incorretos, o que sugere que ele não fez uma busca na web de fato e, em vez disso, confiou em informações desatualizadas do próprio modelo.

Considerações finais

Configurar o NanoClaw levou bem mais tempo do que eu esperava, especialmente no Windows com WSL. Entre Docker, setup de contêiner, vários serviços de suporte e a quantidade de permissões que precisei aprovar dentro do Claude Code, o processo pareceu mais pesado do que um agente local leve deveria ser. Depois de um tempo, os prompts e aprovações constantes ficaram cansativos, e a experiência geral de setup não pareceu amigável para iniciantes.

O fluxo de instalação também não foi tão suave quanto eu esperava. Em vários momentos, o Claude Code me pediu para abrir novos terminais, rodar comandos extras de autenticaçãods, gerar tokens e registrá-los manualmente no OneCLI. Se você é novo em ferramentas de IA, contêineres ou fluxos de trabalho em linha de comando, essa parte pode se tornar confusa rapidamente. É possível fazer, mas exige mais esforço manual do que muitos usuários provavelmente esperam.

Por isso, pessoalmente eu preferi o Nanobot. Levei só alguns minutos para começar a enviar mensagens ao meu agente pelo WhatsApp, e a experiência pareceu muito mais rápida e direta. No caso do NanoClaw, a relação esforço-resultado não me pareceu tão boa.

A experiência no WhatsApp em si também precisa melhorar. As respostas funcionaram, mas a interação pareceu áspera. Não havia um indicador claro de digitando ou respondendo, e a bolha de resposta tinha a mesma aparência das minhas próprias mensagens, o que deixou a conversa menos natural. Uma distinção visual mais clara e algum feedback de que o agente está trabalhando fariam bastante diferença, principalmente quando as respostas demoram.

No geral, ainda acho a proposta do NanoClaw muito boa. Um agente leve, seguro e com foco no local é um caminho bem útil. Mas, na prática, a configuração foi mais complexa do que o esperado, e a experiência final ficou um pouco aquém considerando o esforço necessário para chegar lá.