codex-proxy
icebear0828/codex-proxy加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
你可能已经习惯了在 Cursor、VS Code（Continue 插件）或 Claude Code 中写代码——这些工具配合 AI 模型确实能大幅提升编程效率。但如果你的主力模型是 OpenAI 的 o4-mini，却想在 Cursor 里直接用它调用 ChatGPT 的 Code Interpreter（编程助手能力），事情就没那么简单了。
原因是：Codex Desktop（OpenAI 桌面编程应用）使用的是一套专有的 Responses API，和 OpenAI 标准的 /v1/chat/completions 接口并不完全兼容。Codex Proxy 正是为解决这个「协议断层」而生的。
Codex Proxy 是一个轻量级的本地中转服务（Reverse Proxy），它的核心功能是：将 Codex Desktop 的 Responses API 翻译成多种标准协议，让支持这些协议的客户端（如 Cursor、Claude Code、Continue）能直接调用 Codex Desktop 的编程能力。
项目由个人开发者 IceBearMiner 创建和维护，于 2026 年 2 月上线，目前已在 GitHub 获得 1400+ Stars、189 Fork、23 个 open issues。README 提供了完整的中文文档，并附带微信/Telegram 交流群二维码。
一句话理解：它就像一个「翻译官」，把 Codex Desktop 的语言翻译成各种 AI 客户端都能听懂的话。
项目提供两种部署方式：Docker 一键部署（推荐新手）和源码编译（适合进阶用户）。
# 1. 克隆仓库
git clone https://github.com/icebear0828/codex-proxy.git
cd codex-proxy
# 2. 复制配置
cp .env.example .env
# 编辑 .env，填入你的 ChatGPT JWT Token（可选，也可留空走 OAuth）
# 3. 启动
docker-compose up -d
# 4. 访问管理界面
open http://localhost:8080
Docker 镜像已发布到 GitHub Container Registry（ghcr.io/icebear0828/codex-proxy:latest），无需本地编译。docker-compose 默认仅绑定本地回环地址（127.0.0.1:8080），不会将服务暴露到局域网，更加安全。
# 需要 Node.js 18+ 和 Rust 工具链
git clone https://github.com/icebear0828/codex-proxy.git
cd codex-proxy
npm install
npm run build
npm start
源码构建需要编译 Rust 原生模块（codex-tls），这是用于 TLS 连接优化的 NAPI-RS 插件。如果只想快速试用，建议直接用 Docker 方式。
Codex Proxy 的核心价值在于多协议兼容。它同时暴露了以下接口：
| 协议 | 端点 | 兼容客户端 |
|---|---|---|
| OpenAI /v1/chat/completions | POST /v1/chat/completions | Cursor（OpenAI API 模式）、Continue 插件、任何 OpenAI SDK |
| Anthropic Messages API | POST /v1/messages | Claude Code、部分 Anthropic 兼容客户端 |
| Google Gemini API | POST /v1beta/models/:model:generateContent | Gemini Studio、需要 Gemini key 的工具 |
| Codex Responses API（透传） | POST /v1/responses | WebSocket transport，直通 Codex 原生协议 |
| Ollama 兼容桥接（可选） | POST /api/chat | 本地 Ollama 生态客户端 |
也就是说，一套配置，多端复用。你在 Cursor 里配置好 OpenAI 兼容端点，Claude Code 里配置 Anthropic 端点，实际上都走的是同一个 Codex Desktop 实例。
支持的模型包括 o4-mini、o3、o3-pro 等 OpenAI 模型系列，以及通过 Gemini 端点调用的 Google 模型。项目还支持自定义模型配置（config/models.yaml）。
代码采用 Node.js + TypeScript 编写，核心框架为 Hono（轻量高性能 Web 框架），相比 Express/Koa 有更好的性能表现。项目使用 monorepo 结构：
codex-proxy/
src/
auth/ # 认证模块（AccountPool, RefreshScheduler）
proxy/ # 代理池（ProxyPool, WS-Pool）
routes/ # 路由层（chat, messages, gemini, responses 等）
translation/ # 协议翻译层（14个翻译器）
tls/ # TLS 传输层（Rust 原生 addon）
middleware/ # 中间件（认证、CORS、日志、错误处理）
models/ # 模型配置与刷新
native/ # Rust NAPI-RS 原生模块（codex-tls）
web/ # 前端管理界面（Preact + Vite + Tailwind）
shared/ # 共享类型和 i18n
最核心的模块是 src/translation/ 下的 14 个翻译器。这些翻译器负责在不同的 API 协议之间进行请求和响应的格式转换：
以 OpenAI 到 Codex 的翻译为例：客户端发送 /v1/chat/completions 请求时，openai-to-codex.ts 会把 messages[].role、工具调用格式（tools/function_call）、推理努力参数（reasoning_effort）等转换为 Codex 的 instructions + input + tools 格式。响应则通过 codex-to-openai.ts 将 Codex 的事件流转换为 SSE 格式的 choice.delta 事件。
项目包含一个 Rust 编写的原生模块（native/），使用 NAPI-RS 构建，编译为 Linux（x64/arm64）、macOS（arm64）、Windows（x64）三个平台的 .node 文件。这个模块用于优化 TLS 连接性能，减少 HTTPS 握手开销。多阶段 Dockerfile 会单独构建这个插件再复制到最终镜像中。
AccountPool 管理多个 ChatGPT 账号的 JWT Token，支持轮询（round_robin）、最少使用（least_used）、粘性（sticky）三种负载均衡策略。RefreshScheduler 负责定期刷新 Token，支持带锁的并发刷新防止多实例竞争。
认证方式支持三种模式：
内置的 Web UI（web/）提供了完整的管理面板：
Web UI 使用 Preact（轻量级 React 替代）构建，配合 Tailwind CSS，界面风格为深色 GitHub 风格。
项目包含完整的 Vitest 测试套件，分类清晰：
通过 npm run test 运行完整测试，npm run test:watch 进入监听模式，npm run test:stress 执行压测。测试配置使用 @vitest/coverage-v8 生成覆盖率报告。
Claude Code 使用 Anthropic Messages API，只需将 Endpoint 指向 Codex Proxy 的 /v1/messages 端点即可。
从代码活跃度来看：
项目正处于快速迭代期，功能已经相当完善，文档也做到了中英双语。对于想用 ChatGPT 编程能力但受限于生态锁定的用户来说，这是一个非常实用的工具。
图1：Codex Proxy Telegram 交流群二维码