前言¶

用 OpenClaw 或同类 Agent 跑长会话时，上下文和补全会持续消耗 token，平台告警往往来得晚。想回答「今天花了多少」「本周趋势如何」「预算还剩多少」，通常要翻控制台或各家账单页，和对话上下文是割裂的。

下面介绍社区 Skill token tracker（坐标 @user_4e3fb524/tokentracker，版本 1.0.0）。它把当前会话、按日/按周的统计、预算与告警，以及多家服务商的用量或余额接口，收进 Skill 目录内的一套脚本与本地数据文件，由 Agent 按 SKILL.md 的流程调用。

这是什么¶

token tracker 是面向 OpenClaw 生态的 token 用量追踪 Skill，发布者为 SkillHub 用户 user_4e3fb524，分类为 data-analysis，来源标注为 community。作者在 SkillHub 简介中说明：因自用时常遇到 token 告警，希望做用量提醒并评估每日花销。

代码仓库：https://github.com/moubintju/token_tracker
SkillHub 页面：https://www.skillhub.cn/skills/user_4e3fb524/tokentracker

Skill 元数据标记 requires_api_key=true：若要走服务商账单/余额接口，需要配置相应 API Key（类型因厂商而异，见下文）。

核心功能¶

以下能力均来自官方 SkillHub 说明与仓库内 SKILL.md。

用量查询¶

1. 当前会话：通过 session_status 查看本次对话的 token、费用、cache 命中率、context 占用等（仅针对「这一场」 live session）。
2. 今日 / 指定日期：脚本 summary，支持 --date YYYY-MM-DD 查历史日。
3. 今日明细：脚本 bill。
4. 本周：脚本 week。

本地汇总与账单逻辑由 {baseDir}/scripts/token-tracker.js 执行；持久化数据写在 Skill 目录下的 usage.json（自动创建）。

预算与告警¶

• 设置预算：例如自然语言「设置预算 20」或 set budget 15，对应 set-budget --amount。
• 查看预算状态：budget-status。
• 支持自动日报、周报、预算提醒与超额告警；通过 agent:bootstrap hook 在会话启动时投递，状态文件包括 report-state.json、alert-state.json。日报触发时刻可在 budget.json 的 daily_report_hour 配置（默认 23）。

服务商对接¶

官方说明支持接入：

SkillHub 文案写明：除 Google 外，常见主流厂商大多覆盖。SKILL.md 中支持的 configure-provider --name 取值为：openai、anthropic、openrouter、deepseek、kimi、minimax。

对接细节（与官方文档一致）：

• OpenAI：需 Admin API Key，调用 /v1/organization/costs。
• Anthropic：需 Admin API Key（sk-ant-admin-...），调用组织用量报告接口。
• OpenRouter：需 Management API Key，按日按模型拉 activity，并可查 credits 余额。
• DeepSeek / Kimi / MiniMax：文档说明仅支持余额类查询，无按日明细用量 API。

配置与拉数命令示例（{baseDir} 为 Skill 安装后的绝对路径）：

node "{baseDir}/scripts/token-tracker.js" configure-provider --name openai --api-key <your-key>
node "{baseDir}/scripts/token-tracker.js" fetch-usage --lang zh
node "{baseDir}/scripts/token-tracker.js" provider-balance --name deepseek --lang zh

Agent 何时会用到这个 Skill¶

SKILL.md 的 description 列举了典型意图，例如：「今天用了多少 token」「今日详细账单」「本周报告」「预算还剩多少」「配置 OpenAI」「从 API 获取用量」「查询余额」等。用户用中文提问时，脚本侧建议使用 --lang zh。

安装与启用¶

通过 SkillHub CLI 安装¶

先确认本机是否已有 skillhub（安装方式见 SkillHub 安装文档）。安装 Skill 时必须用 --dir 指向当前 Agent 实际读取的 skills 目录，否则默认落在 ./skills/ 可能不会被加载。

command -v skillhub && skillhub --version
skillhub install @user_4e3fb524/tokentracker --dir <你的 skills 目录>

常见路径（来自 SkillHub 安装文档，按你实际使用的客户端选择）：

• OpenClaw 及同类变体：各自配置中的 skills 目录（NanoBot、PicoClaw、memUBot 等文档中列出的路径）。
• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下 .agents/skills/

SkillHub 页面也提供「让 AI 根据安装文档安装 @user_4e3fb524/tokentracker」的提示词方式，本质仍是指向同一坐标与 skillhub.md。

会话内一次性准备（Agent 侧）¶

按 SKILL.md，每个会话开始处理用量相关请求前，Agent 应：

1. 检查并必要时安装 hook（自动日报/周报/告警）：

node "{baseDir}/scripts/setup-hook.js" check
node "{baseDir}/scripts/setup-hook.js" install

2. 在本会话第一次回答用量类问题前，优先 list-providers；若已有启用且带 key 的厂商，则静默执行 fetch-usage；否则在无厂商配置时可用 session_status + record-session 回退。

相关配置文件（均在 Skill 目录内，勿假设仓库外已有配置）：

• usage.json — 用量数据
• budget.json — 预算与 daily_report_hour
• providers.json — 服务商与 Key

典型用法¶

在 Skill 已安装、Agent 已加载的前提下，用户可直接用自然语言；Agent 按 SKILL.md 调用脚本。下列命令便于人工核对或调试（将 {baseDir} 换成安装路径）。

今日汇总：

node "{baseDir}/scripts/token-tracker.js" summary --lang zh

今日详细账单：

node "{baseDir}/scripts/token-tracker.js" bill --lang zh

本周报告：

node "{baseDir}/scripts/token-tracker.js" week --lang zh

设置预算为 15（美元，以脚本解析为准）：

node "{baseDir}/scripts/token-tracker.js" set-budget --lang zh --amount 15

查看已配置服务商：

node "{baseDir}/scripts/token-tracker.js" list-providers --lang zh

若用户只问「这次对话用了多少」，应走 session_status，而不是把「今天」误当成当前会话。

适用场景与注意¶

适合谁

• 长期在 OpenClaw 或兼容其 Skill 约定的环境里工作，希望用对话查 token/费用、周报和预算的人。
• 已在 OpenAI、Anthropic、OpenRouter 等具备组织/管理类 Key 的账号，或需要盯 DeepSeek、Kimi、MiniMax 余额的用户。

限制与注意

1. Skill 自述为自包含目录实现；数据与配置都在 {baseDir} 下，换机器或清目录会丢本地统计，需重新 fetch-usage 或 record-session。
2. 多家厂商的「明细用量」依赖 Admin/Management 类 Key，普通对话用 Key 可能无法拉账单；DeepSeek/Kimi/MiniMax 侧更偏余额，与 OpenAI 类按日账单不能等同期待。
3. Google 未出现在官方支持列表中；若主力是 Google 模型，需另寻统计方式。
4. Hook 安装失败时，自动日报/周报/告警可能退化为手动执行 automation/ 下模板或自行调度。
5. SkillHub 页面当前显示版本 v1.0.0；安装前可在 SkillHub 或 GitHub 核对是否有更新。

结尾¶

token tracker 把会话级观测、本地账单汇总、预算告警和多服务商 API 合成一个 data-analysis 类 Skill，适合把「token 告警」从事后查看改成对话内可查询、可设预算、可定时提醒。体验与安装以其 SkillHub 条目与 GitHub 仓库为准：

• SkillHub：https://www.skillhub.cn/skills/user_4e3fb524/tokentracker
• GitHub：https://github.com/moubintju/token_tracker