Installation zh CN

安装指南

English · 简体中文

TokenTracker 提供三种安装方式，底层都是同一个 tokentracker-cli npm 包、同一个 ~/.tokentracker/ 数据目录 —— 可以混用。

一句话版

我想	用这个
试一下，不想留东西	npx tokentracker-cli
跨项目用命令行	npm i -g tokentracker-cli
macOS 菜单栏 App + 桌面小组件	brew install --cask mm7894215/tokentracker/tokentracker
用 Homebrew 代替 npm 安装 CLI	brew install mm7894215/tokentracker/tokentracker

环境要求

• Node.js 20+ —— CLI 用了 Node 20 才有的特性（fetch、可读流迭代、test runner）
• macOS / Linux / Windows 都能跑 CLI —— Cursor 的 SQLite 读取和菜单栏 App 仅限 macOS，其他集成全平台可用
• 只有首次 npm install 和可选的排行榜同步需要联网，token 追踪本身完全离线

查 Node 版本：

node --version

低于 20 就升级，可选 nvm、fnm、或系统包管理器（brew upgrade node、apt install nodejs 等）。

各安装路径细节

1. npx（零安装）

npx tokentracker-cli

下载到 npm 缓存跑一次，不留全局命令。适合试玩，下次 npx 会复用缓存。

2. 全局 npm

npm i -g tokentracker-cli

tokentracker          # 打开 Dashboard
tokentracker sync     # 手动同步
tokentracker status   # 集成状态
tokentracker doctor   # 健康检查
tokentracker uninstall

还有别名：tracker、tokentracker-cli、tokentracker-tracker。

3. Homebrew（macOS）

homebrew-tokentracker tap 里同时提供 Cask（菜单栏 App）和 Formula（CLI）。不用先 brew tap，brew install mm7894215/tokentracker/tokentracker 这一步会自动处理。

# 菜单栏 App + CLI（macOS 推荐组合）
brew install --cask mm7894215/tokentracker/tokentracker
brew install mm7894215/tokentracker/tokentracker

# 升级
brew upgrade --cask mm7894215/tokentracker/tokentracker
brew upgrade mm7894215/tokentracker/tokentracker

tap repo 上跑 cron，每个 Release 发布后一小时内自动更新 —— 用户这边 brew upgrade 就行，不用额外操作。

4. macOS DMG（独立安装包）

不想用 Homebrew 的话，到 最新 Release 下载 TokenTrackerBar.dmg，把 TokenTrackerBar.app 拖进「应用程序」。

首次启动可能被 Gatekeeper 拦 —— 见 排障 → macOS App。

Linux / WSL 注意事项

• 所有基于 hook 或 SQLite 文件路径 的集成在 Linux 和 WSL 上完全等价
• macOS 菜单栏 App 只有苹果平台有
• Cursor 集成读取 Cursor 的本地 SQLite —— Linux 上在 ~/.config/Cursor/，macOS 上在 ~/Library/Application Support/Cursor/，TokenTracker 两个位置都会探测
• WSL1 用户：跨 Windows ↔ WSL 边界的文件监听可能不稳，建议 CLI 和 AI 工具都跑在 WSL 里

会往磁盘写什么

位置	内容
~/.tokentracker/	队列、配置、缓存的用量快照
~/.tokentracker/app/	（全局安装时存放嵌入式辅助工具的地方，如 OpenClaw 插件 —— 由 init 初始化）
各 AI 工具自己的配置	例如 ~/.claude/settings.json、~/.codex/config.toml
~/Library/Application Support/TokenTrackerBar/（仅 macOS App）	App 偏好、通过 App Group 共享的小组件快照

tokentracker uninstall 会把上面全部清掉，并解除所有 AI 工具的 hook。

下一步

• tokentracker status 看看自动检测到了什么 → 已支持的 AI 工具 查每个工具的细节
• 遇到怪事 → 排障手册