Plugin OpenClaw Context Meter Mostra Porcentagem de Uso de Token do Telegram

O Que Ele Faz

O plugin openclaw-context-meter mostra automaticamente a porcentagem de uso de tokens após cada resposta do bot do Telegram. Após cada resposta, ele envia um pequeno rodapé como: 📊 45k / 200k (22%). Quando ocorre compactação (os tokens caem significativamente), ele mostra: 📊 30k / 200k (15%) — compactado de 150k.

O Problema Que Ele Resolve

Anteriormente, não havia uma maneira fácil de ver o quão cheia estava a janela de contexto sem digitar constantemente /status. O plugin fornece visibilidade automática do consumo de tokens.

Jornada de Desenvolvimento

v1 — O Desastre de OOM: Inicialmente usou execSync("openclaw models list --json") para descobrir dinamicamente as janelas de contexto do modelo. Isso gerou um processo completo do OpenClaw (~2GB de RAM) toda vez que o plugin era carregado. Com o plugin carregando 4-5 vezes na inicialização (uma vez por agente/runtime), isso causou: 2GB do gateway + 5 × 2GB de subprocessos = 12GB → OOM instantâneo. O matador de OOM eliminou sshd e NetworkManager, tornando os servidores completamente inacessíveis, criando um loop infinito de reinicialização.

v2 — A Correção Leve: Janelas de contexto codificadas para mais de 40 modelos. Zero subprocessos, zero sobrecarga de memória. Realização chave: nunca use execSync em plugins do OpenClaw, pois mesmo uma consulta CLI simples gera todo o runtime com todos os plugins e compilação TypeScript.

Por Que Nenhum Fork É Necessário

O plugin originalmente fez um fork do OpenClaw para corrigir ganchos before_compaction/after_compaction, mas mudanças upstream tornaram isso desnecessário:

• v2026.3.13+ — upstream agora passa sessionId + agentId + sessionKey no contexto do gancho de compactação
• v2026.3.22+ — notificações internas 🧹 Compactando contexto... (issue #38805) tornaram seu código de compactação desnecessário
• v2026.3.22+ — comando interno /usage tokens|full|cost para exibição básica de tokens

O plugin agora se concentra no que ainda falta: exibição da porcentagem da janela de contexto.

Recursos

• Zero custo — usa apenas ganchos agent_end + message_sent, sem chamadas de API extras
• Sem subprocessos — as janelas de contexto do modelo são codificadas (sem risco de OOM do execSync)
• Filtragem inteligente — ignora turnos tool_use, envia rodapé apenas após a resposta de texto final
• Debounced — aguarda 1,5s após a última mensagem para evitar rodapé no meio do stream
• Multiagente — funciona com múltiplos agentes e contas do Telegram
• Detecção de compactação — detecta quedas de tokens e mostra estatísticas antes/depois

Limitações Conhecidas

• Alguns provedores (como Qwen) retornam totalTokens: 0 — o rodapé não será mostrado para esses modelos
• Janelas de contexto codificadas podem estar erradas para modelos mais recentes — extraídas da fonte v2026.3.22
• Apenas Telegram por enquanto (envia rodapé via Bot API)

Instalação

cd ~/.openclaw/extensions
npm pack openclaw-context-meter
tar xzf openclaw-context-meter-*.tgz
mv package context-meter
rm openclaw-context-meter-*.tgz

Adicione ao openclaw.json:

{
  "plugins": {
    "allow": ["context-meter"],
    "entries": {
      "context-meter": {
        "enabled": true
      }
    }
  }
}

Requer OpenClaw >= 2026.3.22.