快速开始

前置条件

一个可访问的 CLIProxyAPI management gateway
CPA management key；除非你明确使用会自动注入 key 的本地 proxy
一个可访问的 gateway health endpoint
可选的 Codex auth 文件目录；如果你想做 direct quota sampling，就需要它

裸 CPA endpoint 需要先准备一个 key file，内容必须和 CPA remote-management.secret-key 的明文值一致。较新的 CPA 在这个 secret 为空时会让 /v0/management/* 返回 404。如果你明确使用会注入 Authorization 的本地 proxy，把 managementBaseUrl 指向那个 proxy，并省略 key file。

把 monitor 指向真实 key 或 auth 文件前，先看安全自审计。它说明数据流、残余风险，以及本地验证 secret 脱敏的检查方式。

如果只是想先预览 UI，可以直接运行 demo 模式：

codex-quota-monitor --demo

--demo 默认会在 127.0.0.1:4516 提供内置示例数据，可以和正常监听 127.0.0.1:4515 的 monitor 同时运行。它不会读取 auth files、management key、 SQLite history、benchmark summary 或 CPA endpoint。浏览器里的 Privacy 按钮默认显示原文；点击后只在当前浏览器页面上打码邮箱和 token-like 字符串。这个开关只影响显示层，/api/* 和 /metrics 仍保持原始机器可读 payload。

典型本机值：

managementBaseUrl = http://127.0.0.1:8317
managementKeyFile = /path/to/management-key
gatewayHealthUrl = http://127.0.0.1:8317/healthz
port = 4515
displayTimezone = local
uiFontFamily = system UI stack
monoFontFamily = system monospace stack

用 Nix 运行

v0.2.0 发布后，可以直接从 release flake 运行：

nix run github:xsyxnx/codex-quota-monitor/v0.2.0#codex-quota-monitor -- \
  --management-base-url http://127.0.0.1:8317 \
  --management-key-file /path/to/management-key \
  --gateway-health-url http://127.0.0.1:8317/healthz \
  --auth-dir /path/to/auth-files

只有在你明确需要局域网访问时才开放监听：

nix run github:xsyxnx/codex-quota-monitor/v0.2.0#codex-quota-monitor -- \
  --host 0.0.0.0 \
  --allowed-host monitor.lan \
  --port 4515 \
  --management-base-url http://127.0.0.1:8317 \
  --management-key-file /path/to/management-key \
  --gateway-health-url http://127.0.0.1:8317/healthz \
  --auth-dir /path/to/auth-files

把 monitor.lan 换成浏览器实际访问时会放进 Host header 的域名或 IP。 dashboard 会拒绝非预期的 Host 和 Origin。

默认会用 weekly 剩余 * 6.0 约束总 5h 容量。用 --weekly-to-five-hour-multiplier <数字> 可以覆盖倍率，用 --weekly-to-five-hour-multiplier off / none 可以关闭这个 cap。 Reset 时间默认使用服务本地时区。需要固定显示时区时，用 --display-timezone UTC、--display-timezone Asia/Shanghai 或其它 IANA 时区名。 Dashboard 语言默认 --display-locale auto，会跟随浏览器，目前支持 en 和 zh-CN；需要服务级固定默认值时可用 --display-locale zh-CN 或 --display-locale en。需要调整服务默认字体时，用 --ui-font-family 和 --mono-font-family 传 CSS font-family 列表。Dashboard 里也有浏览器本地 Preferences，会只覆盖当前浏览器的服务默认值。项目不内置字体文件；"Maple Mono NF CN" 这类字体名只有在渲染页面的设备已安装该字体时才会命中。

直接 nix run 默认不写 SQLite 历史。需要 Trends、ETA、Audit 或 Stats 时间序列 workbench 时，给它一个可写 state DB；Trends 标签页会展示最近 6h 的历史样本，Stats 会用同一个数据库展示 token/request 曲线并支持 JSON/CSV 导出：

nix run github:xsyxnx/codex-quota-monitor/v0.2.0#codex-quota-monitor -- \
  --state-db ./result/codex-quota-monitor.sqlite3 \
  --management-base-url http://127.0.0.1:8317 \
  --management-key-file /path/to/management-key \
  --gateway-health-url http://127.0.0.1:8317/healthz \
  --auth-dir /path/to/auth-files

PyPI、Docker、Debian/Ubuntu systemd 和 Windows 说明见安装指南。

用 Python 运行

uv tool install codex-quota-monitor==0.2.0
codex-quota-monitor init --mode user
codex-quota-monitor \
  --management-base-url http://127.0.0.1:8317 \
  --management-key-file /path/to/management-key \
  --gateway-health-url http://127.0.0.1:8317/healthz \
  --auth-dir /path/to/auth-files

如果你在 tag 发布前预览源码，可先从源码安装：

uv tool install 'git+https://github.com/xsyxnx/codex-quota-monitor.git'

如果你更习惯 pipx，也可以用 pipx install codex-quota-monitor==0.2.0，源码安装时使用同一个 git+https://... URL。 Python 安装后，cqm 是 codex-quota-monitor 的等价短别名。

init 会打印可复制的 config.toml、rootless systemctl --user service 和下一步 smoke check。除非传 --output-dir，它不会写系统路径。

用 Docker 运行

docker run --rm \
  --add-host=host.docker.internal:host-gateway \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --tmpfs /tmp \
  -p 127.0.0.1:4515:4515 \
  -e CODEX_QUOTA_MONITOR_MANAGEMENT_BASE_URL=http://host.docker.internal:8317 \
  -e CODEX_QUOTA_MONITOR_MANAGEMENT_KEY_FILE=/management-key \
  -e CODEX_QUOTA_MONITOR_GATEWAY_HEALTH_URL=http://host.docker.internal:8317/healthz \
  -v codex-quota-monitor-data:/data \
  -v /path/to/management-key:/management-key:ro \
  -v /path/to/auth-files:/auth-files:ro \
  -e CODEX_QUOTA_MONITOR_AUTH_DIR=/auth-files \
  ghcr.io/xsyxnx/codex-quota-monitor:0.2.0

只挂载 monitor 需要的具体 management key 文件和 auth-files 目录，并保持只读；裸 CPA endpoint 挂载的 key file 必须和 CPA remote-management.secret-key 一致。不要把整个 home、.config 或其它无关 secret 目录挂进容器。

如果你在 GHCR release image 发布前预览源码，可先用 docker build -t codex-quota-monitor:local . 本地构建。

共享 Client Labels

CPA usage details 如果用 apiName / api_name 标识共享 client，可以添加一个小 JSON label 文件，并在 Stats 里选择 Client 分组，按 friend 统计 requests / tokens：

{
  "clients": [
    {"apiName": "sk-example-from-cpa", "label": "Alice"},
    {"api_name": "rotated-api-name", "label": "Alice"}
  ]
}

启动时传 --client-labels-file /path/to/client-labels.json。这个文件应按运行时 secret 处理；未映射 client 会显示短 fingerprint。

Smoke Test

cqm tldr
cqm print-config
cqm doctor
curl -fsS http://127.0.0.1:4515/healthz
curl -fsS http://127.0.0.1:4515/api/v1/status | jq '.summary'
curl -fsS http://127.0.0.1:4515/api/v1/recommendations | jq '.summary'
curl -fsS 'http://127.0.0.1:4515/api/v1/stats/series?range=24h&metric=tokens' | jq '.summary'
curl -fsS 'http://127.0.0.1:4515/api/v1/stats/series?range=24h&group=client' | jq '.breakdown.clients'
curl -fsS http://127.0.0.1:4515/api/v1/diagnostics | jq '.summary'
curl -fsS http://127.0.0.1:4515/api/v1/alerts | jq '.'
curl -fsS http://127.0.0.1:4515/metrics | sed -n '1,20p'

进程起来之后，在浏览器打开 http://127.0.0.1:4515/。

Benchmark

如果你还想测 fast 相对 baseline 的表现，或者想把 Team 的 quota 容量折算成 Plus 单位，见 Benchmark 指南。