@token-dashboard/codex-usage-uploader

自动采集本机 Codex CLI 的 token 用量数据，并上报至 Token Data Dashboard 后端，用于团队用量统计与成本分析。

• 后台常驻运行，增量扫描本地 Codex session 数据
• 首次安装自动补采全量历史
• macOS launchd 托管，登录自启动可选

仅支持 macOS，需要 Node.js >= 22.13.0。

快速开始

一行命令完成安装、身份绑定、历史补采和后台服务启动：

npx @token-dashboard/codex-usage-uploader init

安装过程中会自动读取 Codex 登录态（~/.codex/auth.json）获取身份信息。如果读取不到邮箱，会在终端交互式提示你手动填写；同时会询问是否在这台 Mac 上启用登录自启动。

安装完成后，codex-usage-uploader 命令会被写入 ~/bin/，后续可直接使用。

命令一览

初始化 / 升级

codex-usage-uploader init

首次运行时完成安装与配置；重复运行会升级本地版本并重启后台服务，同时可重新选择是否启用登录自启动。后端地址默认为 http://101.126.66.51:8086，如需自定义可通过 --backend-url 指定。

绑定身份

codex-usage-uploader bind
codex-usage-uploader bind --email [email protected] --yes

更新上报身份。如果后台服务正在运行，会自动重启以应用新身份。

后台服务管理

| 命令 | 说明 | | --------------------------------------- | ------------------------------- | | codex-usage-uploader start | 启动后台服务 | | codex-usage-uploader stop | 停止后台服务 | | codex-usage-uploader restart | 重启后台服务 | | codex-usage-uploader status | 查看服务状态与本地队列 | | codex-usage-uploader logs | 查看服务日志（默认最近 100 行） | | codex-usage-uploader logs --lines 500 | 查看更多日志 |

查看本机 token 用量

codex-usage-uploader usage
codex-usage-uploader usage --period today
codex-usage-uploader usage --period 7d
codex-usage-uploader usage --from 2026-04-01 --to 2026-04-17

usage 是一个纯本地只读命令，不依赖后端查询，也不要求先执行 init。它会重新扫描当前机器上的 Codex rollout 文件，默认同时包含：

• ~/.codex/sessions
• 同级的 ~/.codex/archived_sessions

默认输出是一张纯文本表格，列为 Date、Models、Input、Output、Reasoning、Cache Read、Total Tokens，最后一行固定为 Total。默认 --period=all 时，表格覆盖全历史所有有 token 使用的日期。

统计口径与现有 uploader/后端保持一致，使用 token_count 事件中的 last_* token 字段，而不是累计 total_* 字段。切天时区使用当前机器时区。

清除本地状态

codex-usage-uploader clear --yes

清空本地补采进度和待上传队列，不影响已绑定的身份。服务端清库后需要重新补历史时使用：

codex-usage-uploader stop
codex-usage-uploader clear --yes
codex-usage-uploader init

卸载

codex-usage-uploader uninstall

停止后台服务并删除本地安装目录。

常用选项

| 选项 | 说明 | | ------------------------ | ------------------------------------------------------ | | --backend-url <url> | Dashboard 后端地址（默认 http://101.126.66.51:8086） | | --email <email> | 绑定邮箱 | | --employee-name <name> | 绑定姓名 | | --employee-id <id> | 绑定工号 | | --interval <seconds> | 扫描间隔秒数（默认 30） | | --period <value> | usage 时间范围：today、7d、30d、all | | --from <date> | usage 开始日期（YYYY-MM-DD） | | --to <date> | usage 结束日期（YYYY-MM-DD） | | --yes | 跳过所有交互确认 | | --lines <n> | logs 命令输出行数（默认 100） | | -h, --help | 显示帮助 |

工作原理

1. init 将包安装到 ~/.codex-usage-uploader/，绑定身份后前台执行一次全量历史补采，完成后启动 macOS launchd 后台服务，并按交互选择决定是否启用登录自启动。
2. 后台服务每 30 秒（可通过 --interval 调整）增量扫描 ~/.codex/sessions/ 下的 rollout 文件。
3. 扫描到的 token 用量数据暂存在本地 SQLite 队列中，满足条件后自动封批上传至后端。
4. usage 命令会按需重扫本地 sessions + archived_sessions，直接在终端计算并展示本机 token 用量，不写入本地状态库，也不访问后端。
5. 所有数据在上报前已做去敏处理，仅包含 session 元信息、turn 上下文摘要和 token 计数。

本地文件

| 路径 | 说明 | | -------------------------------------- | -------------- | | ~/.codex-usage-uploader/config.json | 运行配置 | | ~/.codex-usage-uploader/state.sqlite | 本地状态数据库 | | ~/.codex-usage-uploader/logs/ | 服务日志 | | ~/.codex-usage-uploader/launchd/ | launchd service plist |

License

MIT