Arquitetura do OpenClaw: Como Funciona por Dentro

Antes de criar seu primeiro agente ou configurar qualquer automação, vale entender como o OpenClaw funciona por dentro. Não estamos falando de teoria acadêmica — estamos falando do modelo mental que vai determinar se você configura tudo certo na primeira tentativa ou passa horas depurando comportamentos inesperados.

Este capítulo explica cada componente, como eles se conectam e por que foram projetados dessa forma.

O Modelo Mental Correto

A analogia mais precisa para o OpenClaw é: pense nele como um Node.js para agentes de IA.

Node.js é um runtime — ele não faz nada por si só, mas fornece a infraestrutura para que código JavaScript execute, gerencie I/O assíncrono e se comunique com o mundo externo. O OpenClaw faz a mesma coisa para agentes de IA: ele fornece a infraestrutura para que um agente receba mensagens, pense no que fazer, execute ferramentas e envie respostas.

Isso significa que o OpenClaw em si é agnóstico ao conteúdo. Ele não “sabe” nada sobre o seu negócio — isso é definido pela configuração do agente e pelo modelo de IA que você conectar.

Outra analogia que ajuda: o OpenClaw é como um gerente de projetos muito eficiente. Quando uma tarefa chega, ele não executa sozinho — ele delega para especialistas (ferramentas), coordena a sequência, verifica os resultados e entrega a resposta final. O gerente não é pedreiro, eletricista ou pintor. Ele sabe chamar quem é.

Os Quatro Componentes Centrais

1. O Agente (O “Cérebro”)

O agente é a entidade central do OpenClaw. Cada agente tem:

Nome e identidade: como o agente se apresenta e qual papel ele desempenha
System prompt: as instruções base que definem comportamento, tom, limites e conhecimento do agente
Memória: contexto da conversa atual e, opcionalmente, memória persistente entre sessões
Conjunto de ferramentas disponíveis: quais ações o agente pode executar

Um agente não executa nada diretamente. Ele raciocina — usando o modelo de IA conectado — e decide quais ferramentas chamar, em qual ordem, com quais parâmetros. O resultado das ferramentas volta para o agente, que processa e decide o próximo passo.

É esse loop de raciocínio-ação que diferencia um agente de IA de uma simples automação baseada em regras.

2. Canais (Como o Agente Comunica)

Os canais são as interfaces de entrada e saída do agente — onde as mensagens chegam e por onde as respostas são enviadas.

O OpenClaw suporta vários canais:

WhatsApp: via WhatsApp Business API ou adaptadores de número pessoal
Telegram: via Bot API (mais simples de configurar, menos regulado)
Slack: para contextos corporativos e equipes
Discord: para comunidades e grupos
HTTP/Webhook: para integrações diretas com outros sistemas

O OpenClaw suporta 30+ canais — incluindo Signal, iMessage, Matrix, Nostr, Google Chat, Mattermost e outros. WhatsApp e Telegram são os mais usados no Brasil.

Para o mercado brasileiro, o WhatsApp é praticamente o único canal que importa para B2C e MEI. 99% dos seus clientes já estão lá, já sabem usar, e esperam atendimento por WhatsApp. Os outros canais têm casos de uso específicos — Telegram para comunidades técnicas, Slack para equipes internas.

Cada canal tem seu próprio adaptador no OpenClaw, que normaliza as mensagens para um formato interno padrão antes de entregar ao agente. Isso significa que o mesmo agente pode operar em múltiplos canais sem modificação — a configuração do canal é separada da configuração do agente.

3. Ferramentas (O Que o Agente Pode Fazer)

Ferramentas são as capacidades de ação do agente. Sem ferramentas, um agente só consegue gerar texto — com ferramentas, ele pode interagir com o mundo.

Exemplos de ferramentas disponíveis no OpenClaw:

web_request: fazer chamadas HTTP para APIs externas
search_web: buscar informações na internet
read_file / write_file: ler e escrever arquivos no sistema
execute_code: executar código Python ou JavaScript em sandbox
database_query: consultar bancos de dados
send_email: enviar e-mails via SMTP ou serviços como Resend

Ferramentas também podem ser criadas por você — qualquer função que possa ser descrita por uma especificação JSON pode virar uma ferramenta do OpenClaw.

O conceito importante aqui: o agente nunca usa uma ferramenta sem antes decidir que ela é necessária. Essa decisão é feita pelo modelo de IA com base no raciocínio sobre o que foi pedido. Não é regra-if-then, é julgamento.

Skills são workflows reutilizáveis que ensinam o agente a usar ferramentas. O OpenClaw organiza skills em 3 níveis de prioridade: workspace (suas skills locais, prioridade máxima), managed (instaladas via ClawHub, o registro público), e bundled (incluídas na instalação). Uma skill local sempre sobrescreve uma skill de mesmo nome instalada via ClawHub.

4. Modelo LLM (O Raciocínio)

O modelo de linguagem é o que faz o agente ser inteligente. O OpenClaw não tem inteligência própria — ele conecta a provedores de IA externos (ou locais) para o raciocínio.

Provedores suportados:

Anthropic Claude (Haiku, Sonnet, Opus): excelente raciocínio, ótimo custo-benefício
OpenAI GPT (GPT-4o, GPT-4o mini): capacidade multimodal forte
Ollama: modelos rodando localmente (Llama 3, Mistral, Qwen)
Google Gemini: alternativa com janela de contexto grande
Groq: inferência muito rápida para modelos open source

A escolha do modelo afeta diretamente custo, velocidade e qualidade das respostas. Para o mercado brasileiro, existe uma consideração importante: modelos locais via Ollama eliminam o custo variável em dólar e mantêm os dados no seu próprio servidor.

Além desses quatro componentes, o OpenClaw tem um sistema de memória persistente. Arquivos markdown no workspace (MEMORY.md + diários em memory/YYYY-MM-DD.md) funcionam como a memória de longo prazo do agente. Desde a v2026.3.22, a busca por memória usa indexação vetorial com busca híbrida (BM25 + semântica) — o agente encontra informações por significado, não só por palavras exatas.

Como um Nó Funciona (O Conceito de Grafo)

O OpenClaw representa fluxos de trabalho como grafos. Cada etapa de um processo é um nó — uma unidade discreta de trabalho.

Tipos de nó:

Nó de entrada: onde a mensagem chega (canal)
Nó de agente: onde o raciocínio acontece
Nó de ferramenta: onde uma ação é executada
Nó de condição: onde um caminho é escolhido baseado em resultado
Nó de saída: onde a resposta é enviada

Um fluxo simples tem apenas 3 nós: entrada → agente → saída. Um fluxo complexo pode ter dezenas de nós com condicionais, loops e múltiplos agentes especializados colaborando.

Para começar, você não precisa pensar em grafos explicitamente — a configuração básica cria o grafo automaticamente. Mas quando você começar a criar automações mais sofisticadas, esse modelo vai fazer muito sentido.

Por Que Modelos Locais Importam no Brasil

Dois motivos práticos para considerar Ollama com modelos locais:

LGPD e privacidade: quando você manda dados de clientes para uma API americana, esses dados saem do Brasil. Para MEIs e pequenas empresas que lidam com informações sensíveis (saúde, finanças, dados pessoais), manter o processamento local reduz o risco de conformidade com a Lei Geral de Proteção de Dados.

Custo sem variação cambial: APIs de IA cobram em dólar. Com o câmbio atual, R$ 0,01 por mil tokens pode não parecer muito, mas em um atendimento de alto volume (mil conversas por dia, cada uma com 2-3 chamadas de API) o custo pode surpreender. Modelos locais têm custo fixo — a energia elétrica e o VPS que já está pago.

A contrapartida: modelos locais menores são menos capazes que Claude Opus ou GPT-4o para tarefas complexas. Para atendimento simples e consulta de dados, Llama 3 8B roda muito bem em um VPS de 8 GB de RAM. Para raciocínio mais sofisticado, modelos cloud ainda levam vantagem.

Na Prática: Visualizando a Arquitetura com WhatsApp

Vamos percorrer o fluxo completo de uma mensagem real:

Cenário: um cliente manda “Qual o horário de funcionamento?” para o WhatsApp do meu restaurante.

Passo 1 — Recepção no Canal O adaptador WhatsApp do OpenClaw recebe a mensagem via webhook. Ela é normalizada para o formato interno: { from: "+5511999999999", text: "Qual o horário de funcionamento?", channel: "whatsapp" }.

Passo 2 — Entrega ao Agente O agente “Atendimento Restaurante” recebe a mensagem. Ele tem no system prompt: “Você é o assistente do Restaurante X. Horário: seg-sex 11h-22h, sab-dom 11h-23h.”

Passo 3 — Raciocínio O modelo de IA (digamos, Claude Haiku) processa a mensagem e o system prompt. Conclui: a resposta está no contexto do system prompt, não precisa chamar nenhuma ferramenta. Gera a resposta diretamente.

Passo 4 — Resposta O agente devolve a resposta ao adaptador WhatsApp, que envia para o número do cliente via API.

Tempo total: 1-3 segundos.

Agora um fluxo mais complexo: o cliente manda o CEP e pergunta se o restaurante faz entrega até aquele endereço.

Nesse caso, o agente vai reconhecer que precisa consultar uma ferramenta de CEP (como ViaCEP), verificar a distância, compará-la com o raio de entrega configurado, e então responder. São 3-4 chamadas de ferramenta antes da resposta final. O agente coordena tudo isso automaticamente.

É exatamente esse tipo de fluxo que vamos explorar nos capítulos seguintes. O próximo passo é entender em detalhes como configurar canais e modelos de IA, e se você quiser já se familiarizar com os termos técnicos, o glossário tem definições de todos os conceitos mencionados aqui.

Baseado no “Automate Everything: The OpenClaw Handbook” por Kelly Claude (CC BY 4.0). Adaptado e expandido para o mercado brasileiro.