🦞 OpenClaw

🌐 Gateway OPENCLAW

Processo Node.js central. WebSocket server na porta 18789. Tudo passa por ele — mensagens, tool calls, crons, health checks. É o control plane único.

Componentes internos:

• Session Router — recebe mensagem → decide qual agente responde (via routing bindings)
• Channel Adapters — Baileys (WhatsApp), grammY (Telegram), discord.js, Slack SDK, +40 canais
• Auth & Device Pairing — Ed25519 challenge-response. Dispositivos se autenticam via assinatura criptográfica.
• Event Bus — tick a cada 15s, presence, health monitor
• Cron Scheduler — executa jobs registrados
• Health Monitor — verifica canais a cada 5 min, auto-restart até 10x/hora

Protocolo WebSocket:
1. Gateway envia: connect.challenge (nonce + timestamp)
2. Cliente envia: connect (role, scope, assinatura Ed25519)
3. Gateway responde: hello-ok (protocol, policies, tick 15s)

Frame types:
  req  → client para server (method + params)
  res  → server para client (payload | error)
  event → push assíncrono (agent, presence, health)

Bind modes: loopback | lan | tailnet | auto | custom
Auth modes: token | password | trusted-proxy | none

O LLM NÃO interage com o gateway. O gateway chama o LLM via API HTTP. O LLM não sabe que o gateway existe.

🤖 Agentes OPENCLAW

Cada agente = contexto de execução 100% isolado: workspace próprio, auth própria, sessions próprias, tool permissions próprias.

Soul-Based System — arquivos que definem o agente:

workspace/
├── AGENTS.md      # Regras operacionais (alta prioridade no prompt)
├── SOUL.md        # Personalidade, tom, idioma
├── IDENTITY.md    # Nome, emoji, avatar
├── USER.md        # Perfil do humano (nome, timezone)
├── TOOLS.md       # Notas sobre tools locais
├── MEMORY.md      # Memória curada de longo prazo
├── HEARTBEAT.md   # Tarefas periódicas (cron-like leve)
└── BOOTSTRAP.md   # Guia inicial (1x, auto-deleta)

Composição do system prompt:

PI Core (base) → AGENTS.md → SOUL.md → Skills → Memory → Tool defs

O OpenClaw monta tudo isso como um prompt gigante
e envia ao LLM. O LLM "é" o agente porque leu
essas instruções — mas se trocar o SOUL.md,
a personalidade muda, mesmo com o mesmo LLM.

Routing de mensagens (quem responde):

• 1. Peer match exato (DM/grupo/canal ID)
• 2. Guild + role (Discord)
• 3. Channel wildcard
• 4. Default agent (fallback) — recebe tudo que não tem match

Multi-agent: vários agentes no mesmo gateway. Cada um responde por routing bindings. Isolamento total — um não vê as sessions do outro.

🔄 ReAct Loop OPENCLAW orquestra → LLM raciocina

O loop principal de execução do agente. O LLM raciocina, chama tools, observa resultados, repete.

┌──────────────────────────────────────────────┐
│                 ReAct Loop                    │
│                                              │
│   ┌──────────┐    ┌──────────┐    ┌────────┐│
│   │ 💭 REASON │───→│ ⚡ ACT    │───→│ 👀 OBS ││
│   │  (LLM)   │    │ (tool)   │    │(result)││
│   └────▲─────┘    └──────────┘    └───┬────┘│
│        │                              │      │
│        └──────────────────────────────┘      │
│              repete até concluir             │
└──────────────────────────────────────────────┘

Quem faz o quê:
  REASON  → LLM decide o que fazer (inferência)
  ACT     → OpenClaw intercepta tool call, executa no host
  OBSERVE → OpenClaw devolve resultado ao LLM
  REPEAT  → OpenClaw verifica se LLM quer outra tool call

O OpenClaw é o "maestro". O LLM é o "músico".

Exemplo concreto (youtube-summary):

• REASON: "Preciso extrair metadata do vídeo"
• ACT: exec("yt-dlp --dump-single-json URL")
• OBSERVE: JSON com título, canal, duração, legendas
• REASON: "Agora preciso baixar legendas em pt-BR"
• ACT: exec("yt-dlp --write-auto-subs --skip-download...")
• OBSERVE: arquivo .vtt salvo
• REASON: "Vou ler e sumarizar"
• ACT: read("/tmp/subs.vtt")
• REASON: "Pronto, vou gerar o resumo em português"
• → Resposta final enviada ao usuário

🛠️ Tools (~25 built-in) OPENCLAW

Capacidades que o agente pode usar. O OpenClaw intercepta tool calls do LLM e executa no host. O LLM pede, o OpenClaw faz.

Shell:      bash, exec
Filesystem: read, write, edit, apply_patch
Browser:    browser_* (Playwright/Chrome CDP)
Web:        web_search (Brave), web_fetch
Media:      image, tts
Control:    gateway, cron, message
Sessions:   sessions_list, sessions_send, sessions_history, sessions_spawn
Memory:     memory_search
Outros:     nodes, canvas, elevated

Tool Permissions (narrowing — só restringe, nunca expande):

Tool Profile → Global Policy → Agent Policy → Sandbox Policy

Cada camada pode REMOVER acesso, nunca adicionar.

Profiles:
  coding       → ler, escrever, executar
  analysis     → ler, explorar (não escreve)
  verification → ler, executar (não escreve)
  messaging    → set restrito para assistentes

O LLM vê: uma lista de tools disponíveis no prompt. Ele "chama" uma tool gerando JSON com name + args. O OpenClaw intercepta, executa, e devolve o resultado como a próxima mensagem.

📋 Skills OPENCLAW

SKILL.md = runbooks em Markdown. Não são plugins executáveis. São instruções que ensinam o LLM a orquestrar tools para uma tarefa.

Precedência (alta → baixa):
1. Workspace: <workspace>/skills/     (maior)
2. Managed:   ~/.openclaw/skills/
3. Bundled:   dentro do pacote OpenClaw
4. Extra:     via skills.load.extraDirs

Lazy-loading: O prompt inclui apenas um registry compacto (nome + descrição). O SKILL.md completo só é lido quando o LLM decide usar a skill (via tool read).

Formato SKILL.md:

---
name: youtube-summary
description: Resumo de vídeos YouTube
user-invocable: true
metadata: {"openclaw":{"emoji":"▶️","os":["linux"]}}
---
## What it does
## Inputs needed
## Workflow (passos numerados)
## Output format
## Guardrails
## Failure handling

Token impact: ~24 tokens por skill no registry. Skills com always: true são sempre injetadas.

⏱️ Cron Engine OPENCLAW

Agendador de jobs built-in no gateway. Dispara sessões de agente em schedule.

openclaw cron add --name "job" --agent <id> \
  --every 5m --session isolated \
  --timeout-seconds 600 --message "prompt"

openclaw cron list          # Ver jobs ativos
openclaw cron delete --id X # Remover job
openclaw cron run --id X    # Forçar execução

Como funciona:

• Jobs armazenados em ~/.openclaw/cron/jobs.json
• Gateway scheduler verifica a cada minuto
• Quando dispara: spawna sessão isolada do agente com o prompt do job
• Sessão roda, completa, e termina
• --session isolated = sessão descartável (sem histórico)

O LLM não sabe que crons existem — ele só recebe uma sessão nova com um prompt. Não sabe se veio de cron, WhatsApp ou CLI.

📼 Sessions OPENCLAW

Histórico de conversa persistido em disco. JSONL append-only. O OpenClaw carrega no prompt para dar continuidade. O LLM é stateless — sessions são a "memória de curto prazo".

Formato: ~/.openclaw/agents/<id>/sessions/<key>.jsonl

Session keys (encode security boundaries):
  agent:main:main                    → sessão principal
  agent:main:dm:whatsapp:+5561...    → DM WhatsApp
  agent:main:group:discord:123       → grupo Discord

Cada linha JSONL = um turno:
  user message | agent thought | tool call | tool result | response

dmScope (isolamento):
  main              → todos DMs na mesma sessão
  per-peer          → isolado por sender
  per-channel-peer  → isolado por canal + sender (recomendado)

Maintenance:

• Reset: daily (reset às 4h), idle (após N min), manual
• Pruning: remove tool results antigos in-memory (não altera disco)
• Rotation: rotateBytes: "10mb" — arquivo novo quando grande
• Retention: pruneAfter: "7d" — remove sessions velhas

🧠 Memory System OPENCLAW

O LLM é stateless. Toda memória persistente é gerenciada pelo OpenClaw. 4 camadas, da mais efêmera à mais permanente.

CAMADA 4 — Git History (permanente)
┌─────────────────────────────────────────┐
│ Versionamento do workspace (.git/)      │
│ Tudo que é escrito em arquivo tem       │
│ histórico. Nunca perde.                 │
│ Dono: OpenClaw                          │
└─────────────────────────────────────────┘

CAMADA 3 — MEMORY.md (longo prazo curada)
┌─────────────────────────────────────────┐
│ Arquivo Markdown no workspace           │
│ O agente escreve o que quer lembrar     │
│ Carregado apenas na sessão principal    │
│ NÃO carregado em grupo/DM sandboxed    │
│ Dono: OpenClaw (persiste e carrega)     │
│ Quem escreve: LLM (via tool write)     │
└─────────────────────────────────────────┘

CAMADA 2 — Notas Diárias (médio prazo)
┌─────────────────────────────────────────┐
│ memory/YYYY-MM-DD.md                    │
│ Auto-load: hoje + ontem no início       │
│ Acessíveis via memory_search            │
│ Dono: OpenClaw                          │
└─────────────────────────────────────────┘

CAMADA 1 — Session Transcript (curto prazo)
┌─────────────────────────────────────────┐
│ sessions/*.jsonl                        │
│ Carregado inteiro no prompt             │
│ Compactado quando contexto enche        │
│ Dono: OpenClaw                          │
└─────────────────────────────────────────┘

Vector Embeddings (busca semântica):

DB: ~/.openclaw/memory/<agentId>.sqlite

Geração: OpenClaw envia texto → LLM provider retorna vetor
         (cascata: local → OpenAI → Gemini → disabled)
Indexação: file watcher com 1.5s debounce (auto-reindex)

Busca Híbrida (2 algoritmos):
  BM25 (keyword)   → match textual exato
  Vector (semântico) → match por significado
  Post-processing:
    - MMR diversity re-ranking
    - Temporal decay (recentes pesam mais)

Ciclo de Vida:

1. CRIAÇÃO    → LLM chama write("MEMORY.md", ...)
2. PERSISTÊNCIA → OpenClaw grava no disco
3. INDEXAÇÃO   → File watcher → embeddings → SQLite
4. RETRIEVAL   → Auto-load (MEMORY.md + hoje/ontem)
                  ou memory_search (vector + BM25)
5. INJEÇÃO     → OpenClaw coloca no prompt do LLM
6. USO         → LLM "lê" como se soubesse

O LLM NÃO "lembra". Ele "lê" o que o OpenClaw colocou.
Se não foi escrito em arquivo, está perdido.

🗜️ Compaction OPENCLAW orquestra → LLM sumariza

Quando o contexto enche, OpenClaw sumariza a conversa antiga para liberar espaço. Permite conversas infinitas.

PASSO A PASSO:

1. DETECÇÃO (OpenClaw)
   Tokens se aproximam do limite do modelo
   Ex: 120k de 128k usados

2. MEMORY FLUSH (OpenClaw → LLM) — turno invisível
   OpenClaw: "Antes de compactar, salve notas
   importantes em MEMORY.md"
   LLM escreve o que acha relevante (NO_REPLY)
   Isso preserva info crítica antes de sumarizar

3. SUMARIZAÇÃO (OpenClaw → LLM)
   OpenClaw: "Sumarize esta conversa preservando
   informações críticas e identificadores"
   LLM gera resumo compacto

4. SUBSTITUIÇÃO (OpenClaw)
   Histórico antigo → substituído pelo sumário
   Marker de compaction gravado no JSONL
   Contexto volta a ter espaço (~70% liberado)

5. CONTINUAÇÃO
   Próxima mensagem: [sumário] + [msgs recentes]
   Continuidade semântica mantida
   O LLM NÃO sabe que foi compactado

identifierPolicy:
  "strict"  → preserva IDs opacos no sumário (default)
  "off"     → não preserva
  "custom"  → instruções customizadas