--- read_when: - Sie verdrahten Provider-Nutzungs- und Kontingentoberflächen - Sie müssen das Verhalten der Nutzungsverfolgung oder Authentifizierungsanforderungen erklären summary: Nutzungsverfolgungsoberflächen und Anmeldeinformationsanforderungen title: Nutzungsverfolgung x-i18n: generated_at: "2026-07-01T18:10:29Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: fa9b2b0b19ca0b4beeea40bfd50b07a92155178d5ec0e1877013843e0caba4fb source_path: concepts/usage-tracking.md workflow: 16 --- ## Was es ist - Ruft Provider-Nutzung/-Kontingent direkt von deren Nutzungsendpunkten ab. - Keine geschätzten Kosten; nur vom Provider gemeldete Kontingentfenster oder Zusammenfassungen des Kontostands. - Die menschenlesbare Statusausgabe für Kontingentfenster wird auf `X% übrig` normalisiert, auch wenn eine Upstream-API verbrauchtes Kontingent, verbleibendes Kontingent oder nur Rohzählungen meldet. Provider ohne zurücksetzbare Kontingentfenster können stattdessen Provider-Zusammenfassungstext anzeigen, etwa ein Guthaben. - `/status` und `session_status` auf Sitzungsebene können auf den neuesten Nutzungs-Eintrag im Transkript zurückfallen, wenn der Live-Sitzungs-Snapshot spärlich ist. Dieser Fallback füllt fehlende Token-/Cache-Zähler, kann die aktive Runtime-Modellbeschriftung wiederherstellen und bevorzugt die größere promptorientierte Gesamtsumme, wenn Sitzungsmetadaten fehlen oder kleiner sind. Vorhandene Live-Werte ungleich null haben weiterhin Vorrang. ## Wo es angezeigt wird - `/status` in Chats: Statuskarte mit vielen Emojis, Sitzungstokens + geschätzten Kosten (nur API-Schlüssel). Provider-Nutzung wird für den **aktuellen Modell-Provider** angezeigt, wenn verfügbar, als normalisiertes `X% übrig`-Fenster oder Provider-Zusammenfassungstext. - `/usage off|tokens|full` in Chats: Nutzungsfußzeile pro Antwort. - `/usage cost` in Chats: lokale Kostenzusammenfassung, aggregiert aus OpenClaw-Sitzungslogs. - CLI: `openclaw status --usage` gibt eine vollständige Aufschlüsselung pro Provider aus. - CLI: `openclaw channels list` gibt denselben Nutzungs-Snapshot zusammen mit der Provider-Konfiguration aus (verwenden Sie `--no-usage`, um dies zu überspringen). - macOS-Menüleiste: Abschnitt „Usage“ unter Context (nur wenn verfügbar). ## Standardmodus der Nutzungsfußzeile `/usage off|tokens|full` legt die Fußzeile für eine Sitzung fest und wird für diese Sitzung gespeichert. `messages.responseUsage` initialisiert diesen Modus für Sitzungen, die noch keinen ausgewählt haben, sodass die Fußzeile standardmäßig aktiviert sein kann, ohne jedes Mal `/usage` einzugeben. Legen Sie einen Modus für jeden Kanal fest oder eine kanalbezogene Zuordnung mit einem `default`-Fallback: ```jsonc { "messages": { "responseUsage": "tokens", // or: { "default": "off", "discord": "full" } }, } ``` ### Drei unterschiedliche Sitzungszustände Das Feld `responseUsage` einer Sitzung hat drei darstellbare Zustände, jeweils mit unterschiedlicher Semantik: | Zustand | Gespeicherter Wert | Effektiver Modus | | ----------------------------- | ------------------------------- | --------------------------------------------------------------------- | | **Nicht gesetzt / vererben** | `undefined` (nicht vorhanden) | Fällt auf den `messages.responseUsage`-Konfigurationsstandard zurück, dann auf `off`. | | **Explizit aus** | `"off"` (gespeichert) | Immer aus — ein Konfigurationsstandard ungleich `off` kann die Fußzeile nicht erneut aktivieren. | | **Explizit an** | `"tokens"` oder `"full"` (gespeichert) | Dieser Modus, unabhängig vom Konfigurationsstandard. | ### Vorrang Effektiver Modus = Sitzungsüberschreibung → Kanalkonfigurationseintrag → `default` → `off`. Ein explizites `/usage off` wird als literaler Wert `"off"` in der Sitzung **persistiert**, nicht als „nicht gesetzt“. Das bedeutet, dass ein `messages.responseUsage`-Standard ungleich `off` die Fußzeile nicht wieder einschalten kann, nachdem der Benutzer sie ausdrücklich deaktiviert hat. ### Zurücksetzen vs. Ausschalten - `/usage off` — erzwingt das Ausschalten der Fußzeile und persistiert diese Auswahl. Ein konfigurierter Standard ungleich `off` kann dies nicht überschreiben. - `/usage reset` (Aliase: `inherit`, `clear`, `default`) — löscht die Sitzungsüberschreibung. Die Sitzung **erbt** dann den effektiven Konfigurationsstandard (`messages.responseUsage`). Wenn kein Standard konfiguriert ist, bleibt die Fußzeile aus (unverändert gegenüber vorher). Verwenden Sie dies, um „zum Standard zurückzukehren“, ohne die Fußzeile ausdrücklich einzuschalten. - Ein vollständiges Zurücksetzen der Sitzung (`/reset` oder `/new`) oder ein Sitzungs-Rollover **bewahrt** die explizite Nutzungsmodus-Präferenz, sodass die Anzeigeauswahl des Benutzers Sitzungs-Rollover übersteht. Nur `/usage reset` (und seine Aliase) löscht die Überschreibung tatsächlich. ### Umschaltverhalten `/usage` ohne Argumente durchläuft: off → tokens → full → off. Der Ausgangspunkt für den Zyklus ist der **effektive** aktuelle Modus (Sitzungsüberschreibung fällt bei Nichtsetzung auf den Konfigurationsstandard zurück), sodass der Zyklus immer mit dem übereinstimmt, was der Benutzer in der Fußzeile sieht. ### Konfiguration Ohne Konfiguration bleibt das bisherige Verhalten bestehen (Fußzeile aus bis `/usage`). Verwenden Sie `/usage reset`, um eine Sitzungsüberschreibung zu löschen und den konfigurierten Standard erneut zu erben. ## Benutzerdefinierte `/usage full`-Fußzeile `/usage full` zeigt eine integrierte kompakte Fußzeile mit Modell, Reasoning, schnell/langsam, Kontextfenster und Kosten, wenn diese Felder verfügbar sind. Token- und Cache-Felder bleiben für benutzerdefinierte Vorlagen verfügbar. Es ist keine Vorlagendatei erforderlich. `messages.usageTemplate` ist nur für fortgeschrittene benutzerdefinierte Layouts vorgesehen. Der Wert ist ein JSON-Dateipfad (unterstützt `~`) oder ein Inline-Objekt und ersetzt bei Gültigkeit die integrierte Fußzeile: ```json { "messages": { "usageTemplate": "~/.openclaw/usage-footer.json" } } ``` Fehlende oder leere Vorlagen fallen stillschweigend auf die integrierte Fußzeile zurück. Nicht lesbare oder ungültig konfigurierte Vorlagen fallen ebenfalls auf die integrierte Fußzeile zurück und geben eine Operator-Warnung aus. Beginnen Sie benutzerdefinierte Vorlagen mit der integrierten Form und bearbeiten Sie dann die Teile, die Sie ändern möchten: ```jsonc { "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": "\u00A0| 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}", }, { "when": "cost.turn_usd", "text": "\u00A0💰{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": "\u00A0| 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}", }, { "when": "cost.turn_usd", "text": "\u00A0💰{cost.turn_usd|fixed:4}" }, ], }, }, } ``` ### Form ```jsonc { "schema": "openclaw.usageBar.v1", "scales": { "": "low-to-high glyphs" }, // string (1 glyph/char) or array "aliases": { "": { "": "