核心用法
codex-cleaner 是专为 Codex Provider Agent (CPA) 设计的认证文件管理工具，通过 CPA 管理 API 实现无效 auth 文件的生命周期管理。工具采用纯 Python 标准库实现，零外部依赖，支持从初始化配置到定时监控的完整工作流。
初始化配置：首次运行 python3 scripts/codex_cleaner.py setup 启动交互式向导，配置 CPA 地址和管理员密钥，配置信息保存至 config.json（自动加入 gitignore）。配置优先级遵循：命令行参数 > 环境变量（CPA_URL/CPA_KEY）> 配置文件。
命令体系：
status：查看当前认证文件状态，支持--json输出check：并发检测活跃文件配额状态，自动禁用返回 401 的失效文件delete：对禁用文件执行双验证删除（两次 401 确认 + 2 秒间隔），防止误删临时故障文件clean：check+delete组合命令，支持--report生成可读报告或--json结构化输出monitor：循环监控模式，默认 300 秒间隔，适合长期守护运行
Nanobot 集成：可通过 HEARTBEAT 或 cron 定时执行 clean --report，将标准输出报告通过 message 工具推送给用户，实现运维自动化。
显著优点
1. 安全删除机制：独创「双验证 + 延迟确认」流程，两次独立检测 401 状态并间隔 2 秒，有效规避因网络抖动或 CPA 瞬时故障导致的误删风险
2. 零依赖部署：仅依赖 Python 标准库，无需 pip 安装，适配各种受限环境
3. 配置灵活：三层配置优先级 + 环境变量支持，便于容器化与 CI/CD 集成
4. 可观测性：内置结构化报告（含 Emoji 状态图标），支持 JSON 输出便于下游处理
5. 并发优化：默认 20 并发配额检测，提升大规模文件处理效率
潜在缺点与局限性
1. 硬编码延迟：delete 阶段的 2 秒固定延迟在极端高频场景可能成为瓶颈，未提供自定义参数
2. 通知渠道单一：配置文件中仅支持 Telegram，缺乏 webhook、邮件等通用通知方式
3. 状态判定简化：仅依赖 HTTP 401 状态码判定失效，无法识别配额耗尽、速率限制等边缘情况
4. 无回滚机制：删除操作不可逆，虽已双验证，但无备份或回收站机制
5. 日志粒度粗：未提及详细日志级别控制，问题排查可能依赖报告输出
适合人群
- CPA 管理员：需要定期维护数十至数百个 Codex 认证文件的运维人员
- 自动化运维工程师：寻求无依赖、易集成的定时任务脚本进行基础设施维护
- 多租户平台开发者：需要程序化清理失效服务商凭证的平台侧开发者
- Nanobot 用户：希望将认证文件健康检查纳入自动化工作流的终端用户
常规风险
| 风险类型 | 描述 | 缓解建议 |
|---------|------|---------|
| 误删风险 | 双验证机制虽降低概率，但 CPA 连续异常时仍可能误删有效文件 | 执行前确认 CPA 服务健康，首次使用建议手动 `check` 观察后再 `delete` |
| 权限泄露 | `cpa_key` 存储于明文 `config.json`，存在泄露风险 | 优先使用环境变量注入，配置文件设置严格权限（600），避免提交至版本控制 |
| 网络中断 | `check`/`delete` 过程中 CPA 失联可能导致状态不一致 | 配合 `status` 命令校验最终状态，关键操作前执行连通性检查 |
| 并发冲击 | 高并发检测可能对 CPA 造成压力 | 根据 CPA 性能调整 `concurrency` 参数，监控 CPA 资源使用率 |
安全等级说明
工具本身实现简洁，无网络服务暴露，操作仅限于 CPA 管理 API 调用。主要风险集中于配置管理与 CPA 通信安全，建议配合 TLS 与密钥轮换策略使用。