Troubleshooting zh CN

排障手册

English · 简体中文

症状 → 根因 → 一条命令解决。

CLI

报 "unsupported engine" 或 Node 版本错误

不支持 Node < 20。先查：

node --version

升级用 nvm、fnm、brew upgrade node 或 apt install nodejs。

端口 7680 被占用

被占时 Dashboard 会自动顺延到 7681、7682……，实际端口在启动日志里有打印。想固定某个端口：

PORT=7700 tokentracker serve

查是谁占着 7680：

lsof -i :7680

某个 provider 没被检测到

tokentracker status       # 各工具状态
tokentracker doctor       # 深度健康检查
tokentracker activate-if-needed  # 重新探测

如果明明装了但还是 skipped，把 tokentracker diagnostics 的输出贴到 新 Issue 里。

队列里有 pending 但一直没上传

常见于开了云同步但设备 token 过期、或者 backoff 定时器还没到。

• 强制同步：tokentracker sync
• 完全不用云排行榜：队列在本地堆着没危害，可以忽略
• 重置上传 backoff / 队列：tokentracker doctor 会根据当前状态建议对应命令

编辑翻译后报 "copy registry" 测试失败

校验器要求 dashboard/src/content/copy.csv 里每个 key 都在源码里被引用。跑：

npm run validate:copy

它会直接打出哪些 key 孤悬无人用、哪些被用了但还没加进 CSV。

完全卸载

tokentracker uninstall

清掉所有 AI 工具里的 hook，以及 ~/.tokentracker/。可以安全重复执行。

macOS App

"无法打开 TokenTrackerBar，因为它来自身份不明的开发者"

TokenTrackerBar 使用 ad-hoc 签名（没付费 Apple Developer ID，因此没做公证）。Gatekeeper 会拦首次启动。

1. 系统设置 → 隐私与安全性
2. 滑到 安全性 —— 会看到「TokenTrackerBar 已被阻止以保护 Mac」
3. 点 仍要打开
4. 在后续对话框里再点 打开

做一次就行。老版 macOS 上的替代方案：访达里右键 App → 打开 → 确认框里再点 打开。

"TokenTrackerBar 已损坏，无法打开"

Gatekeeper 对 com.apple.quarantine（macOS 给所有下载文件自动贴的属性）的反应 —— 不是真坏了。清一次即可：

xattr -cr /Applications/TokenTrackerBar.app

"TokenTrackerBar 想访问其他 App 的数据"

Cursor 和 Kiro 集成需要这个权限。它们把 auth token / 用量数据存在自己的 ~/Library/Application Support/ 目录下，macOS 用 App Management 权限保护。

• ✅ 用 Cursor / Kiro：点 允许
• ❌ 不用：点 不允许，这两个 provider 会被静默跳过，其它一切正常

ad-hoc 签名的版本每次升级签名身份会变，所以每次升级都会重新弹一次。

菜单栏 App 启动不起来 / 没状态图标

通常是嵌入式 Node 服务端口绑不上。看日志：

tail -f ~/Library/Logs/TokenTrackerBar/server.log

常见原因：

• 已经有一个 TokenTrackerBar 实例在跑 → 从菜单退出或者 pkill -f TokenTrackerBar
• 公司防火墙屏蔽了 loopback → 用 Terminal 带 PORT=7700 环境变量启动
• 嵌入式 Node 二进制被单独隔离 → xattr -cr /Applications/TokenTrackerBar.app/Contents/Resources/EmbeddedServer/

桌面小组件显示 "No data"

小组件读的是主 App 通过 App Group 写的快照。如果主 App 没启动或者还没首次同步：

1. 从菜单栏启动 TokenTrackerBar
2. 等大约 5 秒让首次同步跑完
3. 右键小组件 → 编辑小组件 → 强制刷新

如果主 App 明明有数据但小组件还是空，可能是 App Group 链接坏了 —— 重装 App（用 DMG 或 brew reinstall --cask）。

Dashboard / Web

我明明在用 AI 工具但 Dashboard 显示 0 tokens

大概率是 hook 没挂上。跑：

tokentracker status

如果所有工具都 configured 但数据还是 0：那是因为装 hook 之后这些工具还没被用过。随便用一下再回来看 —— hook 只在会话结束时触发，不会追溯历史。

切换语言后有的地方不刷新

在 0.5.84+ 已修复。看到过时文本的话先 Cmd+Shift+R 强刷一次。还在复现就开 issue，附上 URL 和切换的语言组合。

登录 / 排行榜卡住

云同步走 InsForge。检查：

• 有网吗？
• OAuth 回调完成了吗？浏览器应该会自动跳回来
• 实在不行就在 Dashboard 头部登出再登入

注意本地使用完全不依赖登录状态 —— 云端只用于排行榜和跨设备同步。

还是卡住？

• 把 tokentracker diagnostics 的输出贴到 新 Issue（输出是脱敏的：不包含 prompt 内容、不包含 token/密钥）
• 开放性问题到 Discussions 讨论