项目不需要单独准备 OpenAI API Key，也不在本地执行 Codex 登录。Codex OAuth 登录、Token 保存和刷新全部由 CLIProxyAPI 负责；Codex Helper 只保存 CPA authIndex，并通过受 management key 保护的服务端请求读取数据。

安装

git clone git@github.com:zhoujun0601/codex-helper.git
cd codex-helper
cp .env.example .env
# 编辑 .env，填写 CLIProxyAPI Management API 地址和 management key
docker compose up -d --build

.env 至少包含：

CLIPROXY_API_BASE_URL=http://host.docker.internal:8317
CLIPROXY_API_MANAGEMENT_KEY=replace-with-management-key

如果 CLIProxyAPI 位于另一个容器网络，请把两个服务加入同一网络，并将 CLIPROXY_API_BASE_URL 改为对应服务名。Codex Helper 从另一个容器访问 CPA Management API 时，CPA 的 remote-management.allow-remote 必须允许该来源，且 remote-management.secret-key 必须已配置。

查看运行状态：

docker compose ps
docker compose logs -f codex-helper

容器健康后访问：

http://服务器地址:8180

首次打开页面时创建管理员账号，并设置所在时区。用户名至少 3 位，密码至少 10 位。

初始化完成后，首页会显示已勾选“公开显示到未登录总览”的账号；点击“登录后配置”并使用管理员账号登录，才能进入设置中心添加账号、同步数据、修改账号公开状态或配置提醒。未勾选公开的账号只会在登录后的总览中显示。

首次初始化没有额外安装码。创建管理员之前，不要将端口直接暴露到不可信网络。公网部署应使用 HTTPS 反向代理，并限制初始化阶段的访问来源。

连接 Codex 账户

先在 CLIProxyAPI 中完成 Codex OAuth 登录，确认凭据状态可用。
从 CPA GET /v0/management/auth-files 或其管理面板取得该凭据的 auth_index。
使用管理员账号登录 Codex Helper。
打开“设置中心” → “Codex”。
输入 CPA authIndex，选择预期的个人订阅或 Team / Business 类型，并点击“添加账号”。
Codex Helper 会先验证该索引唯一指向未禁用的 Codex 凭据，再读取账号信息和用量；成功后立即显示，之后固定每 5 分钟同步一次。

每条本地账号记录只保存一个 CPA authIndex 及显示配置，不保存 access token、refresh token 或 CPA management key。删除账号只删除 Codex Helper 中的绑定、历史快照和提醒记录，不会删除 CLIProxyAPI 中的凭据。

同一邮箱下的个人订阅与 Team 工作区应在 CPA 中保留为不同凭据，并分别使用各自的 auth_index 添加。Codex Helper 使用 CPA 返回的 ID token claims 和 /wham/usage 的真实套餐进行校验；未知新套餐会安全显示为 unknown，不会自动猜测类型。

通用设置与提醒时间

进入“设置中心” → “通用”，可设置：

时区：用于初始化配置；界面时间按浏览器本地时区显示
自动同步：服务器固定每 5 分钟同步全部账号
历史保留时间：30、60、90、180 或 365 天
提前提醒时间：重置前 1–1440 分钟
是否发送重置前提醒和重置后确认；重置后确认也会通过额度百分比回落识别并提醒官方活动、临时补发等提前重置

提醒只会针对通过 CLIProxyAPI 读取到的 Codex 限额窗口发送。发送失败的提醒会在计划时间后的六小时内自动重试。

配置 Telegram

在 Telegram 中联系 @BotFather，使用 /newbot 创建 Bot，并取得 Bot Token。
打开“设置中心” → “Telegram”。
填写 Bot Token。
点击“验证并保存”。
点击“生成绑定码”。
在 Telegram 中打开刚创建的 Bot，发送页面显示的命令，例如：
```
/bind 123456
```
收到“绑定成功”后，返回页面点击“发送测试”。

绑定码十分钟内有效，一个实例只绑定一个 Telegram 会话。绑定成功后会自动启用额度提醒和查询菜单，可使用以下按钮或命令。/account 会向已绑定会话显示账号的完整邮箱，因此只应绑定受信任的私有会话。

当前用量（包含所有已添加连接）
重置时间 / /reset
历史概览 / /usage
账户信息 / /account
立即刷新 / /refresh

服务器必须能够访问 https://api.telegram.org。

点击“解除绑定”会删除当前 Bot Token、Chat ID 和未使用的绑定码。该操作不可恢复，之后需要重新填写 Token 并绑定。

配置 SMTP 邮件

进入“设置中心” → “SMTP 邮件”，填写：

SMTP 服务器和端口
用户名和密码或应用专用密码
加密方式：STARTTLS、隐式 TLS 或无加密
发件名称、发件地址和收件地址
“启用邮件提醒”开关

保存后点击“发送测试邮件”。常见组合为 STARTTLS/587 或隐式 TLS/465，具体值以邮件服务商文档为准。密码使用 /data/secret.key 加密后存入 SQLite，不会由设置接口返回明文。

日常操作

更新项目：

git pull --ff-only
docker compose up -d --build

停止和重新启动：

docker compose stop
docker compose start

查看日志：

docker compose logs --tail=200 codex-helper

健康检查：

curl http://localhost:8180/health/live
curl http://localhost:8180/health/ready

数据、备份与恢复

所有持久数据位于 Docker 卷的 /data：

codex-helper.db：管理员、设置、历史用量和通知记录
secret.key：用于解密 SMTP 密码和 Telegram Token

Codex OAuth 凭据不在该数据卷中，而是保存在 CLIProxyAPI 自己的凭据存储中。

登录管理页面后，可直接在浏览器访问以下地址下载一致性 SQLite 快照：

http://服务器地址:8180/api/v1/maintenance/backup

SQLite 快照不包含 secret.key。恢复 Codex Helper 本身必须同时备份整个 /data 数据卷；CLIProxyAPI 的配置与 OAuth 凭据需要按照 CPA 自身的备份方式单独保护。恢复时先停止容器，再恢复全部内容，并确保文件所有者仍可被容器中的 UID 10001 读取。

不要使用 docker compose down -v，该命令会删除持久数据卷。

数据边界

Codex Helper 通过 CLIProxyAPI 代请求 ChatGPT 的内部 Codex 接口。当前使用的数据源包括 /wham/usage、/wham/profiles/me 和可选的 /wham/rate-limit-reset-credits，提供：

ChatGPT/Codex 账户和套餐类型
限额窗口使用百分比、窗口长度和重置时间
当前重置周期 Token 合计、本周期单日峰值等摘要
每日总 Token 桶

当前总览的 Token 合计按最长有效限额窗口汇总 /wham/profiles/me 返回的每日 Token bucket，通常对应周窗口；周期边界所在日期按整日统计。系统不根据 Token 推算 Credits、美元价值或订阅价格。额度与 Profile Token 活动来自不同的上游聚合链路，刷新时间可能不一致；缺失数据会显示为“暂无”。这些 /wham/* 路径属于 ChatGPT/Codex 内部接口，上游可能调整字段或访问规则。

常见问题

页面显示“CLIProxyAPI 未配置或不可用”

先核对 .env 中的 CLIPROXY_API_BASE_URL 和 CLIPROXY_API_MANAGEMENT_KEY，然后查看日志：

docker compose logs --tail=200 codex-helper
docker compose restart codex-helper

确认 CPA Management API 已启用、management key 匹配、远程访问策略允许 Codex Helper 容器，并检查两个容器之间的网络连通性。日志和 API 错误不会输出 management key 或 OAuth Token。

添加 authIndex 后仍显示“尚未连接”

确认该索引来自当前配置的 CLIProxyAPI 实例。
确认对应凭据的 provider/type 是 codex 且未 disabled；额度耗尽时 CPA 可能暂时标记 unavailable，这不会阻止 Codex Helper 尝试读取重置时间。
在 CPA 中检查 OAuth Token 刷新是否成功。
点击账号的“立即同步”，并检查 docker compose logs -f codex-helper 中的非敏感错误信息。

Telegram 无法绑定

必须先“验证并保存”Bot Token，再生成绑定码。
将完整的 /bind 数字 命令发送给对应 Bot，而不是 BotFather。
绑定码只有十分钟有效，过期后重新生成。
确认服务器能够访问 Telegram Bot API。

SMTP 测试失败

核对端口和加密方式是否匹配。
部分服务商要求使用应用专用密码，而不是网页登录密码。
检查云服务商是否封禁 SMTP 出站端口。
确认发件地址符合 SMTP 账号或服务商的代发规则。

本地开发

前端与后端分别位于 frontend/ 和 backend/。

维护项目或使用编码代理前，请先阅读 AGENTS.md 和维护者文档中心；修改 HTTP 接口时同时核对后端 API 契约。维护者的可复现验证基线统一使用 Docker，下面的宿主机命令仅用于人工本地开发。

启动前端开发服务器：

cd frontend
npm install
npm run dev

前端提交前检查（格式、lint、类型、生产构建、bundle 门禁和 Vitest）使用 npm run check；浏览器回归测试使用 npm run test:e2e。维护者应按开发指南在固定版本容器中执行这些命令。

启动后端：

cd backend
export DATA_DIR=/tmp/codex-helper-data
export CLIPROXY_API_BASE_URL=http://127.0.0.1:8317
export CLIPROXY_API_MANAGEMENT_KEY=replace-with-management-key
go run ./cmd/server

本地开发需要 Go、Node.js 和 npm，并需要一个可访问的 CLIProxyAPI 实例。Vite 默认将 /api 和 /health 代理到 http://localhost:8080。

README.md Unescape Escape

Codex Helper

功能

运行要求

安装