Codex Proxy

Codex Proxy

Codex API 代理服务，提供 OpenAI / Claude 多协议兼容接口，支持多账号轮询、内部重试、自动 Token 刷新。

目录

- 功能
- 文档
- 快速开始
- 思考配置
- API 接口
- 管理接口文档（详）
- 配置说明
- 项目结构
- 贡献与社区
- Star 历史
- 许可证

功能

- 多协议兼容 — 同时支持 Chat Completions、Responses API、Responses Compact、Claude Messages API
- 多账号轮询 — Round-Robin + 额度均衡，按使用率排序优先使用剩余额度最多的账号
- 内部重试 — 请求失败时在 executor 内部切换账号重试，流式请求 SSE 头只在成功后才写给客户端，客户端不感知重试过程
- 自动 Token 刷新 — 定期并发刷新 access_token，429 限频设冷却而不是删除账号
- 健康检查 — 定期探测账号状态，自动识别 401/403/429 并处理
- 额度查询 — 支持查询每个账号的剩余额度，按额度使用率排序选号
- 热加载 — 运行时自动扫描新增账号文件，无需重启
- 禁用凭据周期清理（磁盘） — 默认按间隔恢复 *.json.disabled 并探测，失败则删文件，减轻目录膨胀（disabled-recovery-interval-sec，0 关闭）
- Codex 客户端目录 — 自动刷新远端 Codex 客户端模型目录，GET /v1/models?client_version=... 返回最新 reasoning 等级和客户端版本信息；/stats 提供目录 revision、来源、模型数量和更新时间，POST /admin/catalog/refresh 可手动刷新
- Tool Schema 自动修复 — 自动补全 type: array 缺少 items 的 JSON Schema，避免上游 400 错误
- 连接池保活 — 定时 ping 上游保持 TCP+TLS 连接，消除冷启动延迟
- API Key 鉴权 — 可选的访问密钥保护
- 运行时导入账号 — POST /admin/accounts/ingest（或同路径 WebSocket）上传 JSON / NDJSON，直接填充号池，无需重启

文档

快速开始

1. 准备账号文件

在 auths/ 目录中放入 JSON 格式的账号文件，每个文件一个账号：

2. 编辑配置

更多字段（数据库、backend-domain、HTTP/2、h2c 等）见 docs/CONFIGURATION.md 与 config.example.yaml。

除将 JSON 放入 auth-dir 外，也可在服务运行后通过管理接口导入，见 docs/API-ADMIN.md 中的 /admin/accounts/ingest。

3. 预编译包（推荐）

解压后编辑 config.yaml，将账号 JSON 放入 auth-dir 指定目录，执行：

- Linux / macOS: ./codex-proxy -config config.yaml
- Windows: codex-proxy.exe -config config.yaml

Release 页附带 SHA256SUMS.txt 可校验文件完整性。

4. 源码编译

5. Docker

镜像发布至 ghcr.io/XxxXTeam/codex-proxy（amd64 / arm64）。打标签或工作流触发时会推送，详见 .github/workflows/release.yml。容器启动与卷挂载的详细步骤见 docs/DEPLOY.md。

6. 调用接口

Chat Completions

Responses API

Claude Messages API

思考配置

在模型名中使用连字符后缀控制思考级别；还可选下列子参数（可与思考后缀任意顺序拼接，解析时先去掉 -fast 再去掉 -1m，最后解析思考后缀）：

- -fast：上游 service_tier 固定为 priority。

可通过配置项…