限制说明

English

codex-quota-monitor 面向一个明确的 operator 工作流：监控自托管的 CLIProxyAPI backed Codex OAuth 账号池。如果你运行的是这类系统，它会很有用；超出这个边界时，它有意保持不完整。

产品边界

它不是覆盖所有 AI 产品的通用桌面 usage tracker。
它不负责安装、配置或替代 CLIProxyAPI。
它不创建账号、不管理订阅、不收集凭据，也不绕过 provider 侧 quota policy。
它不提供托管 analytics、云端采集、内置登录、RBAC、多租户隔离或用户访问审计日志。
它不会自动让 LAN 或公网暴露变得安全。共享 dashboard 时应使用带认证的反向代理或访问层。

数据准确性

Dashboard 会组合多种由 operator 控制的数据源：CPA management endpoints、 gateway health、可选的 direct Codex quota sampling、可选 SQLite history，以及可选 benchmark summary。输入缺失或过期时，账号级 quota 详情可能显示 Unknown，但 5h 和 weekly pool headline 会显示当前已知的 Plus 等价容量，不会把整个 headline 替换成 Unknown。

重要影响：

CPA usage 和 direct quota windows 可能不一致，因为它们来自不同系统。
Reset 时间取决于 direct quota sampling 能观察到什么。
direct quota 返回 deactivated_workspace 表示账号或 workspace 不可用，会从 Plus-unit capacity 和账号推荐中排除。
Trends 和 ETA 需要足够的 SQLite history 才有意义。
Benchmark calibration 的可信度取决于生成它的 benchmark run 和 selectors。
非 Plus 计划可以保持可见，但除非项目已经为该计划定义了明确换算规则，否则不应计入 Plus-unit pool totals。
Stats client 分组是在查询 / 渲染时由已存 CPA API name 和 --client-labels-file 派生的显示层；修改 label 文件不会重写 SQLite history。兼容用的 api 分组仍可能暴露原始 CPA API name，它不是隐私保护型分账视图。

Unknown 表示数据之后可能出现。n/a 只应用在状态确实不适用的时候。

API 兼容性

HTTP API 基本是只读的。受保护的 POST /api/v1/quota/refresh 是例外，默认使用页面内 refresh token。旧部署可以显式设置 manual_quota_refresh_auth = "management-key"，要求用 CPA management key 作为 bearer token；"none" 只适合可信本地部署。在 0.x 阶段，client 应预期 JSON 会增加新字段，并忽略自己不理解的字段。文档列出的 stable fields 应保持语义稳定，但项目还没有到 1.0；把精确 payload shape 接进自动化前，请先看 release notes。

API 不是认证边界。Host / Origin 检查可以减少浏览器误用，但不会认证访问者身份。

部署限制

安全默认值是只监听 127.0.0.1。LAN 访问需要显式 listen address、allowed-host 配置、防火墙决策，并且最好放在带认证的反向代理后面。

NixOS 部署中，services.codexQuotaMonitor.openFirewall 有意默认保持 false。

Container 和 service 部署只应挂载所需的 management key 文件、auth-file 目录和可写 state path。挂载整个 home、password store 或无关 secret 目录不属于预期模型。如果使用 client labels，只额外挂载那一个受保护的 JSON 运行时文件。

安全限制

Monitor 为了完成工作，必须读取敏感的 operator 状态。host、Python runtime、container runtime、browser、reverse proxy、CPA process 或 root account 被攻破时，仍然可能泄露 secret 或运维 metadata。

项目目标是避免把原始 management key 和 OAuth token 值序列化进 UI、API、metrics、history、benchmark summary、diagnostics 和 logs。账号 label、plan tier、quota timing、model activity、health state、SQLite history、截图和 benchmark output 仍可能敏感。

挂载真实凭据或把 dashboard 暴露到 loopback 之外前，先阅读安全自审计。