Pular para conteúdo

Migração: Claude Code → Moltbot

ADR-003 | Data: 2026-02-06 | Status: Concluída | Autor: Werner (CTO)

Resumo Executivo

Em 06 de fevereiro de 2026, migramos do Claude Code (CLI oficial da Anthropic) para o Moltbot (gateway de orquestração). Esta decisão impactou toda a forma como o assistente IA opera na Arcos Scale.

1. Contexto

1.1 O que era o Claude Code

Claude Code é a CLI oficial da Anthropic para interagir com Claude. Características:

  • Interface de terminal (CLI)
  • Execução local, sessões efêmeras
  • Sem persistência nativa de memória
  • Sem integração com canais de mensagem (Telegram, WhatsApp)
  • Sem heartbeats ou crons
  • Workspace isolado por sessão

1.2 Limitações que enfrentávamos

Problema Impacto
Sem Telegram/WhatsApp nativos Precisava de bridges externas
Memória não persistia Perdia contexto entre sessões
Sem agendamentos Não podia executar tarefas periódicas
Sem heartbeats Não sabia se estava "vivo"
Configuração manual Cada sessão precisava setup

1.3 O que é Moltbot

Moltbot é um gateway de orquestração para agentes IA. Arquitetura:

┌─────────────────────────────────────────────────────────────┐
│                        MOLTBOT                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │  Telegram   │  │  WhatsApp   │  │   Discord   │  ...   │
│  │  (grammY)   │  │  (Baileys)  │  │             │        │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘        │
│         │                │                │                │
│         └────────────────┼────────────────┘                │
│                          ▼                                  │
│                   ┌─────────────┐                          │
│                   │   Gateway   │ ← WebSocket API          │
│                   │  (daemon)   │                          │
│                   └──────┬──────┘                          │
│                          │                                  │
│         ┌────────────────┼────────────────┐                │
│         ▼                ▼                ▼                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Agents    │  │    Cron     │  │   Skills    │        │
│  │  (Claude)   │  │  Scheduler  │  │  (modular)  │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
└─────────────────────────────────────────────────────────────┘

2. Decisão

Migrar do Claude Code para Moltbot como runtime principal do assistente IA da Arcos Scale.

2.1 Motivação Técnica

Critério Claude Code Moltbot Vencedor
Multi-channel ❌ Bridges ✅ Nativo Moltbot
Persistência ❌ Efêmero ✅ Workspace Moltbot
Heartbeats ❌ Não tem ✅ Configurável Moltbot
Cron/Agendamentos ❌ Externo ✅ Integrado Moltbot
Skills modulares ❌ Manual ✅ Sistema nativo Moltbot
Browser control ❌ Manual ✅ Integrado Moltbot
Nodes (mobile) ❌ Não tem ✅ iOS/Android Moltbot
Custo ✅ Gratuito ✅ Self-hosted Empate

2.2 Riscos Considerados

Risco Mitigação
Curva de aprendizado Documentação + suporte comunidade
Dependência do projeto Open source, self-hosted
Complexidade de config Arquivos de contexto padronizados

3. O Que Mudou

3.1 Infraestrutura

Antes (Claude Code): 

# Execução manual
claude
# ou
claude -p "tarefa"

Depois (Moltbot): 

# Daemon sempre rodando
moltbot gateway start

# Configuração persistente
/root/.clawdbot/moltbot.json

3.2 Configuração Atual

{
  "agents": {
    "defaults": {
      "workspace": "/root/clawd",
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "allowlist",
      "allowFrom": [745098765]
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local"
  }
}

3.3 Estrutura de Workspace

Antes: Nenhuma estrutura padrão

Depois: Workspace organizado 

/root/clawd/
├── MEMORY.md           # Memória de longo prazo
├── AGENTS.md           # Regras operacionais
├── SOUL.md             # Persona do bot
├── USER.md             # Preferências do usuário
├── HEARTBEAT.md        # Checklist periódico
├── TOOLS.md            # Notas de ferramentas locais
├── IDENTITY.md         # Identidade do agente
├── BOOTSTRAP.md        # Setup inicial (pode deletar)
│
├── memory/             # Diários por data
│   ├── 2026-02-06.md
│   └── 2026-02-07.md
│
├── config/             # Credenciais
│   ├── google-oauth-relri.json
│   ├── google-tokens-relri.json
│   └── supabase-apex.json
│
├── scripts/            # Automações
│   ├── apex.sh
│   ├── apex_client.py
│   └── google_refresh_token.py
│
├── workflows/          # Processos documentados
│   ├── formalizacao-compras.md
│   ├── abertura-vaga.md
│   └── apex-activation.md
│
├── apex/               # Sistema APEX (39 agentes)
│   ├── core/
│   ├── shared/
│   ├── arcosscale/
│   └── sellsync/
│
├── docs/               # Documentação
│   └── MIGRATION-CLAUDECODE-TO-MOLTBOT.md (este arquivo)
│
└── logs/               # Logs operacionais

3.4 Comunicação

Antes: Terminal local apenas

Depois: Multi-channel - ✅ Telegram (ativo, bot @ArcosDiretoriaBot) - 🔜 WhatsApp (disponível, não configurado) - 🔜 Discord (disponível, não configurado)

3.5 Sistema de Memória

Antes: Sem memória persistente

Depois: Sistema hierárquico 

MEMORY.md (longo prazo)
    │
    ├── Decisões importantes
    ├── Preferências descobertas
    ├── TODOs pendentes
    └── Contexto de projetos

memory/YYYY-MM-DD.md (diário)
    │
    ├── O que aconteceu hoje
    ├── Tarefas concluídas
    └── Aprendizados

3.6 Heartbeats

Antes: Não existia

Depois: Checagem periódica - Gateway envia heartbeat configurável - Agente verifica HEARTBEAT.md - Se nada precisa atenção: HEARTBEAT_OK - Se há pendências: alerta proativo

3.7 Skills

Antes: Tudo hardcoded

Depois: Sistema modular 

/opt/moltbot/skills/
├── weather/           # Previsão do tempo
├── video-frames/      # Extração de frames
├── tmux/              # Controle de terminal
├── skill-creator/     # Criar novos skills
└── bluebubbles/       # iMessage bridge

4. Adaptações Realizadas

4.1 Arquivos de Contexto

Criamos arquivos que o Moltbot injeta automaticamente:

Arquivo Função
SOUL.md Define persona (ArcosDiretoriaBot)
USER.md Preferências do Relri
AGENTS.md Regras operacionais (memória, verificação)
MEMORY.md Contexto de longo prazo
HEARTBEAT.md Checklist de manutenção

4.2 Integração APEX

Conectamos o sistema APEX (39 agentes especializados) via: - Scripts: /root/clawd/scripts/apex.sh - CLI: /apex/shared/mcp-server/apex-cli-full.mjs - Supabase: métricas SSoT

4.3 Automações

Script Função Schedule
google_refresh_token.py Renova OAuth tokens Cron 45min

4.4 Workflows Documentados

  • Formalização de compras (financeiro)
  • Abertura de vagas (RH)
  • Ativação de agentes APEX

5. Comandos Operacionais

5.1 Gateway

# Status
moltbot status

# Iniciar daemon
moltbot gateway start

# Parar
moltbot gateway stop

# Reiniciar
moltbot gateway restart

# Logs
moltbot gateway logs

5.2 Configuração

# Ver config atual
moltbot config get

# Editar
nano /root/.clawdbot/moltbot.json

# Aplicar mudanças
moltbot gateway restart

5.3 Telegram

  • Bot: @ArcosDiretoriaBot
  • Usuário autorizado: 745098765 (Relri)
  • Grupos: -5102603330

6. Trade-offs

6.1 Ganhos

✅ Comunicação via Telegram 24/7 ✅ Memória persistente entre sessões ✅ Heartbeats para manutenção ✅ Skills modulares ✅ Agendamentos nativos (cron) ✅ Browser automation integrado ✅ Multi-channel pronto

6.2 Custos

⚠️ Mais complexidade de configuração ⚠️ Curva de aprendizado nova stack ⚠️ Dependência de daemon rodando ⚠️ Arquivos de contexto precisam manutenção

7. Lições Aprendidas

  1. Memória é crítica — Sem persistência, o agente "acorda zerado" toda vez
  2. Estrutura economiza tempo — Arquivos de contexto evitam repetir instruções
  3. Multi-channel é game changer — Telegram permite acesso de qualquer lugar
  4. Heartbeats previnem deriva — Checagem periódica mantém consistência

8. Referências

  • Documentação Moltbot: /opt/moltbot/docs/ ou https://docs.molt.bot
  • Código fonte: https://github.com/moltbot/moltbot
  • Comunidade: https://discord.com/invite/clawd
  • Configuração atual: /root/.clawdbot/moltbot.json
  • Workspace: /root/clawd/

9. Histórico

Data Evento
2026-02-06 Migração inicial
2026-02-06 Primeiro dia operacional
2026-02-07 Integração APEX completa
2026-02-07 CLI APEX desbloqueado (32 comandos)
2026-02-08 Documentação desta migração

Documento criado por Werner (CTO/APEX) em 2026-02-08 Última atualização: 2026-02-08