Skip to content

icebear0828/codex-proxy

BranchesTags

Repository files navigation

Codex Proxy

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

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

Node.js TypeScript Hono Docker Desktop License

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

简体中文 | English


X Issues 赞赏



微信赞赏码
☕ 赞赏 		微信交流群
💬 交流群

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   # 生产模式

macOS / Linux 安装时自动下载 curl-impersonate（Chrome TLS 伪装）。Windows 下不可用，自动降级为系统 curl。

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

验证

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"codex","messages":[{"role":"user","content":"Hello!"}],"stream":true}'

看到 AI 回复的文字流即部署成功。

🌟 核心功能

🔌 全协议兼容

  • 兼容 /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 和延迟
  • 不可达自动标记 — 代理不可达时自动排除

🛡️ 反检测与协议伪装

  • Chrome TLS 指纹 — curl-impersonate 复刻完整 Chrome TLS 握手
  • Desktop 请求头 — originator、User-Agent、sec-ch-* 等头按 Codex Desktop 顺序发送
  • 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   │   │ curl TLS/FFI │   │
│  └──────────┘   └───────────────┘   └──────┬───────┘   │
│       ▲                                     │           │
│       │          ┌───────────────┐          │           │
│       └──────────│  Translation  │◀─────────┘           │
│                  │ Codex→Multi   │  SSE stream          │
│                  └───────────────┘                       │
│                                                          │
│  ┌──────────┐  ┌───────────────┐  ┌──────────────────┐  │
│  │   Auth   │  │  Fingerprint  │  │   Model Store    │  │
│  │ OAuth/JWT│  │Chrome TLS/UA  │  │ Static + Dynamic │  │
│  │  Relay   │  │   Cookie      │  │  Plan Routing    │  │
│  └──────────┘  └───────────────┘  └──────────────────┘  │
│                                                          │
└──────────────────────────────────────────────────────────┘
                          │
                  curl-impersonate / FFI
                    (Chrome TLS 指纹)
                          │
                   ┌──────┴──────┐
                   ▼             ▼
              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 卡片可一键复制环境变量。

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

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

Windsurf

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

Cline (VSCode 扩展)

  1. 打开 Cline 侧边栏 → 设置齿轮
  2. API Provider: 选择 OpenAI Compatible
  3. Base URL: http://localhost:8080/v1
  4. API Key: 你的 API Key
  5. 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

  1. 设置 → 模型服务 → 添加
  2. 类型: OpenAI
  3. API 地址: http://localhost:8080/v1
  4. API Key: 你的 API Key
  5. 添加模型 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 curl_binary, impersonate_profile, proxy_url, force_http11 TLS 伪装与代理
quota refresh_interval_minutes, warning_thresholds, skip_exhausted 额度刷新与预警
session ttl_minutes, cleanup_interval_minutes Dashboard session 管理

TLS 配置

tls:
  curl_binary: auto                # auto 自动检测 curl-impersonate
  impersonate_profile: chrome144   # Chrome 伪装版本
  proxy_url: null                  # null = 自动检测本地代理
  force_http11: false              # HTTP/2 失败时自动降级 HTTP/1.1；true = 强制 HTTP/1.1

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/relay POST 添加 Relay 中转站账号
/auth/accounts/batch-delete POST 批量删除账号
/auth/accounts/batch-status POST 批量修改账号状态

管理接口

端点 方法 说明
/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+）
  • curl — 系统自带即可；npm install 自动下载 curl-impersonate
  • ChatGPT 账号 — 免费账号即可
  • Docker（可选）

⚠️ 注意事项

  • Codex API 为流式输出专用，stream: false 时代理内部流式收集后返回完整 JSON
  • 本项目依赖 Codex Desktop 的公开接口，上游版本更新时会自动检测并更新指纹
  • Windows 下 curl-impersonate 不可用，自动降级为系统 curl，建议搭配本地代理或改用 Docker

📝 最近更新

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

[Unreleased]

Added

  • Dashboard「基础设置」面板：端口、上游代理、强制 HTTP/1.1 可在 UI 配置，保存到 data/local.yaml（更新不覆盖）
  • HTTP/2 自动降级：curl 因 H2 错误失败时自动切换 HTTP/1.1（TTL 10 分钟后重试 H2）
    • exit code 16（H2 专属）无条件触发；其他 exit code 需 stderr 含 H2 关键词
    • force_http11 配置仍可手动强制 HTTP/1.1 Changed
  • TLS 指纹对齐：curl-impersonate 升级支持 chrome144 profile（v1.5.1），KNOWN_CHROME_PROFILES 新增 133/136/142/144
  • 默认协议从 HTTP/1.1 改为 HTTP/2，匹配真实 Codex Desktop 行为
  • 指纹版本同步至 v26.318.11754（build 1100） Fixed
  • 配置 overlay 机制：Dashboard 设置写入 data/local.yaml（gitignored），不再修改 config/default.yaml
    • git pull 不会覆盖用户自定义设置（proxy_api_key、rotation_strategy、quota 等）
    • config/default.yaml 的 proxy_api_key 默认值改为 null（自动生成）

v0.8.0 - 2026-02-24

Added

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

☕ 赞赏 & 交流

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

⭐ Star History

Star History Chart

📄 许可协议

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

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

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

Built with Hono + TypeScript | Powered by Codex Desktop API

About

OpenAI-compatible proxy for ChatGPT Codex Responses API

Resources

Readme
Activity

Stars

375 stars

Watchers

1 watching

Forks

65 forks
Report repository

Releases 75

1.0.88 Latest
Mar 24, 2026
+ 74 releases

Packages

 
 
 

Contributors 4

Languages