TokenWatch

跨 AI 服务商追踪、分析与优化 token 使用量及成本。设置预算、接收告警、对比模型，从而降低支出。

免费且开源（MIT 许可证）• 零依赖 • 本地运行 • 无需 API 密钥

为何需要此 Skill？

在 OpenAI 收购 OpenClaw 后，token 成本已成为高级用户的首要关切。该 Skill 提供完整的支出可见性——你花在哪里、花了多少、以及如何精准降本。

解决的问题：

• 直到账单到账，你才知晓实际支出
• 在选定模型前，无法跨服务商横向比价
• 临近预算上限时，无任何告警机制
• 缺乏可落地的降本建议

功能特性

1. 记录使用量并自动计算成本

from tokenwatch import TokenWatch

monitor = TokenWatch()

monitor.record_usage(
    model="claude-haiku-4-5-20251001",
    input_tokens=1200,
    output_tokens=400,
    task_label="summarize article"
)
# ✅ 已记录：$0.00192

2. 从 API 响应中自动记录

from tokenwatch import record_from_anthropic_response, record_from_openai_response

# Anthropic
response = client.messages.create(model="claude-haiku-4-5-20251001", ...)
record_from_anthropic_response(monitor, response, task_label="my task")

# OpenAI
response = client.chat.completions.create(model="gpt-4o-mini", ...)
record_from_openai_response(monitor, response, task_label="my task")

3. 设置预算并触发告警

monitor.set_budget(
    daily_usd=1.00,
    weekly_usd=5.00,
    monthly_usd=15.00,
    per_call_usd=0.10,
    alert_at_percent=80.0   # 预算使用率达 80% 时触发告警
)
# ✅ 预算已设置：日预算=$1.0，周预算=$5.0，月预算=$15.0
# 🚨 BUDGET ALERT 将在阈值被突破时自动触发

4. 仪表盘

print(monitor.format_dashboard())

💰 支出概览
  今日：   $0.0042  （4 次调用，13,600 tokens）
  本周：   $0.0231  （18 次调用，67,200 tokens）
  本月：   $0.1847  （92 次调用，438,000 tokens）

📋 预算状态
  日预算：   [████░░░░░░░░░░░░░░░░] 42% $0.0042 / $1.00 ✅
  月预算：   [███████░░░░░░░░░░░░░] 37% $0.1847 / $0.50 ⚠️

💡 优化建议
  🔴 对非推理类任务，将 Opus 替换为 Sonnet（每月节省约 $8.20）
  🟡 gpt-4o 平均单次调用成本偏高 —— 缩短 prompt 长度

5. 调用前对比模型

# 对于 2000 输入 tokens + 500 输出 tokens：
for m in monitor.compare_models(2000, 500)[:6]:
    print(f"{m['model']:<42} ${m['cost_usd']:.6f}")

gemini-2.5-flash                           $0.000300
gpt-4o-mini                                $0.000600
mistral-small-2501                         $0.000350
claude-haiku-4-5-20251001                  $0.003600
mistral-large-2501                         $0.007000
gemini-2.5-pro                             $0.007500

6. 调用前预估成本

estimate = monitor.estimate_cost("claude-sonnet-4-5-20250929", input_tokens=5000, output_tokens=1000)
print(f"预估成本：${estimate['estimated_cost_usd']:.6f}")

7. 优化建议

suggestions = monitor.get_optimization_suggestions()
for s in suggestions:
    savings = s.get("estimated_monthly_savings_usd", 0)
    print(f"[{s['priority'].upper()}] {s['message']}")
    if savings:
        print(f"  → 每月节省约 ${savings:.2f}")

8. 导出报告

monitor.export_report("monthly_report.json", period="month")

支持的模型（2026 年 2 月）

覆盖 10 家服务商共 41 款模型 —— 更新于 2026 年 2 月 16 日。

如需添加自定义模型：请在 tokenwatch.py 文件顶部的 PROVIDER_PRICING 字典中新增条目。

API 参考文档

TokenWatch(storage_path)

初始化监控器。默认数据存储于 .tokenwatch/ 目录下。

record_usage(model, input_tokens, output_tokens, task_label, session_id)

记录一次 API 调用。返回包含计算成本的 TokenUsageRecord 对象。

set_budget(daily_usd, weekly_usd, monthly_usd, per_call_usd, alert_at_percent)

配置支出限额。当用量达到设定阈值时，系统自动触发告警。

get_spend(period)

获取聚合支出数据。支持周期参数："today"、"week"、"month"、"all" 或指定日期 "YYYY-MM-DD"。

get_spend_by_model(period)

按模型维度统计支出，结果按成本由高到低排序。

get_spend_by_provider(period)

按服务商维度统计支出。

compare_models(input_tokens, output_tokens)

对比所有已知模型的成本。返回按价格升序排列的模型列表。

estimate_cost(model, input_tokens, output_tokens)

调用前预估成本。

get_optimization_suggestions()

分析历史使用数据，返回带预估月度节省金额的优化建议列表（按优先级排序）。

format_dashboard()

生成面向人类阅读的支出仪表盘，含预算进度条与实用提示。

export_report(output_file, period)

导出完整报告至 JSON 文件。

record_from_anthropic_response(monitor, response, task_label)

辅助函数：从 Anthropic SDK 的响应对象中自动提取并记录 token 使用数据。

record_from_openai_response(monitor, response, task_label)

辅助函数：从 OpenAI SDK 的响应对象中自动提取并记录 token 使用数据。

隐私与安全

• ✅ 零遥测 —— 不向任何地方发送数据
• ✅ 纯本地存储 —— 所有数据仅保存在你设备上的 .tokenwatch/ 目录中
• ✅ 无需 API 密钥 —— 监控器自身不依赖任何认证凭据
• ✅ 无需身份验证 —— 不需要注册账号或登录
• ✅ 完全透明 —— MIT 许可证授权，源代码完全公开

更新日志

[1.2.3] - 2026-02-16

• 📋 更新 SKILL.md 中的模型表格，与代码保持一致：覆盖 10 家服务商共 41 款模型

[1.2.0] - 2026-02-16

• ✨ 新增 DeepSeek、Meta Llama、MiniMax 三家服务商支持
• ✨ 模型总数扩展至 41 款，覆盖 10 家服务商
• ✨ 全面更新 Anthropic / OpenAI / Google / Mistral 四家服务商的定价至 2026 年 2 月标准

[1.1.0] - 2026-02-16

• ✨ 新增 xAI Grok、Kimi（Moonshot）、Qwen（Alibaba）三家服务商支持
• ✨ 模型总数扩展至 32 款，覆盖 7 家服务商

[1.0.0] - 2026-02-16

• ✨ 初始发布 —— TokenWatch
• ✨ 支持 5 家服务商共 11 款模型的定价表
• ✨ 支持日/周/月/单次调用多级预算告警
• ✨ 支持模型成本对比、调用前成本预估、智能优化建议
• ✨ 内置 Anthropic 和 OpenAI SDK 响应对象的自动钩子（auto-hooks）
• ✨ 提供交互式仪表盘、JSON 报告导出、纯本地存储、MIT 开源许可

最后更新时间：2026 年 2 月 16 日
当前版本：1.2.3
状态：活跃维护中 & 社区共同维护

© 2026 UnisAI 社区