JingbiaoMei/Tokdash

English  |  中文  |  日本語  |  한국어  |  Español  |  Português

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

无需安装即可试用 → tokdash.github.io/demo

[!NOTE]
多台机器，一个仪表盘。 在设置中添加运行在 WSL、Mac 或任何其他设备上的 Tokdash 实例：概览、会话和统计会合并你选择的所有内容，“服务器”标签页会并排比较各台机器，而“配额”标签页会按机器分组保留每个提供商的窗口条和重置倒计时。远程访问 → · 配额跟踪 →

同样来自同一作者：Cosyncing。 同步并控制你的代理——从 CLI 到 GUI，从桌面到手机。随时随地接着上次的进度继续。Cosyncing 让你自己的网络中的编码代理保持同步。

[!TIP]
Tokdash Companion 现已上架 Microsoft Store。 无需保持仪表盘打开，即可从 Windows 通知区域或 macOS 菜单栏查看今日支出和订阅配额。从 Microsoft Store 获取 · 截图、下载和设置 →

目录

- 功能
- 支持的客户端
- Tokdash Companion 状态栏应用
- 快速开始
- 平台支持
- 配置
- 隐私与安全
- API（本地）
- 成本准确性说明
- 历史记录保留
- 路线图
- 贡献 / 安全
- 文档
- 项目结构
- 许可证

功能

- 精确的 token 计数：输入/输出/缓存 token 明细
- 状态栏集成 [新]：将实时 token 使用指示器放入 Claude Code 的状态栏（或任何可以访问本地 HTTP 端点的代理）——参见状态栏集成
- 贡献日历：2D 热力图 + 3D 等距视图，支持 Tokens/成本/消息指标
- 会话浏览器：按会话深入查看
- 报告标签页 [新]：按周/月/年初至今报告你自己的代理活动，并为每个详细层级提供可分享卡片。每次导出都会生成一张浅色和一张深色 PNG
- 配额标签页 [新增]：订阅窗口进度条，包含 Codex、Claude Code 和 Antigravity 的重置倒计时。Codex 窗口可直接从本地日志开箱即用；Codex 重置额度、计量功能以及所有 Claude/Antigravity 配额需要选择启用实时轮询
- 配套状态栏应用 [新增]：从 macOS 菜单栏或 Windows 通知区域查看支出和订阅配额——Windows 版本可在 Microsoft Store 获取——截图和下载
- 多服务器视图：在设置中添加 WSL、macOS 和其他 Tokdash 服务器；可组合任意所选服务器的用量，同时按机器分组显示配额。参见远程访问。
- 主题与应用优化：17 种风格主题、浅色/深色模式，以及 PWA 安装支持，界面支持六种语言（英语 / 中文 / 日语 / 韩语 / 西班牙语 / 葡萄牙语）

客户端支持矩阵

| 客户端 | 用量与成本 | 会话浏览器 |
|---|:---:|:---:|
| OpenCode | ✅ | ✅ |
| Codex | ✅ | ✅ |
| Claude Code | ✅ | ✅ |
| Gemini CLI | ✅ | — |
| Antigravity CLI | ✅ | ✅ |
| OpenClaw | ✅ | ✅ |
| Kimi Code / Kimi CLI | ✅ | ✅ |
| MiMo Code | ✅ | ✅ |
| Grok Build | ✅ | ✅ |
| Pi | ✅ | ✅ |
| omp | ✅ | ✅ |
| Kilo Code | ✅ | ✅ |
| Cline | ✅ | ✅ |
| GitHub Copilot CLI | ✅ | — |
| Hermes | ✅ | ✅ |
| DeepSeek Harness | ✅ | ✅ |
| Reasonix | ✅ | ✅ |
| ZCode | ✅ | ✅ |
| WorkBuddy | ✅ | ✅ |
| Qoder IDE | ✅ | ✅ |
| Qoder CLI | ✅ | ✅ |
| Zed | ✅ | — |
| Qwen Code | ✅ | ✅ |
| Crush | ✅ | — |
| Muse Code | ✅ | — |

有关本地数据路径、覆盖设置以及特定来源的计费说明，请参见支持的客户端。

概览

会话

月度用量热力图

年度使用热力图

使用报告

配额跟踪

多台服务器，一个总计

Tokdash 伴侣状态栏应用

Tokdash 伴侣状态栏应用是一个可选的 macOS 原生菜单栏应用，以及 Windows 通知区域应用。它提供 Tokdash 服务的紧凑、只读视图，无需保持完整仪表盘打开。

  

macOS 菜单栏      Windows 通知区域

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

下载

Windows — Microsoft Store（推荐）

由 Microsoft 签名，并通过 Store 更新。需要 Windows 11。

直接下载 — Tokdash Companion 1.0.0：

| 平台 | 下载 | 要求 |
|---|---|---|
| macOS | 通用 DMG（arm64 + x86_64） | macOS 14 或更高版本 |
| Windows | 自包含便携式 ZIP（x64） | Windows 11；Windows on Arm 可使用 x64 模拟 |

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

设置

1. 使用快速开始安装并启动 Tokdash 1.5.2 或更高版本。
2. 安装配套应用。在 Windows 上，使用上面的 Microsoft Store 链接。如需
直接下载，请获取适用于你平台的资源，并根据 SHA256SUMS 进行验证。
3. 从直接下载安装：在 macOS 上，打开 DMG 并将 TokdashCompanion
拖到 Applications；在 Windows 上，将 ZIP 解压到稳定目录并运行
TokdashCompanion.exe。
4. 配套应用默认连接到 http://127.0.0.1:55423。打开其设置以添加、测试、
命名、启用或移除显式 Tokdash 端点，包括私有 Tailscale Serve URL。

配套应用仅联系你配置的 Tokdash 端点。配额不足通知和登录时启动均为
选择加入，且默认禁用。有关校验和、更新和移除说明，请参阅
配套应用发布指南。

快速开始

平台支持

- 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 --bind 0.0.0.0；请先阅读远程访问指南。

若要从 agent、脚本或 bundle 进行非交互式设置：

tokdash setup --auto --json

若要预览设置将会更改的内容：

tokdash setup --dry-run

验证

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 不拥有的包管理器安装的，它会打印确切的手动指引，而不是修改该环境。对于受管理的运行时，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 还会处理那些已经占用端口 55423 但未暴露新的 /health 指纹的 1.0 之前服务：它会重写并重启现有的 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
或者，对于 conda 基础安装：
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 默认保持绑定到回环地址。交互式 tokdash setup 可以在明确确认后配置 Tailscale
Serve，从而提供从 Windows 或其他 tailnet 设备进行的私有 HTTPS 只读访问。当你需要经过身份验证的写入访问时，请使用 SSH 转发。显式
--bind 0.0.0.0 提供只读网络访问，但会在
每个可达接口上暴露未认证的仪表板。

有关设置命令、WSL2 指南、
访问 URL、写入行为和安全权衡，请参阅 docs/guides/REMOTE_ACCESS.md。

前台回退

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

tokdash serve

打开 http://127.0.0.1:55423。如果默认端口被占用，请使用 tokdash serve --port 。

有关完整的入门详情，包括运行时选择、WSL/systemd 行为、macOS launchd、
Tailscale、打包、更新检查和安全卸载语义，请参阅
docs/guides/ONBOARDING.md。

OpenClaw 摘要（定时报告）

Tokdash 可以通过按计划查询本地 API，为每日/每周/每月的 OpenClaw 使用报告提供支持。

面向人类

将此提示复制并粘贴给你的 LLM 代理（Claude Code、AmpCode、Cursor 等）：

Install and configure scheduled Tokdash usage reports for OpenClaw by following the instructions here:
https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/guides/agents/openclaw_reporting/AGENTS.md

Or read the guide yourself, but seriously, let an agent do it.

面向 LLM 代理

获取安装指南并按照其操作：

curl -s https://raw.githubusercontent.com/JingbiaoMei/Tokdash/main/docs/guides/agents/openclaw_reporting/AGENTS.md

状态栏集成

本地 API 可以为你的编码代理（Claude Code 等）中的状态栏项提供支持，显示实时 token/成本统计。

现成模板位于 docs/guides/statusline/ —— 将其中一个复制到 ~/.claude/scripts/，并将 statusLine 块添加到 ~/.claude/settings.json：

- statusline-minimal.sh → 一行：[Claude Sonnet 4.6] 📁 myproject | 📊 12.3M ($4.56) today
- statusline-full.sh → 一个四行仪表板，包含今日 + 本周总计以及按工具划分的前 3 名明细
- statusline.ps1 → 与最小模板相同的单行输出，适用于在 Windows 上原生运行的 Claude Code（PowerShell，无需 curl/jq）

所有这些都是只读的、仅限 localhost，并且如果 Tokdash 未运行则会静默失败。安装/配置请参阅文件夹 README，端点参考请参阅 docs/reference/API.md。

更想自己动手？把这段提示词交给你的 agent，并让它参考 docs/reference/API.md：

“我想从 tokdash 端点的 API 添加一个状态栏项；它应该显示今天使用的总 token 数。”

配置

Tokdash 默认仅限 localhost。

- TOKDASH_HOST（默认值：127.0.0.1）
- TOKDASH_PORT（默认值：55423）
- TOKDASH_CACHE_TTL（默认值：600 秒）
- TOKDASH_CACHE_MAX_ENTRIES（默认值：256）——限制缓存的 API 响应及其空闲的按 key 锁
- TOKDASH_COMPUTE_CONCURRENCY（默认值：2）——同时进行的高开销历史重新解析的上限；多余的冷请求会快速返回 503，而不是在负载下使服务器饱和
- TOKDASH_STARTUP_WARM_JOIN_SECONDS（默认值：30 秒）——对于启动时仍在预热的 key，其首个请求等待该填充完成的时长，而不是返回 503；每个 key 最多只有一个请求等待
- TOKDASH_LIMIT_CONCURRENCY（默认值：64）——uvicorn 连接上限（背压）
- TOKDASH_KEEPALIVE（默认值：5 秒）——uvicorn keep-alive 超时
- TOKDASH_ALLOW_ORIGINS（逗号分隔，默认值：空）
- TOKDASH_ALLOW_ORIGIN_REGEX（默认 CORS 策略允许 localhost/127.0.0.1 以及同一 tailnet 的 Tailscale Serve 读取；设置任一 CORS 选项都会替换该默认策略）
- TOKDASH_NO_RETENTION_NOTICE（设为 1 可静默 tokdash serve 时打印的历史保留提醒）
- TOKDASH_SETUP_NO_OPEN（设为 1 可跳过 tokdash setup 结束时可选地打开浏览器）

会话活跃时间（估算）：

每个会话都会在报告 span_ms 的同时报告 active_ms。Span 是从第一个事件到最后一个事件；活跃时间通过只将连续 token 事件之间的每个间隔计入到空闲上限为止来减去空闲时间，因此一个整夜保持打开的会话不再被读取为 14 小时的会话。

这是一个估算值，API 也如此说明：summary.active_time_estimated 为 true，summary.active_time_method 为 capped-inter-event-gap。这些限制源于该方法——事件之间的短暂暂停与工作无法区分，单次操作长于上限时会被截断到该上限，而只有一个 token 事件的会话测得为零，因为其之前没有任何事件。
并发工作有两种计算方式。active_ms 是时钟时间，重叠部分只计一次；active_ms_sum 将重叠部分累加，即智能体时间。两者都会在 summary 中按会话和按工具分别出现。Kimi 智能体和 Claude 子智能体与主智能体并行运行，每个都作为独立的时间流计时：一个子智能体并行工作一分钟，会增加一分钟的智能体时间，但不增加时钟时间。

- TOKDASH_ACTIVE_GAP_CAP_SECONDS（默认值：300）——空闲上限，单位为秒；超过此值的间隔只按上限计入。取值范围限制在 1 秒至 6 小时。

持久化用量数据库（默认开启）：

Tokdash 默认在 ~/.tokdash/usage.sqlite3 维护一个本地 SQLite 索引。它存储解析后的 token 行以及 Codex/Claude/Kimi/DeepSeek Harness/Reasonix 会话摘要，以便重复的仪表盘和 API 读取可以使用索引化 SQL，而不必重新解析每个源日志。源日志仍然是唯一事实来源；该数据库只是本地性能索引，如果被禁用或不可用，Tokdash 会回退到实时解析。

缓存的会话行与价格无关：它们保存每一轮的计费输入（模型、新输入、缓存读取和写入、输出），成本在读取时根据该进程已加载的定价计算。因此，编辑费率会立即重新定价，而不必重新读取数 GB 的日志；两个共享同一数据库的 Tokdash 版本也不会因定价问题而使彼此的行失效。不过，只有当两个构建支持相同的数据库架构时，共享才是安全的：架构迁移只能向前运行，因此一旦较新的构建迁移了该文件，较旧的构建就会拒绝打开它，直到升级为止，并且在版本匹配之前，每次缓存读取都会失败。tokdash doctor 会报告磁盘上的架构以及正在运行的构建所支持的架构。解析器和源文件的更改仍会正常重新解析。在此之前写入的行（包括 TOKDASH_USAGE_DB_DURABLE 在其日志消失后保留的任何行）会根据其存储的总量重新定价，这能重现相同的数字，但无法将 Claude 或 Kimi 的缓存写入与新输入区分开；只有重新解析这些日志才能恢复这种区分。Codex 按 provider/model 计费并存储裸名称，因此其较旧的行会被重新解析一次，而不是复用。

让检出代码针对自己的数据目录运行，这样它永远不会迁移已安装服务的数据库：

TOKDASH_DATA_DIR=output/dev-data PYTHONPATH=src python3 main.py

- TOKDASH_USAGE_DB（默认值：1）——设置为 0、false、no 或 off 可禁用持久化用量数据库
- TOKDASH_DATA_DIR（默认值：~/.tokdash）——Tokdash 本地状态的基目录
- TOKDASH_USAGE_DB_PATH（默认值：$TOKDASH_DATA_DIR/usage.sqlite3）——显式 SQLite 文件路径
- TOKDASH_USAGE_DB_DURABLE（默认值：1）——如果源文件暂时消失或解析器未返回任何行，则保留已索引的行；设置为 0 可进行严格的源替换
- TOKDASH_USAGE_DB_WATCH（默认值：0）——设置为 1 可在 tokdash serve 内运行后台同步循环
- TOKDASH_USAGE_DB_WATCH_INTERVAL（默认值：30 秒）— tokdash db watch 以及服务时监视循环的同步间隔

数据库维护命令：

tokdash db status --pretty
tokdash db sync --pretty
tokdash db verify --verify-period today --pretty
tokdash db repair --dry-run --pretty
tokdash db resync --pretty
tokdash db watch --pretty

如需通过 Tailscale Serve、SSH 转发或显式网络绑定进行远程访问，请参阅
docs/guides/REMOTE_ACCESS.md。在你选择启用后，交互式 tokdash setup 可以配置并
记录 Tailscale Serve 规则。

默认情况下，tokdash serve 会在启动时在你的浏览器中打开一次仪表板。传入 --no-open 可禁用此行为（在无头/SSH 环境以及后台服务模板中也会自动跳过）。

隐私与安全

- 无遥测：Tokdash 不会有意将你的数据发送到任何地方。
- 本地解析：用量根据本地会话文件计算（参见支持的客户端）。
- 可选的配额轮询：配额标签页默认仅限本地。可按提供商启用 API 轮询，在标签页中操作或使用 tokdash quota consent；它仅使用你的本地 CLI 凭据调用该提供商自己的配额端点，并将响应存储在本地用量 SQLite 数据库中。
- 服务器暴露：Tokdash 默认绑定到 127.0.0.1。Tailscale Serve 提供私有的只读访问，SSH 转发提供经过身份验证的写入访问，而 --bind 0.0.0.0 会在所有网络接口上显式暴露未经身份验证的读取访问。参见远程访问指南。

配额跟踪（可选）

配额标签页显示订阅利用率窗口和重置计时器，数据来自两个来源。本地日志（无网络）：Codex 会在会话文件中记录自己的配额，因此 Codex 的 5 小时/每周窗口开箱即用——但它们仅在你使用 Codex 时更新，而且日志从不包含重置额度或计量功能窗口。请将会话日志中的 Codex 消耗视为可能严重失真的估算值：每个会话会在其最后一次获取时缓存配额快照，并在之后的每条消息中不加更改地重放，因此数字可能过时，重置边界的噪声偶尔还会进一步扭曲某个窗口——配额标签页将这些图表标记为估算值。实时轮询（默认关闭，需按提供商同意）：Tokdash 使用你的 CLI 已有的登录信息调用提供商自己的配额端点。它更新更及时，增加了 Codex 重置额度和计量功能，是获得准确 Codex 消耗所必需的，并且是 Claude Code、Antigravity、MiniMax、Kimi Code、SuperGrok/Grok Build、Z.ai Coding Plan 和 OpenCode Go 的唯一配额来源：

tokdash quota consent --codex-api on --claude-api on --antigravity-api on
tokdash quota consent --minimax-api on --kimi-api on --grok-api on --zai-api on
tokdash quota consent --opencode-go-api on
tokdash quota consent --credential-scan on   # 允许已披露的本地凭据读取器
tokdash quota consent --poll-interval 30      # 后台轮询频率：15、30、60 或 120 分钟
tokdash quota consent --enabled off           # 总开关：关闭所有配额跟踪
tokdash quota poll
tokdash quota show

总开关。 quota.enabled（默认开启）用于开启或关闭所有配额工作——会话扫描、网络轮询和快照写入。可在 Quota 标签页中切换，或使用 tokdash quota consent --enabled on|off。当它关闭时（或设置了 TOKDASH_QUOTA_POLL=0 终止开关），后台轮询器会完全空闲，GET /api/quota/refresh 会返回“quota tracking disabled”错误，并且该标签页会显示一张启用配额跟踪卡片，而不是数据。各提供方的同意键仍保持其更窄的仅网络含义。

轮询间隔。 后台轮询器默认每 30 分钟生成一次快照。可从 Quota 标签页、在 tokdash setup 期间，或使用 tokdash quota consent --poll-interval N 选择 15/30/60/120 分钟；它会作为 quota.poll_interval_minutes 保存在 config.json 中。TOKDASH_QUOTA_POLL_INTERVAL 环境变量（以秒为单位，下限 300）会覆盖已保存的值，并且该标签页会显示当前生效的是哪个来源。间隔更改会在下一个轮询周期生效，无需重启服务器。Codex 会话摄取是增量的——在对你的历史记录进行一次初始回填后，每个周期只会尾读已增长的会话文件，因此稳态轮询的开销仅为个位数毫秒。

对于固定重置的配额窗口，轮询器还会在重置边界附近采样，以便历史记录捕获重置前的高值和重置后的基线。边界采样默认启用，仅调用其窗口触发采样的提供方，合并相邻的提供方边界，并在守护进程轮询周期之间保持至少 300 秒。设置 TOKDASH_QUOTA_BOUNDARY_POLL=0 可禁用它，设置 TOKDASH_QUOTA_BOUNDARY_POST=0 可仅禁用重置后采样，或使用 TOKDASH_QUOTA_BOUNDARY_PRE_SECONDS 和 TOKDASH_QUOTA_BOUNDARY_POST_SECONDS 调整默认的 120 秒提前量。
多个 Claude Code 安装。 Claude Code 每个配置目录保留一个订阅，因此你以 CLAUDE_CONFIG_DIR=~/.claude-academic claude 运行的第二个登录是一个拥有自己窗口的第二个订阅。在同意凭证扫描的情况下，Tokdash 会读取 $CLAUDE_CONFIG_DIR 以及每个拥有自己 .credentials.json 的 ~/.claude 目录，分别轮询每一个，并将它们分组在 Claude Code 卡片内，使用该目录设置时所用的配置文件名称（academic）。历史记录也会将它们分开：Claude-academic 5-hour 是独立于 Claude 5-hour 的单独序列。登录已过期的安装会显示自己的提示，而不是隐藏一个正常工作的安装的数字，并且两个持有相同登录的目录只计一次。对于位于你的主目录之外的安装，将 TOKDASH_CLAUDE_PROFILES 设置为以路径分隔的目录列表。用量总计则无需任何设置：每个 ~/.claude 安装下的会话日志已经计数了一段时间。

实时轮询需要两个独立的决定：quota.credential_scan 允许对所披露的本地凭证存储进行只读访问，然后每个 _api 键允许该提供商的网络请求。Tokdash 读取原生 CLI 认证/配置文件、OpenCode 的 auth.json 加上全局提供商配置、活动的 Claude 设置，以及通过只读 SQLite 连接读取 CC Switch 的 providers 表。它从不扫描提供商日志、shell 配置文件或任意的 {file:...} 引用。MiniMax 接受 mmx 登录或 Token Plan 订阅密钥（MINIMAX_TOKEN_PLAN_GLOBAL_KEY / MINIMAX_TOKEN_PLAN_CN_KEY）；普通的按量付费密钥不保证拥有 Token Plan 配额。Kimi 接受 Kimi Code 登录/密钥（KIMI_API_KEY），而不是 Moonshot 开放平台的按量付费密钥。SuperGrok/Grok Build 配额需要 $GROK_HOME/auth.json 中的 xAI OAuth 登录；普通的 xAI API 密钥无法访问消费者账单。Z.ai 接受来自 $ZCODE_HOME/v2/config.json 的 Coding Plan 密钥、受支持的工具配置、ZAI_API_KEY 或 Z_AI_API_KEY，并查询该计划的 5 小时/每周额度窗口以及旧版 MCP 限制。在 macOS 上，Claude Code 可能需要一次性的只读 Keychain 批准。Tokdash 从不刷新或写入提供商凭证。TOKDASH_QUOTA_POLL=0 是所有配额跟踪的硬性终止开关。tokdash export 默认排除配额数据；仅当你有意将其包含在 JSON 中时才使用 --include-quota。

OpenCode Go 首先使用 OPENCODE_API_KEY，然后使用 OpenCode 的 auth.json 中的 opencode-go 密钥，并从 opencode.ai/zen/go/v1/usage 读取滚动/每周/每月订阅窗口。Zen 按量付费余额没有密钥认证端点，因此不被跟踪。
Grok Build 的 token 用量同样从 $GROK_HOME/logs/unified.jsonl 本地解析。其推理记录会暴露 prompt、cached-prompt、completion 和 reasoning token；Tokdash 使用同一 CLI 进程中的模型事件对它们进行归属，并根据常规定价数据库计算成本。没有模型事件的记录会被跳过，而不是分配一个猜测的价格。

DeepSeek Harness（dsh）的用量和会话从 $DSH_HOME/sessions///session.jsonl.zstd（或未压缩的 session.jsonl）本地读取，DSH_HOME 默认为 ~/.dsh。每个日志是一系列拼接的 zstd 帧；Tokdash 会解码所有帧，将每一步早期的 usage 块合并到其最终消息中，而不是重复计算，并跳过 fork 会话继承的前缀，这样父会话和子会话就不会对相同的 token 重复计费。

Reasonix 的用量和会话从 $REASONIX_HOME（默认 ~/.reasonix）本地读取：每请求 token 来自每日的 stats/YYYY-MM-DD.jsonl 日志，会话结构来自 projects//sessions/.jsonl。Reasonix 会与 config.toml 中指定的任意提供商通信，因此每一行中的 provider/model 对会通过常规定价数据库进行归属和定价；没有公开费率的自托管模型按零成本计算 token。Reasonix 按请求记录用量，并且从不在其上标记会话 id，因此 Session Explorer 的行会显示轮次、项目和时间，但不显示 token 数——Overview 和 Stats 则包含完整总计。
ZCode 的用量从 $ZCODE_HOME/cli/db/db.sqlite 本地读取（默认 ~/.zcode/cli/db/db.sqlite；ZCODE_HOME 遵循 ZCode 自身的设置）。每一行 model_usage 是一次模型请求，包含重试，该行的 model_id 通过常规定价数据库定价，而 provider_id（例如 builtin:zai-start-plan）则保留为标签。ZCode 的 input_tokens 将缓存和未缓存的 prompt token 一起计算，因此缓存部分会被拆分到自己的桶中并按缓存费率计费，而 reasoning token 在显示上与输出分开，但仍按输出费率计费。ZCode 也会出现在 Sessions 标签页中：轮次从同一数据库读取，按（轮次、模型）以相同规则计费，仅限顶层会话，并且即使某个轮次没有产生可计费 token，其测得的时间仍会计入该工具的活跃时间。Coding Plan 配额是远程账户数据，可通过单独征得同意的 Z.ai 实时轮询器获取。
WorkBuddy 的使用情况从本地 ~/.workbuddy-ai/projects//.jsonl 转录文件中读取（WORKBUDDY_DATA_DIR 接受一个以逗号分隔的根目录列表，用于将 Tokdash 指向其他存储位置，例如从 WSL 访问 Windows 数据目录）。每条助手消息行对应一次模型调用；prompt_tokens 中的缓存部分被拆分到单独的桶中，并按缓存费率计费，而推理 token 在显示上与输出分开，但按输出费率计费。模型 id 原样保留：显式 id（例如 gpt-5.5）通过常规定价数据库定价，而 Auto 路由器别名（default-model）不在定价数据库中，费用为 0.00。每轮的 credit 值仅作为元数据存储，不影响费用。Sessions 标签页从相同的根目录读取相同的转录行（每条计费的助手行对应一轮）。

Qoder 的使用情况从本地两个位置读取：IDE 的 SQLite 数据库（位于 IDE 数据目录下的 SharedClientCache/cache/db/local.db；在 Windows 和 WSL 上优先使用 QoderCN 构建版本而非国际版本）以及 CLI 的 JSONL 日志（~/.qoder 和 ~/.qoder-cn，外加 QODER_CONFIG_DIR 和以逗号分隔的 QODER_CLI_HOME）。在 IDE 侧，每条 chat_message 行都计入，所有角色均如此：缓存部分从提示 token 中拆分到单独的桶中，模型来自 model_key（当路由器名称缺失时为 auto）。在 CLI 侧，每个请求的转录计费记录与其跨所有根目录的 segment token 记录合并：携带提供商积分的行以提供商报告的费用为准，按估计的每积分 $0.01 换算（QODER_USD_PER_CREDIT 可覆盖该估计值），且永不重新定价，而仅含 token 的行则通过常规定价数据库定价。没有输入 token 的记录会根据已知上下文窗口通过 context_usage_ratio 恢复输入 token —— 默认情况下 auto 为 180,000，一旦显式设置 QODER_CLI_CONTEXT_WINDOW，则适用于所有模型。Qoder IDE 出现在 Sessions 标签页中：从同一数据库的临时目录快照中读取相同的 chat_message 行（每个角色，每条可解析行对应一轮）。Qoder CLI 也有自己的 Sessions 面板：两个流的逐文件候选通过 Overview 相同的 request_id 合并逻辑进行折叠（相同顺序，相同胜出者），积分行按提供商报告的费用原样保留，而 segment 项目原样显示经过清理的目录标签，因为该清理不可逆。
Zed 的使用情况从 Zed 各操作系统数据目录下的 threads/threads.db 本地读取（Linux：$XDG_DATA_HOME/zed 或 ~/.local/share/zed，并遵循 FLATPAK_XDG_DATA_HOME；macOS：~/Library/Application Support/Zed；Windows：%LOCALAPPDATA%\Zed）。每个 agent 线程对应一行，其 zstd 压缩的 blob（旧版行是纯 JSON）携带由该线程自身的 completion 流累积的 cumulative_token_usage，并带有逐字段的高水位标记——缓存不计入（input + cacheRead = 完整 prompt），因此各桶可直接映射——而子代理线程是单独的行，其用量永远不会并入父线程，因此每个非零线程都恰好计数一次。线程按其当前模型计价（切换过模型的线程按其最后一个模型计价）；定价数据库中不存在的自托管 id 计为 0.00。Zed 没有环境变量数据目录覆盖，因此 --user-data-dir 启动标志是已记录的盲点。Zed 不会出现在 Sessions 标签页中。

Qwen Code 的使用情况从 /projects//chats/.jsonl 本地读取（外加改名前的 /tmp//chats/.jsonl），其中 base 依次解析 $QWEN_RUNTIME_DIR、$QWEN_HOME、~/.qwen——设置级别的 runtime_base_dir 覆盖无法从 Tokdash 访问，是一个已记录的盲点。这些文件是仅追加的，每个会话一个文件，每条 assistant 记录原样携带提供方的 usageMetadata：promptTokenCount 包含缓存，因此缓存部分被拆分到单独的桶中并按缓存费率计费，而 thoughtsTokenCount 显示为推理。每条记录的 uuid 是稳定的源全局键：/branch 会将父记录（相同 uuid）复制到分叉的文件中，因此用量存储按最早出现者拥有每个键，并在规范文件被删除时提升存留的副本。子代理记录共享会话文件并自动计数。费用根据定价数据库计算；没有模型的记录将 token 计为 unknown，费率为 0.00。Sessions 标签页读取相同的 assistant 记录，每条记录为一轮，分叉历史归最早副本所有。
Crush 的使用情况是从 $CRUSH_DATA_DIR（以逗号分隔的数据目录列表，每个目录都包含 crush.db）本地读取的——这是必需的，因为 Crush 的默认数据目录是工作目录旁边按项目划分的 .crush，并没有可供扫描的全局根目录。该数据库处于 WAL 模式，因此 Tokdash 通过与 ZCode 相同的复制并快照路径来读取它。每个 token 数非零的会话都会从其 prompt_tokens/completion_tokens 贡献一条记录，子代理会话也包括在内：Crush 只会将成本归入父会话，而从不归入 token，因此其自身统计查询中仅限顶层的约定（parent_session_id IS NULL）会直接丢弃子代理的使用量。每条记录都归属于其会话最后一条非摘要的助手消息——混合模型的会话按其最后一个模型计价。源码旁边记录了三项注意事项：计数器是按步骤分配而非累积的，因此它们保存的是最后一次请求的上下文大小和最后一轮输出，在多步骤会话中读数偏低（已针对 Crush v0.91.2 验证）；当提供商报告零使用量时，token 可能是字符数估算值（数据库中无标志）；并且缓存/推理的拆分不会被持久化。时间戳以秒为单位；行按 updated_at（最后触碰时间）分桶，一个会话的整个生命周期总量会落在同一天。sessions.cost 会被忽略；成本仅来自定价数据库。Crush 不会出现在 Sessions 标签页中。

tokdash setup 提供一个可选的配额步骤（按提供商进行网络同意，默认为否，外加轮询间隔），而 tokdash doctor 会报告配额状态：主开关、按提供商的同意、终止开关、生效间隔及其来源、上次轮询时间，以及已存储的快照数量。

配额快照及其历史记录存放在本地使用数据库（usage.sqlite3，默认启用）中，并且默认无限期保留——将 TOKDASH_QUOTA_RETENTION_DAYS 设置为正数天数即可修剪较旧的快照。如果你通过 TOKDASH_USAGE_DB=0 选择退出本地持久化，Quota 标签页将失去其主要数据路径：不会保留快照历史记录，后台轮询器不会运行，并且该标签页在当前服务器进程的生命周期内仅显示来自手动 Refresh（已同意的网络提供商）的内存结果。请保持使用数据库启用（默认值）以进行正常的配额跟踪。

API（本地）

Tokdash 是一个本地 HTTP 服务器。常用端点：

- GET /api/usage?period=today|week|month|N
- GET /api/usage?date_from=YYYY-MM-DD&date_to=YYYY-MM-DD
- GET /api/tools?period=...（仅编码工具）
- GET /api/openclaw?period=...（仅 OpenClaw）
- GET /api/sessions?tool=codex|claude|opencode|pi_agent|omp|mimo|kimi|dsh|reasonix|zcode|kilocode|grok|hermes|antigravity_cli|cline&period=...（追加 &include_review_sessions=true 以包含 Codex 审查/权限会话，默认隐藏）
- GET /api/active-time?period=...（跨所有会话工具的活跃时间，外加按工具的细分）
- GET /api/quota 和 GET /api/quota/history（订阅配额快照；网络刷新受写入权限限制且需主动选择启用）
- GET /api/stats（贡献日历与统计数据）

示例：
curl 'http://127.0.0.1:55423/api/usage?period=today'

完整 API 参考：docs/reference/API.md —— 每个端点的 schema、参数和响应结构。

成本准确性说明

Token 数量取决于每个客户端在本地记录的内容。成本默认根据内置的定价数据库（src/tokdash/pricing_db.json）计算，或者当存在你保存的仪表盘定价覆盖文件 /pricing_db.json 时，根据该文件计算（Pricing 标签页会写入该文件，并会完全替换内置费率）。无论哪种方式，它们都可能滞后于提供商的实际定价——请将其用作估算值，如有需要，请对照你的账单来源进行核实。

历史记录保留

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

Tokdash 会读取每个客户端的本地会话日志，并同时维护一个本地 SQLite 性能索引。该索引可以保留 Tokdash 已经见过的行，但无法恢复在被索引之前就已删除的日志，也不能替代保留原始客户端历史记录。如果某个客户端在 Tokdash 同步之前删除了旧日志，过去某个月份的读数仍可能低于你最初记录时的数值。默认情况下只有两个受支持的客户端会这样做，而两者都只需一行修复：

- Claude Code 会在启动时删除早于 cleanupPeriodDays（默认 30 天）的会话。请将以下内容添加到现有的 ~/.claude/settings.json（以及任何备用的 CLAUDE_CONFIG_DIR）中：
{ "cleanupPeriodDays": 3650 }

- Gemini CLI 会删除早于 30 天的会话。请在 ~/.gemini/settings.json 中禁用它；如果某个项目有 .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/。

项目结构

tokdash/
├── main.py                 # 源码入口点 (python3 main.py)
├── tokdash                 # 源码 CLI 包装器 (./tokdash serve)
├── src/
│   └── tokdash/
│       ├── cli.py
│       ├── api.py                # FastAPI 路由/应用
│       ├── compute.py            # 聚合/合并逻辑
│       ├── dateutil.py           # 共享日期范围解析
│       ├── sessions.py           # 会话浏览器逻辑
│       ├── pricing.py            # PricingDatabase 包装器
│       ├── assets.py             # 静态资源管理
│       ├── model_normalization.py
│       ├── pricing_db.json
│       ├── sources/
│       │   ├── openclaw.py       # OpenClaw 会话日志解析器
│       │   └── coding_tools.py   # 本地编码工具解析器
│       └── static/
│           ├── index.html        # 单页仪表盘
│           ├── theme-config.js   # 主题调色板与热力图颜色
│           └── themes.css        # 各主题 CSS 覆盖
└── docs/                   # 文档 — 索引见 docs/README.md
├── guides/             # 入门、远程访问、状态栏、后台服务
├── reference/          # API 参考、支持的客户端、历史保留
└── development/        # 变更日志、发布、路线图、technical-notes/

许可证

MIT 许可证 - 见 LICENSE。