PicoClaw, Docker e homelab: três ingredientes para transformar seu PC antigo em um centro de comando com inteligência artificial própria, sem mensalidade e sem seus dados saindo da sua rede.
Se você já leu nosso guia sobre como montar um homelab com PC antigo Crie seu homelab com pc antigo, sabe que um servidor caseiro pode fazer muito mais do que armazenar arquivos ou rodar câmeras. Agora chegou a hora de dar um passo além: instalar o PicoClaw, seu agente de IA pessoal com docker dentro da sua própria rede, sem depender de nenhuma empresa, sem mensalidade e sem seus dados saindo de casa.
O projeto que vamos explorar hoje se chama PicoClaw.
O Que É o PicoClaw?
PicoClaw é um agente de inteligência artificial de código aberto, construído em Go, projetado para ser extremamente leve e funcionar em qualquer hardware, incluindo aquele PC antigo do seu homelab. Serve como agente de ia para whatsapp, IA para telegram, ou ainda para automatizar processos.
O projeto foi lançado em fevereiro de 2026 e ganhou mais de 25 mil estrelas no GitHub em pouquíssimo tempo, o que dá uma ideia do quanto a comunidade abraçou a proposta.
A premissa é simples e direta: rodar um assistente de IA completo consumindo menos de 10 MB de RAM, com tempo de boot inferior a um segundo. Para comparar, ferramentas similares costumam exigir centenas de megabytes ou até gigabytes de memória só para inicializar.
O mais curioso da história do projeto é que boa parte da sua própria migração arquitetural foi conduzida pelo próprio agente de IA — um processo que os desenvolvedores chamam de “self-bootstrapping”. O código que você vai instalar hoje nasceu, em grande parte, de decisões tomadas por uma versão anterior de si mesmo.
PicoClaw vs Outras IAs: Qual a Diferença Real?
Antes de instalar, vale entender onde o PicoClaw se encaixa no ecossistema de IAs self-hosted, porque a confusão entre as opções é comum.
ChatGPT, Claude, Gemini e similares são serviços em nuvem. Você manda sua pergunta para um servidor de outra empresa, ela processa e te devolve a resposta. Seus dados passam por infraestrutura terceirizada, você paga assinatura ou por uso, e não tem controle nenhum sobre o modelo.
Ollama é uma ferramenta para rodar modelos de linguagem grandes (LLMs) localmente, como LLaMA, Mistral ou Gemma. Ele resolve o problema do modelo em si, mas não é um agente: não tem memória persistente nativa, não se conecta a canais de comunicação como Discord ou Telegram, e não executa tarefas autonomamente.
Open WebUI é uma interface gráfica bonita para conversar com modelos rodando via Ollama. Ótimo para uso pessoal no navegador, mas também não é um agente.
n8n com Ollama monta um ecossistema de automação com IA, muito poderoso, mas exige muito mais configuração, mais recursos de hardware e mais conhecimento técnico para manter.
PicoClaw ocupa um nicho diferente de todos eles: é um agente autônomo e persistente. Isso significa que ele fica rodando em segundo plano 24 horas por dia, conectado a canais como Telegram, Discord, Matrix ou WeChat, e pode executar tarefas de forma proativa — buscar informações na web, rodar automações via protocolo MCP, manter memória entre conversas e até spawnar sub-agentes para tarefas paralelas. Ele não substitui o modelo de linguagem (você ainda precisa de uma chave de API de um provedor como OpenRouter ou Zhipu), mas orquestra tudo isso de forma leve e eficiente.
Em resumo: se o Ollama é o motor, o PicoClaw é o carro inteiro — com GPS, memória e piloto automático.
O Que o PicoClaw Consegue Fazer?
Com o agente configurado e rodando, você tem à disposição:
Integração com canais de mensagens — Telegram, Discord, Matrix, IRC, WeChat e WeCom. Você literalmente manda mensagem para o seu servidor e ele responde, executa tarefas ou busca informações.
Busca na web em tempo real — via Brave Search API (2.000 consultas gratuitas por mês) ou fallback automático para DuckDuckGo.
Suporte ao protocolo MCP — Model Context Protocol, o padrão emergente que permite ao agente se conectar a ferramentas externas como bancos de dados, APIs e serviços locais. (O MCP merece um artigo próprio — é um assunto rico que vamos explorar em breve.)
Memória persistente — o agente lembra de conversas anteriores usando um armazenamento em JSONL, o que permite contexto ao longo do tempo.
Sub-agentes — você pode spawnear agentes filhos para executar tarefas em paralelo, o que abre caminho para automações mais complexas.
Roteamento de modelos — você pode configurar diferentes LLMs para diferentes tipos de tarefa, otimizando custo e qualidade.
Interface web — uma launcher no navegador na porta 18800 para configurar provedores, canais e gateways sem precisar editar JSON na mão.
Suporte a visão — a partir da versão 0.2.1, o pipeline de visão permite que o agente processe imagens.
Como instalar PicoClaw:
Antes de começar, certifique-se de ter:
- Docker e Docker Compose instalados no servidor (se ainda não tem, esse é o primeiro passo do seu homelab — veja nosso guia Crie seu homelab com pc antigo para entender como preparar o ambiente)
- Uma chave de API de um provedor de LLM — recomendamos começar com OpenRouter (tem plano gratuito e suporta dezenas de modelos) ou Zhipu GLM (modelo padrão do PicoClaw)
- Opcional: uma chave da Brave Search API para buscas na web (gratuita até 2.000 consultas/mês)
- Opcional: um bot criado no Telegram ou Discord para o agente se comunicar (configurar um bot no Telegram merece um post separado — deixaremos essa ponta solta por enquanto)
Instalação Passo a Passo com Docker
1. Clone o repositório
Baixe o código-fonte do PicoClaw diretamente do GitHub
git clone https://github.com/sipeed/picoclaw.git
cd picoclaw2. Gere o arquivo de configuração inicial
O primeiro docker compose up vai gerar o arquivo de configuração automaticamente e encerrar sozinho. É um comportamento proposital — o container imprime “First-run setup complete.” e para.
docker compose -f docker/docker-compose.yml --profile gateway upApós a mensagem de conclusão, você vai encontrar o arquivo gerado em docker/data/config.json.
3. Configure suas chaves de API
Abra o arquivo de configuração:
nano docker/data/config.jsonA estrutura básica que você precisa preencher é esta:
json
{
"agents": {
"defaults": {
"workspace": "~/.picoclaw/workspace",
"model": "glm-4.7",
"max_tokens": 8192,
"temperature": 0.7,
"max_tool_iterations": 20
}
},
"providers": {
"openrouter": {
"api_key": "SUA_CHAVE_OPENROUTER_AQUI",
"api_base": "https://openrouter.ai/api/v1"
}
},
"tools": {
"web": {
"search": {
"api_key": "SUA_CHAVE_BRAVE_AQUI",
"max_results": 5
}
}
}
}Se for usar Zhipu GLM como provedor, o api_base muda para https://open.bigmodel.cn/api/paas/v4. O campo model aceita qualquer modelo disponível no provedor configurado.
4. Suba o gateway em modo daemon
docker compose -f docker/docker-compose.yml --profile gateway up -dO flag -d coloca o container rodando em segundo plano. A partir daqui o agente está ativo e aguardando comandos.
5. Verifique os logs
docker compose logs -f picoclaw-gatewaySe tudo correu bem, você vai ver o agente inicializando os canais configurados e indicando que está pronto para receber mensagens. O boot costuma levar menos de um segundo.
6. Faça um teste rápido via linha de comando
Antes de configurar um canal como Telegram, você pode testar o agente diretamente pelo terminal:
docker compose run --rm picoclaw-agent -m "Qual é a capital do Brasil?"Ou entre no modo interativo:
docker compose run --rm picoclaw-agentNo modo interativo, basta digitar suas perguntas e receber respostas diretamente no terminal.
7. Acessar a interface web
Com o gateway rodando, abra o navegador e acesse:
http://IP-DO-SEU-SERVIDOR:18800A launcher web permite configurar provedores, canais de mensagem e gateways de forma visual, sem precisar editar o JSON manualmente. É o caminho mais amigável para adicionar o Telegram ou Discord depois.
Parar e Reiniciar o Container
docker compose -f docker/docker-compose.yml --profile gateway downPara encerrar o gateway:
Se precisar reconstruir a imagem após uma atualização do repositório:
git pull
docker compose -f docker/docker-compose.yml --profile gateway build --no-cache
docker compose -f docker/docker-compose.yml --profile gateway up -dOs seus dados de configuração e workspace ficam em um volume nomeado do Docker, então nada se perde ao reconstruir a imagem.
Dicas de Segurança
Assim como qualquer serviço rodando no seu homelab, o PicoClaw precisa de atenção à segurança:
Não exponha a porta 18800 para a internet. A interface web não tem autenticação embutida por padrão. Se precisar acessar remotamente, use uma VPN — WireGuard ou Tailscale são as melhores opções e já detalhamos isso no artigo sobre homelab: Como montar seu homelab com hardware antigo.
Proteja suas chaves de API. O config.json contém suas chaves em texto simples. Não suba esse arquivo para nenhum repositório público, nem compartilhe sem remover as chaves primeiro.
Cuidado com o acesso externo ao webhook. Se quiser que o agente receba mensagens do Telegram ou Discord, você vai precisar expor a porta 18791. O caminho seguro é fazer isso via VPN ou usar um proxy reverso com HTTPS — assunto que exploraremos em um artigo dedicado sobre acesso externo ao homelab. (Ponta solta intencional: esse tema merece post próprio.)
Próximos Passos (Pontas Soltas para Artigos Futuros)
O PicoClaw é o ponto de entrada, mas o ecossistema ao redor abre muitas possibilidades. Aqui estão os temas que vamos cobrir em breve:
- Como criar um bot no Telegram e conectar ao PicoClaw — para você ter seu assistente pessoal dentro do app que já usa
- O que é o protocolo MCP e por que ele importa — o padrão que está mudando como agentes de IA se conectam a ferramentas
- Proxy reverso com Nginx ou Caddy no homelab — para expor serviços com HTTPS de forma segura
- Roteamento de modelos no PicoClaw — como usar modelos diferentes para tarefas diferentes e otimizar custos de API
- WireGuard e Tailscale no homelab — acesso remoto seguro a todos os seus serviços
Conclusão
O PicoClaw resolve um problema real: ter um agente de IA persistente, leve e sob seu controle total, rodando no mesmo hardware que já hospeda seus outros serviços. Se você já tem um homelab funcionando, adicionar o PicoClaw é uma questão de minutos — e o resultado é um assistente que vive na sua rede, responde no seu Telegram e não manda seus dados para lugar nenhum.
O hardware parado que vira servidor, o servidor que vira nuvem privada, e agora a nuvem privada que ganha inteligência artificial. É exatamente esse o caminho.
📌 Salve este artigo para consultar durante a instalação.
