Usage tracking

​

What it is

• Pulls provider usage/quota directly from each provider’s usage endpoint. No estimated provider billing; only provider-reported plan names, quota windows, balances, spend, budgets, daily cost history, token/model attribution, or account-state summaries.
• Human-readable quota-window output is normalized to X% left, even when a provider reports consumed quota, remaining quota, or only raw counts. Providers without resettable quota windows show provider summary text instead (for example a balance).
• Session-level /status and the session_status tool fall back to the session’s transcript log when the live session snapshot is missing token/model data. That fallback fills missing token/cache counters, can recover the active runtime model label, and prefers the larger prompt-oriented total when session metadata is missing or smaller (totalTokensFresh !== true, zero, or below the transcript-derived value). Nonzero live values always win over the fallback.

​

Where it shows up

• /status in chats: status card with session tokens and estimated cost (API key models only). Provider usage shows for the current model provider when available, as a normalized X% left window or provider summary text.
• /usage off|tokens|full in chats: per-response usage footer.
• /usage cost in chats: local cost summary aggregated from OpenClaw session logs.
• CLI: openclaw status --usage prints a full per-provider usage/quota breakdown.
• CLI: openclaw models status lists OAuth/token auth profiles and shows a usage-window summary next to each provider that has one.
• Control UI: Usage shows provider plan and billing cards above OpenClaw’s session-derived token and estimated-cost analysis. Anthropic and OpenAI Admin API credentials add provider-reported today, 7-day, and 30-day spend, daily trends, token totals, top models, and cost categories.
• macOS menu bar: a root “Usage” section appears below Context when provider usage snapshots are available. See Menu bar.

​

Anthropic and OpenAI cost history

• Anthropic subscription/setup credentials continue to show Claude quota windows and optional extra-usage budgets. Set ANTHROPIC_ADMIN_KEY or ANTHROPIC_ADMIN_API_KEY to show organization Usage and Cost API history instead. An Anthropic provider credential beginning with sk-ant-admin is detected automatically.
• OpenAI ChatGPT/Codex OAuth continues to show plan, quota windows, and credit balance. Set OPENAI_ADMIN_KEY to show organization cost and completions-usage history instead; optionally set OPENAI_PROJECT_ID to scope it to one project. OpenClaw never sends inference credentials from OPENAI_API_KEY, provider config, or auth profiles to organization APIs because those keys may belong to custom endpoints.

​

Default usage footer mode

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

​

Three distinct session states

​

Precedence

​

Resetting vs. turning off

• /usage off forces the footer off and persists that choice. A configured non-off default cannot override this.
• /usage reset (aliases: default, inherit, inherited, clear, unpin) clears the session override. The session then inherits the effective config default (messages.responseUsage). If no default is configured, the footer stays off.
• A full session reset (/reset or /new) or a session rollover preserves the explicit usage-mode preference so the user’s display choice survives session rollovers. Only /usage reset (and its aliases) clears the override.

​

Toggle behavior

​

Config

​

Custom /usage full footer

{
  "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": " | 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}",
      },
      { "when": "cost.turn_usd", "text": " 💰{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": " | 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}",
        },
        { "when": "cost.turn_usd", "text": " 💰{cost.turn_usd|fixed:4}" },
      ],
    },
  },
}

​

Shape

{
  "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 */
      ],
    },
  },
}

​

Contract Paths

​

Verbs

​

Piece forms

• { "text": "📚 {context.max_tokens|num}" }: literal + interpolation.
• { "when": "<path>", "text": "..." }: render only if the path is truthy.
• { "map": "<path>", "cases": { "true": "⚡", "false": "🐌" } }: value to glyph (a _default case covers unmatched values).
• { "each": "<array-path>", "item": "{label}" }: iterate an array-valued path (no current contract path is an array).

​

Example

{
  "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}",
        },
      ],
    },
  },
}

​

Providers + credentials

• Anthropic (Claude): OAuth tokens in auth profiles. If the OAuth token lacks user:profile scope, falls back to a claude.ai web session (CLAUDE_AI_SESSION_KEY, CLAUDE_WEB_SESSION_KEY, or a sessionKey= cookie in CLAUDE_WEB_COOKIE) when set. Model-scoped limits and enabled extra-usage monthly spend/budgets are included when Anthropic reports them. An explicit Anthropic Admin API key, or an auto-detected sk-ant-admin... provider profile, instead shows 30-day organization cost and Messages API history.
• ClawRouter: API key (CLAWROUTER_API_KEY). Shows a monthly budget window and typed USD budget when configured; otherwise shows aggregate spend and a request/token/cost summary.
• DeepSeek: API key via env/config/auth store (DEEPSEEK_API_KEY). Shows each provider-reported currency balance.
• GitHub Copilot: OAuth tokens in auth profiles.
• Gemini CLI: OAuth tokens in auth profiles.
• MiniMax: API key or MiniMax OAuth auth profile. OpenClaw treats minimax, minimax-cn, and minimax-portal as the same MiniMax quota surface, prefers stored MiniMax OAuth when present, and otherwise falls back to MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY, or MINIMAX_API_KEY. Usage polling derives the Coding Plan host from models.providers.minimax-portal.baseUrl or models.providers.minimax.baseUrl when configured, and otherwise uses the MiniMax CN host. MiniMax’s raw usage_percent / usagePercent fields mean remaining quota, so OpenClaw inverts them before display; count-based fields win when present.
  • Window labels come from provider hours/minutes fields when present, then fall back to the start_time / end_time span.
  • If the coding-plan endpoint returns model_remains, OpenClaw prefers the chat-model entry, derives the window label from timestamps when explicit window_hours / window_minutes fields are absent, and includes the model name in the plan label.
• OpenAI (Codex/ChatGPT plan): OAuth tokens in auth profiles (ChatGPT-Account-Id header sent when an account id is present). Shows the ChatGPT plan, resettable Codex windows, and a credit balance when reported. Credits remain provider credits; OpenClaw does not label them as dollars. OPENAI_ADMIN_KEY adds 30-day organization cost and completions-usage history when the key has Usage Dashboard access. Inference credentials are never forwarded to organization APIs.
• OpenRouter: API key or OAuth-backed API key (OPENROUTER_API_KEY or an auth profile). Combines the account credits endpoint with the key quota endpoint, so account balance/spend, key budget, and daily/weekly/monthly usage appear when the credential can access them. Either endpoint can enrich the snapshot independently.
• Venice: API key via env/config/auth store (VENICE_API_KEY). Shows USD and DIEM balances plus DIEM epoch allocation usage when reported.
• Xiaomi MiMo: two separate usage surfaces. Pay-as-you-go uses an API key (XIAOMI_API_KEY); the Token Plan uses a separate key (XIAOMI_TOKEN_PLAN_API_KEY). Neither currently reports quota windows.
• z.ai: API key via env/config/auth store (ZAI_API_KEY or Z_AI_API_KEY).

​

Related

• Token use and costs
• API usage and costs
• Prompt caching
• Menu bar