给你的AI编程工具装一个本地账本查清每月花费

如果你最近同时在用 Claude Code、Cursor、Codex、Gemini CLI 这类 AI 编程工具，大概率会遇到一个很现实的问题：每天都在跑 Agent，但很难说清楚到底是谁烧掉了最多 token，哪类项目最贵，换模型有没有必要。

TokenTracker 做的事很直白：在你的电脑本机，把多款 AI 编程工具产生的 token 用量汇总成一个本地看板。你可以看到总 token、模型拆分、项目拆分、成本估算、活跃热力图、使用限额，还能用桌面 App 或小组件盯着看。

读完这篇，你应该能完成三件事：

• 把 TokenTracker 装起来，或先用 dry-run 预览它会改哪些配置。
• 让它扫描 Claude Code、Codex、Cursor 等工具的本地记录。
• 用看板判断：哪款工具、哪个模型、哪个项目最花钱，是否需要换模型或设限。

我查了仓库的 README、中文 README、PRODUCT、DESIGN、SECURITY、docs/openclaw-integration.md、docs/quality-per-dollar.md、官网 tokentracker.cc、GitHub Releases 页面和最近提交。没有找到论文、arXiv 或单独的技术报告，所以这篇不做论文解读，只做仓库深读加上实用教程。

先说结论

AI智能体学习网站：ai-agent-phd.com

TokenTracker 更像“本机 AI 用量账本”，不是另一个聊天工具。

它适合已经频繁使用 AI 编程/Agent 工具的人，尤其是同时用 Claude Code、Cursor、Codex、Gemini CLI、OpenCode、Copilot、Kimi Code 等多款工具的人。它不适合只偶尔用网页版 ChatGPT、Claude，或者完全不希望任何工具读取本地 AI 工具日志的人。

我建议的用法是：先 dry-run，看它准备接入哪些工具；确认没问题后再正式安装；用一周数据观察模型和项目成本，再决定是否换模型、减少大上下文任务，或给自己设一个月度上限。

它到底能统计什么

AI智能体学习网站：ai-agent-phd.com

按 README 和官网，TokenTracker 当前支持 27 款 AI 编程工具，包括 Claude Code、Codex CLI、Cursor、Gemini CLI、Antigravity、Kiro、OpenCode、OpenClaw、Every Code、Hermes Agent、GitHub Copilot、Kimi Code、CodeBuddy、WorkBuddy、Grok Build、Roo Code、Zed Agent、Goose、Mimo Code、ZCode、AnythingLLM Desktop 等。

它统计的不是“你写了什么 prompt”，而是这些字段：

• 输入 token、输出 token、缓存读取 token、缓存写入 token。
• 使用的工具、模型、时间窗口。
• 项目或工作区归因。
• 估算成本。
• Claude、Codex、Cursor、Gemini、Kiro、Copilot、Antigravity 等工具的限额窗口。

成本引擎主要依赖 LiteLLM 的模型价格表，并带有离线价格快照。我在仓库里实际数了一下：src/lib/pricing/seed-snapshot.json 里有 2284 个模型价格条目，curated-overrides.json 里还有 57 个项目自维护的补充价格。README 也说明，找不到公开价格的模型会统计 token，但成本显示为 0 美元。

这点很重要：它更适合看趋势和相对成本，不应该当成最终付款账单。

我实际跑过的命令

AI智能体学习网站：ai-agent-phd.com

我没有在当前机器上执行正式 npx tokentracker-cli 安装，因为首次正式运行会写入 hook 或配置项。为了不把测试环境改乱，我只跑了非侵入式命令、状态查看和 dry-run。

实测时间：2026-07-16。

node--version

输出：

v24.12.0

查 npm 当前版本：

npmviewtokentracker-cliversion

输出：

0.80.1

直接跑 CLI 版本：

npx--yestokentracker-cli--version

输出：

v0.80.1

查看帮助：

npx--yestokentracker-cli--help

帮助里能看到这些常用命令：

npx tokentracker
npx tokentracker serve
npx tokentracker init --dry-run
npx tokentracker sync
npx tokentracker status
npx tokentracker status --light
npx tokentracker doctor
npx tokentracker uninstall --purge

我还跑了状态表：

npx--yestokentracker-clistatus--light

在一个没有正式初始化数据的环境里，输出会像这样：

Version: 0.80.1
Device token: unset
Queue pending (bytes): 0
Hook · codex_notify: unset
Provider · hermes: not installed
Passive mode active: no

dry-run 的关键输出是：

Dry run complete. Preview only; no changes were applied.
Tracks: Claude Code, Codex CLI, Cursor, Gemini CLI, Antigravity +22 more

这说明你可以先预演，不必一上来就让它改 Claude Code 或 Codex 的配置。

操作步骤

1. 先确认 Node 版本

TokenTracker CLI 要求 Node.js 20+。

node--version

如果低于 20，先升级 Node。普通用户不想折腾的话，也可以直接下载桌面 App。

2. 先做一次预览

推荐先跑 dry-run：

npx--yestokentracker-cliinit--dry-run--no-open

你要看两件事：

• 哪些工具会显示 Will update config 或 Will install plugin。
• 哪些工具显示 Skipped，以及跳过原因是不是你能接受的，比如没有安装对应工具、配置文件不存在。

这一步不会应用改动。

3. 正式安装并打开本地看板

确认没问题后运行：

npxtokentracker-cli

首次运行会自动接入能识别到的 AI 工具，同步数据，并打开本地看板。默认地址是：

http://localhost:7680

如果你习惯全局命令，可以这样装：

npmi-gtokentracker-cli

之后就能直接用：

tokentracker
tokentrackersync
tokentrackerstatus--light
tokentrackerdoctor

macOS 用户也可以装菜单栏 App：

brewinstall--caskmm7894215/tokentracker/tokentracker

Windows 用户可以从 GitHub Releases 下载 TokenTracker-Setup.exe。README 写明 Windows 版是系统托盘 App，使用 WebView2，不需要管理员权限。

4. 手动同步一次

如果你刚跑完一批 Claude Code 或 Codex 任务，可以手动同步：

tokentrackersync

然后查看接入状态：

tokentrackerstatus--light

如果某个工具没有被识别，再跑：

tokentrackerdoctor

status 和 doctor 是排查常见问题最有用的两个命令。

5. Windows + WSL 用户要注意

如果你在 Windows 本机和 WSL 里都用 Codex、Claude Code 或 Gemini CLI，README 提供了 WSL 扫描模式。

PowerShell 临时启用双边扫描：

$env:TOKENTRACKER_WSL_MODE="both"
tokentracker sync

如果端口 7680 被占用，可以换端口：

$env:PORT="7700"
tokentracker serve

macOS / Linux 对应写法：

PORT=7700tokentrackerserve

看板应该怎么看

不要只盯总 token。总 token 变大不一定代表钱变多，因为缓存 token、输出 token、推理 token 的价格可能不同。

我建议按这个顺序看：

第一，看模型拆分。
如果某个高价模型占了大头，先确认这些任务是否真的需要它。很多“整理文件、改小 bug、写普通脚本”的任务，未必需要最贵模型。

第二，看项目拆分。
TokenTracker 会按项目或工作区归因。你可以很快发现：是某个长期重构项目在烧钱，还是某次大规模代码扫描特别贵。

第三，看时间趋势。
如果某天 token 突然暴涨，回想那天是不是跑了大上下文任务、循环修复任务，或让 Agent 反复读整个仓库。

第四，看缓存相关 token。
如果缓存读很多，说明上下文复用多；如果缓存写和输入都很高，可能是任务上下文太大。

第五，看限额窗口。
它能显示 Claude、Codex、Cursor、Gemini 等工具的限额或重置倒计时。这个功能比“月底看账单”更实用，因为你能提前发现自己快撞限额。

一句话：TokenTracker 不能替你判断任务价值，但能告诉你“钱和 token 花在哪儿”。

隐私边界

TokenTracker 的核心卖点是 local-first。

从 SECURITY 和 README 看，它的本地数据主要写在：

~/.tokentracker/tracker/queue.jsonl

本地服务绑定在：

127.0.0.1

官方隐私承诺是：只记录 token 数量、模型、时间戳、项目归因，不读取 prompt、回复和代码文件内容。OpenClaw 文档也说明，插件只传 session 标识、模型名、时间戳和 token 计数。

但这里要说清楚：它不是“完全零联网”。

README 的隐私段落写明，默认有两类匿名统计：

• 每天最多一次的匿名 heartbeat。
• Dashboard 的匿名页面/功能事件，PostHog 关闭 autocapture 和 session recording，并尊重 Do Not Track。

文档说这些统计不包含 token 数量、模型名、prompt 或路径。如果你不想要任何遥测，可以关闭。

PowerShell 临时关闭：

$env:TOKENTRACKER_NO_TELEMETRY="1"
npx tokentracker-cli

Windows 用户级持久关闭：

[Environment]::SetEnvironmentVariable("TOKENTRACKER_NO_TELEMETRY","1","User")

macOS / Linux：

TOKENTRACKER_NO_TELEMETRY=1npxtokentracker-cli

也可以使用：

DO_NOT_TRACK=1npxtokentracker-cli

排行榜和跨设备云同步是可选功能。只想本机记账，就不要开启登录和公开 profile。

限制与不足

第一，成本是估算，不是账单。
它用公开模型价格、LiteLLM 价格表和项目补充价格计算。如果模型没有公开价格，成本会显示 0 美元。真实扣费还可能受套餐、折扣、赠送额度影响。

第二，它不理解任务质量。
看板能告诉你某个模型烧了多少 token，但不能自动判断这些 token 是否产出了好结果。仓库有一个可选的 outcomes.jsonl 设计，用来做 Quality per dollar，但默认关闭，需要你自己记录“任务是否被接受”。

第三，首次正式安装会改配置。
Claude Code、Codex、Gemini 等工具靠 hook 或 notify 接入；OpenCode、OpenClaw 可能会装插件；Cursor、Kiro、Copilot 等更多是被动读取本地 SQLite、JSONL 或日志。正式安装前先 dry-run，是最稳的。

第四，部分工具能不能读到，取决于本机环境。
如果 CLI 不在 PATH、配置文件不存在、权限不足，status 会显示 skipped。macOS 桌面版读取 Cursor / Kiro 时，可能会弹出访问其他 App 数据的权限请求。

第五，Windows 和 WSL 容易遇到端口或双安装问题。
README 特别提到 Windows 的 Delivery Optimization 服务可能占用 7680，WSL 下可能默认用 7681。遇到打不开看板，先看命令行实际打印的端口。

第六，最近版本更新很快。
GitHub Releases 页面当前可见 latest 是 v0.80.0，npm 和仓库 tag 已到 v0.80.1。最近提交集中在 Codex 统计修复、fork replay 重放导致的历史膨胀修复、Codex 同步热路径优化。这说明项目在快速迭代，也意味着你最好保持近期版本。

适合谁和不适合谁

适合：

• 每天重度使用 Claude Code、Cursor、Codex、Gemini CLI 等 AI 编程工具的人。
• 同时使用多款 Agent，想比较哪款最贵的人。
• 想按项目、模型、日期复盘 AI 成本的人。
• 小团队、独立开发者、技术负责人，需要粗略估算 AI 编程成本的人。
• Windows + WSL 或多设备用户，想把本机和 WSL 里的用量看清楚的人。

不适合：

• 只用 ChatGPT 网页版、Claude 网页版，不用本地 AI 编程工具的人。
• 完全不能接受工具读取本地 AI 日志或 SQLite 指标的人。
• 需要财务级精确账单、发票、团队报销凭证的人。
• 不想安装 Node，也不想下载桌面 App 的人。
• 希望工具自动判断“这次任务值不值”的人。

最后建议

我的建议很简单：把它当成本地账本，不要当最终账单。

先跑：

npx--yestokentracker-cliinit--dry-run--no-open

确认它会接入哪些工具。然后正式安装：

npxtokentracker-cli

用一周后重点看三张表：模型成本、项目成本、时间趋势。
如果某个高价模型长期占大头，就换便宜模型试一周；如果某个项目反复烧 token，就减少全仓扫描、拆小任务；如果限额总是被打满，就设使用边界。

TokenTracker 的价值不在于“让 AI 更聪明”，而在于让你第一次看清：你的 AI 工具到底把钱花在哪里。