🐾 Frameworks de Bots Pessoais
Um bot pessoal com IA nao e a mesma coisa que um chatbot. Chatbots sao reativos: voce faz uma pergunta, ele responde. Bots pessoais sao proativos, persistentes e contextuais. Eles rodam 24/7 na sua maquina ou servidor, conhecem suas preferencias, acessam suas ferramentas e executam tarefas reais no mundo. A diferenca entre perguntar "como esta o clima?" e ter um assistente que automaticamente avisa voce de chuva antes de sair e a diferenca entre um chatbot e um bot pessoal.
O conceito de personal AI assistant ganhou forca em 2025 quando desenvolvedores comecaram a construir seus proprios bots que rodavam localmente, conectados a APIs de LLMs, com acesso a emails, calendarios, sistema de arquivos e ferramentas de desenvolvimento. Diferente de assistentes corporativos como Siri ou Google Assistant, esses bots sao totalmente customizaveis, open source em muitos casos, e rodam sob o controle total do usuario.
A motivacao principal e autonomia. Quando voce depende de um assistente de uma big tech, voce esta limitado ao que eles decidiram que voce pode fazer. Com um bot pessoal, voce define as capacidades. Quer que ele leia seus emails e resuma os importantes? Configuravel. Quer que ele monitore precos de passagens aereas? Configuravel. Quer que ele faca deploy de um projeto quando voce manda uma mensagem no Telegram? Totalmente configuravel. A unica limitacao e sua imaginacao e as APIs disponiveis.
Conceito Principal
Personal AI Assistant (always-on bot) e um software que roda permanentemente, conectado a um ou mais canais de comunicacao (Telegram, Slack, Discord, WhatsApp), com acesso a ferramentas externas (email, calendario, browser, sistema de arquivos), e alimentado por um ou mais modelos de linguagem (Claude, GPT, Llama, Qwen). Ele mantem contexto entre conversas, aprende preferencias do usuario, e pode executar tarefas autonomamente.
A arquitetura tipica de um bot pessoal tem quatro camadas. A camada de interface (Telegram, Slack) recebe e envia mensagens. A camada de processamento (router, intent classifier) decide o que fazer com cada mensagem. A camada de execucao (skills, tools, MCP servers) realiza as acoes. E a camada de memoria (banco de dados, embeddings) mantem o contexto ao longo do tempo.
Ter seu proprio bot e diferente de usar ChatGPT pelo browser porque o bot tem persistencia (lembra de conversas anteriores), proatividade (pode enviar mensagens sem ser perguntado, via scheduled tasks), e integracao (conecta a ferramentas reais que afetam o mundo). Ele nao responde perguntas. Ele faz coisas.
Ecossistema de Bots Pessoais em 2026
repositorios no GitHub com tag "personal-ai-assistant" ou similar
canal mais popular para bots pessoais (API aberta, bot-friendly, rich media)
dominantes: Node.js/TS, Python, Go. Node lidera em bots real-time
bots pessoais rodam como servicos permanentes, nao como scripts one-shot
Dica Pratica
Antes de construir seu bot, defina os 3-5 casos de uso mais importantes para voce. Nao tente fazer tudo no dia um. Comece com o caso de uso que voce usaria todo dia. Para muitos devs, isso e "responder perguntas rapidas sobre meus projetos" ou "resumir emails importantes". Comece ai e expanda organicamente.
Escolha Telegram como sua interface inicial. A API e a mais amigavel para bots, suporta markdown, arquivos, fotos, audio, e tem zero custo. Voce pode migrar para outros canais depois, mas Telegram e o melhor ponto de partida por uma margem grande.
Fazer
- ✓Definir casos de uso concretos antes de comecar a codar
- ✓Escolher um canal de comunicacao e domina-lo primeiro
- ✓Pensar em persistencia e memoria desde o inicio
- ✓Rodar o bot como servico (systemd, pm2, Docker)
Evitar
- ✗Construir um "chatbot generico" sem proposito claro
- ✗Ignorar seguranca (qualquer um pode mandar mensagem pro bot)
- ✗Depender de um unico provedor de LLM sem fallback
- ✗Nao implementar rate limiting ou controle de custos
🔓 OpenClaw: Arquitetura Open Source
OpenClaw e um framework open source para construir bots pessoais com IA. Escrito em TypeScript rodando em Node.js, ele fornece a arquitetura base que voce precisa para ter um assistente pessoal funcional sem comecar do zero. A filosofia e ser extensivel, self-hosted e community-driven. Voce clona, configura e tem um bot rodando em minutos.
O stack tecnico foi escolhido por razoes praticas. Node.js e ideal para bots porque e event-driven e non-blocking, perfeito para lidar com multiplas mensagens simultaneas sem travar. TypeScript adiciona type safety, o que e critico em projetos que crescem organicamente. SQLite como banco de dados elimina a necessidade de instalar e gerenciar um servidor de banco separado. Tudo roda em um unico processo.
A extensibilidade via plugins e skills significa que a comunidade pode contribuir funcionalidades sem mexer no core do framework. Cada skill e um modulo independente com seus proprios triggers, dependencias e logica. Voce pode instalar skills prontas ou criar as suas. O sistema de plugins segue o mesmo padrao de ecossistemas maduros como ESLint ou Prettier: a comunidade constroi, voce escolhe o que usar.
Conceito Principal
OpenClaw segue uma arquitetura modular com quatro componentes principais. O Bot Core gerencia o lifecycle da aplicacao, conexao com Telegram, e message handling. O Router analisa cada mensagem e decide qual agente ou skill deve processar. O Agent Layer conecta a diferentes backends de LLM (Ollama local, Claude API, OpenRouter). E o Skill System fornece capacidades concretas como ler emails, agendar tarefas ou buscar na web.
Ser self-hosted significa que seus dados nunca saem da sua maquina (exceto as chamadas de API para o LLM que voce escolher). Suas conversas, memorias, tasks e configuracoes ficam em um arquivo SQLite local. Voce tem controle total sobre o que e armazenado, por quanto tempo, e quem tem acesso. Isso e um diferencial enorme em relacao a assistentes cloud-based onde seus dados estao nos servidores de outra empresa.
A natureza open source permite auditoria completa do codigo. Voce pode ler cada linha que roda na sua maquina. Pode fazer fork e customizar livremente. Pode contribuir features de volta para a comunidade. E pode ter certeza de que nenhum dado esta sendo coletado sem seu conhecimento.
Stack Tecnico do OpenClaw
Runtime event-driven, ideal para I/O concorrente de mensagens
Type safety para codebase extensivel e refatoracao segura
Zero-config database, arquivo unico, backup trivial
Framework Telegram Bot API com middleware pattern
Dica Pratica
Quando clonar o OpenClaw, comece lendo o arquivo de configuracao principal (.env) e o README. Entenda quais variaveis sao obrigatorias (token do Telegram, chave de API do LLM) e quais sao opcionais. Configure o minimo necessario para ter o bot respondendo, e so depois adicione skills e customizacoes.
Use Ollama como backend inicial se voce tem uma maquina com GPU. E gratuito, roda local, e voce pode experimentar sem se preocupar com custos de API. Qwen 2.5 14B e um bom modelo para comecar: rapido, bom em portugues, e cabe em uma GPU com 16GB de VRAM.
Fazer
- ✓Ler o codigo fonte antes de customizar (entender antes de mudar)
- ✓Contribuir bugs e features de volta para o repositorio
- ✓Manter o .env fora do git (seguranca basica)
- ✓Fazer backup regular do banco SQLite
Evitar
- ✗Modificar o core sem entender o lifecycle do bot
- ✗Commitar tokens e API keys no repositorio
- ✗Ignorar atualizacoes do upstream (bugs de seguranca)
- ✗Rodar sem ALLOWED_CHAT_ID (qualquer pessoa pode usar seu bot)
🤖 ClaudeClaw: Bot com Claude
ClaudeClaw e a implementacao de referencia do OpenClaw que usa o Claude Agent SDK como backend principal. A diferenca fundamental em relacao a simplesmente chamar a API do Claude e que o ClaudeClaw usa o modo agentico do Claude Code, onde o modelo tem acesso completo a ferramentas: pode ler e editar arquivos, executar comandos no terminal, fazer buscas na web, e rodar qualquer ferramenta MCP configurada. Voce esta dando ao Claude as mesmas capacidades que um desenvolvedor tem no terminal.
A interface principal e o Telegram. Voce manda uma mensagem de texto ou audio, o bot transcreve se necessario, processa via Claude Agent SDK, e retorna a resposta. Mas nao e so texto entrando e saindo. O Claude pode enviar arquivos de volta (PDFs gerados, screenshots, planilhas), pode executar operacoes no seu servidor (git push, npm build, restart de servicos), e pode acessar APIs externas via MCP servers.
O conceito de sessoes persistentes e central. Diferente de uma conversa no ChatGPT que comeca do zero a cada vez, o ClaudeClaw mantem uma sessao ativa do Claude Code. Isso significa que o contexto da conversa persiste entre mensagens. Voce pode dizer "lembra daquele projeto que discutimos ontem?" e o bot tera esse contexto. Quando a janela de contexto enche, o sistema faz compaction automatica, resumindo o historico para liberar espaco sem perder informacao critica.
Conceito Principal
Claude Agent SDK e a biblioteca oficial da Anthropic para criar agentes autonomos com Claude. No contexto do ClaudeClaw, o SDK e usado para criar um agente que tem acesso a todas as ferramentas do sistema. Quando voce manda "cria um script Python que faz X", o Claude nao apenas gera o codigo. Ele cria o arquivo, executa, verifica se funciona, corrige erros, e envia o resultado final.
A combinacao Telegram + Claude Agent SDK e poderosa porque une a ubiquidade do Telegram (acessivel do celular, computador, web) com o poder agentico do Claude (pode fazer qualquer coisa que voce faria no terminal). Voce literalmente comanda seu servidor a partir de mensagens de texto no celular. Manda um audio dizendo "faz deploy do projeto X" e o bot executa git pull, npm build, restart do servico, e confirma que esta tudo no ar.
O sistema de full tool access significa que o Claude dentro do ClaudeClaw tem as mesmas permissoes que o usuario que roda o processo. Ele pode acessar o filesystem, rodar comandos bash, fazer requests HTTP, e interagir com qualquer MCP server configurado. Isso e extremamente poderoso e requer cuidado: voce precisa configurar ALLOWED_CHAT_ID para garantir que so voce pode enviar comandos ao bot.
Capacidades do ClaudeClaw
Bash, filesystem, web search, browser, MCP servers
Sessao Claude Code que sobrevive entre mensagens com auto-compaction
Texto, audio (transcricao), imagens, arquivos de entrada e saida
Scheduled tasks, notificacoes, monitoramento automatico
Dica Pratica
O ClaudeClaw usa creditos da API Anthropic. Monitore seu uso via dashboard (porta 3141) que mostra tokens consumidos, custo por mensagem, e custo acumulado por agente. Configure alertas de gasto se necessario. Uma conversa longa com muitas tool calls pode custar $1-5, entao tenha visibilidade sobre isso.
Use o sistema multi-agente para economizar. Perguntas simples vao para Ollama (custo zero), e so tarefas que realmente precisam de tools e raciocinio complexo vao para Claude. O router inteligente faz isso automaticamente quando configurado.
Fazer
- ✓Configurar ALLOWED_CHAT_ID imediatamente (seguranca critica)
- ✓Monitorar custo por mensagem via dashboard
- ✓Usar o CLAUDE.md para definir personalidade e comportamento
- ✓Configurar multi-agente para otimizar custos
Evitar
- ✗Rodar sem restricao de chat ID (risco financeiro e de seguranca)
- ✗Enviar tarefas triviais para Claude (use Ollama para perguntas simples)
- ✗Ignorar o custo acumulado de sessoes longas
- ✗Dar permissoes de root ao processo do bot
🧩 Skills e Integracao
Skills sao modulos de capacidade que dao ao bot habilidades concretas e especificas. Em vez de depender apenas do conhecimento geral do LLM, skills conectam o bot a servicos reais: Gmail para emails, Google Calendar para agenda, um browser headless para navegacao web, Obsidian para notas, e qualquer outra API ou ferramenta que voce precise. Cada skill transforma o bot de um conversador em um executor.
O sistema de skills funciona com triggers automaticos. No CLAUDE.md (o arquivo de personalidade do bot), voce define uma tabela de skills com palavras-chave. Quando o usuario menciona "email" ou "inbox", o sistema sabe que deve acionar a skill de Gmail. Quando menciona "agenda" ou "reuniao", aciona a skill de Google Calendar. Essa deteccao acontece no nivel do LLM, que interpreta a intencao da mensagem e invoca a skill apropriada.
MCP (Model Context Protocol) e o padrao aberto que permite ao Claude se conectar a ferramentas externas de forma padronizada. Em vez de cada skill implementar sua propria integracao, o MCP define um protocolo comum. Existem centenas de MCP servers disponiveis: para GitHub, Slack, bancos de dados, APIs REST, e muito mais. Instalar um MCP server novo e adicionar uma capacidade inteira ao bot com uma linha de configuracao.
Skills Principais do Ecossistema
Gmail
Le emails, filtra por remetente ou assunto, resume threads longas, redige respostas, envia emails. Triggers: "email", "inbox", "reply", "send". Usa OAuth2 para autenticacao segura com escopo limitado.
Google Calendar
Lista eventos, cria reunioes, verifica disponibilidade, envia lembretes. Triggers: "schedule", "meeting", "calendar", "availability". Entende linguagem natural: "marca uma call com o Joao amanha as 15h".
Agent Browser
Navega a web, preenche formularios, faz scraping de dados, tira screenshots de paginas. Triggers: "browse", "scrape", "click", "fill form". Usa Puppeteer/Playwright para controle completo do browser.
Todo / Task Manager
Gerencia tarefas, listas de afazeres, lembretes. Integra com Obsidian, Todoist, ou banco local. Triggers: "tasks", "todo", "lembrete". Permite scheduled tasks com cron expressions.
Ecossistema MCP em Numeros
MCP servers disponiveis no registro publico em 2026
Qualquer provedor pode criar MCP servers, nao e lock-in da Anthropic
Protocolo leve, facil de implementar em qualquer linguagem
Claude detecta automaticamente as ferramentas disponiveis via MCP
Dica Pratica
Comece com 2-3 skills e adicione mais conforme a necessidade real aparece. Nao instale 20 MCP servers no dia um. Cada skill adicional aumenta o contexto que o LLM precisa processar (mais ferramentas = mais tokens = mais custo e latencia). Instale o que voce realmente vai usar.
Quando uma skill nao existir pronta, voce pode criar a sua. Um MCP server basico em Node.js pode ser criado em menos de 50 linhas de codigo. A documentacao do protocolo e clara e existem templates prontos. Se voce tem uma API que usa frequentemente, transforme-a em um MCP server e ganhe acesso via linguagem natural.
Fazer
- ✓Documentar triggers de cada skill no CLAUDE.md
- ✓Testar cada skill isoladamente antes de integrar
- ✓Usar OAuth2 com escopos minimos para servicos Google
- ✓Criar MCP servers para APIs que voce usa com frequencia
Evitar
- ✗Instalar dezenas de skills sem uso real (bloat)
- ✗Dar full account access quando read-only basta
- ✗Ignorar rate limits de APIs externas (bans e custos)
- ✗Hardcodar credenciais de skills no codigo
🔧 Customizacao e Extensao
A verdadeira forca de um bot pessoal esta na customizacao. Nao e um produto generico que serve para todo mundo igual. E o SEU assistente, configurado para as SUAS necessidades, com a personalidade que VOCE definiu, acessando as ferramentas que VOCE usa. O CLAUDE.md e o coracao dessa customizacao: um arquivo markdown que funciona como o system prompt persistente do bot, definindo quem ele e, como ele se comporta, e o que ele sabe fazer.
O sistema de memoria permite que o bot aprenda e se adapte ao longo do tempo. Existem dois tipos de memoria: a sessional (contexto dentro de uma conversa) e a persistente (informacoes que sobrevivem entre sessoes). A memoria persistente fica em um banco SQLite com campos de saliencia (quao importante e essa informacao) e setor (semantica, episodica, procedural). O bot pode gravar memorias automaticamente durante conversas e recupera-las quando relevante.
Scheduled tasks transformam o bot de reativo em proativo. Em vez de esperar voce perguntar algo, o bot pode executar acoes em horarios definidos via cron expressions. Exemplos praticos: verificar emails importantes toda manha as 9h e enviar um resumo, monitorar o status de um servidor a cada hora, lembrar de uma tarefa recorrente toda segunda-feira. As notificacoes proativas vao via Telegram, transformando o bot em um sistema de alertas inteligente.
Conceito Principal
O CLAUDE.md e o arquivo mais importante do bot. Ele define a personalidade (nome, tom de voz, regras de comunicacao), o conhecimento contextual (quem e o usuario, quais sao seus projetos, como ele pensa), as capacidades (tabela de skills com triggers), comandos especiais (checkpoint, convolife), e instrucoes sobre como usar ferramentas especificas. Toda mensagem que o bot processa e influenciada pelo conteudo desse arquivo.
O memory system usa uma tabela no SQLite com campos: content (o que lembrar), sector (tipo de memoria), salience (importancia de 1.0 a 5.0), created_at e accessed_at (timestamps). Memorias de alta saliencia sao recuperadas mais frequentemente. O bot pode criar memorias automaticamente ("nota: usuario prefere Python sobre JavaScript") e o usuario pode forcar um checkpoint manual para salvar o estado da conversa.
Para criar skills customizadas, voce precisa de tres coisas: um script que executa a acao (pode ser bash, Python, Node.js, qualquer coisa executavel), uma entrada no CLAUDE.md descrevendo a skill e seus triggers, e opcionalmente um MCP server se voce quer que o Claude interaja com a skill de forma estruturada. O padrao mais simples e um bash script que o Claude executa via tool use.
Anatomia do CLAUDE.md
Personality - Nome, tom de voz, regras de comunicacao (ex: "nunca use em dashes", "fale como pessoa real")
Who Is [User] - Contexto sobre o usuario: profissao, projetos, forma de pensar, preferencias
Your Job - Diretrizes de comportamento: "execute, nao explique", "pergunte se precisar de clarificacao"
Skills Table - Tabela skill/triggers mapeando palavras-chave a capacidades
Special Commands - Comandos como "convolife" (status do contexto) e "checkpoint" (salvar estado)
Dica Pratica
Invista tempo no CLAUDE.md. Quanto mais contexto voce der sobre voce, seus projetos e suas preferencias, melhores serao as respostas. Nao precisa ser um documento de 50 paginas. 2-3 paragrafos bem escritos sobre quem voce e e o que voce faz ja fazem uma diferenca enorme na qualidade das interacoes.
Para scheduled tasks, comece com uma task de teste simples (ex: "manda um oi todo dia as 9h") para validar que o sistema de cron esta funcionando. Depois evolua para tasks uteis. O formato cron pode ser confuso no inicio; use crontab.guru para gerar e validar suas expressoes.
Fazer
- ✓Iterar no CLAUDE.md frequentemente conforme descobre o que funciona
- ✓Usar "checkpoint" regularmente para preservar contexto valioso
- ✓Comecar scheduled tasks com coisas simples e escalar
- ✓Documentar suas skills custom para facilitar manutencao
Evitar
- ✗CLAUDE.md generico sem informacao pessoal (desperdicar contexto)
- ✗Scheduled tasks a cada minuto (custo de API e sobrecarga)
- ✗Memorias sem controle de saliencia (tudo vira ruido)
- ✗Skills que dependem de estado global (dificulta debug)
🛠️ Exercicio: Setup de Framework
Hora de colocar a mao na massa. Neste exercicio voce vai configurar seu proprio bot pessoal usando o OpenClaw como base. O objetivo e ter um bot funcional no Telegram que responde mensagens usando um LLM, com pelo menos uma skill configurada. Ao final, voce tera a base sobre a qual pode construir qualquer coisa.
O exercicio esta dividido em etapas progressivas. Cada etapa produz um resultado funcional, entao mesmo que voce nao complete tudo, tera algo rodando. A estimativa de tempo e 60-90 minutos para o setup basico, mais 30-60 minutos para a skill customizada. Se voce ja tem experiencia com Node.js e Telegram bots, pode ser mais rapido.
Pre-requisitos: Node.js 18+ instalado, uma conta no Telegram, e acesso a pelo menos um provedor de LLM (Ollama local e o mais facil para comecar, pois e gratuito e nao requer API key externa). Se voce quer usar Claude, precisara de uma chave de API da Anthropic.
Passo a Passo do Exercicio
Criar o Bot no Telegram
Abra o Telegram, busque @BotFather, envie /newbot, escolha um nome e username. Copie o token gerado. Depois, envie uma mensagem para o bot e use a API do Telegram para descobrir seu chat_id (ou use @userinfobot).
Clonar e Configurar o Repositorio
Clone o repositorio, copie o .env.example para .env, e preencha as variaveis obrigatorias:
git clone [repo-url] meu-bot && cd meu-bot
cp .env.example .env
# Edite .env: BOT_TOKEN, ALLOWED_CHAT_ID, ANTHROPIC_API_KEY ou OLLAMA config
npm install && npm run build
Personalizar o CLAUDE.md
Abra o CLAUDE.md e substitua todos os placeholders [BRACKETED] com suas informacoes. De um nome ao bot, descreva quem voce e, liste os projetos em que trabalha. Esse arquivo e o que faz o bot ser SEU assistente e nao um chatbot generico.
Primeiro Teste
Rode o bot com npm start ou node dist/index.js. Envie uma mensagem no Telegram. Se tudo estiver correto, voce recebera uma resposta. Verifique os logs no terminal para debug. Erros comuns: token errado, chat_id errado, Ollama nao rodando.
Criar sua Primeira Skill
Crie uma skill simples. Exemplo: um script que retorna o status de um servico ou o clima da sua cidade. Passos:
- 1. Crie o script em ~/.claude/skills/minha-skill.md
- 2. Adicione na tabela de skills do CLAUDE.md
- 3. Teste mandando uma mensagem com o trigger
Rodar como Servico
Configure o bot para rodar permanentemente. Opcoes:
- pm2: npm install -g pm2 && pm2 start dist/index.js --name meu-bot
- systemd: crie um .service file para auto-restart e boot start
- Docker: use o Dockerfile incluido para containerizar
Checklist de Entregaveis
Dica Pratica
Se voce travar em algum passo, use o proprio Claude Code para ajudar. Rode "claude" no terminal dentro do diretorio do projeto e descreva o problema. O Claude pode ler os logs, diagnosticar o erro, e sugerir a correcao. E meta: usar IA para configurar seu bot de IA.
Para a skill customizada, comece com algo util pra voce no dia a dia. Se voce acompanha criptomoedas, faca uma skill que pega precos. Se voce gerencia servidores, faca uma skill de health check. A melhor skill e a que voce vai usar amanha.
Fazer
- ✓Seguir o passo a passo na ordem (cada etapa depende da anterior)
- ✓Testar cada etapa antes de prosseguir para a proxima
- ✓Ler os logs do terminal quando algo nao funcionar
- ✓Usar Claude Code como par de debug quando travar
Evitar
- ✗Pular o CLAUDE.md (vai funcionar, mas mal)
- ✗Nao configurar ALLOWED_CHAT_ID (seguranca!)
- ✗Tentar fazer tudo de uma vez sem testar incrementalmente
- ✗Desistir no primeiro erro (logs sempre tem a resposta)
Resumo do Modulo 5.5
Voce agora conhece os frameworks de referencia para bots pessoais com IA e tem as ferramentas para construir o seu. Vamos revisar: