Spaces:
Paused
Paused
Codex Proxy
您的本地 Codex 编程助手中转站
将 Codex Desktop 的能力以 OpenAI 标准协议对外暴露，无缝接入任意 AI 客户端。
快速开始 • 核心功能 • 技术架构 • 客户端接入 • 配置说明
简体中文 | English
Codex Proxy 是一个轻量级本地中转服务，将 Codex Desktop 的 Responses API 转换为 OpenAI 标准的 /v1/chat/completions 接口。通过本项目，您可以在 Cursor、Continue、VS Code 等任何兼容 OpenAI 协议的客户端中直接使用 Codex 编程模型。
只需一个 ChatGPT 账号，配合本代理即可在本地搭建一个专属的 AI 编程助手网关。
🚀 快速开始 (Quick Start)
桌面应用（最简单）
从 GitHub Releases 下载安装包，开箱即用：
| 平台 | 安装包 |
|---|---|
| Windows | Codex Proxy Setup x.x.x.exe |
| macOS | Codex Proxy-x.x.x.dmg |
| Linux | Codex Proxy-x.x.x.AppImage |
安装后打开应用，使用 ChatGPT 账号登录即可。桌面端默认监听 127.0.0.1:8080，仅本机访问。
CLI / 服务器部署
git clone https://github.com/icebear0828/codex-proxy.git
cd codex-proxy
Docker（推荐，所有平台通用）
docker compose up -d
# 打开 http://localhost:8080 登录
数据持久化通过 volume 映射：data/（账号、Cookie）和 config/（配置文件）。
跨容器访问提示：如果其他 Docker 容器（如 OpenClaw、Cursor Server 等）需要连接 codex-proxy，建议使用宿主机的局域网 IP（如
http://192.168.x.x:8080/v1）而非host.docker.internal，以避免 Docker DNS 解析问题。
macOS / Linux
npm install # 安装后端依赖 + 自动下载 curl-impersonate
cd web && npm install && cd .. # 安装前端依赖
npm run dev # 开发模式（热重载）
# 或：npm run build && npm start # 生产模式
也支持
pnpm或bun，将上方npm替换即可。
Windows
npm install # 安装后端依赖
cd web && npm install && cd .. # 安装前端依赖
npm run dev # 开发模式（热重载）
Windows 下 curl-impersonate 暂不可用，自动降级为系统 curl（无 Chrome TLS 伪装）。建议搭配本地代理使用，或通过 Docker / WSL 部署以获得完整 TLS 伪装能力。
验证
# 打开 http://localhost:8080 使用 ChatGPT 账号登录，然后：
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "codex",
"messages": [{"role": "user", "content": "Hello!"}],
"stream": true
}'
🌟 核心功能 (Features)
1. 🔌 全协议兼容 (Multi-Protocol API)
- 完全兼容
/v1/chat/completions（OpenAI）、/v1/messages（Anthropic）和 Gemini 格式 - 支持 SSE 流式输出，可直接对接所有 OpenAI SDK 和客户端
- 自动完成 Chat Completions ↔ Codex Responses API 双向协议转换
2. 🔐 账号管理与智能轮换 (Auth & Multi-Account)
- OAuth PKCE 登录 — 浏览器一键授权，无需手动复制 Token
- 多账号轮换 — 支持
least_used（最少使用优先）和round_robin（轮询）两种调度策略 - Token 自动续期 — JWT 到期前自动刷新，指数退避重试（5 次），临时失败 10 分钟恢复调度
- 配额实时监控 — 控制面板展示各账号剩余用量，限流窗口滚动时自动重置计数器
- 关键数据即时持久化 — 新增/刷新 Token 立即写盘，不丢失
- 稳定连接 — 自动对齐 Codex Desktop 请求特征，Cookie 持久化减少重复验证
- Web 控制面板 — 账号管理、用量监控、状态总览，中英双语
3. 🌐 代理池 (Proxy Pool)
- Per-Account 代理路由 — 为不同账号配置不同的上游代理，实现 IP 多样化和风险隔离
- 四种分配模式 — Global Default（全局代理）、Direct（直连）、Auto（Round-Robin 轮转）、指定代理
- 健康检查 — 定时（默认 5 分钟）+ 手动，通过 ipify API 获取出口 IP 和延迟
- 不可达自动标记 — 代理不可达时自动标记为 unreachable，不参与自动轮转
- Dashboard 管理面板 — 添加/删除/检查/启用/禁用代理，每个账号可选择代理或模式
🏗️ 技术架构 (Architecture)
Codex Proxy
┌─────────────────────────────────────────────────────┐
│ │
│ Client (Cursor / Continue / SDK) │
│ │ │
│ POST /v1/chat/completions │
│ POST /v1/messages (Anthropic) │
│ │ │
│ ▼ │
│ ┌──────────┐ ┌───────────────┐ ┌──────────┐ │
│ │ Routes │──▶│ Translation │──▶│ Proxy │ │
│ │ (Hono) │ │ OpenAI→Codex │ │ curl TLS │ │
│ └──────────┘ └───────────────┘ └────┬─────┘ │
│ ▲ │ │
│ │ ┌───────────────┐ │ │
│ └──────────│ Translation │◀───────┘ │
│ │ Codex→OpenAI │ SSE stream │
│ └───────────────┘ │
│ │
│ ┌──────────┐ ┌───────────────┐ ┌─────────────┐ │
│ │ Auth │ │ Fingerprint │ │ Session │ │
│ │ OAuth/JWT│ │ Headers/UA │ │ Manager │ │
│ └──────────┘ └───────────────┘ └─────────────┘ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Auto-Maintenance (update-checker + scripts) │ │
│ └──────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────┘
│
curl subprocess
(Chrome TLS)
│
▼
chatgpt.com
/backend-api/codex/responses
📦 可用模型 (Available Models)
| 模型 ID | 别名 | 推理等级 | 说明 |
|---|---|---|---|
gpt-5.4 |
codex |
minimal / low / medium / high | 最新旗舰编程模型（默认） |
gpt-5.3-codex |
— | low / medium / high | 上一代旗舰 agentic 编程模型 |
gpt-5.3-codex-spark |
— | minimal / low | 超轻量编程模型 |
gpt-5.2-codex |
— | low / medium / high | agentic 编程模型 |
gpt-5.1-codex-max |
codex-max |
low / medium / high | 深度推理编程模型 |
gpt-5.1-codex-mini |
codex-mini |
low / medium / high | 轻量快速编程模型 |
模型列表会随 Codex Desktop 版本更新自动同步。后端也会动态获取最新模型目录。
🔗 客户端接入 (Client Setup)
Claude Code
在终端设置环境变量，即可让 Claude Code 通过 codex-proxy 使用 Codex 模型：
export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_API_KEY=your-api-key
export ANTHROPIC_MODEL=claude-opus-4-6 # Opus → gpt-5.4（默认）
# export ANTHROPIC_MODEL=claude-sonnet-4-6 # Sonnet → gpt-5.3-codex
# export ANTHROPIC_MODEL=claude-haiku-4-5-20251001 # Haiku → gpt-5.1-codex-mini
claude # 启动 Claude Code
| Claude Code 模型 | 映射到 Codex 模型 |
|---|---|
Opus (claude-opus-4-6) |
gpt-5.4 |
Sonnet (claude-sonnet-4-6) |
gpt-5.3-codex |
Haiku (claude-haiku-4-5-20251001) |
gpt-5.1-codex-mini |
也可以在控制面板 (
http://localhost:8080) 的 Anthropic SDK Setup 卡片中一键复制环境变量。
Cursor
Settings → Models → OpenAI API Base:
http://localhost:8080/v1
API Key（从控制面板获取）:
your-api-key
Continue (VS Code)
~/.continue/config.json:
{
"models": [{
"title": "Codex",
"provider": "openai",
"model": "codex",
"apiBase": "http://localhost:8080/v1",
"apiKey": "your-api-key"
}]
}
OpenAI Python SDK
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="your-api-key"
)
response = client.chat.completions.create(
model="codex",
messages=[{"role": "user", "content": "Hello!"}],
stream=True
)
for chunk in response:
print(chunk.choices[0].delta.content or "", end="")
OpenAI Node.js SDK
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 || "");
}
⚙️ 配置说明 (Configuration)
所有配置位于 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 版本与 Chromium 版本 |
model |
default, default_reasoning_effort |
默认模型与推理强度 |
auth |
rotation_strategy, rate_limit_backoff_seconds |
轮换策略与限流退避 |
tls |
curl_binary, impersonate_profile, proxy_url |
TLS 伪装与代理配置 |
API 密钥 (proxy_api_key)
在 config/default.yaml 中设置客户端访问代理时使用的 API Key：
server:
proxy_api_key: "pwd" # 自定义密钥，客户端请求时使用此值
# proxy_api_key: null # 设为 null 则自动生成 codex-proxy-xxxx 格式的密钥
- 自定义密钥：设置为任意字符串（如
"pwd"），客户端使用Authorization: Bearer pwd访问 - 自动生成：设为
null，代理会根据账号信息自动生成一个codex-proxy-前缀的哈希密钥 - 当前密钥始终显示在控制面板（
http://localhost:8080）的 API Configuration 区域
环境变量覆盖
| 环境变量 | 覆盖配置 |
|---|---|
PORT |
server.port |
CODEX_PLATFORM |
client.platform |
CODEX_ARCH |
client.arch |
HTTPS_PROXY |
tls.proxy_url |
📡 API 端点一览 (API Endpoints)
| 端点 | 方法 | 说明 |
|---|---|---|
/v1/chat/completions |
POST | 聊天补全 — OpenAI 格式（核心端点） |
/v1/messages |
POST | 聊天补全 — Anthropic 格式 |
/v1/models |
GET | 可用模型列表 |
/health |
GET | 健康检查 |
/auth/accounts |
GET | 账号列表（?quota=true 含配额） |
/auth/accounts/login |
GET | OAuth 登录入口 |
/debug/fingerprint |
GET | 调试：查看当前伪装头信息 |
/api/proxies |
GET | 代理池列表（含分配信息） |
/api/proxies |
POST | 添加代理（HTTP/HTTPS/SOCKS5） |
/api/proxies/:id |
PUT | 更新代理配置 |
/api/proxies/:id |
DELETE | 删除代理 |
/api/proxies/:id/check |
POST | 单个代理健康检查 |
/api/proxies/:id/enable |
POST | 启用代理 |
/api/proxies/:id/disable |
POST | 禁用代理 |
/api/proxies/check-all |
POST | 全部代理健康检查 |
/api/proxies/assign |
POST | 为账号分配代理 |
/api/proxies/assign/:accountId |
DELETE | 取消账号代理分配 |
/api/proxies/settings |
PUT | 更新代理池全局设置 |
🔧 命令 (Commands)
| 命令 | 说明 |
|---|---|
npm run dev |
开发模式启动（热重载） |
npm run build |
编译 TypeScript 到 dist/ |
npm start |
运行编译后的生产版本 |
npm run update |
手动触发完整更新流水线 |
📋 系统要求 (Requirements)
- Node.js 18+（推荐 20+）
- curl — 系统自带即可；
npm install自动下载 curl-impersonate 获得完整 Chrome TLS 伪装 - ChatGPT 账号 — 普通免费账号即可
- Docker（可选） — 推荐使用 Docker 部署
⚠️ 注意事项 (Notes)
- Codex API 为流式输出专用，设置
stream: false时代理会内部流式收集后返回完整 JSON - 本项目依赖 Codex Desktop 的公开接口，上游版本更新时会自动检测并更新指纹
config/default.yaml中的注释在自动更新后会丢失（使用结构化 YAML 写入）
📝 最近更新 (Recent Changes)
完整更新日志请查看 CHANGELOG.md，以下内容由 CI 自动同步。
[Unreleased]
- 代理池功能：支持为不同账号配置不同的上游代理，实现 IP 多样化和风险隔离
- Dashboard GitHub Star 徽章：Header 新增醒目的 ⭐ Star 按钮（amber 药丸样式），点击跳转 GitHub 仓库页面，方便用户收藏和获取更新
- Dashboard 检查更新功能：Footer 显示 Proxy 版本+commit 和 Codex Desktop 指纹版本，提供"检查更新"按钮同时检查两种更新
GET /admin/update-status端点：返回 proxy 和 codex 两种更新的当前状态POST /admin/check-update端点：同时触发 proxy 自检 + codex 指纹检查，自动应用可用更新- ...（查看全部更新）
v0.8.0 - 2026-02-24
- 原生 function_call / tool_calls 支持（所有协议）
v0.7.0 - 2026-02-22
developer角色支持（OpenAI 协议）- 数组格式 content 支持
- tool / function 消息兼容（所有协议）
- 模型响应中自动过滤 Codex Desktop 指令
📄 许可协议 (License)
本项目采用 **非商业许可 (Non-Commercial)**：
- 允许：个人学习、研究、自用部署
- 禁止：任何形式的商业用途，包括但不限于出售、转售、收费代理、商业产品集成
本项目与 OpenAI 无关联。使用者需自行承担风险并遵守 OpenAI 的服务条款。
Built with Hono + TypeScript | Powered by Codex Desktop API