tech

Clawdbot: o assistente pessoal de IA que você roda nos seus próprios dispositivos

Clawdbot é um assistente pessoal de IA open source, self-hosted e orientado a agentes. Ele roda nos seus próprios dispositivos, integra canais como WhatsApp e Telegram e executa tarefas reais com controle, segurança e extensibilidade.

Pablo Murad

Pablo Murad

— 6 min read
Clawdbot: o assistente pessoal de IA que você roda nos seus próprios dispositivos

O Clawdbot é um projeto open source de “assistente pessoal” baseado em agentes de IA, desenhado para funcionar nos seus próprios dispositivos e conversar com você nos canais que você já usa (como WhatsApp, Telegram, Discord, Slack e outros). Em vez de ser apenas um chat, a proposta do Clawdbot é executar tarefas reais: operar arquivos, disparar automações, consultar serviços, acionar “skills” e, quando permitido, até rodar comandos em máquinas locais ou remotas.

A ideia central é simples: você controla o ambiente (onde roda, quais ferramentas existem, quais integrações são permitidas e quem pode falar com o bot). O resultado é um assistente com “sensação de local”, extensível e hackeável.

O que torna o Clawdbot diferente?

Há dois pontos que mudam o jogo:

  1. Arquitetura local-first e controlável
    O “cérebro operacional” é um processo chamado Gateway, que recebe mensagens, monta contexto, chama o modelo e decide quais ferramentas podem ser usadas.

  2. Ferramentas e extensões com governança explícita
    O Clawdbot diferencia (a) ferramentas nativas (tools), (b) skills (pacotes de capacidade) e (c) nós (devices periféricos). E coloca “guard rails” como allowlists, pairing e sandboxing para reduzir o risco de um agente com acesso indevido.

Visão de alto nível: como funciona

Em termos de fluxo, o Clawdbot funciona assim:

  1. Você envia uma mensagem por um canal (ex.: WhatsApp, Telegram, Discord).
  2. O Gateway recebe o evento e decide qual sessão deve ser usada.
  3. Ele monta o contexto (histórico da sessão + arquivos de bootstrap + estado).
  4. Executa um loop agentic (modelo + ferramentas) e produz resposta/ações.
  5. Envia a resposta de volta ao canal de origem (roteamento determinístico).

Componentes principais

1) Gateway (o “control plane”)

O Gateway é o processo central. Ele:

  • mantém o estado das sessões (histórico, tokens, metadados);
  • expõe um protocolo via WebSocket para clientes e nós;
  • gerencia pairing, autenticação e roteamento de mensagens;
  • aplica política de ferramentas (o que é permitido para o agente fazer);
  • serve interfaces (ex.: Control UI / Dashboard, Canvas host) em portas locais.

Em outras palavras: o Gateway é o “dono da verdade” sobre sessões e execução do agente.

2) Agente (runtime) e o “agentic loop”

O Clawdbot executa um runtime de agente embutido e trata cada interação como um loop serializado: ingestão → montagem de contexto → inferência → execução de ferramentas → streaming de resposta → persistência.

Esse loop é deliberadamente “autêntico” (no sentido de ser o caminho oficial que passa por todas as regras de sessão, ferramentas e persistência), e não um atalho.

3) Sessões (memória operacional)

Sessões são a unidade de “continuidade” do assistente. O projeto oferece modos de roteamento (ex.: sessão única “main”, isolamento por peer, isolamento por canal+peer etc.). O ponto importante: a sessão é do Gateway, não do app cliente.

Arquivos típicos ficam no host do Gateway, por agente, com store e transcrições JSONL.

4) Workspace do agente e arquivos de bootstrap

O Clawdbot usa um diretório de workspace do agente como diretório de trabalho para ferramentas e contexto. No primeiro turno de uma sessão, ele injeta arquivos “bootstrap” (se existirem) diretamente no contexto do agente, como:

  • AGENTS.md (instruções operacionais + “memória”),
  • SOUL.md (persona, limites, tom),
  • TOOLS.md (notas de ferramentas e convenções),
  • IDENTITY.md, USER.md, etc.

Isso é parte do que torna o Clawdbot “personalizável sem mexer no core”: você versiona e edita esses arquivos.

5) Tools (ferramentas nativas) vs Skills (pacotes)

Tools são capacidades “first-class” expostas pelo próprio Clawdbot (browser, nodes, cron, canvas etc.). Em paralelo, existem skills, que são diretórios com um SKILL.md e arquivos de suporte. As skills são carregadas de forma controlada e o Clawdbot tira um snapshot das skills elegíveis no início da sessão (com opções de hot reload).

O ecossistema de skills pode ser expandido via ClawdHub, um registro público para buscar/instalar/atualizar/publicar skills.

6) Nodes (dispositivos periféricos)

Um node é um dispositivo/host que se conecta ao Gateway com role: "node" e expõe um conjunto de comandos (ex.: câmera, canvas, system.run, etc.). Isso permite, por exemplo:

  • usar um celular como “câmera” do agente;
  • executar comandos em uma máquina remota (build server, NAS, laboratório) sem rodar um Gateway completo lá;
  • separar “onde o modelo roda” (Gateway) de “onde comandos executam” (Node host).

7) Workflows com Lobster (macro engine)

O Lobster é um “workflow shell” nativo do ecossistema Clawdbot: um motor de pipelines tipados (JSON-first), jobs e gates de aprovação. A proposta é dar determinismo, reusabilidade e resumabilidade a automações — e permitir que o agente dispare um workflow inteiro em “um passo”.

Canais (WhatsApp, Telegram, Discord, Slack, etc.)

O Clawdbot atua como uma ponte: recebe e envia mensagens via conectores específicos do canal e roteia tudo para o Gateway/agent runtime. A documentação oficial descreve setup por canal (tokens, permissões, policies de DM, pairing, roteamento e isolamento por canal).

Como regra, o roteamento de resposta é determinístico: a resposta volta para o mesmo canal de onde a mensagem entrou.

Modelos e provedores (OpenAI, Anthropic, OpenRouter e outros)

O Clawdbot suporta múltiplos provedores de modelos. A convenção típica é provider/model (por exemplo, openai-codex/gpt-5.2 ou zai/glm-4.7). Ele também oferece:

  • wizard (clawdbot onboard) para configurar modelo + autenticação;
  • suporte a OAuth (“subscription auth”) quando o provedor oferece, e API keys quando esse é o caminho recomendado;
  • failover em duas etapas: rotação de perfis de auth dentro do provedor, depois fallback para o próximo modelo configurado.

Há também suporte a modelos locais, mas a própria documentação é direta: para a experiência completa (contexto grande + defesas fortes), “local” exige hardware robusto; setups menores tendem a aumentar latência e risco.

Instalação: o caminho típico

A forma mais comum de começar é via Node.js (requisito: Node 22+ em setups recentes).

1) Instalar CLI

npm install -g clawdbot@latest
# ou
pnpm add -g clawdbot@latest

2) Rodar o wizard de onboarding (recomendado)

clawdbot onboard

3) Subir o Gateway e abrir o Dashboard

O Dashboard local costuma ficar em:

  • http://127.0.0.1:18789/

Se o Gateway não estiver rodando, inicie com:

clawdbot gateway

4) Conectar um canal (exemplo Discord)

A documentação do canal explica token, permissões e policies de DM/pairing. Exemplo de variável:

export DISCORD_BOT_TOKEN="..."

Segurança: onde você NÃO pode ser ingênuo

Se você quer rodar um agente que pode executar ações, precisa tratar isso como infraestrutura — não como “um chatbot”. A documentação do Clawdbot enfatiza duas camadas distintas de segurança:

  1. Quem pode falar com o bot (allowlists/pairing/policies por canal, DM e grupos)
  2. O que o bot pode fazer (tool policy, exec approvals, sandboxing, elevated mode)

Alguns princípios práticos:

1) Trave o acesso de entrada (DM e grupos)

  • Use allowlists (allowFrom) e/ou dmPolicy="pairing" para evitar bot “aberto ao mundo”.
  • Em canais com grupos/servidores, use allowlists por grupo/canal/guild.

2) Separe “conversar” de “executar”

  • Mesmo que o bot aceite mensagens, isso não significa que ele deva poder rodar comandos.
  • Use política de ferramentas para negar o que não precisa (deny wins).

3) Use sandbox quando fizer sentido

O Clawdbot oferece execução em Docker sandbox (especialmente útil para sessões não-main), permitindo isolar tool execution do host.

4) Entenda “Elevated mode”

“Elevated” é um escape hatch (principalmente quando sandboxed) para permitir exec no host em condições controladas. É útil, mas é a primeira coisa que você deve evitar habilitar sem necessidade.

5) Nodes com exec: sempre com approvals

Exec em node host é protegido por allowlists/approvals (ex.: arquivo de approvals no host do node). Isso ajuda a reduzir o risco de prompt injection virar comando arbitrário.

Casos de uso reais (e plausíveis)

Alguns usos que fazem sentido e se beneficiam da arquitetura:

  • Assistente pessoal de mensagens: rascunhar, resumir, organizar, buscar histórico por sessão.
  • Operações leves: criar/atualizar arquivos no workspace, gerar relatórios, organizar pastas.
  • Automação com trilhas de auditoria: workflows “tipados” (Lobster) com gates de aprovação.
  • Orquestração multi-dispositivo: usar um node móvel para câmera/áudio, e um node remoto para exec em servidor.

O que não faz sentido é tratar isso como um “SaaS mágico” sem governança. Se você habilitar exec no host e expor DM aberto, você está pedindo por problemas.

Limitações e trade-offs (sem romantizar)

  • Complexidade operacional: você está operando um sistema com gateway, canais, auth, sessões e (às vezes) Docker. Isso é mais “infra” do que “app”.
  • Risco inerente a agentes com ferramentas: prompt injection e abuso de ferramentas são riscos reais; você precisa configurar e auditar.
  • Manutenção: projetos open source evoluem rápido; mudanças em APIs de provedores e canais são rotina.
  • Modelos locais: possíveis, mas a própria documentação assume que “experiência boa” exige contexto grande e hardware forte; não conte com milagre.

Conclusão

O Clawdbot é uma proposta séria de assistente pessoal agentic, orientada a “rodar com você no controle”: canais do dia a dia, um Gateway como fonte de verdade, sessões persistentes, governança de ferramentas, nodes periféricos e um ecossistema de skills/workflows.

Se você quer “um chatbot”, há alternativas mais simples. Se você quer um assistente que faz coisas e aceita investir em setup e segurança, o Clawdbot é uma das abordagens mais completas e explícitas sobre riscos e controles.

Referências (leitura recomendada)

Read more