3 步装好 UsageHub Open：Claude + Codex 用量看板

3 步装好 UsageHub Open：Claude + Codex 用量看板日报图文

同时用 Claude Code 和 Codex 一段时间后，我总会碰到同一个问题：额度分散在不同入口，5 小时窗口和 7 天窗口的重置时间也不同。忙起来以后，我通常不是忘了看，就是等到任务跑不动才发现额度快见底。

UsageHub Open 把这些数字放在一张常驻看板上。它不会帮你增加额度，也不会替你控制消费。它做的事很朴素：让你抬眼就知道 Claude 和 Codex 还剩多少、什么时候重置，以及本机累计用了多少 Token。

UsageHub Open 在 Android 横屏设备上的实际运行效果

我为什么做这块看板

Claude 和 Codex 给出的官方额度信息各自都能查到，但它们不在同一个地方。Token 历史又是另一套口径。只靠浏览器标签页，我很难在工作过程中形成稳定的用量感知。

我想要的是一块桌面仪表，不是另一套复杂后台。屏幕应该在两秒内回答四件事：

Claude 的 5 小时和 7 天用量是多少；
Codex 的短周期和周周期用量是多少；
各窗口还要多久重置；
今天及累计 Token 大约对应多少 API 费用。

费用栏写的是“API 等价估算”。它按标准 API Token 价格折算本机历史，不是 Claude 或 ChatGPT 订阅账单，也不能拿来推算账户会被扣多少钱。

为什么你会想用它

UsageHub Open 比较适合同时重度使用 Claude Code 和 Codex 的人。你可能有一台闲置 Android 平板、墨水屏设备或横屏手机，希望它长期显示工作状态。你也可能只用网页端，但想把两个工具的额度放在同一页。

它还有一个很实际的好处：采集端的代码、上传字段和接口契约都能审查。仓库公开了 Android 客户端、Claude/Codex 采集器、严格的数据结构，以及给 AI 编程代理读取的安装说明。

下面几种情况不必折腾：

你一周只偶尔用一次 Claude 或 Codex；
你只想查某一次额度，官方页面已经够用；
你要求把整套云服务部署在自己服务器上。当前开源范围不包含 SaaS、数据库、OAuth 和运维代码。

数据是怎么走的

数据链路没有读取聊天内容，也不需要把模型账号密码交给项目。

Claude Code statusLine ─┐
                       ├─> local collector ─> UsageHub ─> Web / Android
Codex local app-server ┘

ccusage / ccusage-codex ─> local token history and API-equivalent cost

Claude 额度来自 Claude Code 已公开的 statusLine 输入。Codex 额度来自本机只读的 account/rateLimits/read 调用。采集器会把原始数据裁成允许上传的数字字段，再加入随机生成的安装 ID。

安装前准备

普通用户需要：

一台 Android 11 或更高版本的设备，或直接使用网页看板；
一台正在使用 Claude Code / Codex 的电脑；
一个可以在本机执行安装任务的可信 AI 编程代理；
一个 UsageHub 账号。

如果只看网页，不需要安装 APK。Android 版更适合放在桌面长期显示。

第 1 步：安装 Android 显示端

打开 UsageHub Open 最新 Release，下载 app-standard-release.apk 并安装。

Standard 版是普通 Android 应用。它不会注册为系统 Home，也不会接管桌面。应用可以全屏、保持亮屏，并在自身位于前台时显示在锁屏上；PIN、图案或密码锁不会被绕过。

以后升级也应继续使用 Release 中的签名 Standard APK。Debug 构建不是稳定升级通道。

第 2 步：配对显示端

应用只兑换一次配对码，随后把只读 Display Token 保存在 Android Keystore 中。它只调用配对、看板和健康检查接口。配对完成后，屏幕已经能访问你的工作空间，但还要等电脑端采集器上传数据。

第 3 步：让 AI 代理接入电脑

在 UsageHub 网页打开“AI 接入”，给电脑起一个名字，点击“生成接入提示词”。把完整提示词交给运行在那台电脑上的可信 AI 编程代理。

提示词包含一个 10 分钟有效、只能使用一次的接入码。代理会完成下面这些工作：

检查 Node.js、ccusage 和 ccusage-codex；
安装并构建开源采集器；
保留你现有的 Claude 状态栏，再接入 UsageHub bridge；
把 Codex 采集器注册为 macOS LaunchAgent 或 Linux user service；
连续取样、上传并检查本地队列是否清空。

接入结束后，代理应该只报告安装目录、后台服务状态、最近一次成功上传时间和验证结果。它不应在聊天中打印接入码或长期 Token。

怎么确认真的装好了

不要只看“服务正在运行”。我建议同时确认四个结果：

网页和 Android 都出现 Claude 与 Codex；
额度窗口有百分比和重置倒计时；
今日 / 累计 Token 能更新，费用旁边明确标注 API 等价估算；
数据没有显示为 stale，电脑端待上传队列为 0。

某个平台暂时没有官方额度时，本地 Token 历史仍可以独立工作。采集器不会因为额度缺失就编一个 0%。

想从源码构建

仓库根目录需要 Node.js 22 或更高版本。Android Gradle 构建需要 Java 17。

git clone https://github.com/cfrs2005/usagehub-open.git
cd usagehub-open
npm ci
npm run check

Android Standard 调试包可以这样构建：

cd android
./gradlew testStandardDebugUnitTest lintStandardDebug assembleStandardDebug --no-daemon

我在发文前重新跑了当前源码的 npm run check。18 个采集器测试和 9 个契约测试全部通过，TypeScript 构建通过，敏感信息扫描结果为 secret_scan=ok。

隐私边界比功能更重要

采集器只上传允许的数字用量字段和随机安装 ID。它不会上传提示词、对话、账号邮箱、工作目录、Cookie、OAuth 凭据或 Claude/Codex 的访问令牌。

长期采集 Token 默认保存在 ~/.local/state/usagehub/ingest-token，文件权限只允许当前用户读取。一次性接入码过期后，应回网页重新生成，不要把长期 Token 复制到聊天里救急。

查看 UsageHub Open 源码。当前开源许可证是 Apache-2.0，最新稳定 Release 为 v0.1.4。