Tutorial PicoClaw: um framework de agente hiperminimalista para pouco espaço em disco

Se as notícias recentes estiverem certas, a IA está consumindo toda a RAM e CPU do mundo — e o PicoClaw chega na hora certa. Não é surpresa que tenha gerado tanto burburinho no lançamento, acumulando milhares de estrelas nos primeiros dias. O agente completo ocupa menos de 10 MB e inicia em menos de um segundo em um processador de 600 MHz. 

Assim que conheci o projeto, precisei testar por conta própria para ver se o hype era real. Neste artigo, vou te guiar pelo PicoClaw e destacar tudo o que encontrei. 

Se você quer se aprofundar em IA agentic, recomendo começar pela trilha de aprendizado AI Agent Fundamentals. 

O que é o PicoClaw?

O PicoClaw é um assistente pessoal de IA leve, inspirado no Nanobot. Ele é escrito em Go pela equipe da Sipeed e roda em dispositivos de borda como Raspberry Pi, placas RISC-V embarcadas e roteadores baseados em MIPS. Isso significa que você pode rodar o PicoClaw com um orçamento de hardware de US$ 10. 

Principais recursos e capacidades do PicoClaw

O PicoClaw é distribuído como um único binário. Isso torna a configuração extremamente rápida, pois não há ambientes virtuais Python para ajustar nem pip para instalar. 

Por ser um arquivo binário, ele roda em várias arquiteturas. A página de releases traz downloads para diversos sistemas operacionais, incluindo Linux, macOS e Windows. 

No quesito IA, o PicoClaw é agnóstico ao provedor. Ele suporta OpenAI, Anthropic, DeepSeek e até Ollama para modelos locais. Isso é ótimo para quem quer alternar entre modelos ou usar modelos locais por questões de privacidade. 

Você pode aprender a configurar o Ollama para modelos locais neste guia de uso do OpenClaw com Ollama. 

O PicoClaw traz ferramentas nativas que conseguem: 

• Ler e escrever arquivos 
• Executar comandos de shell no sistema host 
• Pesquisar na web com Brave Search ou DuckDuckGo 
• Agendar tarefas recorrentes com cron 

Assim como o Nanobot, ele é compatível com os de sempre: WhatsApp, Telegram, Discord, QQ e DingTalk. Mais adiante, vou mostrar como configurá-lo com o Telegram. 

Conheça o Nanobot, a alternativa leve ao OpenClaw. Construa um agente de IA em Python seguro e auditável em menos de 10 minutos com este guia completo de configuração do Nanobot.

Prós e contras do PicoClaw

Você deve estar se perguntando quais são os contras do PicoClaw, já que ele é tão rápido e simples de configurar. A gente chega lá, mas antes vamos ver os pontos fortes. 

Primeiro, por ser um arquivo binário, fica fácil instalar em praticamente qualquer dispositivo. Consegui configurá-lo no meu celular Google Pixel em poucos minutos. 

Segundo, o PicoClaw funciona nas plataformas de mensagens que você já usa, então dá para interagir sem trocar de app. 

Do lado negativo, o PicoClaw ainda está pré-1.0. Por ser uma ferramenta muito nova, pode haver bugs inesperados ou mudanças incompatíveis. Nas minhas pesquisas, também encontrei vários golpes cripto mirando o PicoClaw. A documentação oficial afirma que eles não têm nenhuma moeda — então cuidado por aí. 

Como configurar o PicoClaw

Você consegue colocar o PicoClaw para rodar em poucos passos. Veja como:

Instalação (download de binário único)

Para configurar o PicoClaw, você pode compilar diretamente do código-fonte:

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
# Build, no need to install
make build
# Build for multiple platforms
make build-all
# Build for Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
make build-pi-zero
# Build And Install
make install

Mas eu prefiro usar Docker porque é muito mais rápido: 

# 1. Clone this repo
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
# 2. First run — auto-generates docker/data/config.json then exits
docker compose -f docker/docker-compose.yml --profile gateway up
# The container prints "First-run setup complete." and stops.
# 3. Set your API keys
nano docker/data/config.json   # Set provider API keys, bot tokens, etc.
# 4. Start
docker compose -f docker/docker-compose.yml --profile gateway up -d

Aprenda o essencial de conteinerização neste guia Docker para iniciantes. 

Configurando seu provedor de LLM

Depois da instalação, você precisa configurar o provedor de LLM da sua preferência. Faça isso editando o arquivo docker/data/config.json:

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "gpt4",
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  },
  "model_list": [
    {
      "model_name": "gpt4",
      "model": "openai/gpt-5.2",
      "api_key": "your-api-key",
      "request_timeout": 300
    },
    {
      "model_name": "claude-sonnet-4.6",
      "model": "anthropic/claude-sonnet-4.6",
      "api_key": "your-anthropic-key"
    }
  ],
  "tools": {
    "web": {
      "brave": {
        "enabled": false,
        "api_key": "YOUR_BRAVE_API_KEY",
        "max_results": 5
      },
      "tavily": {
        "enabled": false,
        "api_key": "YOUR_TAVILY_API_KEY",
        "max_results": 5
      },
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      },
      "perplexity": {
        "enabled": false,
        "api_key": "YOUR_PERPLEXITY_API_KEY",
        "max_results": 5
      },
      "searxng": {
        "enabled": false,
        "base_url": "http://your-searxng-instance:8888",
        "max_results": 5
      }
    }
  }
}

Rodando seu primeiro agente

Conectar o PicoClaw ao Telegram leva só alguns passos.

Veja como configurei o Telegram:

• Abra o Telegram e busque por @BotFather 
• Digite /newbot e siga as instruções 
• Copie o token que você receber do BotFather 
• Depois, obtenha seu user ID para garantir que o bot aceite comandos só de você. Procure por @userinfobot no Telegram e clique em Start. Copie o user ID.

Em seguida, atualize o arquivo docker/data/config.json para incluir o token do bot e seu user ID do Telegram. 

Agora, vá até o seu bot no Telegram e comece a interagir com o Picoclaw. 

Vamos testar alguns prompts. 

Primeiro, vou usar o PicoClaw para pesquisar na web e retornar o preço atual das ações da Apple. Como dá para ver na captura, ele usou a ferramenta de busca DuckDuckGo e recuperou o preço. 

Aqui vai outro prompt pedindo ao PicoClaw para rascunhar um post de blog, salvar no disco e ler o conteúdo: 

Fiquei curioso com a capacidade de agendar tarefas. Pedi para me lembrar de publicar o post em cinco minutos — e o lembrete chegou após os 5 minutos. 

Problemas comuns do PicoClaw e como resolver

Ao configurar o PicoClaw, encontrei alguns problemas. Cito rapidamente aqui caso aconteçam com você também. 

Sem resposta no Telegram

Se você não recebe resposta no Telegram, o problema pode ser: 

• Token do Telegram incorreto. Abra o arquivo de configuração e confira novamente 
• O user ID em from não está definido ou você está acessando o agente de outra conta 
• O modelo e as chaves de API não estão configurados. Abra o arquivo e defina-os

Ao verificar os logs, você verá qual é o problema exato: 

docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway

Modelo não definido 

O erro abaixo indica que você não definiu o modelo padrão: 

Error: error creating provider: model "" not found in model_list: model "" not found in model_list or providers

Abra o arquivo JSON de configuração, defina o nome do modelo que deseja usar e garanta que a chave de API correspondente também esteja no arquivo.

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "model_name": "gpt4", ---> make sure this is here 
      "max_tokens": 8192,
      "temperature": 0.7,
      "max_tool_iterations": 20
    }
  }

Chave de API incorreta

Este é direto ao ponto: a chave de API do seu provedor de modelo está vazia ou errada. Abra o arquivo JSON e verifique a chave.

Destaques do PicoClaw

Vamos ver agora algumas capacidades que tornam o PicoClaw diferente — e também parecidas com outros assistentes pessoais de IA. 

Sistema Heartbeat

O PicoClaw mantém um arquivo markdown de heartbeat no diretório de trabalho, que o agente lê a cada 30 minutos e executa as instruções ali descritas. O PicoClaw também pode iniciar subagentes para trabalhar em paralelo. 

Memória persistente

O PicoClaw possui um arquivo de memória que guarda informações importantes que precisam persistir entre sessões. Ele salva suas preferências e habilidades ativadas, para que esse contexto seja recuperado quando necessário. Assim você não precisa recomeçar toda interação do zero. 

Modo isolado/offline

O PicoClaw também pode rodar sem acesso à internet. Isso é essencial para processar dados sensíveis, especialmente em setores regulados como bancos e saúde. Para isso, você precisará configurar um modelo local via Ollama. 

Multiagente e fallback de modelos

Com o PicoClaw, dá para definir cada agente usando seu próprio provedor de LLM. Ele também suporta balanceamento de carga, distribuindo requisições entre vários modelos. Quando configurado, o PicoClaw alterna entre os modelos em round-robin.

Integração com hardware

O PicoClaw inclui ferramentas nativas para comunicação I2C e SPI. Isso permite que o agente interaja com periféricos de hardware em placas compatíveis — sensores, telas, controladores de motor e todo tipo de dispositivo físico. 

PicoClaw em ação: casos de uso reais

Vamos explorar alguns casos de uso do PicoClaw. 

Entre os casos interessantes que encontrei durante a pesquisa estão: 

• Automação residencial e monitoramento com um Raspberry Pi de primeira geração 
• Pesquisas automáticas na web, por exemplo, para te enviar resumos no Telegram todas as manhãs 
• Alertas e monitoramento a partir de dispositivos embarcados, como dados de sensores 

Limitações e ressalvas do PicoClaw

Antes de colocar o PicoClaw na sua rede, há algumas limitações importantes para considerar.

Primeiro, o PicoClaw é seguro por padrão. Ele fica restrito ao workspace em que está operando e, portanto, não consegue acessar pastas e arquivos fora desse diretório. 

Você pode alterar isso no arquivo de configurações. 

Certos comandos, como rm, também são restritos para evitar problemas como apagar seu disco por completo. 

Por exemplo, pedi para excluir minha pasta home e as proteções entraram em ação para impedir isso. 

Como é um software ainda em desenvolvimento inicial, o PicoClaw tem questões de segurança de rede não resolvidas, então não é recomendado colocá-lo em produção antes da versão 1.0. 

Se você busca algo mais maduro, o OpenClaw é uma boa opção. Descubra se ele se encaixa no seu fluxo de trabalho neste guia OpenClaw vs Claude Code. 

Perspectivas futuras

A capacidade de executar grandes modelos de linguagem em dispositivos de borda ganhou muito espaço recentemente, principalmente com a criação de modelos que rodam em celulares e dispositivos embarcados. Acredito que o PicoClaw será muito útil em ambientes com recursos limitados e em aplicações onde a sensibilidade dos dados é absoluta. Em lugares com conectividade instável, não haverá alternativa senão usar uma ferramenta como o PicoClaw. 

Acho que o PicoClaw pode competir de verdade com o Nanobot e o OpenClaw quando estiver pronto para produção. Aposto que ele será a ferramenta que vai permitir que dispositivos de Internet das Coisas executem fluxos agentic. Isso também traz riscos sérios se os modelos alucinarem ou se uma injeção de prompt levá-los a fazer algo malicioso, como superaquecer um micro-ondas. 

O PicoClaw também deve buscar os recursos que faltam e já existem em outros agentes, como o OpenClaw, conforme descrito no roadmap. Entre eles:

• Automação de navegador
• Mais descoberta de habilidades 
• Suporte a MCP 

Conclusão

Quando o OpenClaw foi lançado, rolou um hype de comprar Mac Minis para rodá-lo — embora isso não fosse necessário. Um Mac Mini custa centenas de dólares. 

O PicoClaw surgiu para provar o contrário, permitindo implantar agentes poderosos com um orçamento de US$ 10. Diferente do OpenClaw, o PicoClaw adota uma abordagem security-first, restringindo o acesso do agente apenas ao seu workspace e desativando comandos que podem causar estragos quando o modelo subjacente alucina ou quando há uma injeção de prompt maliciosa. 

Para aprender mais sobre como trabalhar com ferramentas de IA, recomendo conferir nosso guia com as melhores ferramentas de IA gratuitas. Para desenvolver habilidades mais amplas de código com IA, experimente nosso curso AI-Assisted Coding for Developers e desenvolva as competências que tornam os assistentes de IA parceiros mais confiáveis no seu fluxo de desenvolvimento. 

Você também pode aprender a criar aplicativos com IA usando LLMs, prompts, cadeias e agentes em LangChain no nosso curso Developing LLM Applications with LangChain.