令牌仪表盘 JingbiaoMei/Tokdash

本地 token 与成本仪表盘，面向 AI 编程工具

不想安装？直接试用 → tokdash.github.io/demo

[!NOTE]
多台机器，一块面板。 在设置里添加跑在 WSL、Mac 或任意其他机器上的 Tokdash 实例：所有视图都会合并你选中的实例，Servers 标签页并排对比各台机器，Quota 标签页按机器分组，保留每个服务商的窗口条和重置倒计时。远程访问 → · 配额追踪 →

同一作者的另一款作品：Cosyncing。 同步并控制你的智能体——从命令行到图形界面，从桌面到手机。Cosyncing 让你自己的网络内，编码智能体始终保持同步。

目录

- 快速开始
- 一个包，四种视图
- WebUI
- 终端面板（TUI）
- 配套状态栏应用
- 状态栏
- 安装与运行
- 功能
- 配额追踪（可选）
- 成本精度说明
- 历史保留
- 路线图
- 贡献 / 安全
- 文档
- 许可证

快速开始

pipx install tokdash
tokdash setup

就这样。tokdash setup 会检测运行时，需要时安装一个受管运行时，注册本地服务，然后打印面板地址—— http://127.0.0.1:55423。完整选项、首次运行说明和更新方法见安装与运行；想先随便看看？在线演示跑的就是真实界面。

一个包，四种视图

一个本地包，一份本地数据索引，四种读法。每个界面都在你自己的机器上解析同一批会话日志，所以浏览器仪表盘、终端、菜单栏和智能体的状态栏看到的数据始终一致。

| 视图 | 是什么 | 什么时候用 |
| WebUI | 完整仪表盘：Overview、Sessions、Stats、Report、Quota、Servers | 想看全貌、图表和下钻明细 |
| TUI | tokdash tui —— 终端里七个面板：Overview、Sessions、Stats、Report、Speed、Quota、Pricing | 你常驻终端，不想开浏览器就想看数字 |
| Companion | 原生菜单栏（macOS）/ 通知区域（Windows）应用 | 想全天看到今天的花费和配额，仪表盘关着 |
| Statusline | 智能体状态栏里的实时 token/费用项 | 想让你打字的地方正好有个费用计数器 |

WebUI

仪表盘是本地 FastAPI 应用提供的单页：精确的输入 / 缓存 / 输出 token 明细，按工具和按模型的表格，贡献热力图，周/月/年 Report，按服务商的 Quota 窗口和重置倒计时，还有一个 Servers 标签页，用来合并和对比多台机器。点任意截图打开在线演示。

Overview

Usage Report

Quota tracking

多台服务器，一个总量

浅色与深色跟随你的系统外观。应用内置 17 套风格主题、浅色/深色模式、PWA 安装，以及六种界面语言（English / 中文 / 日本語 / 한국어 / Español / Português）。

终端仪表盘（TUI）

更想待在终端里？tokdash tui 打开 七个面板—— Overview、Sessions、Stats、Report、Speed、Quota 和 Pricing——不用浏览器，读取同一份本地索引（旁边跑着 tokdash serve 时，也读取共享的磁盘数据库）。F1–F7 在面板间跳转，v 列出全部面板。

TUI — Overview

TUI — Quota

tokdash tui

键盘操作

| 按键 | 操作 |
| q | 退出 |
| r | 重新加载当前面板 |
| F1–F7 | Overview / Sessions / Stats / Report / Speed / Quota / Pricing（1 / 2 / 3 仍可跳到 Overview / Report / Quota） |
| v | 从列表里选一个视图 |
| t d w m y a | 设置共享时间范围：今天、昨天、本周、本月、今年、全部时间 |
| p | 更多范围（范围条上的 More）；在 Stats 里是上一年 |
| P | Stats：下一年，回到最近 365 天 |
| c | 输入精确的自定义日期范围 |
| [ / ] | 把范围整体前移 / 后移一个周期——不会进入未来 |
| 0 | 回到今天 |
| / | 搜索当前聚焦的表格 |
| s | 切换当前聚焦表格的排序 |
| enter / esc | 打开选中行 / 关闭 |
| h | 选择数据源（Sessions 和 Speed） |
| H | 在 Speed 的数据源里逐个切换 |
| k | 选择 Speed 的序列 |
| x | 切换计时集合（Speed） |
| b | 切换 Speed 的时间桶 |
| u | 轮询配额（仅 Quota 面板） |
| ? | 帮助浮层，列出全部按键 |

一次性报告命令行

需要能管道输出或写脚本的一次性报告：

tokdash report --period week

周期是标志，不是位置参数。可选值：today（ default）、week、month、year、all、天数，或 Nd/Nw/Nm/Ny 简写；week、month、year 与 web Report 标签页展示的日历对齐窗口相同。tokdash report 还接受 --json、--pretty 和 --output <file>，约定与 tokdash export 一致。

配套状态栏应用

可选的 macOS 原生菜单栏应用和 Windows 通知区域应用：无需打开仪表盘，即可紧凑、只读地查看 Tokdash 服务。

macOS menu bar
Windows notification area

Windows — Microsoft Store（推荐，由 Microsoft 签名，需要 Windows 11）：

直接下载 — 最新配套版本：通用 DMG（arm64 + x86_64，macOS 14+）和自包含便携 ZIP（x64，Windows 11；Windows on Arm 通过 x64 模拟运行）。

展示内容与设置方式

- 今日费用、token、消息数和本月累计用量
- 多个 Tokdash 端点的合计总量和按服务器分组配额
- Codex、Claude、Kimi、MiniMax、Antigravity、Grok 和 Z.ai 的配额窗口
- 相对重置时间和可选的配额不足通知
- 系统语言检测，另支持英语、简体中文、日语、韩语、西班牙语和葡萄牙语
- 无遥测、不发现凭据、不扫描端口、不直接解析日志

设置：运行 Tokdash 1.5.2 或更新版本（安装与运行），安装配套应用，默认连接 http://127.0.0.1:55423 —— 其设置让你添加、测试、命名或删除显式端点，包括私有 Tailscale Serve URL。配套程序只联系你配置的端点；低配额通知和登录时启动均为可选项。

[!WARNING]
GitHub Releases 的二进制文件未签名。macOS Gatekeeper 和 Windows SmartScreen 会显示未知发布者警告。只从本仓库下载，核对随附的 SHA256SUMS，确认信任该发布版本后再继续。Microsoft Store 版本由 Microsoft 签名，不受影响；macOS 签名和公证计划在后续版本提供。

校验和、更新与卸载说明见配套程序发布指南。

状态栏

本地 API 可以为编码智能体中的状态栏项提供数据，显示实时 token/费用统计：

现成模板（bash 和 PowerShell）、安装/配置以及端点参考见 docs/guides/statusline/。

安装与运行

平台支持

- Linux（含 WSL2）： 支持
- macOS： 支持
- Windows（原生）： 实验性

前置条件： Python 3.10+，以及一个或多个受支持的客户端。

安装

推荐使用隔离安装：

pipx install tokdash

如果你不用 pipx：

python3 -m pip install --user tokdash

首次运行

运行引导向导：

tokdash setup

平台支持时，向导会配置一个可撤销的用户级后台服务，然后打印仪表盘 URL（默认：http://127.0.0.1:55423）。如果没有可用的服务管理器，它会记录安装状态并打印前台运行指引。向导默认优先使用 localhost，本地服务不需要 sudo，并且保留你的使用历史，除非你之后用 --purge 卸载。

如果要从智能体、脚本或捆绑包中非交互式安装，运行 tokdash setup --auto --json；要预览安装会改动什么，运行 tokdash setup --dry-run。要在所有网络接口上显式暴露仪表盘并禁用写入，运行 tokdash setup --bind 0.0.0.0；请先阅读远程访问指南。

然后检查安装：

tokdash doctor

doctor 检查运行时、后台服务、配置的端口、数据路径和更新检查状态。自动化场景请使用 tokdash doctor --json。

更新或卸载

tokdash update # upgrade the managed runtime and restart the service when possible
tokdash uninstall # reverse exactly what setup created; keeps usage history by default

update 只驱动 Tokdash 能安全管理的安装方式。如果你的运行时是通过如果包管理器不归 Tokdash 管，它会打印出准确的手动操作指引，而不会改动那个环境。

已有安装：从 v1.0 之前迁移

如果你在引导流程之前就装了 Tokdash，先升级：

pipx upgrade tokdash
or: python3 -m pip install --user -U tokdash

然后在你希望 Tokdash 管理后台服务时，运行 tokdash doctor 和 tokdash setup。如果你已经有手写的 systemd 或 launchd 服务，setup 不会悄悄替换它：默认情况下，它会拒绝没有标记的 tokdash.service / plist 文件。你可以继续自己管理那个服务，或者在 setup 之前先删掉它，或者先检查 tokdash setup --dry-run，再运行 tokdash setup --force。--force 也会处理 1.0 之前的服务：这些服务已经占用了 55423 端口，但没有暴露新的 /health 指纹，--force 会重写并重启已有的 tokdash.service。想跳过服务创建，用 tokdash setup --no-service。

如果你当前的安装用的是 conda/system/user-pip 解释器，并且希望 tokdash update 管理后续升级，就把服务迁移到 Tokdash setup 自有的 venv：

Upgrade the tokdash command you are about to run, for example:
python3 -m pip install --user -U tokdash
or, for a conda base install:
conda run -n base python -m pip install -U tokdash
tokdash setup --runtime venv --force
tokdash doctor

这样你的使用历史仍保留在 ~/.tokdash 下，用户服务会被重写为运行 ~/.tokdash/runtime/python-venv/bin/python -m tokdash，后续 tokdash update 就能升级这个受管理的 venv 并重启服务。如果你用 pipx 安装，也可以保留 pipx 运行时，用 tokdash update 或 pipx upgrade tokdash 升级。

前台回退

如果你只想要一次性的前台进程：

tokdash serve

打开 http://127.0.0.1:55423。默认端口被占用时，用 tokdash serve --port <port>。默认情况下，tokdash serve 会在启动时在浏览器里打开一次仪表盘；传 --no-open 可以关掉。不带任何命令的 tokdash 只打印命令帮助然后退出——它不会再背着你启动 tokdash serve。

完整的引导细节——运行时选择、WSL/systemd 行为、macOS launchd、Tailscale、打包、更新检查，以及安全卸载的语义——见 docs/guides/ONBOARDING.md。想通过 Tailscale Serve、SSH 转发或显式网络绑定做远程访问，见 docs/guides/REMOTE_ACCESS.md。

功能

- 精确的 token 计数：输入/输出/缓存 token 明细
- 会话浏览器：按会话下钻
- 贡献日历：2D 热力图 + 3D 等距视图，支持 Tokens/Cost/Messages 指标
- 报告标签页：按周 / 月 / 年初至今查看你自己的智能体活动报告，每一级细节都配一张可分享的卡片。每次导出都会写出一张浅色和一张深色 PNG
- 配额标签页：九个服务商的订阅窗口进度条，带重置倒计时。Codex 窗口直接读取本地日志即可使用；其他多数来源需要主动开启实时轮询
- 终端仪表盘 [新增]：tokdash tui —— 在终端里查看概览、会话、统计、报告、速度、配额和定价，无需浏览器
- 配套状态栏应用：从 macOS 菜单栏或 Windows 通知区域查看花费和订阅配额 —— Windows 版在 Microsoft Store 上架
- 状态栏集成：在 Claude Code 的状态栏里显示实时 token 用量指示器（任何能访问本地 HTTP 端点的智能体也可以）
- 多服务器视图：在设置里添加 WSL、macOS 和其他 Tokdash 服务器；可合并任意所选服务器的用量，同时配额按机器分组。见远程访问。
- 主题与应用打磨：17 种风格主题、浅色/深色模式、支持 PWA 安装、界面支持六种语言

支持的客户端

Tokdash 读取 27 个受支持智能体的本地会话日志 —— 上方胶囊行列出了它们；完整矩阵（用量与成本 / 会话浏览器覆盖范围、各客户端数据路径、覆盖项、各来源的计费说明）见 支持的客户端。

配额跟踪（可选）

配额标签页显示 九个服务商的订阅用量窗口和重置倒计时。Codex 的 5 小时/每周窗口直接读取本地日志即可使用（请视为估算值）；准确的 Codex 消耗量和其他所有服务商 —— Claude Code、Antigravity、MiniMax、Kimi Code、Grok、Z.ai、OpenCode Go、Command Code —— 都来自主动开启的实时轮询：Tokdash 用你命令行里已有的登录信息调用各服务商自己的配额端点。默认关闭，按服务商逐个授权，结果保存在本地数据库。

授权命令、总开关、轮询频率和各服务商凭据说明见 docs/reference/QUOTA.md。

成本准确性说明

token 数量取决于各客户端在本地记录了什么。成本默认根据内置定价数据库（src/tokdash/pricing_db.json）计算；如果存在你保存的仪表盘定价覆盖文件 <data_dir>/pricing_db.json，则改用该文件。两种方式都可能落后于服务商的真实定价 —— 请当作估算值，若结果重要，请与你的账单来源核对。

历史记录保留

[!IMPORTANT]
保留你的历史记录。 Claude Code 和 Gemini CLI 默认删除约 30 天前的本地会话，因此 Tokdash 中较早的月份可能悄悄缩水。

Tokdash 读取各客户端的本地会话日志；本地 SQLite 索引无法恢复在建立索引之前就已删除的日志。只有两个受支持客户端默认删除旧会话，两者都只需一行修复：

- Claude Code：在 ~/.claude/settings.json 中添加 { "cleanupPeriodDays": 3650 }（以及任何备用的 CLAUDE_CONFIG_DIR）。
- Gemini CLI：在 ~/.gemini/settings.json 中设置 { "general": { "sessionRetention": { "enabled": false } } }（工作区设置会覆盖用户设置）。

其他受支持的客户端默认永久保留历史记录。完整的各客户端说明、修复细节，以及本地 SQLite 索引保留什么、不保留什么，见 docs/reference/HISTORY_RETENTION.md。

路线图

见 docs/development/ROADMAP.md。

贡献 / 安全

- 贡献指南：docs/CONTRIBUTING.md
- 安全策略：docs/SECURITY.md

文档

完整文档在 docs/（从索引开始），分为：

- guides/ —— 面向任务的设置：入门、远程访问、状态栏、后台服务。
- reference/ —— 查阅资料：API 参考、配置、配额内部机制、支持的客户端、历史记录保留。
- development/ —— 更新日志、发布、路线图，以及公开的 technical-notes/。

许可证

MIT License - 见 LICENSE。