Codex Usage

核心用法

codex-usage 是一个本地 CLI 辅助工具，用于读取并报告 OpenAI Codex CLI 的授权配置文件健康度与远程使用配额。执行时解析 ~/.openclaw/agents/main/agent/auth-profiles.json 中的 OAuth 凭证，向 chatgpt.com/backend-api/wham/usage 发起 HTTPS 查询，返回 5 小时窗口及周度剩余额度、速率限制状态、Token 过期时间等关键指标。支持 /codex_usage、/codex_usage default|all|<profile> 等多种 Telegram 风格指令，提供交互式按钮或文本菜单选择器，并在执行前发送进度提示以优化 UX。

显著优点

• 只读安全优先：默认仅执行查询，所有删除操作需显式 --confirm-delete 与 --dry-run 预览，避免误删。
• 多配置管理：原生支持多 Profile（如 openai-codex:default、openai-codex:mine），适合团队或公私项目分离场景。
• 容错降级：端点不可达时自动降级为本地健康报告；401 错误时标记为 auth_not_accepted_by_usage_endpoint 而非崩溃。
• 隐私保护：全程隐藏完整 Token，仅输出脱敏的健康与配额元数据。
• 诊断友好：内置 --debug 模式，输出 attempt、elapsed_ms、status 等追踪字段，便于排查网络或认证问题。

潜在局限

• 依赖本地凭证：若用户从未运行过 Codex CLI 或凭证文件路径非标准，需手动指定 --auth-path。
• 仅支持 ChatGPT 端点：当前硬编码 chatgpt.com 用量 API，暂不兼容企业私有部署或其他 OpenAI 端点。
• Token 生命周期盲区：脚本可报告过期时间，但无法主动刷新或续期 Token，需用户手动重新授权。
• 删除操作不可逆：尽管有备份机制，--hard-delete 仍会永久移除配置文件，误操作后恢复需手动还原备份。

适合人群

• 高频使用 Codex CLI 的开发者与 DevOps，需监控多账户配额消耗。
• 团队管理员，需定期检查成员授权健康状态（Token 是否过期、是否触发限速）。
• 将 Codex 集成至 CI/CD 或自动化工作流前，需做预检配额与认证可用性验证的场景。

常规风险

• 凭证泄露风险：虽然脚本本身不打印 Token，但运行环境（日志、shell 历史、CI 输出）若未妥善配置，可能间接暴露 --auth-path 指向的文件路径。
• 网络中间人：尽管强制 HTTPS 并限制 chatgpt.com 白名单，运行环境的 SSL/TLS 库若过期或遭篡改，仍存在证书校验绕过风险。
• 误删除配置：用户可能混淆 --confirm-delete 与 --dry-run 的顺序，导致预期外的配置 detach 或硬删除。
• API 行为变更：OpenAI 端点响应格式或认证头要求可能更新，脚本需随上游文档同步维护。

核心用法

codex-usage 是一个用于查询 OpenAI Codex 使用状态和配额限制的本地命令行工具。用户通过 Telegram 风格的斜杠命令触发，支持 /codex_usage、/codex_usage default、/codex_usage all 以及指定 Profile 的查询模式。工具从本地 ~/.openclaw/agents/main/agent/auth-profiles.json 读取 OAuth 凭证，向 OpenAI 官方 chatgpt.com 端点发起 HTTPS 请求，返回包含 5 小时窗口、周配额剩余量、限流状态等信息的结构化报告。

交互层面支持内联按钮选择（default/all/发现的 Profile）和文本菜单回退，具备 20 秒重复请求抑制机制防止误触刷屏。删除操作需显式 --confirm-delete 确认，默认采用安全脱钩模式（仅从 order/lastGood 移除，保留 token），可选 --hard-delete 永久删除并自动备份。

显著优点

安全设计是该 Skill 的核心亮点。敏感信息通过 scrub_sensitive() 函数自动脱敏，access token、refresh token 等字段输出为 [redacted]，杜绝凭证泄露风险。网络请求严格限制在 ALLOWED_ENDPOINT_HOSTS 白名单（仅 chatgpt.com HTTPS），非白名单域名会被强制重置为默认端点。

依赖层面极为干净，仅使用 Python 标准库（argparse、json、urllib、pathlib 等），零第三方依赖意味着供应链攻击风险为零。输出格式友好，包含 summary、formatted_profiles、suggested_user_message 等字段，便于直接嵌入聊天机器人响应；同时提供 reset_in、reset_at 等本地化时间提示，用户体验细腻。

潜在缺点与局限性

功能单一性是一把双刃剑。该 Skill 仅限读取 Codex 使用配额，无法主动管理额度、充值或调整配额策略，本质是一个只读监控工具。网络依赖方面，若 chatgpt.com 端点不可达或返回 401，工具会降级为本地健康状态输出，此时无法获取实时配额数据。

来源可信度为 T3 级别（本地临时路径），缺乏 GitHub 仓库信誉背书（star 数、作者历史、维护活跃度），用户需自行验证代码完整性。此外，读取本地 OAuth 凭证文件涉及隐私敏感操作，虽然已脱敏处理，但仍要求文件系统权限隔离到位。

适合的目标群体

主要面向 OpenAI Codex CLI 的重度用户和开发者，尤其是需要同时管理多个 Profile（如 default、openai-codex:work、openai-codex:personal）的团队工程师。适合集成到内部运维机器人或 Slack/Telegram 工作流中，作为实时配额告警的基础设施。对安全敏感的企业环境也适用，因无外部依赖、无动态代码下载、无危险函数调用，可通过代码审计后白名单部署。

不适合需要复杂配额策略管理、多服务商统一监控或离线历史数据分析的场景——它只是一个轻量的、聚焦 Codex 的实时状态探头。

使用风险

性能风险：查询依赖外部 HTTPS 请求，默认 25 秒超时和 1 次重试，网络抖动时可能延迟响应。建议在高频调用场景下增加本地缓存层。

依赖项风险：虽无第三方依赖，但依赖 Python 标准库版本兼容性。pathlib 在 Python 3.4+ 才稳定，老旧环境可能需适配。

凭证泄露风险：虽然输出已脱敏，但进程运行时内存中仍持有原始 token。建议在容器化或受限环境中运行，避免进程内存被转储。

误操作风险：--hard-delete 会永久删除 Profile 和 usage 条目，虽有备份机制，但恢复需手动干预。建议优先使用默认脱钩模式。

来源验证风险：T3 可信度意味着代码未经社区广泛审计，生产环境使用前建议与官方发布版本进行哈希比对，或从可信渠道重新安装。