AI 用量桌面小部件 Javis603/token-monitor

EN | 简 | 繁 | KO | JA | PT

Token Monitor

跨设备聚合每个 AI 编程工具的实时用量。

Token Monitor 是什么？

一款桌面应用，实时显示 Claude Code、Codex、Cursor、GitHub Copilot、Cherry Studio 等 48+ 种 AI 编程工具的 Token 用量与 AI 工具额度，具备实时多设备同步与历史使用趋势功能，并支持按工具、设备、模型、session 或项目分项显示。它出现在你目光所及之处：主窗口、MacBook 刘海、菜单栏或系统托盘、屏幕边缘、悬浮小窗，以及原生 macOS 小部件。

支持的工具

从你已在用的 AI 编程工具和提供方读取 Token 用量、AI 工具额度和 session 明细：

查看每个工具的支持项和数据路径 →

界面展示

桌面呈现

刘海面板：刘海旁显示运行中的 session；向下滑动即可查看今日用量、各账号额度、session 与用量分布

侧边栏：额度与用量停靠在屏幕边缘；悬停即可查看额度、最近的 session 与 token 菜单栏与系统托盘：选用内置版式或自己排：AI 工具图标、额度条、重置时间、成本或实时 tok/s

App 界面

多账号并列，Codex 可一键切换本机账号点任一工具展开输入／输出与缓存命中明细点进单个 session，逐条提问拆解 token 与用到的工具

更多视图：项目、模型与设备

每个项目的用量与成本，跨工具与设备汇总跨工具汇总每个模型的用量与成本每台设备的用量、成本与同步状态，可展开看单机明细

使用仪表板

跨所有设备汇总的一年活跃热力图与连续天数一年的每日趋势，按工具／模型堆叠，含 K 线

为什么用 Token Monitor？

大多数用量监控工具只在它运行的那台机器上有用。Token Monitor 是为多设备工作流而设计的：每台设备监视自己的本地日志、把汇总更新发送到你的 hub，每个连接中的小部件几乎都能实时看到 Token 变化。

快速安装

macOS 可通过官方 Homebrew Cask 安装：

brew install --cask token-monitor

也可从 GitHub Releases 下载 macOS、Windows 或 Linux 版 App。

启动 App 即可开始追踪这台设备的本地用量，无需配置 hub。完整说明请见安装。

功能特性

用量追踪

- 实时 Token 追踪：Claude Code、Codex、Cursor、GitHub Copilot、Antigravity、OpenCode 等 38+ 种 AI 工具，每轮对话后 UI 在数秒内刷新（完整列表见上方表格）
- 实时 Token 速率：可选显示的实时读数，以 tok/s 显示生成速度或以 tok/min 显示总消耗
- 单个 session 明细：点进某个 session，可看每条提问的 Token 消耗，并展开查看每次回复的 Token 拆分与用到的工具（打开时才实时读取本机 transcript 或数据库，绝不同步）
- 缓存命中统计：点击任何工具或模型，展开查看输入 Token（缓存命中与未命中）、输出 Token 的详细分类及命中率百分比
- 成本与币别：Token 数量旁附带成本；可用 USD、TWD、HKD 或 CNY 显示，汇率每日自动更新，也可在设置中手动覆写
- 自定义扫描路径：session 不在默认位置时，可为个别工具加入额外的文件夹
- WSL 用量（Windows）：运行中 WSL 发行版里的文件型用量会自动识别，约每 5 分钟并入总量；OpenCode、Hermes 等 SQLite 来源可能需要按照指南在 WSL 内运行 headless agent

额度、趋势与导出

- AI 工具额度检测：涵盖 Claude Code、Codex、Cursor、OpenRouter、第三方 API、GLM、Kimi 等 31+ 家提供方的 session、每日、每周、账单与 credits 窗口，支持多个 OpenRouter／第三方 profile，以及余额型账户（Claude credits、DeepSeek 预付余额与消费历史、第三方余额）
- 多账号与 Codex 账号切换：同一提供方可追踪多个账号、各自显示额度；已加入追踪的 Codex 账号还能一键切换为本机使用账号，免重新登录授权
- Codex 重置预测：可选开启的第三方重置预测，显示预计重置时间、重置类型（Regular 或 Banked）与上次重置时间
- 保留已删除会话用量：许多工具会定期清除旧 session（Claude Code 默认清 30 天前的 transcript），一删就再也算不到。开启后，Token Monitor 会在本地不设期限地归档已观测到的每日工具／模型用量，让热力图与趋势即使在来源文件被清掉后仍然完整（详见下方〈会话数据保留期〉）
- 使用趋势与仪表板：主页的活跃热力图与趋势图，加上独立的仪表板窗口，提供连续天数，以及跨所有设备、按工具／按模型堆叠的历史（柱状图与 K 线两种视图）
- 固定时间范围：除了原本的日、月、总计，还可以切换本周、近 7 天与近 30 天
- 可选的状态视图：追踪 Claude、OpenAI、Cursor 与 DeepSeek status 页，支持手动或定时重新检查
- 数据导出：把使用数据导出成与工具无关的 CSV + JSON，可手动或自动写入文件夹，接电子表格、Obsidian、Grafana 或自写脚本；详见 docs/export.md
- 订阅资料：手动记录每个 AI 账号的实际费用；方案标签的 tooltip 会显示费用、下次续费或到期日、已订阅时间，以及本月用量成本相对订阅费的回本倍数，定期方案与储值记录均适用

多设备与部署

- 多设备同步：Hub 同步通过 Server-Sent Events 在数秒内推送更新；iCloud Drive 同步具有最终一致性
- 本地优先：单设备使用完全无需服务器
- 自托管同步后端：小部件内 hub、Node CLI hub 或 Cloudflare Worker
- Headless agent：不装桌面 app 也能从服务器、SSH 主机与 WSL 上报用量，见 Headless agent
- iOS 小部件支持：通过 Worker hub 搭配 Widgy、Scriptable
- 隐私优先：提示词、回复、源代码和文件内容都留在你的设备上

界面与呈现

- 刘海面板（macOS）：运行中与等待中的 session 会显示在刘海旁（没有刘海的屏幕则以胶囊形式显示）；悬停或向下滑动即可打开分页，查看今日与最近七天的用量、并列的各账号额度、进行中与最近的 session，以及按工具／模型分类的明细
- 侧边栏（macOS 与 Windows）：在屏幕边缘显示额度与用量，可选择自动隐藏、始终显示或全屏自动隐藏模式。通过悬停卡片查看各账号额度、最近会话及 token 用量。可在设置中选择、排序及配置项目，也可从菜单栏或系统托盘开关
- 菜单栏（macOS）与系统托盘（Windows）弹出窗口：图标旁可显示成本、token 数，或最接近用完的提供方剩余额度百分比
- 菜单栏排版自定义：菜单栏与悬浮小窗的显示内容可以直接挑内置版式，也可以选“自定义…”自己排——加入 AI 工具图标、额度条、百分比、重置时间、成本、Token 速率或自定义文字等项目，拖动排序并实时预览，每个项目还能各自指定 AI 工具、账号、额度周期与字体
- 悬浮小窗模式：可将组件收成可拖动的紧凑小窗，支持点击或悬停预览展开，并可显示托盘同款内容
- 原生 macOS 小部件：在 macOS 14+ 上通过小号、中号和大号布局查看 Token 用量与成本、趋势、各 AI 工具的剩余额度与重置时间、活动热力图，以及按工具或模型分类的明细
- 分组视图：可按工具、设备、模型、session、项目或账户额度分组查看用量
- 外观控制：界面主题切换（含浅色模式）、各工具厂商色、玻璃透明度、模糊度、完全透明窗口、自定义字体
- 工具列表自定义：可隐藏、置顶和拖曳排序主列表中的工具，不影响实际追踪
- 可录制全局快捷键：可从任何地方快速显示或隐藏窗口
- Discord Rich Presence：将今日 Token、花费与主要工具广播到你的 Discord 个人资料（需手动开启）

插件（实验性）

用自定义内容扩展桌面页面、新增插件页面与设置，并将内容放到刘海、Edge Dock、菜单栏／系统托盘或悬浮小窗。作者可以设计自己的界面，并选用本机 Node 后端接入数据源及执行计算。

在“设置 → 插件”管理插件。参阅使用指南、社区插件、开发指南及插件 API。插件 API 属于实验性功能，日后可能变更，插件可能需要更新。只启用你信任的代码：插件并非沙盒隔离，Node 后端以你的操作系统用户权限运行。

支持工具详情

Token Monitor 对 Token 用量、账户额度和 session 明细分别支持：

| Logo | 工具 | 数据路径 | Token 用量 | AI 工具额度 | session 明细 |
| | Claude Code | ~/.claude/projects/、~/.claude/transcripts/ | ✅ | ✅ | ✅ |
| | Codex | ~/.codex/（sessions/、archived_sessions/） | ✅ | ✅ | ✅ |
| | OpenCode | ~/.local/share/opencode/（opencode.db、storage/message/） | ✅ | ✅ | ✅ |
| | Hermes Agent | ~/.hermes/state.db | ✅ | — | — |
| | OpenClaw | ~/.openclaw/agents/ | ✅ | — | — |
| | Cursor IDE / Cursor CLI / Grok Bot | ~/.config/tokscale/cursor-cache/（账号层级用量导出） | ✅ | ✅ | — |
| | Antigravity | ~/.gemini/（antigravity/、antigravity-ide/、antigravity-backup/、antigravity-cli/conversations/） | ✅ | ✅ | — |
| | Cline | VS Code globalStorage tasks（.../saoudrizwan.claude-dev/tasks/）、~/.cline/data/sessions/ | ✅ | ✅ | — |
| | Amp | ~/.local/share/amp/threads/ | ✅ | — | — |
| | Factory Droid | ~/.factory/sessions/ | ✅ | ✅ | — |
| | Kimi CLI / Kimi Code / Kimi Work | ~/.kimi/sessions/、~/.kimi-code/sessions/、<platform-app-data>/kimi-desktop/ | ✅ | ✅ | — |
| | Qwen CLI | ~/.qwen/projects/ | ✅ | — | — |
| | Grok Build | ~/.grok/（sessions/、logs/unified.jsonl） | ✅ | ✅ | — |
| | GitHub Copilot | VS Code workspaceStorage//chatSessions/、~/.copilot/（otel/、data.db、session-store.db） | ✅ | ✅ | — |
| | Pi | ~/.pi/agent/sessions/ | ✅ | — | ✅ |
| | Oh My Pi | ~/.omp/agent/sessions/ | ✅ | — | ✅ |
| | OmO Native | ~/.omo/agent/sessions/, ~/.senpi/agent/sessions/, ~/.omo/senpi-task/children/, <project>/.omo/senpi-task/children/ | ✅ | — | ✅ |
| | Goose | ~/.local/share/goose/sessions/sessions.db | ✅ | — | — |
| | Zed | ~/.local/share/zed/threads/threads.db | ✅ | ✅ | — |
| | Kilo | ~/.local/share/kilo/kilo.db；VS Code globalStorage tasks（.../kilocode.kilo-code/tasks/） | ✅ | — | — |
| | Command Code | ~/.commandcode/projects/*/.jsonl | ✅ | ✅ | — |
| | MiMo Code / MiMo Desktop | ~/.local/share/mimocode/mimocode.db | ✅ | ✅ | — |
| | Muse / Muse Code | ~/.local/share/muse/sessions/; muse.ai Cookie | ✅ | ✅ | — |
| | ZCode / GLM | ~/.zcode/（projects/、cli/db/db.sqlite） | ✅ | ✅ | — |
| | Kiro | ~/.kiro/sessions/cli/、Kiro IDE globalStorage 与 kiro-cli 数据库 | ✅ | ✅ | — |
| | CodeBuddy | ~/.codebuddy/projects/ 与 IDE / VS Code 扩展日志 | ✅ | — | ✅ |
| | WorkBuddy | ~/.workbuddy/projects/、~/.workbuddy/workbuddy.db | ✅ | ✅ | ✅ |
| | Proma | ~/.proma/ (agent-sessions/, sdk-config/sessions/, sdk-config/projects/), ~/.proma-dev/ | ✅ | — | — |
| | CatPaw | <platform-app-data>/ (catpaw-moon/, catpaw-overseas/, catpaw-memory-.db) | ✅ | — | — |
| | Qoder | ~/.qoder-cn/projects//.jsonl, legacy <platform-app-data>/QoderCN/SharedClientCache/cache/db/local.db（仅限中国版） | ✅ | ✅ | — |
| | Reasonix | ~/.reasonix/（stats/、sessions/、projects//sessions/） | ✅ | — | — |
| | DeepSeek / DeepSeek Harness | ~/.dsh/sessions/（session.jsonl、session.jsonl.zstd） | ✅ | ✅ | ✅ |
| | Cherry Studio | <platform-app-data>/CherryStudio/（Data/Agents/.claude/projects/ V2、.claude/projects/ legacy） | ✅ | — | — |
| | LM Studio | ~/.lmstudio/server-logs//.log | ✅ | — | — |
| | Unsloth Studio | ~/.unsloth/studio/studio.db | ✅ | — | — |
| | Devin CLI / Devin Desktop | ~/.local/share/devin/cli/sessions.db, <platform-app-data>/Devin/User/acp-events/ | ✅ | ✅ | — |
| | fx | ~/.fx/sessions/ | ✅ | — | — |
| | MiniMax / MiniMax Code | ~/.minimax/v2/sessions/ | ✅ | ✅ | — |
| | TypeSafe | TypeSafe Console Cookie（账单余额及根据 token 用量估算花费） | — | ✅ | — |
| | OpenRouter | OpenRouter API 密钥（查询用量／密钥上限；获授权访问 credits 时显示余额，官方文档指定 Management 密钥） | — | ✅ | — |
| | Volcengine | Ark API key 或火山引擎 AK/SK（通过火山引擎 API 查询火山方舟 Coding Plan / Agent Plan 额度） | — | ✅ | — |
| | Ollama | Ollama Cloud API key 或 Cookie（每月内含用量、旧方案 session／每周额度及 credits 余额） | — | ✅ | — |
| | Trae CN | Trae CN access token（通过 trae.cn 查询 Trae CN／SOLO credits） | — | ✅ | — |
| | Alibaba Cloud | 阿里云控制台 cookie（百炼／Model Studio Token Plan 额度，团队版与个人版） | — | ✅ | — |
| | StepFun | StepFun Oasis-Token（Coding Plan／Token Plan 额度） | — | ✅ | — |
| | Notion AI | Notion AI 滚动／每月额度，仅限 Business/Enterprise；手动 token_v2 Cookie + 明确的工作区 ID | — | ✅ | — |
| | Manus | Manus 积分（月度 + 每日／周期刷新额度 + 余额）；桌面会话（macOS／Windows）或手动网页会话（所有 OS） | — | ✅ | — |
| | 第三方 API | New API / Sub2API 兼容账号预设方案（包括兼容的 One API 分支）、New API 密钥预设方案与自定义余额端点 | — | ✅ | — |

注意事项、Custom 余额端点，以及用环境变量覆盖的数据路径

- 上表为默认路径。Token Monitor 与 Tokscale 遵循相同的环境变量覆盖：~/.local/share/ 下的路径跟随 $XDG_DATA_HOME，各工具另有 $CODEX_HOME、$SENPI_CODING_AGENT_DIR、$SENPI_CODING_AGENT_SESSION_DIR、$GROK_HOME、$HERMES_HOME、$GOOSE_PATH_ROOT、$KIMI_CODE_HOME、$UNSLOTH_STUDIO_HOME、$LM_STUDIO_HOME、$DSH_HOME、$REASONIX_STATE_HOME、$REASONIX_HOME 以及 $CLINE_ 系列。
- Muse Code 订阅额度通过 Muse Code 1.4.13+ 的 muse usage --json 和现有登录读取。未提供额度或使用 API 密钥计费时，无法显示额度百分比。详见 Muse 数据来源说明。
- Goose 的跨日用量仍计入会话创建日；暂不支持远程 goosed 与自定义扫描路径。详见 Goose 数据来源说明。
- CatPaw 默认关闭，可在 Settings → tools 中启用；读取 macOS 和 Windows 上国内版与外区版助手的数据库。路径与验证边界见 CatPaw 数据来源说明。
- OmO Native 同时统计 OmO Native 与独立 Senpi 的本机 session 记录。全新安装会跟踪它；已保存的工具选择在升级后不会自动加上，请在 Settings → tools 中启用 OmO Native。见 OmO Native 数据来源说明。 部分子任务记录只计入用量，暂不支持 Session Detail。
- LM Studio 追踪目前仅涵盖服务器日志中记录的 OpenAI 兼容 /v1/chat/completions 和 /v1/responses 请求。通过 LM Studio 内置 Chat 界面发起的对话，以及原生 /api/v1/chat 请求均不包括在内。
- Unsloth Studio 从 studio.db 追踪 Studio 对话与本地 API 的推理用量。本地推理的 API 费用为零；可识别的按量计费供应商使用 Tokscale 的价格估算。不包括训练 Token。详见 Unsloth 数据来源说明。
- Devin 从本地 sessions.db 追踪 Devin CLI 会话，并从 acp-events ACP 日志追踪 Devin Desktop 代理会话；同一 session 两边都有数据时以 CLI 数据库为准。Desktop 的覆盖范围取决于连接的 ACP 代理：只有会在本地写入 usage_update 事件的代理才会计入，而 Devin Desktop 默认的 devin-cloud 代理在服务端计量，因此默认的 Desktop 配置不会报告 Desktop token。session 标题与项目归属取自 CLI 数据库。详见 Devin 数据来源说明。
- Notion AI 使用内部 API，需要手动粘贴 token_v2 Cookie 和明确的 Business/Enterprise 工作区 ID。目前仅以测试数据验证，尚无真实响应样本，实际登录验证待批准。不会自动获取 Cookie，也不保证公开 API 兼容性。详见 Notion 数据来源说明。
- Manus 支持 macOS／Windows 桌面会话自动读取，所有 OS（含 Linux）也可手动输入网页会话。月度积分、刷新额度与余额使用相同的未公开内部接口，不保证兼容性。详见 Manus 数据来源说明。
- MiniMax Code 读取 CLI 写入的本地会话记录，位于 ~/.minimax 或 MINIMAX_DATA_DIR / MAVIS_DATA_DIR（也包括 ~/.mavis 与 ~/.minimax-<profile> / ~/.mavis-<profile>），并加上通过 tokscale headless mcode 捕获的运行；两边都有的同一轮只计一次。

- Command Code transcript 不包含实际 Token 数或每条消息的模型信息。Token 用量根据 transcript 文本估算；模型归属与推算成本可能反映当前配置的模型，而不是每次请求当时实际使用的模型。
- Cursor 缓存来自 Cursor 的账号层级用量导出，因此涵盖 Cursor IDE、Cursor CLI 与 Grok Bot 的用量。Token Monitor 会自动检测 Cursor 桌面版已登录的账号，也可在设置中手动新增。缓存过期时会自动重新同步，但刚完成的 session 可能需要几分钟才会出现在 Cursor 控制台，因此最新用量仍可能延迟显示。

- Custom 会从一个 GET 余额端点映射数值 JSON 字段；仅兼容 OpenAI 或 Anthropic API 并不足够。

Qoder CN（本地适配器）

Qoder CN 的 Token 用量来自应用本地数据，而非 API —— 在 Settings → tools 中启用（可选，默认关闭）。当前版本使用 Qoder 配置目录下的 projects JSONL 记录（通常为 ~/.qoder-cn/projects），旧版本使用 SQLite；Token Monitor 内置的 tokscale 会同时读取两者。JSONL 路径优先使用 TOKEN_MONITOR_QODER_CN_PROJECTS_PATH，其次为 QODERCN_CONFIG_DIR/projects，最后使用默认路径；旧数据库可用 TOKEN_MONITOR_QODER_CN_DB_PATH 覆盖。详见 Qoder 数据来源说明。

这是高级本地集成，但两种格式都无需额外运行时。无法读取的来源会保留上一次完整读取的数据。旧数据库的会话只记录项目名称而非路径，因此不会显示所属项目。只统计记录了真实 Token 字段的 JSONL 行；当前第一方套餐模型可能只有 credits 和上下文占用比例，缺少可靠的会话级 context window，因此不会猜测 Token。Credits 仍会显示在 AI Tool Limits，带真实 Token 的 BYOK／自定义模型会正常统计。

其他功能支持

| 功能 | 支持的工具／来源 | 补充说明 |
| 会话标题 | Claude Code, Codex, OpenCode, Cursor, Antigravity, Cline CLI, Factory Droid, Kimi CLI, Grok Build, Pi, Oh My Pi, OmO Native, MiMo, ZCode, CodeBuddy, WorkBuddy, Reasonix, DeepSeek Harness, Cherry Studio, Devin CLI, fx, MiniMax Code | — |
| 每次提示／回复的用量与工具调用 | Claude Code, Codex, OpenCode, Pi, Oh My Pi, OmO Native, CodeBuddy, WorkBuddy, Reasonix, DeepSeek Harness | 明细仅在本地读取，不会同步。 |
| 上下文用量／剩余空间 | Claude Code, Codex, DeepSeek Harness | Claude Code 的上下文上限根据模型估算。 |
| 缓存用量／会话缓存命中率 | 提供缓存字段的来源，例如 Claude Code, Codex, OpenCode, Cursor, Kimi, Pi, Oh My Pi, OmO Native, DeepSeek Harness | 有缓存用量数据时才显示命中率。 |
| 缓存剩余时间估算 | Claude Code | 根据记录中的缓存层级估算为 5 分钟或 1 小时。 |
| 输出速度／Token 消耗速率 | Claude Code, Codex, OpenCode, Antigravity, Kimi, GitHub Copilot, Pi, Oh My Pi, OmO Native, Kilo CLI, MiMo Code/MiMo Desktop, Muse Code, ZCode CLI, Kiro, DeepSeek Harness, Devin CLI | tok/s 为输出速度，tok/min 为总 Token 消耗速率；计时可能包含等待。 |
| 推理强度设置 | Claude Code, Codex | 仅显示会话中明确记录的设置值。 |
| 推理 Token 数 | Codex, OpenCode, Pi, Oh My Pi, OmO Native, CodeBuddy, WorkBuddy, Reasonix, DeepSeek Harness | — |
| 回合开始／完成识别 | Claude Code, Codex, OpenCode, Cursor, CodeBuddy, WorkBuddy, DeepSeek Harness | 依据工具记录的回合信号。其他工具或缺少有效信号时，最后活动后约 10 分钟内估算为运行中。 |
| 原生运行中／等待输入状态 | Claude Code, Codex | — |
| 父会话／子代理分组 | Codex, Antigravity, Oh My Pi, ZCode；具有可验证父会话链接的 T3 Code 会话 | Claude Code 的分组通过 T3 Code 提供。 |
| 同一对话的续接记录分组 | Codex；具有已验证线程链接的 T3 Code 会话 | — |
| 切换本地账号 | Codex | 可切换至已添加到 Token Monitor 的账号。 |
| 额度重置时间／倒计时 | 提供重置时间的来源，例如 Claude Code, Codex, OpenCode, Cursor, Antigravity | — |
| 可用额度重置券 | Claude Code, Codex | 显示剩余次数及到期时间，仅供查看。 |
| 额度重置预测 | Codex | 可选的 codex-resets.com 第三方预测。 |

安装

macOS 可通过官方 Homebrew Cask 安装：

brew install --cask token-monitor

也可从 GitHub Releases 下载。

- macOS（Apple Silicon） — .dmg，已签名并 notarize
- macOS（Intel） — x64 .dmg，已签名并 notarize
- Windows 10/11 — 安装版和便携版 .exe，均已签名
- Linux x64 — .AppImage

打包版会自动检查 GitHub Releases。有新版本时，界面会显示更新提示；受支持的平台也可在 设置 → 常规 中安装更新。

首次启动

本地模式是默认模式：启动 App 后会开始追踪这台设备。无需 hub、代理或配置。

多设备同步

挑一个供设备（与任何无头代理）使用的多设备同步后端。在每台设备上打开小部件，在 设置 → 多设备同步 选一个模式。小部件会自动上报本机用量；只在没有小部件的机器上跑 headless agent。iCloud Drive 仅供 macOS 小部件使用，不支持无头代理。

方案 A——直接在小部件内开 hub（最简单，无需命令行）

在一台长期开机的机器上打开小部件，进入 设置 → 多设备同步，选 在这台设备托管 Hub。小部件会生成随机 secret，并列出其他设备可以连入的局域网 URL（Tailscale 或 ZeroTier 地址也会显示在这里）。在其他每台设备上选 连接到 Hub，把 URL 与 secret 贴进去即可。

只要 Token Monitor 还在跑，hub 就会运行——退出 App（仅关闭窗口不算）会停掉 hub，所有连入的设备都会断开。

方案 B——自托管 Node hub（长期开机的无头机器）

在长期开机的机器上
cp .env.example .env
把 TOKEN_MONITOR_SECRET 设为你私有的值，然后:
npm run hub

方案 C——Cloudflare Worker hub（跨网络，包含 iPhone）

部署到 Cloudflare

一键部署——Cloudflare 会在过程中提示你输入 TOKEN_MONITOR_SECRET。或手动部署:

cd worker
npm install
npx wrangler login
npx wrangler secret put TOKEN_MONITOR_SECRET
npx wrangler deploy

把部署 URL 贴到每台设备的小部件 设置 → 多设备同步。iOS 小部件配方与端点参考见 worker/README.md，hub HTTP API 见 docs/API.md。

方案 D——iCloud Drive（macOS，无需 Hub Server）

在每台登录同一 Apple ID 的 Mac 上，进入 设置 → 多设备同步并选择 iCloud Drive。这是可选的 macOS 专属模式：Token Monitor 会在 iCloud Drive 的 Token Monitor/sync-v1/ 下为每台设备和每个写入者保存原子快照，再由每台 Mac 聚合有效文件。不使用 Token Monitor 服务器、CloudKit 或凭据；提供方 API key、Cookie 和 token 保留在本机。iCloud Drive 采用最终一致性，其他 Mac 的更新可能需要一点时间才会出现，损坏或暂时缺失的文件也不会清空最后一次有效的聚合结果。

Headless agent

在服务器、SSH 主机或 WSL 内——任何使用 AI 工具但没有桌面小部件的地方——运行 headless agent。它会采集该机器的用量并上传到你的 hub（方案 A、B 或 C）。需要 Node.js 22.15+ 与 git。

git clone https://github.com/Javis603/token-monitor.git
cd token-monitor
npm ci
cp .env.example .env # 设置 TOKEN_MONITOR_HUB_URL、TOKEN_MONITOR_SECRET 与不重复的 TOKEN_MONITOR_DEVICE_ID
npm run agent # 持续运行

以服务方式运行、更新、卸载与排查，请见 docs/headless-agent.zh-CN.md。WSL 内的 SQLite 工具请按照 WSL SQLite 指南。

App 数据

App 状态保存在系统的用户数据目录——卸载时一并删除该目录即可完整移除。

| 平台 | 路径 |
| macOS | ~/Library/Application Support/Token Monitor/ |
| Windows | %APPDATA%/Token Monitor/ |
| Linux | ~/.config/Token Monitor/ |

从源码构建

如需自己从源码打包安装包，请在对应的操作系统上使用 Node.js 22.15+（electron-builder 无法在 Windows 上交叉构建 macOS 的 .dmg，反之亦然）。

npm install
npm run dist:mac # macOS arm64 .dmg → dist/
npm run dist:mac:x64 # macOS Intel x64 .dmg → dist/
npm run dist:win # Windows x64 安装包 .exe → dist/
npm run dist:linux # Linux x64 AppImage → dist/
npm run pack # 未打包的 app 目录（无安装包），方便本机快速测试

产物会放在 dist/。Windows 和 Linux 请在对应系统上使用上面的 dist: 脚本。如果要打包 macOS 发布版，需要本机有 Developer ID Application 签名身份；本地开发或未列出的平台请用 npm start 运行。

运行和打包脚本会在每个有 vendored 构建的目标上明确确保使用 pinned tokscale binary。其他源码平台会保留 npm binary，并过滤它不支持的 clients；npm install、lint 和测试不会下载它。

工作原理

模式 A——本地（默认，免配置）
小部件 (Electron) ──▶ tokscale ──▶ ~/.claude、~/.codex、$HERMES_HOME

模式 B——同步（可选，多设备）设备 A 小部件 ──▶ 设备 B 小部件 ──▶ hub ──▶ 任一设备上的小部件设备 C agent ──▶

小部件会根据 设置 → 多设备同步 决定走本地还是同步模式。hub 本身可以是单独的 npm run hub 进程、Cloudflare Worker，或直接跑在某一个小部件里（Host 模式）。在 Hub Client 和 Host 模式下，hub 通过 Server-Sent Events 把聚合后的统计推送给每个连接中的小部件，所以一台设备上的更新通常会在数秒内出现在其他设备上。iCloud Drive 模式直接同步文件，具有最终一致性，更新可能需要更长时间才会出现。

会话数据保留期

开启保留已删除会话用量（设置 → 采集）后，Token Monitor 会在本地不设期限地归档已观测到的每日工具／模型用量——即使来源工具日后清掉 session，热力图与趋势也不受影响。

进阶：延长来源工具本身的保留期

热力图与同步数据采用 370 天的滚动窗口（更早的观测数据仍保留在本地供日后查看）。Claude Code 默认只保留 30 天的 transcript（cleanupPeriodDays）；若想在归档启用前就保住完整的滚动年份，请在时限过去之前于 ~/.claude/settings.json 调高：

{
"cleanupPeriodDays": 370
}

设更大能留更多，代价是 transcript 会按你设定的期限一直留在磁盘上。其他工具的默认值与配置文件路径，请见 tokscale 的 Session Data Retention 表。

这份归档只涵盖 Token Monitor 已观测过的日期；在它开始追踪之前就被删除的数据无法找回。

设置

设置分两处，日常使用只需要前者：

- 小部件（GUI）——点右下角的 ⚙ 打开，分区依次为：常规（语言、登录启动、更新）、主画面（首页模块与显示币别）、窗口（窗口行为、菜单栏与悬浮小窗排版、托盘模式、快捷键）、外观（主题与厂商色）、采集（追踪的工具、采集频率、保留已删除会话用量、数据导出）、AI 工具额度（提供方选择、额度与凭据）、订阅资料（每个账号实际付多少）、多设备同步。标题栏的 ⇧ 按钮可循环切换窗口行为。
- 无头代理与 hub——没有 UI，用项目根目录的 .env 配置（从 .env.example 复制）；优先级为 CLI 参数 → 环境变量 → 内置默认。详见 docs/configuration.md。

每一项设置与所有环境变量的完整说明，请见设置参考文档。

隐私

Token Monitor 在本地处理使用日志，不会向项目维护者发送分析或遥测数据。网络访问仅用于文档所述或由用户启用的功能；更新、提供方集成、Discord Rich Presence 与可选多设备同步所使用的数据，请参阅隐私政策。

Star 历史

参与贡献

欢迎提交 Issue 和 PR。项目规范、架构说明和命令参考都在 AGENTS.md 中——它是为编码代理编写的，但同样可以作为贡献者指南。

致谢

- tokscale 提供日志解析与 Token 计算。
- CodexBar 提供 AI 工具额度的研究参考。
- 代码签名政策： 免费代码签名由 SignPath.io 提供，证书由 SignPath Foundation 提供。

许可证

MIT © @Javis