fix(usage): tidy compact footer defaults

obviyus · obviyus · commit 817b06bd53c0 · 2026-07-01T09:48:35.000-07:00
diff --git a/docs/concepts/usage-tracking.md b/docs/concepts/usage-tracking.md
@@ -24,7 +24,7 @@ title: "Usage tracking"
 ## 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 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 breakdown.
 - CLI: `openclaw channels list` prints the same usage snapshot alongside provider config (use `--no-usage` to skip).
@@ -95,8 +95,8 @@ With no config the prior behavior holds (footer off until `/usage`). Use
 ## Custom `/usage full` footer
 
 `/usage full` shows a built-in compact footer with model, reasoning, fast/slow,
-context window, turn tokens, cache, and cost when those fields are available. No
-template file is required.
+context window, and cost when those fields are available. Token and cache fields
+remain available to custom templates. No template file is required.
 
 `messages.usageTemplate` is only for advanced custom layouts. The value is a
 JSON file path (supports `~`) or an inline object, and it replaces the built-in
@@ -150,42 +150,30 @@ change:
   "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": " 🐌" } },
+      { "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}",
+        "text": "\u00A0| 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}",
       },
-      {
-        "when": "usage.has_split_tokens",
-        "text": " ↕️ {usage.input_tokens|num|?}/{usage.output_tokens|num|?}",
-      },
-      { "when": "usage.has_total_only_tokens", "text": " ↕️ {usage.total_tokens|num}" },
-      { "when": "usage.cache_hit_pct", "text": " 🗄 {usage.cache_hit_pct|pct}" },
-      { "when": "cost.turn_usd", "text": " 💰{cost.turn_usd|fixed:4}" },
+      { "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}" },
+        { "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": "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": "usage.has_split_tokens",
-          "text": " ↕️ {usage.input_tokens|num|?}/{usage.output_tokens|num|?}",
+          "text": "\u00A0| 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}",
         },
-        { "when": "usage.has_total_only_tokens", "text": " ↕️ {usage.total_tokens|num}" },
-        { "when": "usage.cache_hit_pct", "text": " 🗄 {usage.cache_hit_pct|pct}" },
-        { "when": "cost.turn_usd", "text": " 💰{cost.turn_usd|fixed:4}" },
+        { "when": "cost.turn_usd", "text": "\u00A0💰{cost.turn_usd|fixed:4}" },
       ],
     },
   },
diff --git a/docs/reference/prompt-caching.md b/docs/reference/prompt-caching.md
@@ -333,7 +333,7 @@ Defaults:
 ### What to inspect
 
 - Cache trace events are JSONL and include staged snapshots like `session:loaded`, `prompt:before`, `stream:context`, and `session:after`.
-- Per-turn cache token impact is visible in normal usage surfaces via `cacheRead` and `cacheWrite` (for example `/usage full` and session usage summaries).
+- Per-turn cache token impact is visible in normal usage surfaces via `cacheRead` and `cacheWrite` (for example `/usage tokens`, `/status`, session usage summaries, and custom `messages.usageTemplate` layouts).
 - For Anthropic, expect both `cacheRead` and `cacheWrite` when caching is active.
 - For OpenAI, expect `cacheRead` on cache hits. GPT-5.6 Responses can also report `cacheWrite` while prompt segments are written; other Responses payloads that omit the write counter keep it at `0`.
 - If you need request tracing, log request IDs and rate-limit headers separately from cache metrics. OpenClaw's current cache-trace output is focused on prompt/session shape and normalized token usage rather than raw provider response headers.
diff --git a/docs/reference/token-use.md b/docs/reference/token-use.md
@@ -78,8 +78,10 @@ Use these in chat:
   - Persists per session (stored as `responseUsage`).
   - `/usage reset` (aliases: `inherit`, `clear`, `default`) — clears the session
     override so the session re-inherits the configured default.
-  - `/usage full` shows estimated cost only when OpenClaw has usage metadata and
-    local pricing for the active model. Otherwise it shows tokens only.
+  - `/usage tokens` shows turn token/cache details.
+  - `/usage full` shows compact model/context/cost details; estimated cost appears
+    only when OpenClaw has usage metadata and local pricing for the active model.
+    Custom `messages.usageTemplate` layouts can include token/cache fields.
 - `/usage cost` → shows a local cost summary from OpenClaw session logs.
 
 Other surfaces:
@@ -131,10 +133,11 @@ models.providers.<provider>.models[].cost
 ```
 
 These are **USD per 1M tokens** for `input`, `output`, `cacheRead`, and
-`cacheWrite`. If pricing is missing, OpenClaw shows tokens only. Cost display is
-not limited to API-key auth: non-API-key providers such as `aws-sdk` can show
-estimated cost when their configured model entry includes local pricing and the
-provider returns usage metadata.
+`cacheWrite`. If pricing is missing, `/usage full` omits cost; use `/usage tokens`
+or a custom `messages.usageTemplate` when you need token/cache details in every
+reply. Cost display is not limited to API-key auth: non-API-key providers such
+as `aws-sdk` can show estimated cost when their configured model entry includes
+local pricing and the provider returns usage metadata.
 
 After sidecars and channels reach the Gateway ready path, OpenClaw starts an
 optional background pricing bootstrap for configured model refs that do not
diff --git a/src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts b/src/auto-reply/reply/agent-runner.misc.runreplyagent.test.ts
@@ -2776,6 +2776,8 @@ describe("runReplyAgent response usage footer", () => {
     const res = await createRun({ responseUsage: "full", sessionKey });
     const payload = Array.isArray(res) ? res[0] : res;
     const text = payload?.text ?? "";
+    expect(text).toContain("ok\nanthropic🤖claude🌘🐌");
+    expect(text).not.toContain("ok\n\nanthropic");
     expect(text).toContain("anthropic🤖claude🌘🐌");
     expect(text).not.toContain("↕️");
     expect(text).not.toContain("🗄");
diff --git a/src/auto-reply/usage-bar/default-template.ts b/src/auto-reply/usage-bar/default-template.ts
@@ -24,15 +24,8 @@ export const DEFAULT_USAGE_BAR_TEMPLATE: UsageBarTemplate = {
   },
   output: {
     sep: "",
-    // Telegram (and any surface without its own list) falls through to `default`,
-    // so the default is built to read well on a narrow phone screen:
-    // - Tight badges: no separators between model/flags/reasoning/fast.
-    // - NBSP (\u00A0) before "|" and before 💰 keeps those joins non-breaking.
-    // - 📚 is glued hard to the meter so it can't wrap between books and bars.
-    // - The single regular space after "|" is the only sanctioned wrap point.
-    // - Leading \n drops the footer onto its own line, below the message body.
     default: [
-      { text: "\n{model.provider}{identity.emoji|🤖}{model.display_name|alias:models}" },
+      { 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}" },
