Rastreamento de uso

​

O que é

• Busca o uso/cota do provedor diretamente nos endpoints de uso deles.
• Sem custos estimados; apenas janelas de cota relatadas pelo provedor ou resumos de estado da conta.
• A saída de status de janela de cota legível por humanos é normalizada para X% left, mesmo quando uma API upstream relata cota consumida, cota restante ou apenas contagens brutas. Provedores sem janelas de cota redefiníveis podem mostrar texto de resumo do provedor em vez disso, como um saldo.
• /status em nível de sessão e session_status podem recorrer à entrada de uso mais recente da transcrição quando o snapshot da sessão ao vivo está escasso. Esse fallback preenche contadores ausentes de tokens/cache, pode recuperar o rótulo do modelo de runtime ativo e prefere o total maior orientado a prompt quando os metadados da sessão estão ausentes ou são menores. Valores ao vivo não zero existentes ainda prevalecem.

​

Onde aparece

• /status em chats: cartão de status com muitos emojis, tokens da sessão + custo estimado (somente chave de API). O uso do provedor aparece para o provedor do modelo atual quando disponível como uma janela normalizada X% left ou texto de resumo do provedor.
• /usage off|tokens|full em chats: rodapé de uso por resposta.
• /usage cost em chats: resumo de custo local agregado dos logs de sessão do OpenClaw.
• CLI: openclaw status --usage imprime uma decomposição completa por provedor.
• CLI: openclaw channels list imprime o mesmo snapshot de uso junto da configuração do provedor (use --no-usage para pular).
• Barra de menus do macOS: seção “Uso” em Contexto (somente se disponível).

​

Modo padrão do rodapé de uso

{
  "messages": {
    "responseUsage": "tokens",
    // or: { "default": "off", "discord": "full" }
  },
}

​

Três estados distintos da sessão

​

Precedência

​

Redefinir vs. desativar

• /usage off — força o rodapé a ficar desativado e persiste essa escolha. Um padrão configurado diferente de desativado não pode substituir isso.
• /usage reset (aliases: inherit, clear, default) — limpa a substituição da sessão. A sessão então herda o padrão efetivo de configuração (messages.responseUsage). Se nenhum padrão estiver configurado, o rodapé fica desativado (sem alteração em relação a antes). Use isso para “voltar ao padrão” sem ativar explicitamente o rodapé.
• Uma redefinição completa de sessão (/reset ou /new) ou uma rolagem de sessão preserva a preferência explícita de modo de uso, para que a escolha de exibição do usuário sobreviva a rolagens de sessão. Somente /usage reset (e seus aliases) realmente limpa a substituição.

​

Comportamento de alternância

​

Configuração

​

Rodapé personalizado de /usage full

{
  "messages": {
    "usageTemplate": "~/.openclaw/usage-footer.json"
  }
}

{
  "schema": "openclaw.usageBar.v1",
  "scales": {
    "braille": "⠐⡀⡄⡆⡇⣇⣧⣷⣿",
    "block": "░▏▎▍▌▋▊▉█",
    "shade": "░▒▓█",
    "moon": "🌑🌘🌗🌖🌕",
    "level": "▁▂▃▄▅▆▇█",
    "weather": ["🥶", "☁️", "🌥", "⛅️", "🌤", "☀️"],
    "plants": ["🪾", "🍂", "🌱", "☘️", "🍀", "🌿"],
    "moons6": ["🌑", "🌚", "🌘", "🌗", "🌖", "🌝"],
  },
  "aliases": {
    "models": {
      "claude-opus-4-6": "opus46",
      "claude-opus-4-8": "opus48",
      "claude-sonnet-4-6": "sonnet46",
      "claude-haiku-4-5": "haiku45",
      "gpt-5.5": "gpt5.5",
    },
    "reasoning": {
      "off": "🌑",
      "minimal": "🌚",
      "low": "🌘",
      "medium": "🌗",
      "high": "🌕",
      "xhigh": "🌝",
    },
  },
  "output": {
    "sep": "",
    "default": [
      { "text": "{model.provider}{identity.emoji|🤖}{model.display_name|alias:models}" },
      { "map": "model.is_fallback", "cases": { "true": "🔄" } },
      { "map": "model.is_override", "cases": { "true": "📌" } },
      { "when": "model.reasoning", "text": "{model.reasoning|alias:reasoning}" },
      { "map": "state.fast_mode", "cases": { "true": "⚡️", "false": "🐌" } },
      {
        "when": "context.max_tokens",
        "text": "\u00A0| 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}",
      },
      { "when": "cost.turn_usd", "text": "\u00A0💰{cost.turn_usd|fixed:4}" },
    ],
    "surfaces": {
      "discord": [
        { "text": "-# -\n" },
        { "text": "-# {model.provider}{identity.emoji|🤖}{model.display_name|alias:models}" },
        { "map": "model.is_fallback", "cases": { "true": "🔄" } },
        { "map": "model.is_override", "cases": { "true": "📌" } },
        { "when": "model.reasoning", "text": "{model.reasoning|alias:reasoning}" },
        { "map": "state.fast_mode", "cases": { "true": "⚡️", "false": "🐌" } },
        {
          "when": "context.max_tokens",
          "text": "\u00A0| 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}",
        },
        { "when": "cost.turn_usd", "text": "\u00A0💰{cost.turn_usd|fixed:4}" },
      ],
    },
  },
}

​

Formato

{
  "schema": "openclaw.usageBar.v1",
  "scales": { "<name>": "low-to-high glyphs" }, // string (1 glyph/char) or array
  "aliases": { "<table>": { "<value>": "<label>" } },
  "output": {
    "sep": "", // joins surviving pieces
    "default": [
      /* pieces */
    ], // fallback for any surface
    "surfaces": {
      "discord": [
        /* pieces */
      ],
      "telegram": [
        /* pieces */
      ],
    },
  },
}

​

Caminhos do contrato

​

Verbos

​

Formas de parte

• { "text": "📚 {context.max_tokens|num}" }: literal + interpolação.
• { "when": "<path>", "text": "..." }: renderiza somente se o caminho for verdadeiro.
• { "map": "<path>", "cases": { "true": "⚡", "false": "🐌" } }: valor para glifo.
• { "each": "limits.windows", "item": "{label}" }: itera um array.

​

Exemplo

{
  "schema": "openclaw.usageBar.v1",
  "scales": { "braille": "⠐⡀⡄⡆⡇⣇⣧⣷⣿" },
  "aliases": { "reasoning": { "medium": "🌗", "high": "🌕" } },
  "output": {
    "surfaces": {
      "discord": [
        { "text": "{model.display_name}" },
        { "when": "model.reasoning", "text": " {model.reasoning|alias:reasoning}" },
        { "map": "state.fast_mode", "cases": { "true": " ⚡", "false": " 🐌" } },
        {
          "when": "context.max_tokens",
          "text": " | 📚 [{context.pct_used|meter:5:braille}]{context.max_tokens|num}",
        },
      ],
    },
  },
}

​

Provedores + credenciais

• Anthropic (Claude): tokens OAuth em perfis de autenticação.
• GitHub Copilot: tokens OAuth em perfis de autenticação.
• Gemini CLI: tokens OAuth em perfis de autenticação.
  • O uso em JSON recorre a stats; stats.cached é normalizado para cacheRead.
• OpenAI Codex: tokens OAuth em perfis de autenticação (accountId usado quando presente).
• MiniMax: chave de API ou perfil de autenticação OAuth da MiniMax. O OpenClaw trata minimax, minimax-cn e minimax-portal como a mesma superfície de cota da MiniMax, prefere OAuth da MiniMax armazenado quando presente e, caso contrário, recorre a MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY ou MINIMAX_API_KEY. A consulta de uso deriva o host do Coding Plan de models.providers.minimax-portal.baseUrl ou models.providers.minimax.baseUrl quando configurado e, caso contrário, usa o host MiniMax CN. Os campos brutos usage_percent / usagePercent da MiniMax significam cota restante, portanto o OpenClaw os inverte antes da exibição; campos baseados em contagem prevalecem quando presentes.
  • Os rótulos da janela do plano de codificação vêm dos campos de horas/minutos do provedor quando presentes e, em seguida, recorrem ao intervalo start_time / end_time.
  • Se o endpoint do plano de codificação retornar model_remains, o OpenClaw prefere a entrada do modelo de chat, deriva o rótulo da janela dos carimbos de data/hora quando os campos explícitos window_hours / window_minutes estão ausentes e inclui o nome do modelo no rótulo do plano.
• Xiaomi MiMo: chave de API via env/config/repositório de autenticação (XIAOMI_API_KEY).
• z.ai: chave de API via env/config/repositório de autenticação.
• DeepSeek: chave de API via env/config/repositório de autenticação (DEEPSEEK_API_KEY). O OpenClaw chama o endpoint de saldo da DeepSeek e mostra o saldo informado pelo provedor como texto em vez de uma janela de cota com percentual restante.

​

Relacionados

• Uso de tokens e custos
• Uso e custos de API
• Cache de prompts