🚀 Codex Open-Source Provider

让 Codex Desktop 接入本地开源推理模型

轻量级 Node.js 代理网关，实现 Responses API ↔ Chat Completions 协议双向转换

快速开始 · 功能特性 · 支持模型 · 配置指南 · 常见问题 · 参与贡献

---

📖 这是什么？

Codex Open-Source Provider 是一个轻量级的 Node.js 代理网关，用于让 Codex Desktop 通过 vLLM 接入本地开源推理模型。

🎯 解决的核心问题

Codex Desktop 原生仅支持 OpenAI 的 Responses API，而本地 vLLM 服务通常只暴露标准的 Chat Completions API。这两个协议在消息格式、角色定义和流式事件上存在显著差异。

本项目在中间架设了一层智能代理，自动完成以下转换：

┌─────────────────────┐         ┌──────────────────┐         ┌──────────────────┐
│   Codex Desktop     │   HTTP  │  codex-proxy.js  │   HTTP  │     vLLM        │
│   (Responses API)   │ ◄─────► │  (localhost:8001) │ ◄─────► │ (your-server)    │
└─────────────────────┘         └──────────────────┘         └──────────────────┘

转换方向	Desktop 发送	代理转发给 vLLM
消息格式	{input: [{type:"message", role:"developer", ...}]}	{messages: [{role:"system", ...}]}
角色映射	developer	system
响应事件	response.completed	SSE data: [DONE]

---

✨ 功能特性

功能	描述
🔄 协议转换	Responses API ↔ Chat Completions 无缝双向转换
🤖 多模型支持	Qwen3/3.5/3.6、DeepSeek-R1、Kimi K2、GPT-OSS-120B
🧠 智能思考控制	自动识别模型家族，自动配置 thinking 模式
⚡ SSE 流式传输	实时流式响应，告别等待
🔧 灵活配置	环境变量一键调整端口和服务地址
🛡️ CORS 支持	跨域请求支持，本地开发无障碍
📦 零依赖核心	仅需 Node.js，无需额外依赖
🔄 PM2 生产就绪	推荐使用 PM2 进行进程管理和守护

---

🧩 支持模型

模型	思考模式	输出格式	自动配置
Qwen3 / 3.5 / 3.6	默认开启	仅 reasoning，content 为空	自动禁用 thinking
DeepSeek-R1 系列	默认开启	reasoning + content 双输出	保持默认
Kimi K2 Thinking	默认开启	reasoning + content 双输出	保持默认
GPT-OSS-120B	默认开启	reasoning + content 双输出	保持默认

💡 提示：代理会根据模型名称自动匹配最佳配置，无需手动干预。

---

🚀 快速开始

前置条件

• ✅ Node.js 18+
• ✅ vLLM 服务已运行（默认 http://localhost:8000）
• ✅ Codex Desktop 已安装
• ⭐ PM2（推荐，用于生产部署）

1. 克隆仓库

git clone https://github.com/Delight0628/codex-opensource-provider.git
cd codex-opensource-provider

2. 安装依赖

npm install

3. 启动代理

# 开发模式
npm start

# 或使用 npm run dev（热重载）
npm run dev

# 生产模式（推荐）
npm install -g pm2
pm2 start codex-proxy.js --name "codex-proxy"
pm2 save

4. 配置 Codex Desktop

编辑 ~/.codex/config.toml：

[profiles]
active = "local-qwen"

[profiles.local-qwen]
base_url = "http://localhost:8001/v1"
api_key = "empty"
model = "Qwen/Qwen3.6-35B-A3B-FP8"
wire_api = "responses"

[profiles.local-deepseek]
base_url = "http://localhost:8001/v1"
api_key = "empty"
model = "deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B"
wire_api = "responses"

5. 验证服务

# 测试代理是否正常响应
curl http://localhost:8001/v1/models

---

⚙️ 配置指南

环境变量

变量名	默认值	说明
PROXY_PORT	8001	代理监听端口
VLLM_URL	http://localhost:8000	vLLM 服务地址

# Linux / macOS
export PROXY_PORT=8002
export VLLM_URL="http://192.168.1.100:8000"
pm2 restart codex-proxy --update-env

# Windows PowerShell
$env:PROXY_PORT = "8002"
$env:VLLM_URL = "http://192.168.1.100:8000"
pm2 restart codex-proxy --update-env

手动控制 Thinking 模式

在请求体中添加 thinking 字段可覆盖自动检测：

{
  "input": [...],
  "model": "Qwen/Qwen3.6-35B-A3B-FP8",
  "thinking": true,
  "max_output_tokens": 4096
}

---

🔄 模型切换指南

第一步：确认 vLLM 中已加载目标模型

curl http://localhost:8000/v1/models

第二步：更新配置

[profiles]
active = "local-deepseek"  # 切换到目标 profile

第三步：重启 Codex Desktop

完全退出并重新打开 Codex Desktop，选择新模型即可。

---

🛠️ PM2 进程管理

# 启动
pm2 start codex-proxy.js --name "codex-proxy"
pm2 save

# 重启
pm2 restart codex-proxy

# 停止
pm2 stop codex-proxy

# 删除
pm2 delete codex-proxy

# 查看日志
pm2 logs codex-proxy

# 设置开机自启
pm2 startup

---

❓ 常见问题 (FAQ)

🔄 Desktop 显示 "Reconnecting..." 怎么办？

原因：代理未正确发送 response.completed 终止事件。

解决方案：检查代理日志，确认看到 <- 200 from vLLM (N chars) 消息。

❌ "Unexpected message role" 错误

原因：vLLM 不识别 developer 角色。

解决方案：代理已自动将 developer 映射为 system，确保使用最新版本的代理。

🧠 输出包含思考过程

Qwen 模型：代理已自动禁用 thinking（enable_thinking: false）。如需查看思考过程，发送 "thinking": true。

DeepSeek/Kimi：reasoning 和 content 会被提取并合并。如只需最终答案，可修改代理仅提取 delta.content。

📊 日志显示 "0 chars"

常见原因：

• SSE 分隔符不匹配（\n\n vs \n）
• vLLM 返回了 400/500 错误
• 角色映射错误

解决方案：检查 vLLM 服务日志和代理错误输出。

🔌 "stream disconnected before completion" 错误

原因：代理在发送 response.completed 之前关闭了 HTTP 连接。

解决方案：确保所有完成事件在 res.end() 之前发送完毕。

🔐 如何在生产环境配置 API Key？

修改 codex-proxy.js 中的 Authorization header，或通过环境变量传入：

export API_KEY="your-production-key"

---

📁 项目结构

codex-opensource-provider/
├── codex-proxy.js           # 🎯 主代理服务器
├── package.json             # 📦 项目配置
├── README.md                # 📖 本文档
├── CONTRIBUTING.md          # 🤝 贡献指南
├── CHANGELOG.md             # 📝 更新日志
├── LICENSE                  # 📜 MIT 许可证
├── .gitignore               # 🙈 Git 忽略规则
└── docs/
    └── deployment-guide.md  # 📋 详细部署指南

---

🔒 安全说明

• ✅ 代码中无硬编码 API Key 或密钥
• ✅ CORS 已启用，支持本地开发
• ✅ 默认使用 Bearer empty（生产环境请自行配置）
• ✅ 请求解析包含输入验证

---

🤝 参与贡献

欢迎所有形式的贡献！无论是提交 Bug 报告、功能建议还是代码贡献。

贡献流程

1. 🍴 Fork 本仓库
2. 🌿 创建特性分支：git checkout -b feature/amazing-feature
3. 💾 提交更改：git commit -m '✨ Add amazing feature'
4. 📤 推送分支：git push origin feature/amazing-feature
5. 📬 创建 Pull Request

详细贡献指南请查看 CONTRIBUTING.md。

---

📄 许可证

本项目基于 MIT 许可证 开源。

---

⭐ Star 历史

如果这个项目对你有帮助，请给个 ⭐ 支持一下！

---

Made with ❤️ by Delight0628

如果觉得有用，请给个 ⭐ 鼓励一下！