mirror of
https://github.com/openclaw/openclaw.git
synced 2026-06-05 04:52:55 +00:00
d446c26acb
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>
73 lines
3.8 KiB
Markdown
73 lines
3.8 KiB
Markdown
---
|
|
summary: "Usage tracking surfaces and credential requirements"
|
|
read_when:
|
|
- You are wiring provider usage/quota surfaces
|
|
- You need to explain usage tracking behavior or auth requirements
|
|
title: "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.
|
|
|
|
## Related
|
|
|
|
- [Token use and costs](/reference/token-use)
|
|
- [API usage and costs](/reference/api-usage-costs)
|
|
- [Prompt caching](/reference/prompt-caching)
|