openclaw/docs/concepts/usage-tracking.md at c317fd2bd79fd11ac2c2ce6f1529bd7e27d7aeef

mirror of https://github.com/openclaw/openclaw.git synced 2026-06-03 15:24:03 +00:00

Files

litang9 d446c26acb feat(deepseek): show provider balance in usage status

Show DeepSeek API-key account balance in status/auth-status usage surfaces by adding a summary-only provider usage snapshot path, a DeepSeek balance fetcher, SDK/docs coverage, and focused regression tests.

Maintainer verification accepted the additive provider-usage/status contract and the DeepSeek balance visibility boundary for authenticated status surfaces.

Proof:
- Live DeepSeek balance proof via 1Password-backed DEEPSEEK_API_KEY against https://api.deepseek.com/user/balance; key and balance amount redacted.
- GitHub CI run 26717953383 passed on the current head.
- Real behavior proof run 26718215605 passed after the PR body was refreshed.
- Local clean PR clone: git diff --check; node --max-old-space-size=8192 --import tsx scripts/generate-plugin-sdk-api-baseline.ts --check; node scripts/run-vitest.mjs run src/agents/bash-tools.exec.path.test.ts.

Co-authored-by: Alex Tang <tangli1987118@hotmail.com>
Co-authored-by: litang9 <141409885+litang9@users.noreply.github.com>

2026-05-31 17:35:41 +01:00

3.8 KiB

Raw Blame History

summary, read_when, title

summary

read_when

title

Usage tracking surfaces and credential requirements

You are wiring provider usage/quota surfaces

You need to explain usage tracking behavior or auth requirements

Usage tracking

What it is

Pulls provider usage/quota directly from their usage endpoints.
No estimated costs; only provider-reported quota windows or account-state summaries.
Human-readable quota-window status output is normalized to X% left, even when an upstream API reports consumed quota, remaining quota, or only raw counts. Providers without resettable quota windows can show provider summary text instead, such as a balance.
Session-level /status and session_status can fall back to the latest transcript usage entry when the live session snapshot is sparse. 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. Existing nonzero live values still win.

Where it shows up

/status in chats: emoji-rich status card with session tokens + estimated cost (API key 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 (OAuth shows tokens only).
/usage cost in chats: local cost summary aggregated from OpenClaw session logs.
CLI: openclaw status --usage prints a full per-provider breakdown.
CLI: openclaw channels list prints the same usage snapshot alongside provider config (use --no-usage to skip).
macOS menu bar: "Usage" section under Context (only if available).

Providers + credentials

Anthropic (Claude): OAuth tokens in auth profiles.
GitHub Copilot: OAuth tokens in auth profiles.
Gemini CLI: OAuth tokens in auth profiles.
- JSON usage falls back to stats; stats.cached is normalized into cacheRead.
OpenAI Codex: OAuth tokens in auth profiles (accountId used when present).
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.
- Coding-plan 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.
Xiaomi MiMo: API key via env/config/auth store (XIAOMI_API_KEY).
z.ai: API key via env/config/auth store.
DeepSeek: API key via env/config/auth store (DEEPSEEK_API_KEY). OpenClaw calls DeepSeek's balance endpoint and shows the provider-reported balance as text instead of a percent-left quota window.

Usage is hidden when no usable provider usage auth can be resolved. Providers can supply plugin-specific usage auth logic; otherwise OpenClaw falls back to matching OAuth/API-key credentials from auth profiles, environment variables, or config.

3.8 KiB Raw Blame History

What it is

Where it shows up

Providers + credentials

Related

3.8 KiB

Raw Blame History