Imported from MindOpsTeam/agente-cfo (skills/agente-cfo/SKILL.md). Install upstream with npx skills add MindOpsTeam/agente-cfo --skill agente-cfo. Copyright stays with the author.

Agente CFO

CFO virtual para PME brasileira. Conecta o ERP Omie ao WhatsApp do dono da empresa, gerando insights financeiros diários sem intervenção manual.

Modelo: single-tenant — cada cliente roda sua própria instância (VPS + OpenClaw + skill). Sem multi-tenancy, sem license key. Auth VPS↔painel via X-Panel-Token.

Arquitetura

[Cron 07:00] ──▶ agente lê prompts/alerta_manha.md
[Cron 18:00] ──▶ agente lê prompts/alerta_tarde.md
                     │
                     ▼
            omie_client.py (dados ERP)
                     │
                     ▼
            LLM gera insight em PT-BR
                     │
                     ▼
            wacli send text (WhatsApp)
                     │
                     ▼
            curl → PANEL_BASE_URL/event (painel central)

Variáveis de Ambiente Requeridas

Variáveis Opcionais

Endpoint /hooks/agent

O OpenClaw Gateway expõe nativamente o endpoint /hooks/agent na porta 18789 (porta padrão do gateway).

• Método: POST
• Auth: Authorization: Bearer <HOOKS_TOKEN> (ou X-OpenClaw-Token: <HOOKS_TOKEN>)
• Body JSON:

{
  "message":        "Execute: bash ~/.openclaw/workspace/skills/agente-cfo/scripts/cfo-reporter.sh ...",
  "name":           "PainelCFO",
  "wakeMode":       "now",
  "deliver":        false,
  "timeoutSeconds": 60
}

• Configuração: o token vem de hooks.token no config do OpenClaw (setado automaticamente pelo setup.sh via variável de ambiente HOOKS_TOKEN).
• HTTPS externo: o Cloudflare Tunnel (INGRESS_URL) faz proxy para http://localhost:18789, portanto o painel acessa via ${INGRESS_URL}/hooks/agent.

O push-command da edge function Supabase usa exatamente esse endpoint para enviar comandos do painel para a VPS.

Ferramentas Expostas pela Skill

1. doctor.sh — Diagnóstico do sistema

bash skills/agente-cfo/scripts/doctor.sh

Testa: WhatsApp pareado, Omie acessível, PANEL_TOKEN presente, conectividade com painel, endpoint /hooks/agent. Exit 0 = tudo ok. Exit 1 = falha em algum componente.

2. repare.sh — Re-pareamento WhatsApp

bash skills/agente-cfo/scripts/repare.sh

Guia o usuário pelo re-pareamento do WhatsApp quando o QR expira.

3. cfo-reporter.sh — Relatório sob demanda

bash skills/agente-cfo/scripts/cfo-reporter.sh <prompt_file>
# Exemplos:
bash skills/agente-cfo/scripts/cfo-reporter.sh prompts/alerta_manha.md
bash skills/agente-cfo/scripts/cfo-reporter.sh prompts/alerta_tarde.md

Wrapper principal: coleta dados Omie → chama LLM com prompt → envia WhatsApp → reporta ao painel.

4. omie-pull-wrapper.sh — Coleta de dados Omie com retry

bash skills/agente-cfo/scripts/omie-pull-wrapper.sh <comando_omie> [args...]
# Exemplo:
bash skills/agente-cfo/scripts/omie-pull-wrapper.sh resumo_financeiro
bash skills/agente-cfo/scripts/omie-pull-wrapper.sh contas_receber 1 50

5. check-budget.sh — Controle de custo LLM

bash skills/agente-cfo/scripts/check-budget.sh

Parseia sessões do OpenClaw, estima custo mensal em BRL. Se ultrapassar LLM_BUDGET_BRL, desabilita os cron jobs de alerta e notifica via WhatsApp.

6. whatsapp-watch.sh — Monitor de conexão WhatsApp

bash skills/agente-cfo/scripts/whatsapp-watch.sh

Poll a cada 30 minutos via wacli doctor. Se QR expirado, alerta via mensagem no terminal e reporta ao painel. Rode como processo background ou cron separado.

7. heartbeat.sh — Heartbeat ao painel

bash skills/agente-cfo/scripts/heartbeat.sh

Chamado pelo cron */5 * * * *. Envia heartbeat ao painel incluindo INGRESS_URL atual (re-detectada do cloudflared se mudou).

Cron Jobs (registrados pelo setup.sh)

5 cron jobs são registrados. Os IDs são salvos em ~/.agente-cfo/cron-ids.env:

# ~/.agente-cfo/cron-ids.env (gerado pelo setup.sh)
CRON_ID_MANHA=<uuid>
CRON_ID_TARDE=<uuid>
CRON_ID_HEARTBEAT=<uuid>
CRON_ID_BUDGET=<uuid>
CRON_ID_WA_WATCH=<uuid>

O check-budget.sh lê esse arquivo para pausar/retomar os crons via openclaw cron disable/enable.

Notificações Proativas (Sprint 5)

Marcos detecta anomalias financeiras e comerciais autonomamente, sem esperar cron ou mensagem do dono.

Daemon: cfo_proactive_watcher.py

Roda como cfo-proactive.service (systemd). Loop a cada 30 minutos (configurável via CFO_PROACTIVE_INTERVAL_MINUTES).

Fluxo por ciclo:

1. Carrega ERP client (CFO_ERP_NAME) e CRM client (CFO_CRM_NAME) dinamicamente
2. Executa todas as regras em proactive_rules/
3. Aplica cooldown por dedup_key (estado em ~/.agente-cfo/state/proactive_alerts.json)
4. Dispara /hooks/agent com name=proactive_alert para cada nova anomalia
5. Marcos formata mensagem curta (≤600 chars) usando prompts/proactive.md e envia via WhatsApp
6. Emite _panel_event "proactive_alert" → aparece em /audit e /events do painel

Governance: daemon é 100% read-only. Nenhum write no ERP/CRM.

Regras de detecção

Thresholds configuráveis via env vars:

Ressalvas por skill ERP:

• Regras que dependem de get_balance() silenciosamente pulam se o ERP retorna not_supported
• rule_pipeline_drop e rule_deal_stale são puladas se CFO_CRM_NAME=nenhum
• ERPs sem list_overdue() nativo usam o fallback da BaseERPClient (filtra por due_date < hoje)

Logs e estado

~/.agente-cfo/
├── logs/
│   └── proactive.log              # logs do daemon proativo
└── state/
    └── proactive_alerts.json      # cooldown state: dedup_key + sent_at por regra

Prompts

Estrutura de Logs e Memória

~/.agente-cfo/
├── logs/
│   ├── cfo-reporter.log
│   ├── omie-pull-wrapper.log
│   ├── check-budget.log
│   ├── whatsapp-watch.log
│   ├── heartbeat.log
│   ├── doctor.log
│   ├── repare.log
│   └── proactive.log
├── memory/               # chmod 700 — memória local do agente (nunca vai ao painel)
│   ├── empresa.md        # fatos sobre a empresa (nome, segmento, sazonalidade)
│   ├── preferencias_dono.md
│   ├── eventos.md        # linha do tempo append-only
│   ├── decisoes.md       # decisões registradas
│   └── metricas_baseline.md
├── state/
│   └── proactive_alerts.json  # cooldown state do daemon proativo
├── cron-ids.env          # IDs dos cron jobs (escrito pelo setup.sh)
└── budget-state.json     # Acumulador de custo mensal

Identidade do Agente

Os arquivos em skills/agente-cfo/identity/ definem quem é o agente, como ele fala e como gerencia memória. São lidos no início de cada prompt:

Setup Inicial (feito pelo setup.sh do instalador)

O setup.sh registra os crons e salva os IDs. A skill não registra crons por conta própria — apenas documenta os comandos esperados:

# Alerta manhã
CRON_ID_MANHA=$(openclaw cron add \
  --name "CFO Alerta Manhã" \
  --cron "0 7 * * *" --tz "America/Sao_Paulo" \
  --session isolated \
  --message "Execute: bash ~/.openclaw/workspace/skills/agente-cfo/scripts/cfo-reporter.sh ~/.openclaw/workspace/skills/agente-cfo/prompts/alerta_manha.md" \
  --no-deliver --json | jq -r '.id')

# Alerta tarde
CRON_ID_TARDE=$(openclaw cron add \
  --name "CFO Alerta Tarde" \
  --cron "0 18 * * *" --tz "America/Sao_Paulo" \
  --session isolated \
  --message "Execute: bash ~/.openclaw/workspace/skills/agente-cfo/scripts/cfo-reporter.sh ~/.openclaw/workspace/skills/agente-cfo/prompts/alerta_tarde.md" \
  --no-deliver --json | jq -r '.id')

# Salvar IDs
echo "CRON_ID_MANHA=${CRON_ID_MANHA}" > ~/.agente-cfo/cron-ids.env
echo "CRON_ID_TARDE=${CRON_ID_TARDE}" >> ~/.agente-cfo/cron-ids.env