docs: clarify minimax usage window semantics

docs/cli/index.md

@@ -1197,6 +1197,7 @@ Options:
 Notes:
 
 - Overview includes Gateway + node host service status when available.
+- `--usage` prints normalized provider usage windows as `X% left`.
 
 ### Usage tracking
 
@@ -1211,7 +1212,9 @@ Surfaces:
 Notes:
 
 - Data comes directly from provider usage endpoints (no estimates).
-- Providers: Anthropic, GitHub Copilot, OpenAI Codex OAuth, plus Gemini CLI via the bundled `google` plugin and Antigravity where configured.
+- Human-readable output is normalized to `X% left` across providers.
+- Providers with current usage windows: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, and z.ai.
+- MiniMax note: raw `usage_percent` / `usagePercent` means remaining quota, so OpenClaw inverts it before display; count-based fields still win when present.
 - If no matching credentials exist, usage is hidden.
 - Details: see [Usage tracking](/concepts/usage-tracking).
 

docs/cli/models.md

@@ -25,7 +25,7 @@ openclaw models scan
 ```
 
 `openclaw models status` shows the resolved default/fallbacks plus an auth overview.
-When provider usage snapshots are available, the OAuth/token status section includes
+When provider usage snapshots are available, the OAuth/API-key status section includes
 provider usage windows and quota snapshots.
 Add `--probe` to run live auth probes against each configured provider profile.
 Probes are real requests (may consume tokens and trigger rate limits).

docs/cli/status.md

@@ -20,6 +20,8 @@ openclaw status --usage
 Notes:
 
 - `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal).
+- `--usage` prints normalized provider usage windows as `X% left`.
+- MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota, so OpenClaw inverts them before display; count-based fields win when present.
 - Output includes per-agent session stores when multiple agents are configured.
 - Overview includes Gateway + node host service install/runtime status when available.
 - Overview includes update channel + git SHA (for source checkouts).

docs/concepts/usage-tracking.md

@@ -12,10 +12,12 @@ title: "Usage Tracking"
 
 - Pulls provider usage/quota directly from their usage endpoints.
 - No estimated costs; only the provider-reported windows.
+- Human-readable status output is normalized to `X% left`, even when an
+  upstream API reports consumed quota, remaining quota, or only raw counts.
 
 ## 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.
+- `/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.
 - `/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.
@@ -27,9 +29,8 @@ title: "Usage Tracking"
 - **Anthropic (Claude)**: OAuth tokens in auth profiles.
 - **GitHub Copilot**: OAuth tokens in auth profiles.
 - **Gemini CLI**: OAuth tokens in auth profiles.
-- **Antigravity**: OAuth tokens in auth profiles.
 - **OpenAI Codex**: OAuth tokens in auth profiles (accountId used when present).
-- **MiniMax**: API key (coding plan key; `MINIMAX_CODE_PLAN_KEY` or `MINIMAX_API_KEY`); uses the 5‑hour coding plan window.
+- **MiniMax**: API key (coding plan key; `MINIMAX_CODE_PLAN_KEY` or `MINIMAX_API_KEY`); uses the 5‑hour coding plan window. MiniMax's raw `usage_percent` / `usagePercent` fields mean **remaining** quota, so OpenClaw inverts them before display; count-based fields win when present.
 - **z.ai**: API key via env/config/auth store.
 
 Usage is hidden if no matching OAuth/API credentials exist.

docs/providers/minimax.md

@@ -180,6 +180,10 @@ Current MiniMax auth choices in the wizard/CLI:
 - The bundled provider catalog currently exposes the chat refs as text-only
   metadata until explicit MiniMax provider config exists
 - Coding Plan usage API: `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` (requires a coding plan key).
+- OpenClaw normalizes MiniMax coding-plan usage to the same `% left` display
+  used by other providers. MiniMax's raw `usage_percent` / `usagePercent`
+  fields are remaining quota, not consumed quota, so OpenClaw inverts them.
+  Count-based fields win when present.
 - Update pricing values in `models.json` if you need exact cost tracking.
 - Referral link for MiniMax Coding Plan (10% off): [https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
 - See [/concepts/model-providers](/concepts/model-providers) for provider rules.

docs/reference/api-usage-costs.md

@@ -34,6 +34,10 @@ per-message dollar estimate that OpenClaw can show in `/usage full`.
 
 - `openclaw status --usage` and `openclaw channels list` show provider **usage windows**
   (quota snapshots, not per-message costs).
+- Human output is normalized to `X% left` across providers.
+- MiniMax note: its raw `usage_percent` / `usagePercent` fields mean remaining
+  quota, so OpenClaw inverts them before display. Count-based fields still win
+  when present.
 
 See [Token use & costs](/reference/token-use) for details and examples.
 

docs/reference/token-use.md

@@ -59,7 +59,7 @@ Other surfaces:
 
 - **TUI/Web TUI:** `/status` + `/usage` are supported.
 - **CLI:** `openclaw status --usage` and `openclaw channels list` show
-  provider quota windows (not per-response costs).
+  normalized provider quota windows (`X% left`, not per-response costs).
 
 ## Cost estimation (when shown)
 

docs/tools/slash-commands.md

@@ -179,7 +179,7 @@ of treating `/tools` as a static catalog.
 
 ## Usage surfaces (what shows where)
 
-- **Provider usage/quota** (example: “Claude 80% left”) shows up in `/status` for the current model provider when usage tracking is enabled.
+- **Provider usage/quota** (example: “Claude 80% left”) shows up in `/status` for the current model provider when usage tracking is enabled. OpenClaw normalizes provider windows to `% left`; for MiniMax, remaining-only percent fields are inverted before display.
 - **Per-response tokens/cost** is controlled by `/usage off|tokens|full` (appended to normal replies).
 - `/model status` is about **models/auth/endpoints**, not usage.