使用跟踪

这是什么¶

• 直接从每个提供商的用量端点拉取提供商用量/配额。不涉及估算的提供商计费；仅显示提供商报告的套餐名称、配额窗口、余额、支出、预算、每日成本历史、Token/模型归属或账户状态摘要。
• 人类可读的配额窗口输出被规范化为 X% left，即使提供商报告的是已消耗配额、剩余配额或仅原始计数。没有可重置配额窗口的提供商则显示提供商摘要文本（例如余额）。
• 会话级 /status 和 session_status 工具在实时会话快照缺少 Token/模型数据时，会回退到会话的转录日志。该回退会填补缺失的 Token/缓存计数器，可以恢复活动的运行时模型标签，并在会话元数据缺失或较小时（totalTokensFresh !== true、为零或低于转录推导值）优先采用更大的面向提示的总数。非零实时值始终优先于回退值。

显示位置¶

• 聊天中的 /status：状态卡片显示会话 Token 和估算成本（仅限 API 密钥模型）。提供商用量在可用时显示当前模型提供商的用量，以规范化的 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 菜单栏：当提供商用量快照可用时，顶层 “Usage” 部分会出现在 Context 下方。参见菜单栏。

自 v2026.5.7 起，openclaw channels list 不再打印提供商用量；它会引导用户改用 openclaw status 或 openclaw models list。

/usage cost 会警告 今日 和 最近 30 天 的总计可能不完整（如果它们的聚合缓存正在刷新、不完整或已过期），并建议稍后重新运行该命令。会话 总计单独加载。CLI 的 openclaw gateway usage-cost 也会先报告记录的缓存状态，再给出总计。

Control UI 会在 5 秒、10 秒和 20 秒后再次检查不完整的用量总计。这些间隔检查让大型历史记录有时间加载，同时将刷新流量限制在可控范围内。在冷缓存获得任何用量数据之前，页面会显示加载占位符而不是零总计。已有的部分总计保持可见；如果自动检查完成后仍没有完整数据，请选择 刷新 重试。

用量视图打开时默认选中最近 30 个日历日。今日、7 天、30 天、90 天、1 年、全部 或日期输入可更改报告范围。历史沿袭包含会话保留的早期实例；日期范围仍控制图表中显示哪些活动。总计和每日图表来自同一会话报告，包括超出可见列表限制的会话。

记录的零美元成本是有效的成本数据。平均成本提示仅在所选报告包含未定价用量时才警告缺少价格；过滤到已知零成本的会话可清除该警告。

发起者 按记录的会话创建者分组用量。选择一个身份可过滤完整报告，包括其历史和总计。人类配置文件、Agent 和系统创建的会话保持独立；没有记录创建者的历史会话显示为 未归属。这会将整个会话归属于其创建者，而不是将单个轮次归属于参与者，或将费用归属于提供商 API 账户。当前账户设置不用于猜测历史归属。

选择图表中的日期可缩小完整报告中创建者总计和会话计数的范围，包括超出可见列表限制的会话。在多个选定日期处于活跃状态的会话只计一次。会话、文本和小时过滤器则使用已加载的会话行。

用量日期范围¶

Gateway 方法 usage.cost 和 sessions.usage 默认按 UTC 解释日期范围。在 mode: "specific" 中，使用有效的 IANA timeZone（例如 Europe/Vienna），以遵循本地日历日和夏令时变化。它优先于旧的 utcOffset 字段。

没有 timeZone 时，固定的 utcOffset 必须在 UTC-12:00 到 UTC+14:00 之间（含两端，例如 UTC+5:30）。无效的非空偏移会返回 INVALID_REQUEST，而不是静默使用 UTC。省略这两个字段则使用 UTC。usage.cost 还将空偏移视为省略；sessions.usage 要求任何提供的偏移都符合 UTC 偏移格式，因此请省略该字段，而不要发送空值。

Anthropic 与 OpenAI 成本历史¶

订阅配额和 API 计费是不同的提供商维度：

• Anthropic 订阅/设置凭据继续显示 Claude 配额窗口和可选的额外用量预算。设置 ANTHROPIC_ADMIN_KEY 或 ANTHROPIC_ADMIN_API_KEY 改为显示组织的 Usage 和 Cost API 历史。以 sk-ant-admin 开头的 Anthropic 提供商凭据会被自动检测。
• OpenAI ChatGPT/Codex OAuth 继续显示套餐、配额窗口和信用余额。设置 OPENAI_ADMIN_KEY 改为显示组织成本和 completions 用量历史；可选择设置 OPENAI_PROJECT_ID 将其范围限定到单个项目。OpenClaw 绝不会将来自 OPENAI_API_KEY、提供商配置或认证配置文件的推理凭据发送到组织 API，因为这些密钥可能属于自定义端点。

管理员凭据具有优先权，因为它们提供实际的组织计费。OpenClaw 不会将这些提供商报告的总计与其本地会话估算合并；这两个部分有意回答不同的问题。

默认用量页脚模式¶

/usage off|tokens|full 为会话设置页脚，并会被该会话记住。messages.responseUsage 为尚未选择模式的会话预置该模式，因此页脚可以默认开启，而无需每次输入 /usage。

为每个渠道设置一个模式，或使用带 default 回退的按渠道映射：

{
  "messages": {
    "responseUsage": "tokens",
    // or: { "default": "off", "discord": "full" }
  },
}

接受的值："off"、"tokens"、"full"，以及旧版别名 "on"（按 "tokens" 处理）。

三种不同的会话状态¶

会话的 responseUsage 字段有三种可表示状态，每种都有不同语义：

优先级¶

生效模式 = 会话覆盖 → 渠道配置项 → default → off。

显式 /usage off 会作为字面值 "off" 持久化到会话中，而不是等同于“未设置”。一旦用户显式禁用页脚，非 off 的 messages.responseUsage 默认值就无法将其重新打开。

重置与关闭¶

• /usage off 强制关闭页脚并持久化该选择。已配置的非 off 默认值无法覆盖此选择。
• /usage reset（别名：default、inherit、inherited、clear、unpin）清除会话覆盖。随后会话继承生效的配置默认值（messages.responseUsage）。如果未配置默认值，页脚保持关闭。
• 完整会话重置（/reset 或 /new）或会话滚动保留显式用量模式偏好，使用户的显示选择能够跨会话滚动保留。只有 /usage reset（及其别名）会清除覆盖。

切换行为¶

不带参数的 /usage 循环切换：off → tokens → full → off。循环的起点是生效的当前模式（会话覆盖，未设置时回落到配置默认值），因此循环始终与用户当前在页脚中看到的内容一致。

配置¶

没有配置时，原有行为保持不变（页脚在 /usage 之前保持关闭）。使用 /usage reset 清除会话覆盖并重新继承已配置的默认值。

自定义 /usage full 页脚¶

当可用时，/usage tokens 会渲染一行普通的 Usage: X in / Y out，并显示缓存计数器。缺失的输入或输出计数保持为 ?；OpenClaw 不会根据总计推断拆分。当两个方向都未报告时，已知总计显示为 Usage: 1.3k total。即使输入、输出和总计计数都不可用，缓存计数器仍会显示。此模式从不估算成本。只有 /usage full 会渲染下文描述的更丰富页脚。

/usage full 在相应字段可用时显示内置紧凑页脚，包括模型、推理、快速/慢速、上下文窗口和成本。内置页脚不需要模板文件。

messages.usageTemplate 仅用于高级自定义布局。其值是一个 JSON 文件路径（支持 ~）或内联对象，有效时会替换内置页脚。文件路径会被监视，并在更改时实时重新加载。

{
  "messages": {
    "usageTemplate": "~/.openclaw/usage-footer.json"
  }
}

缺失或空模板会静默回落到内置页脚。不可读或无效的已配置模板（JSON 错误，或没有可渲染输出片段的形状）也会回落到内置页脚，并发出操作员警告。

从内置形状开始创建自定义模板，然后编辑要更改的部分：

{
  "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}" },
      ],
    },
  },
}

形状¶

{
  "schema": "openclaw.usageBar.v1",
  "scales": { "<name>": "low-to-high glyphs" }, // string (1 glyph/char) or array
  "aliases": { "<table>": { "<value>": "<label>" } },
  "output": {
    "sep": "", // joins surviving pieces
    "default": [/* pieces */], // fallback for any surface
    "surfaces": {
      "discord": [/* pieces */],
      "telegram": [/* pieces */],
    },
  },
}

每个 surface 是一个有序的 片段 列表；引擎会渲染每个片段，丢弃空值，并用 sep 连接剩余片段。没有条目的 surface 使用 output.default。

契约路径¶

片段通过点路径从每轮契约中读取值。缺失的值为空（因此 when 守卫或 |fallback 可保持片段干净）。

（提供商速率限制窗口不在此契约中；目前没有数组值路径，因此 each 片段没有可迭代的内容。）

动词¶

将值从左到右依次通过动词处理；非动词段是回退。

fixed:N 仅接受 0 到 100 的完整十进制整数。无效的精度参数会使该插值为空。

meter:W:SCALE 仅接受 1 到 100 的完整十进制整数宽度。将宽度留空以使用默认值 5（meter::braille）；无效宽度会使该插值为空。

片段形式¶

• { "text": "📚 {context.max_tokens|num}" }：字面量 + 插值。
• { "when": "<path>", "text": "..." }：仅当路径为真值时渲染。
• { "map": "<path>", "cases": { "true": "⚡", "false": "🐌" } }：值到字形（_default 情况覆盖未匹配的值）。
• { "each": "<array-path>", "item": "{label}" }：迭代数组值路径（当前没有契约路径是数组）。

示例¶

{
  "schema": "openclaw.usageBar.v1",
  "scales": { "braille": "⠐⡀⡄⡆⡇⣇⣧⣷⣿" },
  "aliases": { "reasoning": { "medium": "🌗", "high": "🌕" } },
  "output": {
    "surfaces": {
      "discord": [
        { "text": "{model.display_name}" },
        { "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}",
        },
      ],
    },
  },
}

例如渲染为 claude-sonnet-4-6 🌗 🐌 | 📚 [⣿⣿⣿⣿⣧]272k。

提供商 + 凭据¶

当无法解析可用的提供商用量身份验证时，用量会被隐藏。OpenClaw 会自动发现声明 contracts.usageProviders 并同时实现 resolveUsageAuth 和 fetchUsageSnapshot 的已启用提供商插件；没有单独的核心提供商允许列表。静态契约使发现范围保持有限，而无需导入每个提供商插件。每个插件拥有自己的上游端点和响应映射。共享快照使套餐名称、配额窗口、余额、支出和预算对 CLI、应用和 Control UI 消费者保持提供商中立。

• Anthropic (Claude)：身份验证配置中的 OAuth 令牌。如果 OAuth 令牌缺少 user:profile 范围，则在已设置时回退到 claude.ai Web 会话（CLAUDE_AI_SESSION_KEY、CLAUDE_WEB_SESSION_KEY，或 CLAUDE_WEB_COOKIE 中的 sessionKey= Cookie）。当 Anthropic 报告时，会包含模型范围限制和已启用的额外用量月度支出/预算。显式的 Anthropic Admin API 密钥，或自动检测到的 sk-ant-admin... 提供商配置，则显示 30 天组织成本和 Messages API 历史记录。
• ClawRouter：API 密钥（CLAWROUTER_API_KEY）。配置时显示月度预算窗口和类型化 USD 预算；否则显示总支出以及请求/Token/成本摘要。
• DeepSeek：通过环境变量/配置/身份验证存储的 API 密钥（DEEPSEEK_API_KEY）。显示每个提供商报告的货币余额。
• GitHub Copilot：身份验证配置中的 OAuth 令牌。
• MiniMax：API 密钥或 MiniMax OAuth 身份验证配置。OpenClaw 将 minimax、minimax-cn 和 minimax-portal 视为同一 MiniMax 配额界面，存在时优先使用已存储的 MiniMax OAuth，否则回退到 MINIMAX_CODE_PLAN_KEY、MINIMAX_CODING_API_KEY 或 MINIMAX_API_KEY。用量轮询在已配置时从 models.providers.minimax-portal.baseUrl 或 models.providers.minimax.baseUrl 派生 Coding Plan 主机，否则使用 MiniMax CN 主机。MiniMax 的原始 usage_percent / usagePercent 字段表示剩余配额，因此 OpenClaw 在显示前会反转它们；存在基于计数的字段时优先使用。
• 窗口标签在存在时来自提供商的小时/分钟字段，然后回退到 start_time / end_time 跨度。
• 如果 coding-plan 端点返回 model_remains，OpenClaw 优先选择聊天模型条目，在缺少显式 window_hours / window_minutes 字段时从时间戳派生窗口标签，并在计划标签中包含模型名称。
• OpenAI (Codex/ChatGPT 计划)：身份验证配置中的 OAuth 令牌（存在账户 ID 时发送 ChatGPT-Account-Id 请求头）。显示 ChatGPT 计划、可重置的 Codex 窗口，并在报告时显示信用余额。信用仍为提供商信用；OpenClaw 不会将其标记为美元。当密钥具有 Usage Dashboard 访问权限时，OPENAI_ADMIN_KEY 会添加 30 天组织成本和 completions-usage 历史记录。推理凭据永远不会转发到组织 API。
• OpenRouter：API 密钥或 OAuth 支持的 API 密钥（OPENROUTER_API_KEY 或身份验证配置）。组合账户信用端点和密钥配额端点，因此当凭据可以访问时，会显示账户余额/支出、密钥预算以及每日/每周/每月用量。任一端点都可以独立丰富快照。
• Venice：通过环境变量/配置/身份验证存储的 API 密钥（VENICE_API_KEY）。显示 USD 和 DIEM 余额，并在报告时显示 DIEM epoch 分配用量。
• Xiaomi MiMo：两个独立的用量界面。按量付费使用 API 密钥（XIAOMI_API_KEY）；Token Plan 使用单独的密钥（XIAOMI_TOKEN_PLAN_API_KEY）。目前两者都不报告配额窗口。
• z.ai：通过环境变量/配置/身份验证存储的 API 密钥（ZAI_API_KEY 或 Z_AI_API_KEY）。

相关¶

• Token 使用和成本
• API 用量和成本
• Prompt 缓存
• 菜单栏