TokenTracker：本地优先的 AI 编程工具用量追踪器，零配置起步
项目速览：本地优先的 AI 代币使用和成本跟踪器，适用于 28 种编码工具，包括。 Claude Code、Codex、Cursor、Gemini 和 Qoder - 带有本机应用程序。从不阅读提示。
秒懂
- 它是什么？
- TokenTracker 是一个本地优先的 AI 编程工具 token 用量与成本追踪器，支持 34 款工具，宣称无需 API 密钥即可运行。它通过自动安装钩子捕获用量数据，并提供仪表盘、桌面组件和成就系统。本文基于仓库文档分析其机制、安装方式与适用边界。
- 适合谁用？
- TokenTracker 适合那些同时使用多款 AI 编程工具、希望集中查看 token 消耗与成本、且对数据隐私敏感的开发者。它不适合需要跨设备同步、或依赖云端分析的团队，因为所有数据默认留在本机。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库最近一次提交在 2 天前。
- 用什么语言写的？
- 主要是 JavaScript（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月15日）和我们的分析，不构成法律意见。
开源项目深度解析
解决什么问题：多工具 token 消耗的碎片化
现在一个开发者可能同时使用 Claude Code、Codex CLI、Cursor 和 Gemini CLI。每个工具都有自己的用量统计，但格式不同，位置分散。TokenTracker 的目标是把这些数据汇总到一个本地仪表盘，让你看到总消耗、按模型拆分成本，以及项目归属。它不读取提示词内容，只追踪 token 数量，这从隐私角度看是合理的取舍。适合的对象是那些已经习惯用多个 AI 工具、且不想为用量统计注册云账号的人。
核心机制：钩子与本地同步
TokenTracker 的工作原理依赖于自动安装的钩子。首次运行时，它会检测你已安装的受支持工具，并安装相应的钩子来记录 token 使用事件。这些事件数据被同步到本地，然后由内置服务器在 `http://localhost:7680` 提供仪表盘。文档强调没有网络调用，除了可选的排行榜功能。这意味着数据流是单向的：工具产生事件，钩子捕获，本地存储，仪表盘展示。这种设计避免了云端中转，但代价是你无法在多台机器之间共享数据。
安装与启动：一条命令与多种分发方式
最简单的启动方式是运行 `npx tokentracker-cli`，前提是 Node.js 20+。首次运行会自动安装钩子并打开仪表盘。如果你喜欢全局命令，可以 `npm i -g tokentracker-cli`，然后用 `tokentracker` 打开仪表盘，`tokentracker sync` 手动同步，`tokentracker status` 查看钩子状态，`tokentracker doctor` 做健康检查。macOS 用户可以用 Homebrew 安装：`brew install --cask xiufengsun/tokentracker/tokentracker`。Linux 用户下载 AppImage 后 `chmod +x` 即可运行，但需要安装 webkit2gtk-4.1、gtk3 和 libayatana-appindicator。这些依赖在 GNOME 下还需要额外扩展，文档明确指出了这个限制。
桌面端：菜单栏、托盘与组件
除了 CLI，TokenTracker 还提供原生桌面应用。macOS 是菜单栏应用，Windows 是系统托盘应用，Linux 是 AppImage 形式的托盘应用。桌面应用内置了服务器，并用原生 webview 加载仪表盘。它还提供四个桌面组件：用量、活动热力图、热门模型和用量限制，可以固定在桌面上。此外有一个桌面宠物，会根据你的编码活动做出反应，比如庆祝连续使用天数。这些功能更像是锦上添花，对于纯粹想追踪成本的用户来说可能并不必要，但它们确实让工具显得有特色。
局限性与失败模式
TokenTracker 的本地优先设计带来一个明显的局限：无法跨设备同步。如果你在工作和家用电脑上都使用 AI 工具，数据会各自独立，无法合并。另一个潜在问题是 Cursor 的 token 读取依赖系统 sqlite3 命令行，如果系统没有安装，会回退到 `node:sqlite`，但并非所有 Node 版本都支持。这意味着在某些环境下，Cursor 的用量可能无法被捕获。文档没有详细说明钩子失败时的行为，也没有提到数据损坏或恢复机制。如果你是重度 Cursor 用户且使用旧版 Node，需要先用 `tokentracker doctor` 验证钩子是否工作正常。
替代方案：各工具的官方统计与云端服务
如果你只使用单一工具，其自带的用量统计页面可能已经足够。Claude Code 有 `/usage` 命令，Codex CLI 也有自己的用量报告。这些官方统计通常更准确，且没有额外的安装依赖。如果你想跨工具聚合，可以考虑商业服务，比如那些需要 API 密钥的云端追踪器。它们的优势是数据自动同步到云端，可以在任何设备上查看，但代价是隐私和额外的配置。TokenTracker 的差异化在于零配置和本地存储，适合那些不想把 token 数据发送到第三方服务器的用户。
维护与升级成本
TokenTracker 采用 MIT 许可证，这意味着你可以自由使用、修改和分发。仓库的发布频率较高，最近的版本是 v0.94.0，距离前一个版本只有一天。Homebrew tap 会在新版本发布后一小时内自动更新，这减少了升级的摩擦。但频繁发布也意味着你需要定期运行 `brew upgrade --cask` 或重新下载 AppImage 来获得修复和新工具支持。由于项目依赖钩子机制，每次 AI 工具更新可能都需要 TokenTracker 适配，因此维护成本与上游工具的变更频率相关。如果某个工具改变了日志格式，TokenTracker 需要及时跟进，否则追踪会失效。
编辑结论
TokenTracker 适合那些同时使用多款 AI 编程工具、希望集中查看 token 消耗与成本、且对数据隐私敏感的开发者。它不适合需要跨设备同步、或依赖云端分析的团队，因为所有数据默认留在本机。首次部署前，请先运行 `tokentracker doctor` 检查钩子安装状态，并确认你使用的工具（如 Cursor）是否依赖系统 sqlite3 命令行，否则可能无法读取数据。若你只使用单一工具，其自带的使用统计页面可能已足够，无需额外安装。
社区笔记