Codex Proxy

您的本地 Codex 编程助手中转站

将 Codex Desktop 的能力以 OpenAI / Anthropic / Gemini 标准协议对外暴露，无缝接入任意 AI 客户端。

快速开始 • 核心功能 • 可用模型 • 客户端接入 • 配置说明

简体中文 | English

_{☕ 赞赏}

_{💬 交流群}

声明：本项目由个人独立开发和维护，初衷是解决自己的需求。我有自己的注册机，根本不缺 token，所以这个项目不是为了"薅"谁的资源而存在的。

我自愿开源、自愿维护。该有的功能我会加，有 bug 我也会第一时间修。但我没有义务为任何单个用户提供定制服务。

觉得代码垃圾？可以不用。觉得你写得更好？欢迎提 PR 加入贡献者。Issue 区用来反馈 bug 和建议，不是用来提需求、催更新、或指点江山的。

Codex Proxy 是一个轻量级本地中转服务，将 Codex Desktop 的 Responses API 转换为多种标准协议接口（OpenAI /v1/chat/completions、Anthropic /v1/messages、Gemini、Codex /v1/responses 直通）。通过本项目，您可以在 Cursor、Claude Code、Continue 等任何兼容上述协议的客户端中直接使用 Codex 编程模型。

只需一个 ChatGPT 账号（或接入第三方 API 中转站），配合本代理即可在本地搭建一个专属的 AI 编程助手网关。

🚀 快速开始

前置条件：你需要一个 ChatGPT 账号（免费账号即可）。如果还没有，先去 chat.openai.com 注册一个。

方式一：桌面应用（推荐新手）

下载 → 安装 → 打开就能用。

下载安装包 — 打开 Releases 页面，根据系统下载：

系统	文件
Windows	`Codex Proxy Setup x.x.x.exe`
macOS	`Codex Proxy-x.x.x.dmg`
Linux	`Codex Proxy-x.x.x.AppImage`

安装后打开应用，点击登录按钮用 ChatGPT 账号登录。浏览器访问 http://localhost:8080 即可看到控制面板。

方式二：Docker 部署

mkdir codex-proxy && cd codex-proxy
curl -O https://raw.githubusercontent.com/icebear0828/codex-proxy/master/docker-compose.yml
curl -O https://raw.githubusercontent.com/icebear0828/codex-proxy/master/.env.example
cp .env.example .env
docker compose up -d
# 打开 http://localhost:8080 登录

账号数据保存在 data/ 文件夹，重启不丢失。其他容器连本服务用宿主机 IP（如 192.168.x.x:8080），不要用 localhost。

取消 docker-compose.yml 中 Watchtower 的注释即可自动更新。

方式三：源码运行

git clone https://github.com/icebear0828/codex-proxy.git
cd codex-proxy
npm install                        # 安装后端依赖
cd web && npm install && cd ..     # 安装前端依赖
npm run dev                        # 开发模式（热重载）
# 或: npm run build && npm start   # 生产模式

需要 Rust 工具链（用于编译 TLS native addon）：
# 1. 安装 Rust（如果没有的话）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# 2. 编译 TLS addon
cd native && npm install && npm run build && cd ..
Docker / 桌面应用已内置编译好的 addon，无需手动编译。

打开 http://localhost:8080 登录。

验证

登录后打开控制面板 http://localhost:8080，在 API Configuration 区域找到你的 API Key，然后：

# 把 your-api-key 替换成控制面板里显示的密钥
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{"model":"codex","messages":[{"role":"user","content":"Hello!"}],"stream":true}'

看到 AI 回复的文字流即部署成功。如果返回 401，请检查 API Key 是否正确。

🌟 核心功能

🔌 全协议兼容

兼容 /v1/chat/completions（OpenAI）、/v1/messages（Anthropic）、Gemini 格式及 /v1/responses（Codex 直通）
SSE 流式输出，可直接对接所有 OpenAI / Anthropic SDK 和客户端
自动完成 Chat Completions / Anthropic / Gemini ↔ Codex Responses API 双向协议转换
Structured Outputs — response_format（json_object / json_schema）和 Gemini responseMimeType
Function Calling — 原生 function_call / tool_calls 支持（所有协议）

🔐 账号管理与智能轮换

OAuth PKCE 登录 — 浏览器一键授权，无需手动复制 Token
多账号轮换 — least_used（最少使用优先）、round_robin（轮询）、sticky（粘性）三种策略
Plan Routing — 不同 plan（free/plus/team/business）的账号自动路由到各自支持的模型
Token 自动续期 — JWT 到期前自动刷新，指数退避重试
配额自动刷新 — 后台每 5 分钟拉取各账号额度，达到阈值时弹出预警横幅；额度耗尽自动跳过
封禁检测 — 上游 403 自动标记 banned；401 token 吊销自动过期并切换账号
Relay 中转站 — 支持接入第三方 API 中转站（API Key + baseUrl），自动按 format 决定直通或翻译
Web 控制面板 — 账号管理、用量统计、批量操作，中英双语；远程访问需 Dashboard 登录门

🌐 代理池

Per-Account 代理路由 — 为不同账号配置不同的上游代理
四种分配模式 — Global Default / Direct / Auto / 指定代理
健康检查 — 定时 + 手动，通过 ipify 获取出口 IP 和延迟
不可达自动标记 — 代理不可达时自动排除

🛡️ 反检测与协议伪装

Rust Native TLS — 内置 reqwest + rustls native addon，TLS 指纹与真实 Codex Desktop 精确一致（依赖版本锁定）
完整请求头 — originator、User-Agent、x-openai-internal-codex-residency、x-codex-turn-state、x-client-request-id 等头按真实客户端行为发送
Cookie 持久化 — 自动捕获和回放 Cloudflare Cookie
指纹自动更新 — 轮询 Codex Desktop 更新源，自动同步 app_version 和 build_number

🏗️ 技术架构

                                Codex Proxy
┌──────────────────────────────────────────────────────────┐
│                                                          │
│  Client (Cursor / Claude Code / Continue / SDK / ...)    │
│       │                                                  │
│  POST /v1/chat/completions (OpenAI)                      │
│  POST /v1/messages         (Anthropic)                   │
│  POST /v1/responses        (Codex 直通)                  │
│  POST /gemini/*            (Gemini)                      │
│       │                                                  │
│       ▼                                                  │
│  ┌──────────┐    ┌───────────────┐    ┌──────────────┐   │
│  │  Routes   │──▶│  Translation  │──▶│    Proxy     │   │
│  │  (Hono)  │   │ Multi→Codex   │   │ Native TLS   │   │
│  └──────────┘   └───────────────┘   └──────┬───────┘   │
│       ▲                                     │           │
│       │          ┌───────────────┐          │           │
│       └──────────│  Translation  │◀─────────┘           │
│                  │ Codex→Multi   │  SSE stream          │
│                  └───────────────┘                       │
│                                                          │
│  ┌──────────┐  ┌───────────────┐  ┌──────────────────┐  │
│  │   Auth   │  │  Fingerprint  │  │   Model Store    │  │
│  │ OAuth/JWT│  │ Rust (rustls) │  │ Static + Dynamic │  │
│  │  Relay   │  │  Headers/UA   │  │  Plan Routing    │  │
│  └──────────┘  └───────────────┘  └──────────────────┘  │
│                                                          │
└──────────────────────────────────────────────────────────┘
                          │
                Rust Native Addon (napi-rs)
              reqwest 0.12.28 + rustls 0.23.36
             (TLS 指纹 = 真实 Codex Desktop)
                          │
                   ┌──────┴──────┐
                   ▼             ▼
              chatgpt.com   Relay 中转站
         /backend-api/codex  (第三方 API)

📦 可用模型

模型 ID	别名	推理等级	说明
`gpt-5.4`	—	low / medium / high / xhigh	最新旗舰模型
`gpt-5.4-mini`	—	low / medium / high / xhigh	5.4 轻量版
`gpt-5.3-codex`	—	low / medium / high / xhigh	5.3 编程优化模型
`gpt-5.2-codex`	`codex`	low / medium / high / xhigh	前沿 agentic 编程模型（默认）
`gpt-5.2`	—	low / medium / high / xhigh	专业工作 + 长时间代理
`gpt-5.1-codex-max`	—	low / medium / high / xhigh	扩展上下文 / 深度推理
`gpt-5.1-codex`	—	low / medium / high	GPT-5.1 编程模型
`gpt-5.1`	—	low / medium / high	通用 GPT-5.1
`gpt-5-codex`	—	low / medium / high	GPT-5 编程模型
`gpt-5`	—	minimal / low / medium / high	通用 GPT-5
`gpt-oss-120b`	—	low / medium / high	开源 120B 模型
`gpt-oss-20b`	—	low / medium / high	开源 20B 模型
`gpt-5.1-codex-mini`	—	medium / high	轻量快速编程模型
`gpt-5-codex-mini`	—	medium / high	轻量编程模型

后缀：任意模型名后追加 -fast 启用 Fast 模式，-high/-low 切换推理等级。例如：codex-fast、gpt-5.2-codex-high-fast。

Plan Routing：不同 plan（free/plus/team/business）的账号自动路由到各自支持的模型。模型列表由后端动态获取，自动同步。

🔗 客户端接入

所有客户端的 API Key 均从控制面板 (http://localhost:8080) 获取。模型名填 codex（默认 gpt-5.2-codex）或任意可用模型 ID。

Claude Code (CLI)

export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_API_KEY=your-api-key
# 切换模型: export ANTHROPIC_MODEL=codex-fast / gpt-5.4 / gpt-5.1-codex-mini ...
claude

控制面板的 Anthropic SDK Setup 卡片可一键复制环境变量（含 Opus / Sonnet / Haiku 层级模型配置）。

推荐模型：Opus → gpt-5.4，Sonnet → gpt-5.3-codex，Haiku → gpt-5.4-mini。

⚠️ 配置不生效？请参考 Claude Code 配置避坑指南（AUTH_TOKEN 劫持、API Key 黑名单等常见问题）。

Codex CLI

~/.codex/config.toml:

[model_providers.proxy_codex]
name = "Codex Proxy"
base_url = "http://localhost:8080/v1"
wire_api = "responses"
env_key = "PROXY_API_KEY"

[profiles.default]
model = "gpt-5.4"
model_provider = "proxy_codex"

export PROXY_API_KEY=your-api-key
codex

Claude for VSCode / JetBrains

打开 Claude 扩展设置，找到 API Configuration：

API Provider: 选择 Anthropic
Base URL: http://localhost:8080
API Key: 你的 API Key

或在 VS Code settings.json 中添加：

{
  "claude.apiEndpoint": "http://localhost:8080",
  "claude.apiKey": "your-api-key"
}

Cursor

打开 Settings → Models
选择 OpenAI API
设置 Base URL: http://localhost:8080/v1
设置 API Key: 你的 API Key
添加模型名 codex（或其他模型 ID）

Windsurf

打开 Settings → AI Provider
选择 OpenAI Compatible
API Base URL: http://localhost:8080/v1
API Key: 你的 API Key
Model: codex

Cline (VSCode 扩展)

打开 Cline 侧边栏 → 设置齿轮
API Provider: 选择 OpenAI Compatible
Base URL: http://localhost:8080/v1
API Key: 你的 API Key
Model ID: codex

Continue (VSCode 扩展)

~/.continue/config.json:

{
  "models": [{
    "title": "Codex",
    "provider": "openai",
    "model": "codex",
    "apiBase": "http://localhost:8080/v1",
    "apiKey": "your-api-key"
  }]
}

aider

aider --openai-api-base http://localhost:8080/v1 \
      --openai-api-key your-api-key \
      --model openai/codex

或设置环境变量：

export OPENAI_API_BASE=http://localhost:8080/v1
export OPENAI_API_KEY=your-api-key
aider --model openai/codex

Cherry Studio

设置 → 模型服务 → 添加
类型: OpenAI
API 地址: http://localhost:8080/v1
API Key: 你的 API Key
添加模型 codex

通用 OpenAI 兼容客户端

任何支持自定义 OpenAI API Base 的客户端均可接入：

设置项	值
Base URL	`http://localhost:8080/v1`
API Key	控制面板获取
Model	`codex`（或其他模型 ID）

SDK 代码示例（Python / Node.js）

Python

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8080/v1", api_key="your-api-key")
for chunk in client.chat.completions.create(
    model="codex", messages=[{"role": "user", "content": "Hello!"}], stream=True
):
    print(chunk.choices[0].delta.content or "", end="")

Node.js

import OpenAI from "openai";
const client = new OpenAI({ baseURL: "http://localhost:8080/v1", apiKey: "your-api-key" });
const stream = await client.chat.completions.create({
  model: "codex", messages: [{ role: "user", content: "Hello!" }], stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

⚙️ 配置说明

重要：不要直接修改 config/default.yaml，该文件会在版本更新时被覆盖。自定义配置请通过 Dashboard 设置面板修改（自动保存到 data/local.yaml），或手动创建 data/local.yaml 写入需要覆盖的字段。data/ 目录不受更新影响。

默认配置位于 config/default.yaml：

分类	关键配置	说明
`server`	`host`, `port`, `proxy_api_key`	监听地址与 API 密钥
`api`	`base_url`, `timeout_seconds`	上游 API 地址与超时
`client`	`app_version`, `build_number`, `chromium_version`	模拟的 Codex Desktop 版本
`model`	`default`, `default_reasoning_effort`, `inject_desktop_context`	默认模型与推理配置
`auth`	`rotation_strategy`, `rate_limit_backoff_seconds`	轮换策略与限流退避
`tls`	`proxy_url`, `force_http11`	TLS 代理与 HTTP 版本
`quota`	`refresh_interval_minutes`, `warning_thresholds`, `skip_exhausted`	额度刷新与预警
`session`	`ttl_minutes`, `cleanup_interval_minutes`	Dashboard session 管理

局域网访问

默认监听 127.0.0.1（仅本机）。如需局域网内其他设备访问，在 data/local.yaml 中添加：

server:
  host: "0.0.0.0"

Electron 桌面版的 data/local.yaml 路径：

系统	路径
macOS	`~/Library/Application Support/Codex Proxy/data/local.yaml`
Windows	`%APPDATA%/Codex Proxy/data/local.yaml`
Linux	`~/.config/Codex Proxy/data/local.yaml`

⚠️ 绑定 0.0.0.0 会将服务暴露到局域网，务必在 Dashboard → 密钥设置中配置强密钥。

TLS 配置

tls:
  proxy_url: null                  # null = 自动检测本地代理；填写代理 URL 指定上游代理
  force_http11: false              # HTTP/2 失败时自动降级 HTTP/1.1；true = 强制 HTTP/1.1

内置 Rust native addon（reqwest + rustls），TLS 指纹与真实 Codex Desktop 完全一致。源码运行需先编译：cd native && npm install && npm run build。

API 密钥

server:
  proxy_api_key: "pwd"    # 自定义密钥，客户端用 Bearer pwd 访问
  # proxy_api_key: null   # null = 自动生成 codex-proxy-xxxx 格式密钥

当前密钥始终显示在控制面板的 API Configuration 区域。

环境变量覆盖

环境变量	覆盖配置
`PORT`	`server.port`
`CODEX_PLATFORM`	`client.platform`
`CODEX_ARCH`	`client.arch`
`HTTPS_PROXY`	`tls.proxy_url`

📡 API 端点

点击展开完整端点列表

协议端点

端点	方法	说明
`/v1/chat/completions`	POST	OpenAI 格式聊天补全
`/v1/responses`	POST	Codex Responses API 直通
`/v1/messages`	POST	Anthropic 格式聊天补全
`/v1/models`	GET	可用模型列表

账号与认证

端点	方法	说明
`/auth/login`	GET	OAuth 登录入口
`/auth/accounts`	GET	账号列表（`?quota=true` / `?quota=fresh`）
`/auth/accounts`	POST	添加单个账号（token 或 refreshToken）
`/auth/accounts/import`	POST	批量导入账号
`/auth/accounts/export`	GET	导出账号（`?format=minimal` 精简格式）
`/auth/accounts/relay`	POST	添加 Relay 中转站账号
`/auth/accounts/batch-delete`	POST	批量删除账号
`/auth/accounts/batch-status`	POST	批量修改账号状态

账号导入导出示例

# 导出所有账号（完整格式，含 token）
curl -s http://localhost:8080/auth/accounts/export \
  -H "Authorization: Bearer your-api-key" > backup.json

# 导出精简格式（仅 refreshToken + label，适合分享）
curl -s "http://localhost:8080/auth/accounts/export?format=minimal" \
  -H "Authorization: Bearer your-api-key" > backup-minimal.json

# 批量导入（支持 token、refreshToken，或两者同时传）
curl -X POST http://localhost:8080/auth/accounts/import \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "accounts": [
      { "token": "eyJhbGciOi..." },
      { "refreshToken": "v1.abc..." },
      { "refreshToken": "v1.def...", "label": "备用账号" }
    ]
  }'
# 返回: { "added": 2, "updated": 1, "failed": 0, "errors": [] }

# 备份恢复一键操作（导出后直接导入到另一个实例）
curl -X POST http://localhost:8080/auth/accounts/import \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d @backup.json

管理接口

端点	方法	说明
`/admin/rotation-settings`	GET/POST	轮换策略配置
`/admin/quota-settings`	GET/POST	额度刷新与预警配置
`/admin/refresh-models`	POST	手动刷新模型列表
`/admin/usage-stats/summary`	GET	用量统计汇总
`/admin/usage-stats/history`	GET	用量时间序列
`/health`	GET	健康检查

代理池

端点	方法	说明
`/api/proxies`	GET/POST	代理池列表 / 添加代理
`/api/proxies/:id`	PUT/DELETE	更新 / 删除代理
`/api/proxies/:id/check`	POST	健康检查单个代理
`/api/proxies/check-all`	POST	全部代理健康检查
`/api/proxies/assign`	POST	为账号分配代理

📋 系统要求

Node.js 18+（推荐 20+）
Rust — 源码运行需 Rust 工具链（编译 TLS native addon）；Docker / 桌面应用已内置
ChatGPT 账号 — 免费账号即可
Docker（可选）

⚠️ 注意事项

Codex API 为流式输出专用，stream: false 时代理内部流式收集后返回完整 JSON
本项目依赖 Codex Desktop 的公开接口，上游版本更新时会自动检测并更新指纹
Windows 下 native TLS addon 需 Rust 工具链编译；Docker 部署已预编译，无需额外配置

📝 最近更新

完整更新日志请查看 CHANGELOG.md，以下内容由 CI 自动同步。

[Unreleased]

Added

第三方 API Key 管理：支持 Anthropic / OpenAI / Gemini / OpenRouter 预设模型 + 自定义 provider，每个 key 绑定一个具体模型，运行时动态路由（优先于 config 固定 key），LRU 轮转多 key 负载均衡
- REST API：GET/POST /auth/api-keys、GET /auth/api-keys/catalog、POST /auth/api-keys/import、GET /auth/api-keys/export、批量删除、label/status 管理
- Dashboard 新增 API Keys tab：表单添加（御三家下拉选模型 / custom 手填）、import/export、toggle 启停、删除
- 持久化 data/api-keys.json，UpstreamRouter 优先级 0 匹配 pool entry
加强伪装：Rust native transport（reqwest + rustls），TLS 指纹精确匹配真实 Codex Desktop；补齐 x-openai-internal-codex-residency、x-client-request-id、x-codex-turn-state 请求头
账号探活：POST /auth/accounts/health-check 批量健康检查 + POST /auth/accounts/:id/refresh 单账号刷新，通过 OAuth refresh 探测存活状态，带 stagger 延迟和并发控制
Session affinity：同一对话链路由到同一账号，修复 previous_response_id 跨账号失效问题
prompt_cache_key：每个对话链生成唯一 UUID 传递给后端，启用 prompt cache
...（查看全部） Changed
Dashboard session 默认 TTL 从 1 小时延长至 24 小时 Fixed
上游 401 时立即触发 RT→AT 刷新，而非等待定时器（修复 token 被提前作废后账号一直显示 expired 的问题）
Dashboard session 滑动窗口续期：每次有效请求自动延长过期时间，不再固定 TTL 后断连
Dashboard 前端全局 401 拦截：session 过期后自动跳回登录页，不再卡死在空白页
Add Account 对话框新增 Cancel 按钮，OAuth 流程中可随时关闭对话框 (#319)
Electron 打包前清空旧 public/ 目录，防止残留旧版前端资源导致显示异常 (#320)

v0.8.0 - 2026-02-24

Added

原生 function_call / tool_calls 支持（所有协议） Fixed
格式错误的 chat payload 返回 400 invalid_json 错误

☕ 赞赏 & 交流

觉得有帮助？请作者喝杯咖啡，或加入微信交流群获取使用帮助。二维码见页面顶部。

⭐ Star History

📄 许可协议

本项目采用 非商业许可 (Non-Commercial)：

允许：个人学习、研究、自用部署
禁止：任何形式的商业用途，包括但不限于出售、转售、收费代理、商业产品集成

本项目与 OpenAI 无关联。使用者需自行承担风险并遵守 OpenAI 的服务条款。

_{Built with Hono + TypeScript + Rust | Powered by Codex Desktop API}

Name		Name	Last commit message	Last commit date
Latest commit History 517 Commits
.github		.github
config		config
native		native
packages/electron		packages/electron
scripts		scripts
shared		shared
src		src
tests		tests
web		web
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
API.md		API.md
API_CN.md		API_CN.md
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
README.md		README.md
README_EN.md		README_EN.md
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
docker-healthcheck.sh		docker-healthcheck.sh
opencode.json		opencode.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Codex Proxy

您的本地 Codex 编程助手中转站

🚀 快速开始

方式一：桌面应用（推荐新手）

方式二：Docker 部署

方式三：源码运行

验证

🌟 核心功能

🔌 全协议兼容

🔐 账号管理与智能轮换

🌐 代理池

🛡️ 反检测与协议伪装

🏗️ 技术架构

📦 可用模型

🔗 客户端接入

Claude Code (CLI)

Codex CLI

Claude for VSCode / JetBrains

Cursor

Windsurf

Cline (VSCode 扩展)

Continue (VSCode 扩展)

aider

Cherry Studio

通用 OpenAI 兼容客户端

⚙️ 配置说明

局域网访问

TLS 配置

API 密钥

环境变量覆盖

📡 API 端点

📋 系统要求

⚠️ 注意事项

📝 最近更新

[Unreleased]

v0.8.0 - 2026-02-24

☕ 赞赏 & 交流

⭐ Star History

📄 许可协议

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 22

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages