Tokens 是一款追踪、可视化并竞技 AI 编程助手 token 用量的工具，由 CLI + Web 排行榜/团队榜组成。Tokens CLI 会扫描你机器上已安装的 AI 编程客户端，在本地汇总 token 用量，再把汇总数据提交到排行榜。本文是一份面向新手的完整安装与配置避坑指南，核心只讲一件事：搞懂TOKENS_API_URL铁律，让 CLI 一次性正确连上你的站点，不再踩 401、上报错站等经典坑。

📦 Tokens CLI 能做什么

• 本地扫描：自动检测 54 种 AI 编程客户端（Claude Code、Codex、Cursor、Copilot 等），读取它们本就会写盘的会话文件；
• 本地汇总：所有计算在你机器上完成，只上传汇总数据（token 数、模型名、客户端名、时间戳），Prompt 与文件内容永不离开本机；
• 排行榜 + 团队榜：Web 端展示全站排名、Team/Group 两级团队榜、个人主页与可嵌入卡片。

不放心可以先"空跑"看一眼将要上传什么：

tokens submit --dry-run

隐私管线的源码都开放可读：解析器在 cli/tokens-core/src/sessions/，提交路径在 cli/tokens-cli/src/commands/。

🚀 三平台最快安装命令

⚠️ 避坑 1：不要用bunx tokens-cli@latest登录或提交。它会跳过站点固定（site pin），直接走上游默认站。

⚠️ 避坑 2：Linux 用官方install.sh安装时，默认会拉起一个常驻自动上报服务tokens.service。它不读 shell alias，若你不做处理，它会一直把数据报给上游站。要么安装时加TOKENS_NO_SERVICE=1，要么给服务补上TOKENS_API_URL环境变量后重启。

🔑 全文核心：TOKENS_API_URL 铁律

CLI 只认TOKENS_API_URL，默认指向上游站；凭据不记录自己属于哪个站点，换站必须先tokens logout。

这三句话解释了 90% 的新手问题。源码里写得很直白——cli/tokens-cli/src/auth.rs 中，未设置环境变量时就直接回落到上游默认地址：

std::env::var("TOKENS_API_URL").unwrap_or_else(|_| "https://tokens.ci".to_string())

由此推导出三条操作铁律：

1. 每条命令都要带上它（TOKENS_API_URL=https://<你的域名> tokens submit），或在当前 shellexport TOKENS_API_URL=...一次；
2. 登录前先tokens logout——哪怕你没登录过。旧的上游凭据不清掉，发到你站上就是 401；
3. 本地开发例外：http://localhost:3000是 CLI 唯一允许的http地址，用于对接本地 Compose 栈自测。

✅ 标准流程：从登录到上榜一站到位

按顺序执行，每一步都对应一个常见坑：

# 第 1 步：清掉其他站点的旧凭据（避免 401） tokens logout # 第 2 步：登录你的站点（浏览器自动打开 /device 授权页） TOKENS_API_URL=https://<你的域名> tokens login # 第 3 步：提交用量，浏览器打开 /leaderboard 即可看到自己 TOKENS_API_URL=https://<你的域名> tokens submit

注意：CLI 登录前，要先在网站上用邮箱注册账号（浏览器打开https://<你的域名>/register）。另外https://tokens.ci的历史用量不会迁移，自托管站是全新独立库，需重新注册登录。

可选动作：tokens login --private可把账号从公开排名中隐藏（私密模式），并打印一次性读令牌。

🛠 懒人方案：一键预安装脚本

如果不想逐条手敲，仓库根目录提供了一键脚本，它只干三件事：检测/安装 CLI → 执行tokens logout→ 写入全局 alias（让tokens命令永远自动带上你的TOKENS_API_URL，长期生效）：

• macOS / Linux：pre-install-tokens.sh
• Windows：pre-install-tokens.ps1

本地执行示例（站点地址作为参数显式传入）：

bash pre-install-tokens.sh https://<你的域名>

支持--dry-run先预览再执行；脚本幂等，换域名重跑即可原地更新。

预装并登录后，还能配置常驻自动提交（脚本由你部署的站点提供）：

• Linux：enable-tokens-service.sh——systemd 用户服务常驻上报；
• Windows：register-tokens-submit-task.ps1——计划任务默认每 30 分钟提交一次。

🤖 支持哪些客户端：你的用量都去哪了

扫描目录覆盖 54 种客户端，装过并写过会话就会被统计，其中 Copilot、Hermes 等客户端都有专属解析器：

少数只通过账号 API 暴露用量的客户端（Cursor、Warp、Trae、Antigravity 等）需要先执行一次同步命令，例如tokens cursor sync、tokens warp sync，之后提交方式与其它客户端完全一致。完整的数据存放位置表见 README_zh.md。

⚠️ 避坑速查清单

📚 延伸阅读

• CLI 完整手册（本地开发 + 线上接入 + 脚本说明）：docs/deploy/tokens-cli-usage.md
• 自托管部署清单（环境变量、验收标准）：docs/deploy/self-host-production.md
• 生产 Docker 资产与操作手册：docs/deploy/docker/prod/
• 认证与默认地址逻辑源码：cli/tokens-cli/src/auth.rs
• 各版本发布说明：CHANGELOG.zh.md

一句话总结：装好 CLI 只是开始，把TOKENS_API_URL带对、把旧凭据清干净，你的用量就能稳稳落在自己的排行榜上。