# 用量跟踪 > 用量跟踪界面和凭据要求 - 网址：https://funcoding.ai/agents/openclaw/concepts/usage-tracking/ - 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11 - 官方原文：https://docs.openclaw.ai/zh-CN/concepts/usage-tracking --- ## 它是什么 - 直接从每个提供商的用量端点提取提供商用量/配额。不估算提供商账单；仅提供提供商报告的套餐名称、配额窗口、余额、支出、预算、每日成本历史、Token/模型归因或账户状态摘要。 - 人类可读的配额窗口输出统一规范化为 `X% left`，即使提供商报告的是已消耗配额、剩余配额或仅原始计数。不提供可重置配额窗口的提供商将改为显示提供商摘要文本（例如余额）。 - 当实时会话快照缺少 Token/模型数据时，会话级 `/status` 和 `session_status` 工具会回退到会话的转录日志。此回退会补全缺失的 Token/缓存计数器，可以恢复当前运行时模型标签，并且当会话元数据缺失或较小时（`totalTokensFresh !== true`、零或低于从转录记录推导的值），优先采用面向提示词的较大总数。非零实时值始终优先于回退值。 ## 显示位置 - 聊天中的 `/status`：显示会话 Token 和估算成本的状态卡（仅限 API key 模型）。如果可用，将显示**当前模型提供商**的提供商用量，形式为规范化的 `X% left` 窗口或提供商摘要文本。 - 聊天中的 `/usage off|tokens|full`：每次响应的用量页脚。 - 聊天中的 `/usage cost`：根据 OpenClaw 会话日志汇总的本地成本摘要。 - CLI：`openclaw status --usage` 输出完整的各提供商用量/配额明细。 - CLI：`openclaw models status` 列出 OAuth/Token 身份验证配置文件，并在每个具有用量窗口的提供商旁显示用量窗口摘要。 - Control UI：**用量**会在 OpenClaw 根据会话推导的 Token 和估算成本分析上方显示提供商套餐及账单卡片。Anthropic 和 OpenAI Admin API 凭据还会添加提供商报告的今日、7 天及 30 天支出、每日趋势、Token 总数、热门模型和成本类别。 - Control UI：聊天输入框的上下文环形弹出框会显示订阅提供商的**套餐用量**——各窗口进度条（5 小时、每周、模型范围），包括重置时间、已知的提供商套餐（例如 `Max (20x)`）以及额外用量额度。通过套餐计费的会话会隐藏按 Token 计算的美元估值；通过 API 计费的会话则保留 `Est. cost` 和按类型划分的成本明细。Claude Code CLI（`claude-cli`）设置会复用相同的 Anthropic 订阅用量。 - macOS 菜单栏：当提供商用量快照可用时，根级“用量”部分会显示在“上下文”下方。请参阅[菜单栏](https://funcoding.ai/agents/openclaw/platforms/mac/menu-bar/)。 `openclaw channels list` 不再输出提供商用量；它会改为引导用户使用 `openclaw status` 或 `openclaw models list`。 ## Anthropic 和 OpenAI 成本历史 订阅配额与 API 账单是不同的提供商界面： - Anthropic 订阅/设置凭据继续显示 Claude 配额窗口和可选的额外用量预算。设置 `ANTHROPIC_ADMIN_KEY` 或 `ANTHROPIC_ADMIN_API_KEY` 可改为显示组织 Usage and Cost API 历史记录。以 `sk-ant-admin` 开头的 Anthropic 提供商凭据会被自动检测。 - OpenAI ChatGPT/Codex OAuth 继续显示套餐、配额窗口和额度余额。设置 `OPENAI_ADMIN_KEY` 可改为显示组织成本和补全用量历史记录；还可选择设置 `OPENAI_PROJECT_ID`，将范围限定到单个项目。OpenClaw 绝不会将 `OPENAI_API_KEY`、提供商配置或身份验证配置文件中的推理凭据发送到组织 API，因为这些密钥可能属于自定义端点。 Admin 凭据具有优先权，因为它们提供实际的组织账单数据。OpenClaw 不会将这些提供商报告的总数与本地会话估算值合并；这两个部分有意回答不同的问题。 ## 默认用量页脚模式 `/usage off|tokens|full` 设置会话的页脚，并会为该 会话记住此设置。对于尚未选择模式的会话，`messages.responseUsage` 会设定初始模式， 因此无需每次输入 `/usage`，页脚也可以默认启用。 可以为所有渠道设置一个模式，也可以设置按渠道划分的映射，并提供 `default` 回退： ```jsonc { "messages": { "responseUsage": "tokens", // 或：{ "default": "off", "discord": "full" } }, } ``` 接受的值：`"off"`、`"tokens"`、`"full"`，以及旧版别名 `"on"`（按 `"tokens"` 处理）。 ### 三种不同的会话状态 会话的 `responseUsage` 字段有三种可表示的状态，每种状态具有 不同的语义： | 状态 | 存储值 | 生效模式 | | ------------------- | ------------------------------- | --------------------------------------------------------------------- | | **未设置/继承** | `undefined`（不存在） | 依次回退到 `messages.responseUsage` 配置默认值，然后是 `off`。 | | **显式关闭** | `"off"`（已存储） | 始终关闭；非关闭的配置默认值无法重新启用页脚。 | | **显式开启** | `"tokens"` 或 `"full"`（已存储） | 无论配置默认值如何，均使用该模式。 | ### 优先级 生效模式 = 会话覆盖 → 渠道配置条目 → `default` → `off`。 显式的 `/usage off` 会以字面值 `"off"` **持久化**到 会话中，它与“未设置”不同。一旦用户显式禁用页脚，非关闭的 `messages.responseUsage` 默认值无法将其重新开启。 ### 重置与关闭 - `/usage off` 强制关闭页脚并持久化该选择。已配置的 非关闭默认值无法覆盖它。 - `/usage reset`（别名：`default`、`inherit`、`inherited`、`clear`、`unpin`）会清除会话 覆盖。随后，会话会**继承**生效的配置默认值 （`messages.responseUsage`）。如果未配置默认值，页脚将保持关闭。 - 完整会话重置（`/reset` 或 `/new`）或会话滚动会**保留** 显式的用量模式偏好，因此用户的显示选择可在 会话滚动后继续保留。只有 `/usage reset`（及其别名）会清除覆盖。 ### 切换行为 不带参数的 `/usage` 会按以下顺序循环：关闭 → Token → 完整 → 关闭。循环的起点 是当前的**生效**模式（未设置会话覆盖时会回退到 配置默认值），因此循环始终与用户当前在页脚中 看到的内容一致。 ### 配置 未进行配置时，保留之前的行为（页脚关闭，直到使用 `/usage`）。使用 `/usage reset` 可清除会话覆盖，并重新继承已配置的默认值。 ## 自定义 `/usage full` 页脚 `/usage tokens` 始终呈现一行纯 `Usage: X in / Y out`（如果可用，还会附加缓存和 估算成本后缀）。只有 `/usage full` 会呈现下述更丰富的 页脚。 `/usage full` 会显示内置的紧凑页脚；当相应字段可用时，其中包含模型、推理、快速/慢速、 上下文窗口和成本。内置页脚 不需要模板文件。 `messages.usageTemplate` 仅用于高级自定义布局。该值可以是 JSON 文件路径（支持 `~`）或内联对象；有效时会替换内置 页脚。文件路径会被监视，并在发生变化时实时重新加载。 ```json { "messages": { "usageTemplate": "~/.openclaw/usage-footer.json" } } ``` 缺失或空模板会静默回退到内置页脚。无法读取 或无效的已配置模板（JSON 错误，或其结构中没有可呈现的输出 片段）也会回退到内置页脚，并发出操作员警告。 以该内置结构为起点创建自定义模板，然后编辑想要 更改的部分： ```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": " | 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}", }, { "when": "cost.turn_usd", "text": " 💰{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": " | 📚[{context.pct_used|meter:5:braille}]{context.max_tokens|num}", }, { "when": "cost.turn_usd", "text": " 💰{cost.turn_usd|fixed:4}" }, ], }, }, } ``` ### 结构 ```jsonc { "schema": "openclaw.usageBar.v1", "scales": { "": "从低到高的字形" }, // 字符串（每个字符 1 个字形）或数组 "aliases": { "": { "": "