max-banking

MaxBank Skill para OpenClaw

Skill que conecta seu OpenClaw ao MaxBank para consultar saldo, fazer PIX e pagar boletos.

Toda a comunicação é via MCP (Model Context Protocol). O MCP roda hospedado — a autenticação (Agent API Key) é injetada diretamente via header no mcporter, sem necessidade de proxy local.

Ambientes

Health check do MCP em produção: https://maxbank-mcp.max.com.br/health.

Funcionalidades

Instalação

Via git clone (recomendado enquanto não está no ClawHub)

# Clone direto no diretório de skills do OpenClaw
git clone https://github.com/appmaxbrasil/openclaw-max-banking-skill.git \
  ~/.openclaw/skills/max-banking

# Ou, se usar workspace:
git clone https://github.com/appmaxbrasil/openclaw-max-banking-skill.git \
  ~/.openclaw/workspace/skills/max-banking

Reinicie o gateway do OpenClaw após instalar.

Via ClawHub (em breve)

clawhub install max-banking

Setup (conectar conta)

O setup pode ser feito via chat ou manualmente:

Via chat (recomendado)

Diga ao assistente: "Quero conectar minha conta max, código AX7K-92QF"

O assistente executa o setup completo: mcporter, pareamento e configuração do header de autenticação.

Manual

# Prod (padrão)
bash ~/.openclaw/skills/max-banking/scripts/maxbank.sh setup ABCD-EF12 prod

# Homolog
bash ~/.openclaw/skills/max-banking/scripts/maxbank.sh setup ABCD-EF12 homolog

# Local (requer URL do ngrok)
bash ~/.openclaw/skills/max-banking/scripts/maxbank.sh setup ABCD-EF12 local https://xxx.ngrok-free.app/mcp

O setup faz:

1. Instala/verifica mcporter
2. Configura openclaw.json
3. Pareia via MCP (tool pairing_exchange)
4. Configura mcporter com Authorization: Bearer <agent_key> no header

Pagamentos

PIX

Aceita formato posicional ou nomeado:

# Posicional: chave + valor
maxbank.sh pix email@exemplo.com 50.00
maxbank.sh pix 11999998888 100

# Nomeado
maxbank.sh pix code=email@exemplo.com amount:50.00

# QR Code (copia-e-cola)
maxbank.sh pix 00020126...

Chaves aceitas: e-mail, telefone (10-11 dígitos), CPF/CNPJ, EVP (aleatória) ou payload QR (começa com 00020).

Boleto

Aceita apenas a linha digitável (o valor é extraído automaticamente dela):

# Posicional
maxbank.sh billet 23793.38128 60000.000003 00000.000008 1 10250000012345

# Nomeado
maxbank.sh billet code="23793.38128 60000.000003 00000.000008 1 10250000012345"

Importante: Não envie amount ou outros parâmetros para boleto — apenas code com a linha digitável completa.

Arquitetura

Usuário → OpenClaw (LLM) → exec maxbank.sh → mcporter → MCP hospedado → Banking API
                                                ↑
                                     Authorization: Bearer <agent_key>
                                     (injetado via header no mcporter config)

Arquivos

skills/max-banking/
├── SKILL.md                    # Instruções para a LLM
├── README.md                   # Este arquivo
└── scripts/
    ├── maxbank.sh              # Wrapper unificado (entry point)
    ├── setup.sh                # Setup: pareamento + config mcporter
    └── connect-mcp.js          # Pareamento via MCP JSON-RPC

Armazenamento

Tokens e sessão ficam em ~/.openclaw/secrets/maxbank/ com permissões restritas:

Configuração mcporter

Após o setup, o mcporter fica configurado assim (equivalente a mcporter config list):

{
  "banking": {
    "type": "http",
    "url": "https://maxbank-mcp.max.com.br/mcp",
    "headers": {
      "Authorization": "Bearer max_live_..."
    }
  }
}

Configuração do OpenClaw

O setup.sh configura automaticamente. Para referência manual:

{
  "skills": {
    "entries": {
      "mcporter": { "enabled": true },
      "max-banking": { "enabled": true }
    }
  },
  "tools": {
    "allow": ["exec", "process", "read", "write", "edit", "apply_patch"],
    "exec": { "host": "gateway" }
  }
}

Troubleshooting

"pairing not done" — Execute o setup com um código de pareamento válido.

"agent_key invalid" — Chave revogada ou inválida. Refaça o pareamento com um novo código.

"servidor 'banking' não encontrado no mcporter" — O mcporter perdeu a configuração. Execute maxbank.sh setup novamente ou reconfigure manualmente:

mcporter config add banking --http-url https://maxbank-mcp.max.com.br/mcp --header '{"Authorization": "Bearer <sua_agent_key>"}'

Agente não reconhece comandos — Verifique:

1. Skill está em ~/.openclaw/skills/max-banking/SKILL.md
2. openclaw.json tem max-banking habilitada
3. Permissão exec está em tools.allow
4. Inicie uma nova sessão (/new) após alterar configurações

BILLET_TOO_MANY_ARGS — O boleto aceita apenas a linha digitável em code=. Não envie amount=, description= ou outros parâmetros extras.