Agent Manager

O que e o Agent Manager?

O Agent Manager e um servico Node.js construido com Fastify que roda em cada VPS do QuickClaw. Ele e o responsavel por todo o ciclo de vida dos containers de bot: criar, configurar, iniciar, monitorar, parar e remover.

As Edge Functions do Supabase se comunicam com o Agent Manager via HTTP para executar operacoes nos containers. O Agent Manager garante que o estado real dos containers esteja sempre sincronizado com o banco de dados.

Lifecycle

O Agent Manager gerencia 4 fases do ciclo de vida de um container:

Provisionar

Quando um agente e ativado pela primeira vez, o Agent Manager cria toda a infraestrutura necessaria para o container:

• Cria o diretorio de dados em /opt/quickclaw/containers/bot-X/data
• Configura o namespace de rede isolado para o slot
• Prepara os bind mounts para dados persistentes
• Aplica perfis de Seccomp e AppArmor
• Configura bandwidth shaping via tc (50 Mbps)
• Injeta variaveis de ambiente (tokens, config do agente)
• Skills sao clonadas individualmente via git_repo configurado no banco (org QuickClaw-Skills ou repos de terceiros)

Iniciar

Apos o provisionamento (ou quando um agente parado e reativado), o Agent Manager usa o PM2 para iniciar o processo OpenClaw dentro do container:

• PM2 inicia o OpenClaw com as variaveis de ambiente do container
• Configura restart automatico em caso de crash
• Aguarda o health check inicial confirmar que o agente esta responsivo
• Atualiza o status no banco para running

Parar

Quando um agente e desativado (pelo usuario ou por processo automatizado):

• Envia SIGTERM para graceful shutdown do OpenClaw
• Aguarda ate 10 segundos para encerramento limpo
• Se nao encerrar, envia SIGKILL
• Libera o slot no banco (status: stopped)
• Dados persistentes permanecem em disco para reativacao futura

Desprovisionar

Quando um agente e permanentemente removido (ex: assinatura cancelada, reembolso):

• Para o container (se estiver rodando)
• Cria backup dos dados do agente (retido por 15 dias)
• Realiza wipe seguro do diretorio do container
• Libera completamente o slot
• Um cron diario limpa backups expirados automaticamente

Health Checks

O Agent Manager monitora continuamente a saude de cada container ativo:

• HTTP health check: Verifica periodicamente se o gateway do OpenClaw esta respondendo requisicoes HTTP. O endpoint de health retorna o estado interno do agente.
• Threshold de falha: Se o health check falhar 3 vezes consecutivas, o Agent Manager reinicia o container automaticamente.
• Erro persistente: Se o container nao se recuperar apos o restart, o status e marcado como error e um alerta e enviado ao usuario via email e no dashboard.
• Deep health check: Alem do HTTP basico, verifica se o processo PM2 esta respondendo e se o container nao esta em estado zombie.

Reconciliacao

A cada 5 minutos, o Agent Manager executa um processo de reconciliacao que compara o estado registrado no banco de dados (Supabase) com o estado real dos containers na VPS. Isso garante consistencia mesmo apos falhas ou reinicializacoes.

Cenarios detectados e corrigidos automaticamente:

Skills Management

O Agent Manager tambem e responsavel por instalar e desinstalar skills nos bots:

• Instalacao: Copia o arquivo SKILL.md correspondente do catalogo para o diretorio de skills do container (/home/node/.openclaw/skills/). Skills ficam ativas imediatamente gracas ao skill watcher do OpenClaw.
• Desinstalacao: Remove o arquivo SKILL.md do diretorio de skills. O skill watcher detecta a remocao e desativa a skill automaticamente.
• Skill watcher: O Agent Manager garante que o campo skill_watcher esteja habilitado no openclaw.json do container, permitindo hot-reload de skills sem reiniciar o agente.
• Skills: Skills sao clonadas individualmente via git_repo (org QuickClaw-Skills para skills proprias, ou repos de terceiros como claude-mem). Gerenciadas pelo AM com auto-update.