API Proxy

O que e o API Proxy?

O API Proxy e um servico Node.js que roda em cada VPS na porta 3100. Ele e o intermediario entre o OpenClaw (dentro do container) e os provedores de IA (Anthropic, OpenAI, Google, OpenRouter).

Todas as chamadas de IA passam obrigatoriamente pelo proxy. Nenhum container tem acesso direto as APIs dos provedores. Isso permite autenticar, rotear, contabilizar e controlar o consumo de forma centralizada.

Autenticacao

Cada agente tem um proxy token unico gerado automaticamente no momento da ativacao. O formato do token e:

qc_bot_{32 caracteres hexadecimais}

O container envia esse token no header de autorizacao de cada requisicao:

Authorization: Bearer qc_bot_a1b2c3d4e5f6...

O proxy valida o token contra o banco de dados e identifica qual bot esta fazendo a requisicao. Se o token for invalido ou o agente nao tiver creditos, a requisicao e rejeitada com erro 401 ou 402.

Roteamento

O proxy roteia a requisicao para o provedor correto baseado no campo ai_provider do agente no banco de dados:

Metering

A contabilizacao precisa de tokens e uma das funcoes mais criticas do proxy. O processo funciona assim:

1. Forca stream=false: O OpenClaw envia stream=true por padrao. O proxy sobrescreve para false para receber a resposta completa de uma vez, permitindo extrair a contagem exata de tokens.
2. Extrai tokens da resposta: Apos receber a resposta do provedor, o proxy extrai os campos de uso (usage) que incluem ate 4 tipos de tokens.
3. Calcula custo: Usando a tabela model_pricing, multiplica a quantidade de cada tipo de token pelo preco correspondente por Mtok (milhao de tokens).
4. Debita creditos: Debita primeiro dos creditos de assinatura do agente. Se insuficientes, debita dos creditos de topup da conta do usuario.

Os 4 tipos de tokens contabilizados:

Cache-Aware Pricing

O QuickClaw implementa precificacao diferenciada por tipo de token. Cada modelo na tabela model_pricing tem 4 precos diferentes (em USD por Mtok):

• Input: Preco padrao por token de entrada
• Output: Preco por token de saida (geralmente mais caro)
• Cache Write: Preco por token escrito no cache pela primeira vez
• Cache Read: Preco por token lido do cache (ate 90% mais barato que input)

A tabela model_pricing e a fonte unica de verdade para precos. O API Proxy recarrega os precos automaticamente a cada 10 minutos, garantindo que alteracoes de preco sejam refletidas sem reiniciar o servico.

Resiliencia

O API Proxy foi projetado para ser resiliente a falhas:

• Grace period de 30 minutos: Se o banco de dados (Supabase) ficar temporariamente indisponivel, o proxy usa um cache local com os dados dos bots e precos. Os bots continuam funcionando por ate 30 minutos sem conexao ao banco.
• Retry em metering: Se o debito de creditos falhar (ex: timeout no banco), o proxy tenta novamente. Nenhum consumo e perdido.
• Reload periodico: Configuracoes (precos, lista de bots, limites) sao recarregadas a cada 10 minutos, sem necessidade de restart.
• Validacao na startup: O proxy valida o schema de configuracao ao iniciar. Se credenciais master estiverem ausentes ou invalidas, ele falha imediatamente com erro claro, em vez de aceitar requisicoes e retornar 401.