Usage tracking

기준일: 2026-07-26
공식 기준: Usage tracking

Usage tracking 문서는 OpenClaw 공식 문서(concepts/usage-tracking)를 한국어로 정리한 가이드입니다. Usage tracking surfaces and credential requirements 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Usage tracking surfaces and credential requirements

한국어 가이드 범위: concepts/usage-tracking 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• What it is
• Where it shows up
• Anthropic and OpenAI cost history
• Default usage footer mode
• Three distinct session states
• Precedence
• Resetting vs. turning off
• Toggle behavior
• 구성
• Custom /usage full footer
• Shape
• Contract Paths
• Verbs
• Piece forms
• 예제
• Providers + credentials
• 관련 문서

상세 내용

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

openclaw channels list no longer prints provider usage; it points users to openclaw status or openclaw models list instead.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• /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.
• Control UI: the chat composer's context ring popover shows plan usage for subscription providers — per-window bars (5-hour, weekly, model-scoped) with reset times, the provider plan when known (for example Max (20x)), and extra-usage credits. Sessions billed through a plan hide per-token dollar estimates; API-billed sessions keep Est. cost and the cost-by-type breakdown. Claude Code CLI (claude-cli) setups reuse the same Anthropic subscription usage.
• macOS menu bar: a root "Usage" section appears below Context when provider usage snapshots are available. See Menu bar.

Anthropic and OpenAI cost history

Subscription quota and API billing are different provider surfaces:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 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

/usage off|tokens|full sets the footer for a session and is remembered for that session. messages.responseUsage seeds that mode for sessions that have not chosen one, so the footer can be on by default without typing /usage each time.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

Three distinct session states

A session's responseUsage field has three representable states, each with different semantics:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

State	Stored value	Effective mode
Unset / inherit	undefined (absent)	Falls through to messages.responseUsage config default, then off.
Explicit off	"off" (stored)	Always off, a non-off config default cannot re-enable the footer.
Explicit on	"tokens" or "full" (stored)	That mode, regardless of config default.

Precedence

Effective mode = session override → channel config entry → default → off.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Resetting vs. turning off

override. The session then inherits the effective config default (messages.responseUsage). If no default is configured, the footer stays off.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• /usage off forces the footer off and persists that choice. A configured
• /usage reset (aliases: default, inherit, inherited, clear, unpin) clears the session
• A full session reset (/reset or /new) or a session rollover preserves

Toggle behavior

/usage with no arguments cycles: off → tokens → full → off. The starting point for the cycle is the effective current mode (session override falling through to the config default when unset), so the cycle always matches what the user currently sees in the footer.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

구성

With no config the prior behavior holds (footer off until /usage). Use /usage reset to clear a session override and re-inherit the configured default.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Custom /usage full footer

/usage tokens always renders a plain Usage: X in / Y out line (plus cache and estimated-cost suffixes when available). Only /usage full renders the richer footer described below.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

{
  "schema": "openclaw.usageBar.v1",
  "scales": {
    "braille": "⠐⡀⡄⡆⡇⣇⣧⣷⣿",
    "block": "░▏▎▍▌▋▊▉█",
    "shade": "░▒▓█",
    "moon": "🌑🌘🌗🌖🌕",
    "level": "▁▂▃▄▅▆▇█",
    "weather": ["🥶", "☁️", "🌥", "⛅️", "🌤", "☀️"],
    "plants": ["🪾", "🍂", "🌱", "☘️", "🍀", "🌿"],
    "moons6": ["🌑", "🌚", "🌘", "🌗", "🌖", "🌝"],
  },
  "aliases": {
    "models": {
      "claude-opus-4": "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

Each surface is an ordered list of pieces; the engine renders each, drops empties, and joins survivors with sep. A surface with no entry uses output.default.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  "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

A piece reads values from the per-turn contract by dot-path. Absent values are empty (so a when guard or a |fallback keeps the piece clean).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Path	Meaning
surface	channel id (discord/telegram/etc.)
agentId / chat_type	owning agent id / chat surface kind
model.id / model.display_name / model.provider	model id / display name / provider id
model.actual, model.resolved_ref	provider/model ref actually used for the turn
model.requested	provider/model ref requested (before fallback)
model.reasoning	effort (off through xhigh)
model.is_fallback / model.is_override	bool: fallback used / model pinned
model.override_source / model.auth_mode	override source label / credential mode (oauth, api-key, token, mixed, aws-sdk, unknown)
state.fast_mode	bool: fast vs slow
state.compactions	compaction count for the session
context.max_tokens / context.used_tokens / context.pct_used	window budget / occupied tokens / 0-100 used
usage.input_tokens / usage.output_tokens / usage.total_tokens	turn aggregate
usage.cache_read_tokens / usage.cache_write_tokens	cache-read and cache-write tokens for the turn
usage.has_tokens / usage.has_split_tokens / usage.has_total_only_tokens	token display guards
usage.cache_hit_pct	cache-read share of total prompt tokens
usage.last.input_tokens / usage.last.output_tokens / usage.last.cache_hit_pct	final model call only (also has cache_read_tokens, cache_write_tokens, total_tokens)
cost.turn_usd / cost.available	estimated turn cost / whether a cost table resolved
timing.duration_ms	wall-clock turn duration
identity.name / identity.emoji / identity.avatar	agent identity name / emoji / avatar
session.id	session id

Verbs

Pipe a value through verbs left to right; a non-verb segment is the fallback.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Verb	Effect	Example
num	compact count	272000 -> 272k
fixed:N	N decimals (0..100, default 2)	0.0377
dur	seconds to duration	14820 -> 4h07m
pct	append %	96 -> 96%
inv	100 - x	for used to remaining
alias:TABLE	lookup in aliases, echo if unlisted	medium -> 🌗
meter:W:SCALE	W-cell glyph bar over a 0-100 value	[⣿⣿⠐⠐⠐] (meter:1 = one glyph)

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).

예제

renders e.g. claude-sonnet-4-6 🌗 🐌 | 📚 [⣿⣿⣿⣿⣧]272k.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

{
  "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

Usage is hidden when no usable provider usage auth can be resolved. OpenClaw automatically discovers enabled provider plugins that declare contracts.usageProviders and implement both resolveUsageAuth and fetchUsageSnapshot; there is no separate core provider allowlist. The static contract keeps discovery scoped without importing every provider plugin. Each plugin owns its upstream endpoint and response mapping. The shared snapshot keeps plan names, quota windows, balances, spend, and budgets provider-neutral for CLI, app, and Control UI consumers.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Anthropic (Claude): OAuth tokens in auth profiles. If the OAuth token lacks
• ClawRouter: API key (CLAWROUTER_API_KEY). Shows a monthly budget window
• DeepSeek: API key via env/config/auth store (DEEPSEEK_API_KEY).
• GitHub Copilot: OAuth tokens in auth profiles.
• Gemini CLI: OAuth tokens in auth profiles.
• MiniMax: API key or MiniMax OAuth auth profile. OpenClaw treats
• Window labels come from provider hours/minutes fields when present, then
• If the coding-plan endpoint returns model_remains, OpenClaw prefers the
• OpenAI (Codex/ChatGPT plan): OAuth tokens in auth profiles (ChatGPT-Account-Id
• OpenRouter: API key or OAuth-backed API key (OPENROUTER_API_KEY or an auth
• Venice: API key via env/config/auth store (VENICE_API_KEY). Shows USD and
• Xiaomi MiMo: two separate usage surfaces. Pay-as-you-go uses an API key
• z.ai: API key via env/config/auth store (ZAI_API_KEY or Z_AI_API_KEY).

관련 문서

주요 항목:

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

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/usage-tracking
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

{
  "messages": {
    "responseUsage": "tokens",
    // or: { "default": "off", "discord": "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": "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}" },
      ],
    },
  },
}

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

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

관련 링크

• 공식 원문: concepts/usage-tracking
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.