cpa-warden：一个命令行CLIProxyAPI认证文件管理脚本，支持自动删除401账号，自动禁用限额账户功能

---

Change Log

[0.2.0] - 2026-03-09

新增

• 新增 upload 模式：通过 POST /v0/management/auth-files 并发上传本地认证 JSON 文件。
• 新增上传相关 CLI/配置项：upload_dir、upload_workers、upload_retries、upload_method、upload_recursive、upload_force。
• 新增 SQLite 表 auth_file_uploads：用于上传状态跟踪与并发场景下的幂等去重。
• 新增 maintain-refill 模式：维护后自动补齐最小有效账号阈值。
• 新增补量与外部注册钩子配置：min_valid_accounts、refill_strategy、auto_register、register_command、register_timeout、
  register_workdir。
• 新增限额自动禁用阈值：quota_disable_threshold / --quota-disable-threshold（0~1，默认 0）。
• 新增自动恢复范围控制：reenable_scope / --reenable-scope（signal 或 managed，默认 signal）。

变更

• 默认 probe_workers 从 40 提升到 100。
• 默认 action_workers 从 20 提升到 100。
• 默认 retries 从 1 提升到 3。
• upload 模式在任意文件校验或上传失败时会以非零状态退出。
• maintain-refill 在维护后有效账号仍低于阈值时会以非零状态退出。
• 文档统一使用 cpa_warden.py 作为 CLI 入口。
• 限额判定支持阈值禁用：剩余额度比例 <= quota_disable_threshold 即可触发（limit_reached 兜底逻辑保持不变）。
• Pro 计划限额信号选择优化：Spark 信号不完整（limit_reached 不可用）时回退到主 rate_limit。
• 探测重试策略优化：429 与 5xx 进行退避重试，其他 4xx 快速失败。
• 布尔配置改为严格解析（true/false/1/0/yes/no/on/off），避免字符串误判。
• 恢复账号判定改为依赖实时 usage 信号 + 当前禁用状态，并由 reenable_scope 控制“全部信号恢复”或“仅工具管理恢复”。

[details=“过去的Change Log”]

[0.1.0] - 2026-03-01

新增

• 面向本地 CLIProxyAPI (CPA) (https://github.com/router-for-me/CLIProxyAPI) 运维的交互式 scan / maintain 工作流。
• 外部 JSON 配置（连接参数与运行行为）。
• 通过 CLIProxyAPI api-call 并发探测 wham/usage。
• 基于 SQLite 的认证清单与探测结果状态跟踪。
• 401 失效账号与限额账号 JSON 导出。
• TTY 环境下的 Rich 进度展示。
• 全量调试日志写入日志文件。
• 英文与简体中文 README。
• 贡献指南、Issue 模板、PR 模板。
• CI 工作流（依赖同步、字节码编译、CLI 帮助检查）。

变更

• 项目命名由 cpa-clean 更名为 cpa-warden。
• 明确了基于 auth-files 清单与 wham/usage 探测的账号分类逻辑。
• 终端输出保持简洁，详细信息沉淀到日志文件。

Github链接：https://github.com/fantasticjoe/cpa-warden

在LinuxDO论坛上学习了一些佬的CPA认证文件管理脚本，想自己写一个练练手，于是在cc和codex的帮助下自己从抓包开始写了一个终端的CPA认证脚本管理工具，下面是项目介绍

cpa-warden 是一个面向本地运维场景的交互式 CLIProxyAPI（CPA） 认证文件扫描与账号维护工具，适用于特定 CPA 管理环境。

它当前依赖两类管理接口：GET /v0/management/auth-files 用于拉取认证文件清单，POST /v0/management/api-call 用于请求 https://chatgpt.com/backend-api/wham/usage 并完成用量探测。

特别注意！！！ 本项目大量使用vibe coding，为了稳妥起见，建议先行备份所有的codex认证json文件，避免因为代码bug而产生误删等侵入性操作。

他能做什么

• 拉取当前认证文件清单
• 把本地状态写入 SQLite
• 并发探测 usage
• 在 upload 模式下并发上传本地认证 JSON
• 导出当前的 401 和限额账号结果
• 在维护模式下按配置执行删除、禁用或恢复启用
• 批量快速且并行的上传认证json文件
• 可在维护后自动补充至最小有效账号阈值

核心特性

• 在终端中没有提供命令行参数时自动进入交互模式，可以交互式的设定脚本运行的各项参数，适合新手和不需要定时任务的调试场景
• 支持先运行scan模式来非侵入性的查看当前的auth文件状态，再考虑用maintain模式来维护auth文件
• 敏感信息（如url或者token）通过外部的JSON文件来提供
• 并发上传认证文件
• 当补充后仍不足阈值时，可选调用外部注册命令钩子
• 每次运行都会写入完整的 debug 级别日志文件

特别说明

目前在我自己的服务器上测试通过，但是项目比较多依赖于vibecoding，所以可能会有bug，而且脚本涉及到对服务器上的auth文件的不可逆操作（删除），在生产环境中慎重使用，或者备份好认证文件后再使用，新人还在学习阶段，欢迎大家在github上给我提issue和pr

安装和使用流程

本项目使用uv来管理环境

环境要求

• Python 3.11+
• uv

克隆和安装

git clone https://github.com/fantasticjoe/cpa-warden
cd cpa-warden

uv sync

配置

先复制示例配置：

cp config.example.json config.json

至少需要填写：

• base_url
• token

config.json 已被 git 忽略，不应提交到仓库。

示例配置：

{
  "base_url": "https://your-cpa.example.com",
  "token": "replace-with-your-management-token",
  "target_type": "codex",
  "provider": "",
  "probe_workers": 100,
  "action_workers": 100,
  "timeout": 15,
  "retries": 3,
  "delete_retries": 2,
  "quota_action": "disable",
  "quota_disable_threshold": 0.0,
  "delete_401": true,
  "auto_reenable": true,
  "reenable_scope": "signal",
  "upload_dir": "",
  "upload_workers": 20,
  "upload_retries": 2,
  "upload_method": "json",
  "upload_recursive": false,
  "upload_force": false,
  "min_valid_accounts": 100,
  "refill_strategy": "to-threshold",
  "auto_register": false,
  "register_command": "",
  "register_timeout": 300,
  "register_workdir": "",
  "db_path": "cpa_warden_state.sqlite3",
  "invalid_output": "cpa_warden_401_accounts.json",
  "quota_output": "cpa_warden_quota_accounts.json",
  "log_file": "cpa_warden.log",
  "debug": false,
  "user_agent": "codex_cli_rs/0.76.0 (Debian 13.0.0; x86_64) WindowsTerminal"
}

布尔型配置会做严格解析。支持写法：true/false、1/0、yes/no、on/off（不区分大小写）；非法值会在启动时直接报错。

重要配置项说明：

• base_url：CLIProxyAPI 管理接口基础地址
• token：CLIProxyAPI 管理 token
• target_type：按 files[].type 过滤记录
• provider：按 provider 字段过滤记录
• probe_workers：usage 探测并发数
• action_workers：删除 / 禁用 / 启用动作并发数
• timeout：请求超时时间，单位秒
• retries：探测“可重试失败”（超时、网络异常、429、5xx）时的重试次数
• delete_retries：删除失败重试次数（网络异常、429、5xx 等）
• quota_action：限额账号的处理动作，只能是 disable 或 delete
• quota_disable_threshold：按剩余额度比例自动禁用阈值（0~1）；0 保持旧行为（仅额度耗尽才禁用）
• delete_401：维护模式下是否删除 401 账号
• auto_reenable：是否自动恢复启用已恢复账号
• reenable_scope：自动恢复范围，signal 或 managed（默认：signal）
• upload_dir：upload 模式读取 .json 文件的目录
• upload_workers：upload 模式并发 worker 数
• upload_retries：上传失败重试次数
• upload_method：上传请求类型，json 或 multipart
• upload_recursive：upload 模式是否递归扫描子目录
• upload_force：远端已存在同名文件时是否继续上传
• min_valid_accounts：maintain-refill 模式下的最小有效账号阈值
• refill_strategy：maintain-refill 补充策略，to-threshold 或 fixed
• auto_register：补充后仍不足时是否调用外部注册命令
• register_command：外部注册命令模板（注册逻辑不在本仓库）
• register_timeout：外部注册命令超时秒数
• register_workdir：外部注册命令工作目录
• db_path：本地 SQLite 状态库路径
• invalid_output：401 账号 JSON 导出路径
• quota_output：限额账号 JSON 导出路径
• log_file：运行日志路径
• debug：是否在终端输出更详细日志
• user_agent：探测 wham/usage 时使用的 User-Agent

注意：在测试过程中，并发数似乎不能设置过高，过高会导致请求失败，解决方案是略微降低并发数（例如50～100左右我自己测试没问题），然后加大重试次数（三次以上）

使用方式

交互式运行：

uv run python cpa_warden.py

非交互运行示例：

scan 场景：

• 基础清单扫描与 usage 探测（不修改远端状态）：
  uv run python cpa_warden.py --mode scan
• 排查探测问题，开启更详细终端日志：
  uv run python cpa_warden.py --mode scan --debug
• 只扫描特定账号分组（type + provider）：
  uv run python cpa_warden.py --mode scan --target-type codex --provider openai

maintain 场景：

• 按当前配置执行标准维护流程：
  uv run python cpa_warden.py --mode maintain
• 先看维护结果，不删除 401 且不自动恢复：
  uv run python cpa_warden.py --mode maintain --no-delete-401 --no-auto-reenable
• 对限额账号使用更激进策略（直接删除）：
  uv run python cpa_warden.py --mode maintain --quota-action delete
• 当剩余额度比例降到 10% 时提前禁用：
  uv run python cpa_warden.py --mode maintain --quota-disable-threshold 0.1
• 仅恢复本工具曾管理过的账号：
  uv run python cpa_warden.py --mode maintain --reenable-scope managed
• 非交互执行危险维护（跳过确认）：
  uv run python cpa_warden.py --mode maintain --quota-action delete --yes

upload 场景：

• 从单个目录上传认证文件：
  uv run python cpa_warden.py --mode upload --upload-dir ./auth_files
• 递归扫描子目录并提高并发做批量上传：
  uv run python cpa_warden.py --mode upload --upload-dir ./auth_files --upload-recursive --upload-workers 50
• 使用 multipart 上传并强制尝试同名覆盖：
  uv run python cpa_warden.py --mode upload --upload-dir ./auth_files --upload-method multipart --upload-force

maintain-refill 场景：（由于代理池和注册机的问题还没有完善解决，目前还在测试中）

• 先维护，再按缺口补充到目标有效账号数：
  uv run python cpa_warden.py --mode maintain-refill --min-valid-accounts 200 --upload-dir ./auth_files
• 先维护，再按固定批量策略补充上传：
  uv run python cpa_warden.py --mode maintain-refill --min-valid-accounts 200 --refill-strategy fixed --upload-dir ./auth_files
• 补充后仍不足时，启用外部注册命令兜底：
  uv run python cpa_warden.py --mode maintain-refill --min-valid-accounts 200 --upload-dir ./auth_files --auto-register --register-command 'python /opt/register-machine/register.py'

支持的 CLI 参数：

• --config
• --mode
• --target-type
• --provider
• --probe-workers
• --action-workers
• --timeout
• --retries
• --delete-retries
• --user-agent
• --quota-action
• --quota-disable-threshold
• --db-path
• --invalid-output
• --quota-output
• --log-file
• --debug
• --upload-dir
• --upload-workers
• --upload-retries
• --upload-method
• --upload-force
• --no-upload-force
• --min-valid-accounts
• --refill-strategy
• --auto-register
• --no-auto-register
• --register-command
• --register-timeout
• --register-workdir
• --delete-401
• --no-delete-401
• --auto-reenable
• --no-auto-reenable
• --reenable-scope
• --upload-recursive
• --no-upload-recursive
• --yes

运行模式

scan 扫描模式

scan 只会读取账号清单、探测 usage、更新本地 SQLite 状态并导出当前结果，不会修改远端账号状态。

maintain 维护模式

maintain 一定会先执行一次完整的 scan，然后再按配置执行后续动作：

• 删除 401 账号
• 禁用或删除限额账号
• 重新启用已恢复账号

说明：默认 reenable_scope=signal 时，auto_reenable 也可能重新启用“人工禁用但当前满足恢复条件”的账号。若只想恢复本工具曾标记为 quota_disabled 的账号，请使用 reenable_scope=managed。

删除动作默认需要确认；提供 --yes 后会跳过危险操作确认。（适合定时任务，但是需要确保目前运行顺利，否则是危险操作）

upload 上传模式

upload 会从 upload_dir 读取 .json 文件，校验内容后并发上传到 /v0/management/auth-files。

上传状态会写入 SQLite，并以 {base_url, file_name, content_sha256} 作为唯一键保证“同一文件只上传一次”，避免并发导致重复上传。

如果存在任意文件校验失败或上传失败，命令会以非零状态码退出。

maintain-refill 维护并补充模式 (谨慎使用，仍在测试中)

maintain-refill 会先执行 maintain，然后按严格规则计算有效账号（disabled=0、非 401、非限额、且无探测错误）。

若有效账号数低于 min_valid_accounts，则从 upload_dir 补充上传，补充规则由 refill_strategy 决定：

• to-threshold：仅补齐缺口（min_valid_accounts - 当前有效数）
• fixed：每次触发都固定上传 min_valid_accounts 个

若补充后仍低于阈值且 auto_register=true，将调用外部 register_command（不在本仓库实现）：

• 本工具自动追加参数：--count <N> --output-dir <upload_dir>
• 注入环境变量：CPA_REGISTER_COUNT、CPA_REGISTER_OUTPUT_DIR
  注册逻辑保持外置，本项目仅提供调用钩子。

过滤与判定规则

过滤规则：

• target_type 基于 files[].type
• provider 是对 provider 字段做大小写不敏感的精确匹配，不是 provider 类型枚举

判定规则：

• 401：unavailable == true 或 api-call.status_code == 401
• quota limited：api-call.status_code == 200，且满足其一：
  1. “有效限额信号”已耗尽（limit_reached == true）；
  2. 剩余额度比例 <= quota_disable_threshold。

  plan_type=pro 时优先使用 additional_rate_limits 的 Spark（metered_feature=codex_bengalfox，回退规则为 limit_name 包含 Spark）；
  仅当 Spark 的 limit_reached 可用时才使用 Spark，否则回退到顶层 rate_limit

• recovered：账号当前为禁用状态，且当前同一“有效限额信号”满足 allowed == true 且 limit_reached == false

探测重试规则：

• 429 和 5xx：按 retries 次数进行退避重试
• 其他 4xx：快速失败，不重试

输出文件

默认输出物：

• cpa_warden_state.sqlite3：本地 SQLite 状态数据库
• cpa_warden_401_accounts.json：失效 401 账号导出
• cpa_warden_quota_accounts.json：限额账号导出
• cpa_warden.log：运行日志

日志与调试行为

• 生产模式的终端输出尽量简短
• 如果当前会话是 TTY，生产模式会优先显示 Rich 进度
• --debug 或 debug: true 会让终端输出更详细
• 日志文件始终保留完整的 debug 级别信息

项目结构

• cpa_warden.py：主入口脚本
• clean_codex_accounts.py：旧命令名的兼容包装脚本
• config.example.json：示例配置
• pyproject.toml：项目元数据与依赖

作者想说 & 未来想法

未来想把注册机批量产生的json通过cpa的接口直接添加进号池的功能也加进去。这样方便（注册机）-（代理池）-（CPA）-（cpa-warden）自动维持号池，当然只是有初步想法，并且实现了新的运行模式来尝试完成一部分这个逻辑循环，仍然需要很多工作和测试，各位佬可以给我提提建议，或者帮忙找找bug做做测试，因为目前日常学业和工作比较繁忙，空闲的时间才能更新和debug，再次感谢各位支持～