CPACodexKeeper 是一个用于巡检和维护 CPA 管理端中的 codex token 的 Python 工具。
它的目标不是生成 token，而是对已经存储在 CPA 管理 API 中的 codex token 做持续维护。
- 检查 token 是否失效
- 按周限额 / 主限额自动禁用或启用
- 自动刷新即将过期的 token
- 支持
.env配置、Docker 和 GitHub Actions CI
如果你已经有一个 CPA 管理 API，并且希望：
- 定期清理失效 token
- 控制 token 的 usage 配额占用
- 在额度恢复后自动启用 token
- 在过期前自动刷新 token
那么这个项目就是为这个场景准备的。
cp .env.example .env
python main.py --once更多配置和运行方式见下文。
在实际使用中，codex token 往往不是静态资源，而是会随着时间推移出现以下情况：
- token 已失效，但仍残留在管理端
- token 的 usage 配额已经耗尽，不适合继续分发
- token 已被手动禁用，但额度恢复后没有自动启用
- token 快过期了，需要提前刷新
- team 账号和非 team 账号的 usage 返回结构不同，需要统一处理
CPACodexKeeper 会把这些维护动作自动化，减少人工巡检和手工清理。
每轮巡检中，程序会按下面的顺序处理：
- 从 CPA 管理 API 拉取 token 列表
- 只保留
type=codex的 token - 逐个获取 token 详情
- 读取 token 过期时间和剩余有效期
- 调用 OpenAI usage 接口检查可用性和限额
- 如果 usage 返回
401或402，则判定 token 无效或 workspace 已停用，并删除 - 如果存在周限额，优先使用周限额决定禁用 / 启用
- 如果不存在周限额，则回退到主窗口限额
- 如果 token 没有
refresh_token，并且已经过期，则直接删除 - 如果 token 没有
refresh_token，并且检测额度已达到阈值，则直接删除 - 如果 token 临近过期，则尝试刷新
- 刷新成功后将最新 token 数据上传回 CPA
这是一个按轮次运行、轮内可并发的流程：一轮结束后才会进入下一轮，但同一轮中的多个 token 可以并发巡检。
项目已经兼容 team 模式和普通模式。
如果 usage 返回中包含周限额窗口：
rate_limit.primary_window：通常表示较短窗口，例如 5 小时rate_limit.secondary_window：通常表示周限额
此时程序会：
- 优先使用
secondary_window.used_percent作为禁用 / 启用判断依据 - 自动携带
Chatgpt-Account-Id请求头
如果 usage 中没有周限额窗口：
- 程序会回退到
primary_window.used_percent进行判断
默认：
CPA_QUOTA_THRESHOLD=100
也就是：
- 达到 100% 才禁用
- 低于 100% 时可重新启用
- 但如果 token 没有
refresh_token，达到阈值时会直接删除，而不是仅禁用
项目现在只保留 .env 配置方式。
已经不再使用：
config.jsonconfig.example.json
先复制模板：
cp .env.example .env然后编辑 .env。
CPA_ENDPOINT：CPA 管理 API 地址CPA_TOKEN：CPA 管理 tokenCPA_PROXY：可选代理CPA_INTERVAL：守护模式轮询间隔，默认1800CPA_QUOTA_THRESHOLD：禁用阈值，默认100CPA_EXPIRY_THRESHOLD_DAYS：刷新阈值天数，默认3CPA_HTTP_TIMEOUT：CPA API 请求超时秒数，默认30CPA_USAGE_TIMEOUT：OpenAI usage 请求超时秒数，默认15CPA_MAX_RETRIES：临时网络 / 5xx 错误重试次数，默认2CPA_WORKER_THREADS：单轮巡检的并发线程数，默认8
推荐直接参考 .env.example 中的中英双语注释填写。
- Python 3.11+
- 依赖：
curl-cffi
安装依赖：
pip install -r requirements.txt适合手动巡检、调试或配合外部调度器使用：
cp .env.example .env
python main.py --once适合持续运行：
python main.py不会真正删除、禁用、启用或上传更新：
python main.py --once --dry-run项目支持通过 Docker 运行，配置同样只来自 .env / 环境变量。
docker build -t cpacodexkeeper .docker run -d \
--name cpacodexkeeper \
-e CPA_ENDPOINT=https://your-cpa-endpoint \
-e CPA_TOKEN=your-management-token \
-e CPA_INTERVAL=1800 \
cpacodexkeeper先复制模板：
cp .env.example .env然后编辑 .env，再启动：
docker compose up -d --build程序会为每个 token 输出一段巡检日志，通常包含：
-
同一轮内可以并发巡检多个 token
-
但每个 token 的日志会缓冲后一次性输出，避免多线程下控制台内容交错
-
token 名称
-
邮箱
-
当前禁用状态
-
过期时间
-
剩余有效期
-
usage 检查结果
-
5 小时 / 周限额信息
-
是否被删除、禁用、启用或刷新
在每轮结束后，还会输出汇总统计，例如：
- 总计
- 存活
- 死号（已删除）
- 已禁用
- 已启用
- 已刷新
- 跳过
- 网络失败
当前版本已经补了几项关键保护：
- 启动时强校验
.env配置 - 对数值配置做范围检查
- 对 CPA API 和 usage API 设置独立超时
- 对临时网络错误和 5xx 做有限重试
- 对
secondary_window = null做安全回退 - 单个 token 失败不会中断整轮任务
- 守护模式下单轮报错不会导致整个进程退出
项目内置了 justfile，方便统一常用命令。
如果你安装了 just，可以直接使用：
just install
just test
just run-once
just dry-run
just daemon
just docker-build
just docker-up
just docker-downpython -m unittest discover -s tests或者：
just test项目已包含 CI 工作流：
- 自动运行单元测试
- 自动验证 Docker 镜像可以构建
工作流文件：
.github/workflows/ci.yml
CPACodexKeeper/
├─ src/
│ ├─ cli.py
│ ├─ cpa_client.py
│ ├─ logging_utils.py
│ ├─ maintainer.py
│ ├─ models.py
│ ├─ openai_client.py
│ ├─ settings.py
│ └─ utils.py
├─ tests/
├─ .env.example
├─ docker-compose.yml
├─ Dockerfile
├─ justfile
├─ main.py
├─ README.md
└─ README.en.md
通常是 .env 缺字段，或者字段格式不对。
重点检查：
CPA_ENDPOINTCPA_TOKEN- 数值项是否为合法整数
表示 token 已无效。按当前逻辑会直接删除。
通常表示 workspace 已停用或不可用。按当前逻辑也会直接删除。
表示没有周限额窗口。程序会自动回退到主窗口判断。
先确认本机是否安装并启用了 Docker CLI。
这个项目面向已授权的内部维护场景，适合：
- 私有 CPA 管理系统
- 内部 token 池维护
- 已获得授权的自动巡检和清理任务
不建议将真实凭据提交到版本控制中。.env 应始终保留在本地或安全的部署环境中。