Arquitetura OpenClaw: Como Funciona Por Dentro

Quer entender como o OpenClaw realmente funciona? Este guia técnico explica a arquitetura completa — do processamento de mensagens até a orquestração de múltiplos agentes.

Baseado em threads técnicas da comunidade, traduzidas e expandidas para brasileiros que querem ir além do básico.

O Que é o OpenClaw Tecnicamente?

Todo mundo sabe que o OpenClaw é um assistente pessoal de IA que roda localmente. Mas o que ele é realmente?

OpenClaw é uma aplicação CLI em TypeScript.

Não é Python. Não é Next.js. Não é um web app.

É um processo que:

• Roda na sua máquina e expõe um servidor gateway para conexões de canais (Telegram, WhatsApp, Slack, etc.)
• Faz chamadas para APIs de LLM (Anthropic, OpenAI, modelos locais)
• Executa ferramentas localmente
• Faz o que você quiser no seu computador

A Arquitetura

Quando você manda uma mensagem pro Clawd, aqui está o que acontece:

1. Channel Adapter (Adaptador de Canal)

O adaptador do canal recebe sua mensagem e processa (normaliza, extrai anexos). Cada mensageiro tem seu adaptador dedicado - WhatsApp, Telegram, Discord, etc.

2. Gateway Server (Servidor Gateway)

O coração do OpenClaw. É o coordenador de tarefas e sessões.

Ele pega sua mensagem e passa para a sessão correta, gerenciando múltiplas requisições simultâneas.

Para serializar operações, o Clawd usa uma fila de comandos baseada em lanes:

• Cada sessão tem sua própria lane dedicada
• Tarefas de baixo risco podem rodar em lanes paralelas (cron jobs)

Princípio: Default para Serial, vá para Paralelo explicitamente.

Esse insight vem do artigo “Don’t Build Multi-Agents” da Cognition. Um setup async simples por agente deixa você com um monte de lixo intercalado. Logs ficam ilegíveis e race conditions viram um medo constante.

A Lane é uma abstração sobre filas onde serialização é a arquitetura padrão, não um afterthought. O modelo mental muda de “o que preciso lockar?” para “o que é seguro paralelizar?”

3. Agent Runner

Aqui entra a IA de verdade. O Agent Runner:

• Decide qual modelo usar
• Escolhe a API key (se nenhuma funcionar, marca o perfil em cooldown e tenta o próximo)
• Faz fallback para modelo diferente se o primário falhar
• Monta o system prompt dinamicamente com ferramentas, skills, memória
• Adiciona o histórico da sessão (de um arquivo .jsonl)
• Verifica se há espaço suficiente na context window

Se o contexto estiver quase cheio, ele compacta a sessão (resume o contexto) ou falha graciosamente.

4. LLM API Call

A chamada pro LLM faz streaming de respostas com uma abstração sobre diferentes providers. Também pode solicitar extended thinking se o modelo suportar.

5. Agentic Loop (Loop Agêntico)

Se o LLM retorna uma chamada de ferramenta, o Clawd executa localmente e adiciona os resultados à conversa. Isso se repete até o LLM responder com texto final ou atingir o máximo de turnos (padrão ~20).

É aqui que a mágica do Computer Use acontece.

6. Response Path

As respostas voltam pelo canal. A sessão é persistida em um JSONL básico com cada linha sendo um objeto JSON da mensagem, tool calls, resultados, respostas, etc.

Como o Clawd Lembra

Sem um sistema de memória apropriado, um assistente de IA é tão bom quanto um peixinho dourado.

O Clawd gerencia memória através de dois sistemas:

1. Transcripts de sessão em JSONL - histórico da conversa
2. Arquivos de memória em markdown - MEMORY.md ou pasta memory/

Busca Híbrida

Para pesquisa, usa uma combinação de:

• Busca vetorial (semântica)
• Keyword matches (exata)

Então buscar por “bug de autenticação” encontra documentos mencionando “problemas de auth” (semântico) E a frase exata (keyword).

• SQLite para busca vetorial
• FTS5 (extensão SQLite) para keywords
• Provider de embedding configurável

Smart Syncing

O sincronismo dispara quando o file watcher detecta mudanças nos arquivos.

O markdown é gerado pelo próprio agente usando a ferramenta write padrão. Não existe API especial de memory-write. O agente simplesmente escreve em memory/*.md.

Quando uma nova conversa começa, um hook pega a conversa anterior e escreve um resumo em markdown.

Insight: O sistema de memória do Clawd é surpreendentemente simples. Sem merge de memórias, sem compressões mensais/semanais. Simplicidade explicável ao invés de spaghetti complexo.

As Garras do Clawd: Como Ele Usa Seu Computador

Um dos MOATs do Clawd: você dá um computador pra ele e deixa ele usar.

Ferramenta Exec

Roda comandos shell em:

• Sandbox (padrão) - comandos rodam em container Docker
• Diretamente na máquina host
• Em dispositivos remotos

Outras Ferramentas

• Filesystem - read, write, edit
• Browser - baseado em Playwright com snapshots semânticos
• Process management - comandos de longa duração, kill de processos

Segurança

Similar ao Claude Code, existe uma allowlist para comandos:

• Allow once / Always / Deny

// ~/.clawdbot/exec-approvals.json
{
  "agents": {
    "main": {
      "allowlist": [
        { "pattern": "/usr/bin/npm", "lastUsedAt": 1706644800 },
        { "pattern": "/opt/homebrew/bin/git", "lastUsedAt": 1706644900 }
      ]
    }
  }
}

Comandos seguros (jq, grep, cut, sort, uniq, head, tail, tr, wc) são pré-aprovados.

Construções shell perigosas são bloqueadas por padrão:

# Esses são rejeitados antes da execução:
npm install $(cat /etc/passwd)  # command substitution
cat file > /etc/hosts           # redirection
rm -rf / || echo "failed"       # chained with ||
(sudo rm -rf /)                 # subshell

A ideia é ter tanta autonomia quanto o usuário permitir.

Browser: Snapshots Semânticos

A ferramenta de browser não usa screenshots primariamente, mas snapshots semânticos - representação textual da árvore de acessibilidade (ARIA) da página.

O agente vê:

- button "Sign In" [ref=1]
- textbox "Email" [ref=2]
- textbox "Password" [ref=3]
- link "Forgot password?" [ref=4]
- heading "Welcome back"

Vantagens:

• Screenshot: ~5 MB | Snapshot semântico: <50 KB
• Fração do custo de tokens de uma imagem
• Navegar sites não é necessariamente uma tarefa visual

Agentes Paralelos vs Sub-Agentes

Baseado no artigo de @dansemperepico, existem três momentos marcantes na jornada de quem entra em IA:

1. Primeira vez usando LLM em chat (ChatGPT, Claude)
2. Primeira vez usando um agente de IA (Claude Code, OpenClaw)
3. Primeira vez usando múltiplos agentes simultaneamente

É aqui que você faz em 5 minutos o que levaria 5 horas.

Agentes Paralelos

São agentes que rodam independentemente, cada um com:

• Próprio contexto
• Própria memória
• Própria personalidade
• Bot Telegram separado

Eles podem se comunicar e compartilhar conhecimento.

Pense como: Três funcionários diferentes com papéis distintos que reportam diretamente a você.

Exemplo prático:

• Chief of Staff (Opus 4.5 - complexo)
• Chief Marketing Officer (Gemini - escrita)
• Health Coach (Sonnet - mais barato)

Sub-Agentes

São workers temporários spawneados por um agente paralelo para tarefas específicas.

Características:

• Descartáveis
• Não retêm memória (feature, não bug - mantém context windows limpos)
• Gerenciados pelo agente principal
• Quando terminam, o agente principal entrega o resultado

Pense como: Um chefe de departamento contratando freelancers projeto a projeto.

Quando Usar Cada Um

Caso de Uso: Backup

Quando o agente principal quebra algo na própria configuração, você pode usar outro agente paralelo para troubleshootar e trazer o primeiro de volta online!

Caso de Uso: Economia

Agente principal (Opus 4.5 - caro) spawna sub-agentes (Sonnet - barato) para organizar 40+ tarefas. Enquanto o sub-agente trabalha, você ainda pode usar o principal para outras coisas.

Conclusão

O OpenClaw é elegantemente simples por dentro:

• Lanes para serialização ao invés de async spaghetti
• Memória híbrida com busca vetorial + keyword
• Snapshots semânticos ao invés de screenshots
• Allowlist para segurança com autonomia

E com agentes paralelos + sub-agentes, você tem um exército de robôs trabalhando para você.

Próximos Passos

Agora que você entende a arquitetura:

• 🛠️ Criar Skills Personalizadas — Aproveite o sistema de extensões
• 🔒 Segurança e Prompt Injection — Entenda as proteções
• 📊 Auditoria e Logs — Configure monitoramento
• 🚀 Setup Completo em 30 Minutos — Coloque tudo em prática

Baseado nas threads de @Hesamation e @dansemperepico.