--- read_when: - Você está conectando superfícies de uso/cota do provedor - Você precisa explicar o comportamento de rastreamento de uso ou os requisitos de autenticação summary: Superfícies de rastreamento de uso e requisitos de credenciais title: Rastreamento de uso x-i18n: generated_at: "2026-07-01T18:09:29Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: fa9b2b0b19ca0b4beeea40bfd50b07a92155178d5ec0e1877013843e0caba4fb source_path: concepts/usage-tracking.md workflow: 16 --- ## 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 `/usage off|tokens|full` define o rodapé de uma sessão e é lembrado para essa sessão. `messages.responseUsage` inicializa esse modo para sessões que ainda não escolheram um, para que o rodapé possa ficar ativado por padrão sem digitar `/usage` a cada vez. Defina um modo para todos os canais, ou um mapa por canal com um fallback `default`: ```jsonc { "messages": { "responseUsage": "tokens", // or: { "default": "off", "discord": "full" } }, } ``` ### Três estados distintos da sessão O campo `responseUsage` de uma sessão tem três estados representáveis, cada um com semântica diferente: | Estado | Valor armazenado | Modo efetivo | | --------------------- | -------------------------------- | ------------------------------------------------------------------------- | | **Não definido / herdar** | `undefined` (ausente) | Recorre ao padrão de configuração `messages.responseUsage`, depois `off`. | | **Desativado explícito** | `"off"` (armazenado) | Sempre desativado — um padrão de configuração diferente de desativado não pode reativar o rodapé. | | **Ativado explícito** | `"tokens"` ou `"full"` (armazenado) | Esse modo, independentemente do padrão de configuração. | ### Precedência Modo efetivo = substituição da sessão → entrada de configuração do canal → `default` → `off`. Um `/usage off` explícito é **persistido** como o valor literal `"off"` na sessão, não o mesmo que "não definido". Isso significa que um padrão `messages.responseUsage` diferente de desativado não pode reativar o rodapé depois que o usuário o desativou explicitamente. ### 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 `/usage` sem argumentos alterna em ciclo: off → tokens → full → off. O ponto inicial do ciclo é o modo atual **efetivo** (substituição da sessão recorrendo ao padrão de configuração quando não definida), então o ciclo é sempre consistente com o que o usuário vê no rodapé. ### Configuração Sem configuração, o comportamento anterior permanece (rodapé desativado até `/usage`). Use `/usage reset` para limpar uma substituição de sessão e voltar a herdar o padrão configurado. ## Rodapé personalizado de `/usage full` `/usage full` mostra um rodapé compacto integrado com modelo, raciocínio, rápido/lento, janela de contexto e custo quando esses campos estão disponíveis. Campos de token e cache permanecem disponíveis para templates personalizados. Nenhum arquivo de template é necessário. `messages.usageTemplate` é apenas para layouts personalizados avançados. O valor é um caminho de arquivo JSON (compatível com `~`) ou um objeto inline, e substitui o rodapé integrado quando válido: ```json { "messages": { "usageTemplate": "~/.openclaw/usage-footer.json" } } ``` Templates ausentes ou vazios retornam silenciosamente ao rodapé integrado. Templates configurados ilegíveis ou inválidos também retornam ao rodapé integrado e emitem um aviso ao operador. Comece templates personalizados pelo formato integrado e depois edite as partes que você quer alterar: ```jsonc { "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 ```jsonc { "schema": "openclaw.usageBar.v1", "scales": { "": "low-to-high glyphs" }, // string (1 glyph/char) or array "aliases": { "": { "": "