Codex Quota

核心用法

codex-quota 是一款轻量级 Python 工具，用于监控 OpenAI Codex CLI 的速率限制状态。它通过读取本地会话日志文件（~/.codex/sessions/ 下的 JSONL 文件），提取最新的 rate_limits 数据，直观展示 5 小时短期窗口和 7 天长期窗口的配额使用情况。

主要功能

• 离线查询：默认读取本地缓存，无需 API 调用
• 实时刷新：--fresh 模式先触发 Codex 会话获取最新数据
• JSON 输出：--json 便于脚本集成和数据处理
• 友好展示：本地时区转换 + 倒计时显示

显著优点

1. 零配置即用：单文件 Python 脚本，无依赖项（标准库即可运行）
2. 隐私安全：数据完全本地处理，不向第三方发送任何信息
3. 跨平台：Python 脚本天然支持 macOS/Linux/Windows
4. 精准溯源：显示数据来源会话文件及时间戳，便于审计

潜在缺点与局限性

• 依赖 Codex CLI 日志格式：若 OpenAI 更改日志结构，工具可能失效
• 非官方工具：非 OpenAI 官方支持，无 SLA 保障
• 仅支持已登录会话：需先有 Codex CLI 使用记录才能提取数据
• 功能单一：仅做配额查询，无配额预警或自动化管理功能

适合人群

• 高频 Codex 用户：需要随时掌握剩余额度，避免工作流中断
• 多账户开发者：快速切换检查不同账号的配额状态
• 自动化运维：结合 --json 输出集成到 CI/CD 或监控脚本

常规风险

• 日志文件权限：需确保对 ~/.codex/sessions/ 目录有读取权限
• 数据时效性：缓存模式可能显示过期配额，关键决策建议用 --fresh
• 路径硬编码：若 Codex CLI 更改默认存储路径，需手动调整脚本

核心用法

codex-quota 是一款轻量级 Python 脚本，用于监控 OpenAI Codex CLI 的 API 速率限制状态。用户可直接运行 ./codex-quota.py 或安装到 PATH 后使用 codex-quota 命令。支持三种运行模式：默认模式读取本地缓存的最新会话数据；--fresh 模式先调用 Codex CLI 获取实时数据；--json 模式输出结构化 JSON 便于二次处理。

工具解析 Codex CLI 在 ~/.codex/sessions/ 目录下生成的 JSONL 会话日志，提取其中的 rate_limits 对象，格式化展示Primary Window（5 小时短期限制）和Secondary Window（7 天周限制）的剩余配额、重置时间及倒计时。

显著优点

1. 零依赖安全架构：仅使用 Python 标准库（json、os、sys、datetime、pathlib、subprocess），彻底规避供应链攻击风险，无需 pip 安装任何包。

2. 纯本地数据处理：所有操作限于本地文件系统，无 HTTP/HTTPS 网络请求，API 密钥等敏感信息始终保留在 Codex CLI 内部，工具本身不接触凭证。

3. 精准功能边界：严格聚焦单一职责——配额查询，无超出声明范围的行为。子进程调用仅限 Codex CLI 原生命令，无命令注入向量。

4. 开发者友好设计：输出格式清晰，支持 JSON 导出便于脚本集成；MIT 开源许可证允许自由修改分发。

潜在局限性

• 功能单一性：仅支持速率限制查询，不提供配额预测、历史趋势分析或自动限流保护功能。

• 依赖 Codex CLI 存在性：--fresh 模式要求目标系统已安装并配置好 Codex CLI，否则需用户自行排查。

• 会话文件时效性：默认模式依赖最近一次会话的缓存数据，若 Codex 长期未使用，显示信息可能滞后。

• 平台假设：隐式假设标准 Unix 路径结构（~/.codex/sessions/YYYY/MM/DD/），未明确支持 Windows 路径格式。

适合人群

• 高频使用 Codex CLI 的开发者，需在工作前快速确认配额余量
• 多账号管理场景下需要监控各账户配额分配的团队
• 对工具安全性要求严苛、拒绝安装第三方依赖的谨慎用户
• 希望将配额查询集成到自动化工作流（CI/CD、定时脚本）的运维人员

常规风险

• 版本兼容风险：Codex CLI 的会话日志格式若未来变更，可能导致解析失败，需关注上游更新。

• 误读 stale 数据风险：用户可能忽略默认模式使用缓存数据，在配额实际已重置的情况下做出错误判断，建议高频场景配合 --fresh 使用。

• 路径遍历边界：虽当前实现严格限定 ~/.codex/sessions/ 目录，但若未来扩展功能时未保持路径校验，可能引入文件系统越界访问。

整体而言，这是一个安全设计优秀、功能聚焦的实用小工具，适合对供应链安全敏感的技术用户日常使用。