文档

AIUsage 是一个命令行工具，内置 Web 仪表盘。安装完成后，它会解析 AI 工具生成的日志文件，并在本地数据库中追踪用量数据。

安装

npm install -g @juliantanx/aiusage

或使用 pnpm：

pnpm add -g @juliantanx/aiusage

手动解析数据（可选）

aiusage serve 启动时会自动解析日志。如需在不启动仪表盘的情况下单独解析，可手动运行：

aiusage parse

启动仪表盘

aiusage serve
# Listens on http://localhost:3847 by default

浏览器打开 http://localhost:3847 即可查看仪表盘。

仪表盘密码

本地仪表盘默认不需要登录。设置 AIUSAGE_DASHBOARD_PASSWORD 后，除首页、静态资源和公开 summary / quotas API 外，其他 API 会要求先输入密码。密码仅用于本地 dashboard cookie，不会写入数据库。

后台运行 (PM2)

aiusage serve 默认在前台运行，关闭终端后服务会终止。如需后台持续运行，请使用 PM2：

npm install -g pm2  # 全局安装 PM2
aiusage pm2-start  # 现在启动后台服务并保存进程列表
pm2 startup  # 注册开机自启

如需同时启用仪表盘密码，请按当前系统选择命令：

pm2-start 会生成 ~/.aiusage/ecosystem.config.cjs，并通过 wrapper 继承启动命令当时的环境变量。修改密码后需要用新环境重启：

pm2 logs aiusage-server
pm2 list
pm2 save
aiusage pm2-start --server-only  # skip widget process

Docker

使用官方 Docker 镜像运行 AIUsage，无需安装 Node.js：

docker run -d \
  -p 3847:3847 \
  -v ~/.aiusage:/root/.aiusage \
  juliantanx/aiusage

Docker 中启用仪表盘密码：

docker run -d \
  -p 3847:3847 \
  -e AIUSAGE_DASHBOARD_PASSWORD=change-me \
  -v ~/.aiusage:/root/.aiusage \
  juliantanx/aiusage

首页是实时总览页，包含 LIVE 状态、当前时间范围、时钟、主 Token 计数器、配额预警、自动刷新进度条，以及费用 / 会话 / 活跃天数三项摘要。

界面元素

• 实时计数器 — 显示总 Token 数，支持动画计数效果
• 子统计 — 分别展示输入、输出与缓存总量（缓存读写合并显示）
• 范围与时钟 — 顶部显示当前时间范围、实时时钟和 LIVE 状态
• 费用 / 会话 / 活跃天数 — 三个摘要统计块
• Token 构成条 — 按比例显示输入、输出、缓存读写分布
• 刷新进度条 — 显示下次自动刷新的倒计时，并可手动立即刷新
• 配额预警 — 当 Claude Code / Codex / Copilot 配额层级达到 80% 以上时会在首页顶部提示

显示配置

点击右上角的齿轮按钮可打开显示配置面板：

• 时间范围 — 全部 / 今天 / 本周 / 本月 / 近 30 天
• 数字格式 — 精确（1,234,567）或简写（1.2K / 1.2M）
• 刷新说明 — 面板底部会显示当前轮询间隔，并可跳转到 Settings 修改 dashboard poll interval

概览页展示聚合统计摘要，并支持按日期范围、设备和 AI 工具筛选。这里也是查看按工具聚合和 Top Tool Calls / MCP 服务调用的入口。

统计卡片

• 总 Token — 所有类型 Token 的合计
• 总费用 — 基于定价表计算的估算费用
• 活跃天数 — 有记录的天数
• 会话数 — 独立会话的总数

Token 明细

在卡片下方展示输入、输出、缓存读取、缓存写入的分项数据。

按 AI 助手统计

按使用的 AI 工具（claude-code、codex 等）分组，显示各工具的 Token 数和费用。列出调用次数最多的工具（如 Bash、Read、Edit 等）。

页面支持两种图表模式：Breakdown 会按输入、输出、缓存读取、缓存写入、思考 Token 分开展示；Total 会将一天内所有 Token 合并成单柱。

每日柱状图

每组柱子展示同一天内的各类 Token（输入、输出、缓存读取、缓存写入、思考 Token），悬停可查看具体数值。

明细表格

表格列出每天各类型的 Token 数量及合计，支持横向滚动查看较长时间范围的数据。

Token 类型说明

• 输入 — 发送给模型的提示 Token
• 输出 — 模型生成的回复 Token
• 缓存读取 — 从缓存中命中并读取的 Token（计费更低）
• 缓存写入 — 写入缓存的 Token
• 思考 — 扩展思考功能使用的 Token

费用页面展示总费用卡片、每日费用柱状图，以及按工具和按模型的前 10 名费用排行。

每日费用图

柱状图展示每天的费用，悬停可查看当日金额。

按助手与模型分布

不同工具（Claude Code、Codex 等）的费用排名。不同模型（claude-sonnet-4-5、gpt-4o 等）的费用排名。

模型页面按总 Token 使用量排序，展示模型 ID、提供商、调用次数、总 Token，以及占比进度条。

• 模型 — 模型 ID（如 claude-sonnet-4-6）
• 提供商 — 服务提供商（Anthropic、OpenAI 等）
• 调用次数 — 该模型被调用的次数
• Token — 该模型消耗的 Token 总量
• 占比 — 在当前筛选结果中的占比（含进度条）

工具调用页面展示会话内工具调用频次排行，可切换查看全部、builtin、mcp、skill 三种类型。Qoder 和 Cursor 当前不会产出工具调用数据，因此切换到这两类工具时页面会显示提示。

项目页面按项目目录汇总 Token 和费用，并显示项目名、完整路径、占比条、Token 总量、费用与百分比。适合快速找出最耗资源的仓库。

会话页面按分页展示会话列表（每页 50 条），点击任意一行可进入详情页。列表列包含时间、工具、模型、持续时长、工具调用次数、输入 / 输出 Token 与费用。

配额页面当前覆盖 Claude Code、Codex 和 GitHub Copilot。页面会把有凭证的工具显示为卡片，没有本地凭证的工具则放到下方的 inactive 列表中。

配额卡片

每个已配置凭证的工具会显示最后更新时间，以及当前查询状态：正常显示 tiers、凭证过期、解析失败、查询失败、或暂无 tiers。未配置凭证的工具会显示在底部 inactive 列表中。

配额条

每个配额层级（如 5h、7d）显示一个进度条，颜色表示使用率：绿色（<70%）、橙色（70-90%）、红色（>90%）。显示重置倒计时。

定价页面按模型显示卡片，可直接编辑 input / output / cache read / cache write 的每百万 Token 单价。状态标签会区分内置价格、用户自定义价格、前缀匹配或无定价；部分模型还会显示 CNY 标签。

设置页按模块分区，当前包含 General、Data Sources、Sync、Data、Currency 五个区域，每个区域独立保存。

通用

数据源

为每种 AI 工具指定自定义日志目录路径。留空则使用默认路径：

• Claude Code — ~/.claude/projects
• Codex — ~/.codex/sessions + ~/.codex/archived_sessions
• OpenClaw — ~/.openclaw/agents
• OpenCode — ~/.local/share/opencode/opencode.db 及 opencode-*.db
• Hermes — ~/.hermes/state.db
• Qoder — ~/.qoder/logs/sessions + 平台相关的 local.db
• Cursor — 平台相关的 state.vscdb
• Copilot — ~/.copilot/otel （需配置 OTEL 环境变量）
• KiloCode — IDE 扩展目录 + 平台相关的 SQLite DB
• Kelivo — 通过手动导入 Kelivo 备份文件（chats.json / .zip），详见下方「手动导入」
• Gemini CLI — ~/.gemini/tmp
• Kimi Code — ~/.kimi-code/sessions
• CodeBuddy — ~/.codebuddy/projects
• Kiro — IDE SQLite + CLI JSON/JSONL 会话文件
• Grok Build — ~/.grok/sessions
• Antigravity — ~/.gemini/tmp/antigravity
• Roo Code — IDE 扩展 ui_messages.json
• Zed — 平台相关的 threads.db
• Goose — 平台相关的 sessions.db
• oh-my-pi — ~/.omp/agent/sessions
• pi — ~/.pi/agent/sessions
• Craft — ~/.craft-agent
• Droid — ~/.droid/sessions
• ZCode — ~/.zcode/cli/db/db.sqlite

手动导入

部分 AI 工具不暴露本地日志文件，需要通过导出备份的方式手动导入用量数据。当前支持手动导入的工具：

• Kelivo — 从 Kelivo 导出的chats.json 或 .zip 备份文件

操作步骤：

1. 在 Kelivo 中导出聊天记录备份（通常为 chats.json 或包含它的 .zip 文件）
2. 打开 AIUsage 仪表盘，进入 Settings → Data Sources
3. 找到「手动导入」区域，点击 Kelivo 旁边的导入按钮，选择备份文件
4. 等待导入完成，页面会显示导入结果（总记录数和新增记录数）

数据源环境变量

所有数据源都可以通过 AIUSAGE_*_PATH 覆盖默认路径。环境变量优先级高于旧版 config.sources，适合 Docker、PM2、WSL 或日志目录不在默认位置的机器。

跨平台示例：

数据管理

本地数据保留天数 — 用于配置后续清理策略。设为 0 或留空则表示永久保留；设置页面本身不会立即删除数据。

同步功能会把本机数据上传到远端，再拉取其他设备的数据并合并。你可以通过侧边栏 Sync 按钮手动触发，也可以先用 init 命令或设置页完成后端配置。

• GitHub — 推送到 GitHub 仓库
• S3 / 兼容存储 — 推送到 Amazon S3 或任何 S3 兼容存储（Cloudflare R2、MinIO 等）

aiusage init --backend github --repo owner/repo --token ghp_xxx
aiusage sync  # push/pull

设置页还支持自动同步间隔。设为 0 或留空可关闭；启用后 serve 进程会按间隔触发同步。

将用量数据导出为 CSV、JSON 或 NDJSON 格式，方便集成到已有的数据管道和报表系统。

aiusage export --format csv -o usage.csv
aiusage export --format json -o usage.json
aiusage export --format ndjson

Widget 是一个独立发布的 Electron 系统托盘应用，让你无需打开浏览器，就能随时在菜单栏（macOS）或系统托盘（Windows / Linux）瞥一眼今日 Token 用量。它与 CLI 共用同一个本地数据库，每 60 秒自动刷新一次。

安装

作为独立 npm 包安装：

npm install -g @juliantanx/aiusage-widget

安装后，可以直接启动：

aiusage-widget

或通过 aiusage CLI 启动（如未安装会提示先安装）：

aiusage widget

面板功能

点击托盘图标展开悬浮面板，再次点击或点击面板右上角的 ✕ 可关闭。面板显示以下三项统计：

• TODAY — 今日总 Token 数，附带输入（↑）/ 输出（↓）明细
• THIS MONTH — 本月累计 Token 数
• TOP MODEL — 本月使用最多的模型及其占比

面板右上角的刷新图标按钮会立即重新读取本地用量数据。打开完整仪表盘入口位于托盘右键菜单的 Open Dashboard；如果本地 dashboard 服务未运行，Widget 会先尝试启动 aiusage serve，再在浏览器中打开仪表盘。

托盘图标

左键单击托盘图标可切换面板的显示 / 隐藏；右键单击会弹出上下文菜单：

• Show Panel — 显示面板
• Refresh — 立即从数据库拉取最新数据
• Quit — 完全退出 Widget

aiusage 内置交互式管理菜单，涵盖所有 CLI 命令，通过数字选择即可操作，无需记忆命令和参数。支持 Windows、macOS 和 Linux。

aiusage menu

使用方式

运行 aiusage menu 进入主菜单，选择分组后进入子菜单，子菜单内选择具体命令。输入 0 返回上级，输入 6 退出。

========================================
  AI Usage Manager (aiusage)
========================================

  Dashboard: RUNNING  http://localhost:3847

  [1] Dashboard      (serve/stop/restart/open)
  [2] Data           (parse/summary/export/clean/recalc)
  [3] Sync           (init/sync)
  [4] Leaderboard    (view/login/upload/status/logout)
  [5] System         (status/widget/pm2/update)
  [6] Exit

命令分组

桌面快捷方式

Windows 用户可创建桌面快捷方式，双击即可打开交互菜单：

1. 右键桌面 → 新建 → 快捷方式
2. 目标输入： cmd /k aiusage menu
3. 命名为 "AI Usage Manager"

macOS / Linux 用户可添加 shell alias：

alias aim="aiusage menu"

AIUsage 官方站点（aiusage.jtanx.com）提供账号系统，用于排行榜上传、设备授权和个人资料管理。注册和登录支持密码和第三方 OAuth。

注册与登录

• 密码注册 — 使用邮箱和密码注册
• GitHub OAuth — 通过 GitHub 账号授权登录
• LINUX DO OAuth — 通过 LINUX DO 社区账号授权登录

邮箱验证

使用邮箱注册后，系统会发送验证邮件到你的注册邮箱。点击邮件中的验证链接完成邮箱验证。邮箱验证是上传排行榜数据的前提条件。

个人设置

登录后可在 /settings 页面管理个人资料：

• 用户名 — 修改用户名（30 天冷却期）
• 显示名称 — 设置公开显示名称
• 头像 — 上传或移除头像
• 密码 — 设置或修改密码
• 排行榜可见性 — 公开或私有
• 匿名模式 — 在排行榜上隐藏用户名和头像

公开排行榜用于展示用户主动提交的聚合数据。支持按 Token 总量或费用排名，可按工具和模型维度细分。查看不需要登录；上传需要登录并授权 CLI 设备。

查看与筛选

站点排行榜和 CLI 都支持以下筛选维度：

• 周期 — daily, weekly, monthly, yearly, all_time
• 指标 — Token 总量或费用
• 范围 — all（全部）、tool（按工具）、model（按模型）、tool_model（工具+模型）
• 工具筛选 — 指定工具名（如 claude-code）
• 模型筛选 — 指定模型名（如 claude-sonnet-4-6）

上传数据

推荐在本地仪表盘完成上传。启动仪表盘后访问 /leaderboard，登录 AIUsage 账号并授权当前设备，即可点击“上传数据”提交聚合用量；也可以在同一页面开启自动上传。

• 界面上传 — 启动本地仪表盘后访问 /leaderboard，完成登录后点击“上传数据”
• 自动上传 — 开启自动上传开关后，本地服务会按设定频率定时解析并上传聚合总量
• 上传状态 — 页面内可查看最近一次上传的周期、状态和 Token 总量
• 站点管理 — /uploads 用于查看上传历史和管理授权设备

如需在自动化脚本、远程主机或纯终端环境中上传，可以使用 CLI 完成同等流程：先授权设备，再提交聚合快照，最后查看上传与审核状态。

aiusage login
aiusage upload
aiusage upload-status

上传内容仅包含排名周期内的聚合 Token 总量和必要元数据，不包含 prompt、completion、源码、文件路径或本地费用估算。

上传后系统会自动进行风控评估。以下情况会被自动标记为 flagged 并进入管理员审核队列：breakdown 一致性偏差超过 1%、未知模型占比超过 80%、同设备同周期 24 小时内重复上传超过 5 次、token 总量超过用户 30 天平均值 10 倍。

本地上传面板

本地仪表盘的 /leaderboard 页面主要用于登录授权、上传聚合用量和配置自动上传。公开排行榜的浏览入口仍在官网。

• 账号与设备 — 显示当前登录账号、授权设备和授权时间
• 手动上传 — 点击“上传数据”立即提交当前本地可见的聚合用量
• 自动上传 — 开启后按每天、每周或每月频率自动上传，每个频率周期最多执行一次
• 最近上传 — 显示最近一次上传的周期、审核状态、Token 总量和上传时间

匿名模式

在 /settings 中开启匿名模式后，排行榜上你的用户名和头像将被隐藏，但仍会计入排名。适合希望参与排行但不想公开身份的用户。

登录后访问 /uploads 页面，可以管理授权设备和查看上传历史。

• 授权设备 — 查看设备名称、创建时间、最后上传时间、状态，可撤销设备授权
• 上传历史 — 最近 100 条上传快照，包含周期类型、Token 总量、设备名、时间和审核状态（accepted/rejected/flagged）

管理员登录后访问 /admin 页面，可管理上传审核、用户、定价表和审计日志。需要 admin 角色。

• 上传审核 — 查看 flagged 上传，执行 approve / reject / hide 操作
• 用户管理 — 搜索用户、封禁 / 解封、设置角色（admin / user）
• 定价表 — 从 LiteLLM 同步价格、管理内置 / 自定义条目、触发榜单重算
• 审计日志 — 查看所有管理员操作记录
• 数据维护 — 清理过期 nonces、旧批次、tombstone 记录、过期授权请求等

仪表盘侧边栏的 Support 页面（/support）列出了所有可用的联系方式和社区渠道。

• 微信 — 扫描 QR 码添加个人微信
• 邮箱 — [email protected]
• Discord — 社区服务器
• Telegram — 社区群组

所有 CLI 命令均通过 aiusage <command> 调用；不带子命令时会输出 summary。当前内置的主要命令包括 summary、status、parse、serve、export、clean、recalc、init、sync、widget、leaderboard、login、upload、upload-status、logout、menu、pm2-setup 和 pm2-start。

parse — 解析日志

serve — 启动仪表盘

summary — 终端摘要

默认命令。输出总 Token、总费用、记录数；当存在数据时还会显示按工具汇总，默认入口还会附带 Top Tool Calls。

export — 导出数据

导出命令当前要求显式指定格式，可输出到文件，也可直接打印到 stdout。

clean — 清理数据

清理本地数据。配合 --all 可清空全部数据（等价于原 reset）。如果配置了云同步（GitHub、S3），默认会将删除传播到所有远端后端，并在执行前列出受影响的后端供确认。

leaderboard — 公开榜单与上传

不带子命令时会查看公开排行榜。查看不需要登录；上传和上传状态查询需要先完成设备授权。

其他命令