nanoclaw v2.1.54

Um assistente de IA que executa agentes de forma segura em seus próprios contêineres. Leve, projetado para ser facilmente compreendido e completamente personalizado para suas necessidades.

nanoclaw.dev  •   docs  •   中文  •   日本語  •   한국어  •     •  

Por que construí o NanoClaw

O OpenClaw é um projeto impressionante, mas eu não conseguiria dormir se tivesse dado a um software complexo que não entendo acesso total à minha vida. O OpenClaw tem quase meio milhão de linhas de código, 53 arquivos de configuração e mais de 70 dependências. Sua segurança está no nível da aplicação (listas de permissão, códigos de emparelhamento) em vez de isolamento real em nível de sistema operacional. Tudo roda em um único processo Node com memória compartilhada.

O NanoClaw oferece a mesma funcionalidade principal, mas em uma base de código pequena o suficiente para ser compreendida: um processo e um punhado de arquivos. Os agentes rodam em seus próprios contêineres Linux com isolamento de sistema de arquivos, não apenas atrás de verificações de permissão.

Início Rápido

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash nanoclaw.sh

nanoclaw.sh guia você desde uma máquina nova até um agente nomeado com quem você pode trocar mensagens. Ele instala Node, pnpm e Docker se estiverem faltando, registra sua credencial Anthropic com o OneCLI, constrói o contêiner do agente e emparelha seu primeiro canal (Telegram, Discord, WhatsApp ou um CLI local). Se alguma etapa falhar, o Claude Code é invocado automaticamente para diagnosticar e retomar de onde parou.

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2
cd nanoclaw-v2
bash migrate-v2.sh

Filosofia

Pequeno o suficiente para entender. Um processo, alguns arquivos fonte e sem microsserviços. Se você quiser entender toda a base de código do NanoClaw, basta pedir ao Claude Code para guiá-lo por ela.

Seguro pelo isolamento. Os agentes rodam em contêineres Linux e só podem ver o que está explicitamente montado. O acesso ao Bash é seguro porque os comandos são executados dentro do contêiner, não no seu host.

Construído para o usuário individual. O NanoClaw não é um framework monolítico; é um software que se adapta exatamente às necessidades de cada usuário. Em vez de se tornar um software inchado, o NanoClaw é projetado para ser sob medida. Você cria seu próprio fork e pede ao Claude Code para modificá-lo de acordo com suas necessidades.

Personalização = mudanças no código. Sem proliferação de configurações. Quer um comportamento diferente? Modifique o código. A base de código é pequena o suficiente para que seja seguro fazer alterações.

Nativo de IA, híbrido por design. O fluxo de instalação e integração é um caminho scriptado otimizado, rápido e determinístico. Quando uma etapa precisa de julgamento — seja uma instalação falha, uma decisão guiada ou uma personalização — o controle é transferido perfeitamente para o Claude Code. Além da configuração, também não há painel de monitoramento ou interface de depuração: descreva o problema no chat e o Claude Code cuida dele.

Habilidades em vez de recursos. O tronco contém o registro e a infraestrutura, não adaptadores de canal específicos ou provedores de agentes alternativos. Canais (Discord, Slack, Telegram, WhatsApp, …) ficam em um branch channels de longa duração; provedores alternativos (OpenCode, Ollama) ficam em providers. Você executa /add-telegram, /add-opencode, etc., e a habilidade copia exatamente o(s) módulo(s) que você precisa para o seu fork. Nenhum recurso que você não pediu.

Melhor harness, melhor modelo. O NanoClaw usa nativamente o Claude Code através do SDK oficial do Claude Agent da Anthropic, então você obtém os modelos Claude mais recentes e o conjunto completo de ferramentas do Claude Code, incluindo a capacidade de modificar e expandir seu próprio fork do NanoClaw. Outros provedores são opções plug-in: /add-codex para o Codex da OpenAI (assinatura ChatGPT ou chave de API), /add-opencode para OpenRouter, Google, DeepSeek e mais via OpenCode, e /add-ollama-provider para modelos locais de peso aberto. O provedor é configurável por grupo de agente.

O que ele suporta

• Mensagens multicanal — WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat e e-mail via Resend. Instalados sob demanda com habilidades /add-<canal>. Execute um ou vários ao mesmo tempo.
• Isolamento flexível — conecte cada canal ao seu próprio agente para privacidade total, compartilhe um agente entre muitos canais para memória unificada com conversas separadas, ou agrupe vários canais em uma única sessão compartilhada para que uma conversa abranja várias superfícies. Escolha por canal via /manage-channels. Consulte docs/isolation-model.md.
• Espaço de trabalho por agente — cada grupo de agente tem seu próprio CLAUDE.md, sua própria memória, seu próprio contêiner e apenas as montagens que você permitir. Nada cruza o limite a menos que você o conecte.
• Tarefas agendadas: trabalhos recorrentes executados pelo agente, com portões de script opcionais que evitam acordá-lo quando não há trabalho.
• Acesso à web — pesquise e obtenha conteúdo da web.
• Isolamento em contêiner — agentes são isolados em contêineres Docker (macOS/Linux/WSL2).
• Segurança de credenciais — agentes nunca armazenam chaves de API brutas. Requisições de saída passam pelo Agent Vault do OneCLI, que injeta credenciais no momento da requisição e aplica políticas por agente e limites de taxa.
• Modelos de agente: crie um agente pronto para uso (instruções + ferramentas MCP + habilidades, sem segredos) a partir de um pacote reutilizável via ncl groups create --template <ref>. Os modelos são carregados da pasta local templates/; preencha-a manualmente ou copiando da biblioteca pública. Consulte docs/templates.md.

Uso

Converse com seu assistente usando a palavra de ativação (padrão: @Andy):

@Andy envie uma visão geral do pipeline de vendas toda manhã de dia de semana às 9h (tem acesso à minha pasta do Obsidian)
@Andy revise o histórico do git da última semana toda sexta-feira e atualize o README se houver divergência
@Andy toda segunda às 8h, compile notícias sobre desenvolvimentos de IA do Hacker News e TechCrunch e me envie um resumo

A partir de um canal que você possui ou administra, você pode gerenciar grupos e tarefas:

@Andy liste todas as tarefas agendadas em todos os grupos
@Andy pause a tarefa de briefing de segunda-feira
@Andy entre no grupo Family Chat

Personalizando

O NanoClaw não usa arquivos de configuração. Para fazer alterações, basta dizer ao Claude Code o que você quer:

• "Altere a palavra de ativação para @Bob"
• "Lembre-se no futuro de tornar as respostas mais curtas e diretas"
• "Adicione uma saudação personalizada quando eu disser bom dia"
• "Armazene resumos de conversas semanalmente"

Ou execute /customize para alterações guiadas.

A base de código é pequena o suficiente para o Claude modificá-la com segurança.

Contribuindo

Não adicione recursos. Adicione habilidades.

Se você quiser adicionar um novo canal ou provedor de agente, não o adicione ao tronco. Novos adaptadores de canal vão para o branch channels; novos provedores de agente vão para providers. Os usuários os instalam em seu próprio fork com habilidades /add-<nome>, que copiam o(s) módulo(s) relevante(s) para os caminhos padrão, conectam o registro e fixam as dependências.

Isso mantém o tronco como registro e infraestrutura puros, e cada fork permanece enxuto — os usuários obtêm os canais e provedores que pediram e nada mais.

RFS (Request for Skills – Solicitação de Habilidades)

Nenhuma habilidade de canal ou provedor é solicitada no momento — proponha uma através de uma issue.

Requisitos

• macOS ou Linux (Windows via WSL2)
• Node.js 20+ e pnpm 10+ (o instalador instalará ambos se estiverem faltando)
• Docker Desktop (macOS/Windows) ou Docker Engine (Linux)
• Claude Code para /customize, /debug, recuperação de erros durante a configuração e todas as habilidades /add-<canal>

Arquitetura

aplicativos de mensagens → processo host (roteador) → inbound.db → contêiner (Bun, Claude Agent SDK) → outbound.db → processo host (entrega) → aplicativos de mensagens

Um único host Node orquestra contêineres de agente por sessão. Quando uma mensagem chega, o host a roteia através do modelo de entidade (usuário → grupo de mensagens → grupo de agente → sessão), escreve-a no inbound.db da sessão e ativa o contêiner. O executor do agente dentro do contêiner consulta inbound.db, executa o agente e escreve as respostas no outbound.db. O host consulta outbound.db e entrega de volta através do adaptador de canal.

Dois arquivos SQLite por sessão, cada um com exatamente um escritor — sem contenção entre montagens, sem IPC, sem piping de stdin. Canais e provedores alternativos se registram automaticamente na inicialização; o tronco contém o registro e a ponte do Chat SDK, enquanto os próprios adaptadores são instalados como habilidades por fork.

Para a descrição completa da arquitetura, consulte docs/architecture.md; para o modelo de isolamento de três níveis, consulte docs/isolation-model.md.

Arquivos principais:

• src/index.ts — ponto de entrada: inicialização do DB, adaptadores de canal, consultas de entrega, sweep
• src/router.ts — roteamento de entrada: grupo de mensagens → grupo de agente → sessão → inbound.db
• src/delivery.ts — consulta outbound.db, entrega via adaptador, trata ações do sistema
• src/host-sweep.ts — sweep a cada 60s: detecção de inatividade, ativação por mensagem pendente, recorrência
• src/session-manager.ts — resolve sessões, abre inbound.db / outbound.db
• src/container-runner.ts — cria contêineres por grupo de agente, injeção de credenciais OneCLI
• src/db/ — DB central (usuários, funções, grupos de agente, grupos de mensagens, conexões, migrações)
• src/channels/ — infraestrutura de adaptadores de canal (adaptadores instalados via habilidades /add-<canal>)
• src/providers/ — configuração do provedor no host (claude embutido; outros via habilidades)
• container/agent-runner/ — executor do agente em Bun: loop de consulta, ferramentas MCP, abstração de provedor
• groups/<pasta>/ — sistema de arquivos por grupo de agente (CLAUDE.md, habilidades, configuração do contêiner)

FAQ

Por que Docker?

O Docker oferece suporte multiplataforma (macOS, Linux e Windows via WSL2) e um ecossistema maduro.

Posso executar isso no Linux ou Windows?

Sim. O Docker é o runtime padrão e funciona em macOS, Linux e Windows (via WSL2). Basta executar bash nanoclaw.sh.

Isso é seguro?

Os agentes são executados em contêineres, não atrás de verificações de permissão em nível de aplicação. Eles só podem acessar diretórios explicitamente montados. As credenciais nunca entram no contêiner — as requisições de API de saída passam pelo Agent Vault do OneCLI, que injeta autenticação no nível do proxy e suporta limites de taxa e políticas de acesso. Você ainda deve revisar o que está executando, mas a base de código é pequena o suficiente para que você realmente possa. Consulte a documentação de segurança para o modelo de segurança completo.

Por que não há arquivos de configuração?

Não queremos proliferação de configurações. Cada usuário deve personalizar o NanoClaw para que o código faça exatamente o que ele deseja, em vez de configurar um sistema genérico. Se você preferir ter arquivos de configuração, pode pedir ao Claude para adicioná-los.

Posso usar modelos de terceiros ou de código aberto?

Sim. O caminho suportado é /add-opencode (OpenRouter, OpenAI, Google, DeepSeek e mais via configuração do OpenCode) ou /add-ollama-provider (modelos locais de peso aberto via Ollama). Ambos são configuráveis por grupo de agente, então diferentes agentes podem rodar em diferentes backends na mesma instalação.

Para experimentos pontuais, qualquer endpoint compatível com a API Claude também funciona via .env:

ANTHROPIC_BASE_URL=https://seu-endpoint-api.com
ANTHROPIC_AUTH_TOKEN=seu-token-aqui

Como depuro problemas?

Pergunte ao Claude Code. "Por que o agendador não está rodando?" "O que está nos logs recentes?" "Por que esta mensagem não recebeu resposta?" Essa é a abordagem nativa de IA que fundamenta o NanoClaw.

Por que a configuração não está funcionando para mim?

Se uma etapa falhar, nanoclaw.sh transfere o controle para o Claude Code para diagnosticar e retomar. Se isso não resolver, execute claude e depois /debug. Se o Claude identificar um problema que provavelmente afeta outros usuários, abra um PR contra a etapa de configuração ou habilidade relevante.

Como desinstalo o NanoClaw?

bash nanoclaw.sh --uninstall

Cada instalação é marcada com um ID por checkout, então o desinstalador remove apenas o que pertence àquela cópia: o serviço em segundo plano, contêineres e imagem, dados do aplicativo e logs, arquivos de seus agentes e os agentes do vault do OneCLI desta cópia. Coisas compartilhadas — o aplicativo OneCLI e suas credenciais, outras cópias do NanoClaw na máquina — são deixadas em paz. Ele mostra exatamente o que encontrou e pede confirmação por grupo; nada é deletado até que você confirme. Use --dry-run para pré-visualizar sem alterar nada, ou --yes para pular os prompts. Seu .env é copiado antes da remoção. Para finalizar, exclua a própria pasta do checkout.

Que alterações serão aceitas no código base?

Apenas correções de segurança, correções de bugs e melhorias claras serão aceitas na configuração base. Só isso.

Tudo o mais (novas capacidades, compatibilidade com SO, suporte a hardware, melhorias) deve ser contribuído como habilidades: código de canal e provedor nos branches de registro channels/providers, todo o resto como uma habilidade autocontida. Consulte docs/customizing.md e CONTRIBUTING.md.

Isso mantém o sistema base mínimo e permite que cada usuário personalize sua instalação sem herdar recursos que não deseja.

Comunidade

Perguntas? Ideias? Junte-se ao Discord.

Changelog

Consulte CHANGELOG.md para mudanças significativas, ou o histórico completo de versões no site de documentação.

Licença

MIT