AI 用量账本，账户额度、Token 消耗、费用估算与多维统计。
Meterleaf 可以只读采集一个 Sub2API PostgreSQL 实例，也可以接收采集器推送的 Claude Code、Codex 本地用量和 CLIProxyAPI（CPA）插件账本。各来源可单独或同时使用，用量保存到本地 SQLite 并生成独立报表。不代理模型请求、不修改上游，也不直接请求 OpenAI 或 Anthropic；账本服务单个容器即可运行，CPA 接入另启一个同步容器。
- 用量总览：默认看历史至今的 Tokens、费用、请求和缓存命中率，可切到今天、近 7 天等范围；下方是同一范围的消耗趋势和模型分布。
- 账户额度：总览中按当前周期显示 5 小时与 7 天窗口、重置时间及七天额度预估；支持排序、重命名、归档，以及将多个来源账户的额度与用量合并到目标账户，随时可解除。
- 统计报表：顶部是所选范围的摘要与环比，按小时、天、周、模型或账户汇总 Tokens、缓存命中率、请求数和费用，附合计行。
- 请求明细：查看模型、来源、推理强度、Token 拆分与计价依据。
- Claude Code 本地用量：不经过网关的 Claude Code 由 Mac 上的本机采集器推送用量、套餐和 5 小时、7 天及 Fable 周额度，与网关用量在同一账本中统计。
- 独立估值：同时保留订阅 Credits 与 USD，美元可切换订阅等价和标准 API 口径。
- 独立估值：同时保留订阅 Credits 与 USD，美元可切换订阅等价和标准 API 口径。
支持自定义日期、页面筛选、明暗主题和移动端；同步在后台进行，已有报表继续可读。
统计报表
请求明细
| 用量总览 | 统计报表 |
|---|---|
请求明细
Meterleaf 支持以下数据来源，至少配置一种。
- Sub2API 网关：在
.env填写SUB2API_DATABASE_URL。数据库账号只需读取public.accounts和public.usage_logs，不需要写权限。 - 本地直连的 Claude Code：在
.env填写本机采集器生成的METERLEAF_INGEST_KEYS，见下文接入 Claude Code。只用 Claude Code 时把SUB2API_DATABASE_URL留空，并先生成写入密钥再启动服务。 - CLIProxyAPI（CPA）：使用可选同步容器只读接入 usage-report 插件的历史和新增请求，见接入 CPA。它统计经过 CPA 的请求，不读取本机 Codex 会话。
- Codex 与 OpenCode 本地用量：同一个采集器逐轮读取 Codex 会话记录与 OpenCode 本地数据库的用量，按真实付费通道排队到正确账户，不再依赖按模型写死的月度上限。配置与统计边界见本机采集器。
在仓库目录中准备配置：
cp .env.example .env按上面填写 .env，然后运行：
docker compose build
mkdir -p app_data
docker compose run --rm --no-deps --pull never --user root --entrypoint sh meterleaf -c 'chown bun:bun /app/app_data'
docker compose up -d --pull never访问 http://127.0.0.1:4318。连接了 Sub2API 时，从右上角「数据同步」启动首次采集，默认不自动采集，可自行开启自动同步。只用 Claude Code 时没有这个入口，采集器推送后数据自动出现。
已发布镜像的拉取方式、跨主机访问、反向代理、配置项及备份恢复见部署指南。对外开放前可开启 GitHub 登录，只允许指定账号访问。
本地直连的 Claude Code 需要在使用它的 Mac 上安装本机采集器。采集器暂不提供下载，需要在 Mac 上构建，要求 Bun 与 Xcode 命令行工具：
bun install --frozen-lockfile
bun run build:collector把 dist/Meterleaf.app 移到「应用程序」，然后生成写入密钥。--server 填这台 Mac 能访问到的 Meterleaf 地址，服务端不在本机时先按部署指南开放访问：
/Applications/Meterleaf.app/Contents/MacOS/meterleaf-collector init --server https://meterleaf.example.com命令会打印一行 METERLEAF_INGEST_KEYS=来源标识:摘要。把它加到服务端的 .env，再执行一次 docker compose up -d --pull never 让配置生效（docker compose restart 不会读取新配置）。之后在 Mac 上依次执行 bind-history、sync 和 install-launchd，每一步的含义见本机采集器。
- 使用与报表：筛选、账户管理、同步显示及统计口径。
- 部署指南：安装、环境变量、升级、备份和排障。
- 计价说明：USD 分支、费率版本与自定义 JSON。
- 本机采集器：接入本地直连的 Claude Code 用量、账户与额度。
- 接入 CPA：只读同步 CPA 插件账本、按来源查看，以及重复统计和费用估算的边界。
- 贡献指南：目录结构、代码规范、测试与提交要求。
- 版本与发布：版本递增、双架构镜像及 Release 流程。
本地演示无需上游凭据，需要 Bun 1.4.4 或更新版本：
bun install --frozen-lockfile
bun run dev:demoApache-2.0。第三方组件声明见 THIRD_PARTY_NOTICES.md。