Skip to content

linzy66/Codex-nexus

BranchesTags

Repository files navigation

English | 简体中文

Codex Nexus

让 Codex CLI / IDE / App 使用任何兼容 OpenAI 的 AI 模型

🔀 协议翻译 · 🎛️ Web 配置 · 🔑 多密钥 · 🗺️ 智能路由

Node.js Zero Dependencies License

目录

为什么需要它

OpenAI Codex 使用私有的 Responses API 协议，而 DeepSeek、Kimi、通义千问等绝大多数 AI 提供商只支持标准的 Chat Completions API。两者协议格式、事件流、工具调用结构完全不同。

Codex Nexus 充当智能协议翻译层：

  • 将 Codex 的 Responses API 请求实时翻译成 Chat Completions API
  • 将上游的流式 SSE 响应精确映射回 Responses API 事件序列
  • 完整保留多轮对话历史、工具调用、推理内容
  • 无需修改 Codex 的任何代码，零侵入
┌─────────────────┐      ┌─────────────────┐      ┌──────────────────┐
│  Codex CLI/IDE  │─────▶│   Codex Nexus   │─────▶│  DeepSeek / Kimi │
│  / Codex App    │◀─────│   :5800         │◀─────│  / Qwen / ...    │
└─────────────────┘      └─────────────────┘      └──────────────────┘
    Responses API          ↕ Translation            Chat Completions
                           Web Config :5801

核心特性

特性 说明
零依赖 纯 Node.js 原生模块，无需 npm install，复制即用
协议翻译 Responses API ↔ Chat Completions API 完整双向翻译
Web 配置界面 内置 HUD 风格配置面板，浏览器中完成全部设置
多提供商聚合 支持 10+ 主流提供商 + 任意自定义端点
模型智能路由 按 Codex 模型名自动路由到不同提供商
多密钥管理 每个提供商可配置独立 API Key
模型名映射 Codex 请求 gpt-4.1 自动映射为上游实际模型名
流式传输 精确的 SSE 事件序列翻译，兼容所有 Codex 客户端
多轮对话 完整的 previous_response_id 会话历史持久化
工具调用 支持 function calling、并行工具调用、tool_choice 转换
推理模型 支持 reasoning_content 回传（DeepSeek-R1、Kimi k2.6）
CORS Codex App（Web 端）可直接跨域访问
密钥转发 未配置静态密钥时，自动透传客户端 Bearer Token
自动配置 启动时自动注入 ~/.codex/config.toml + ~/.codex/auth.json
安全 路径遍历防护、密钥仅本地存储、会话数据不离境

支持的提供商

ID 名称 上游地址 默认映射
deepseek DeepSeek https://api.deepseek.com/v1 gpt-4.1 → deepseek-chat
kimi Kimi (Moonshot) https://api.moonshot.cn/v1 gpt-4.1 → kimi-k2.6
qwen 通义千问 https://dashscope.aliyuncs.com/compatible-mode/v1 gpt-4.1 → qwen-plus
mistral Mistral AI https://api.mistral.ai/v1 gpt-4.1 → mistral-large-latest
groq Groq https://api.groq.com/openai/v1 gpt-4.1 → llama-3.3-70b-versatile
xai xAI (Grok) https://api.x.ai/v1 gpt-4.1 → grok-3
openrouter OpenRouter https://openrouter.ai/api/v1 gpt-4.1 → deepseek/deepseek-chat
ollama Ollama (本地) http://localhost:11434/v1 本地模型
lmstudio LM Studio (本地) http://localhost:1234/v1 本地模型
custom 自定义 用户填写 用户配置

所有商标均属于其各自所有者，本项目与上述任何公司无关联关系。

快速开始

前置要求

  • Node.js ≥ 18
  • 一个兼容 OpenAI 的 API Key（如 DeepSeek、Kimi 等）

1. 下载并启动

# 克隆仓库
git clone https://github.com/linzy66/Codex-nexus.git
cd Codex-nexus

# 直接启动，零依赖
node server.js

Windows 用户：双击 start.cmd 或运行 start.ps1

2. 打开 Web 配置界面

启动后会显示：

[nexus] Codex Nexus 运行中: http://0.0.0.0:5800
[web]  配置界面: http://127.0.0.1:5801

在浏览器中打开：http://127.0.0.1:5801

3. 在浏览器中完成配置

  1. 核心链路配置 → 选择提供商（如 DeepSeek）
  2. 填写 API Key
  3. 模型路由配置 → 确认/修改模型映射
  4. 点击 「💾 保存当前部署图纸」 或 「🔄 执行保存并热重启」

完成！Codex 将自动通过 Nexus 使用你选择的模型。

工作原理

双服务架构

Codex Nexus 同时运行两个 HTTP 服务：

服务 端口 用途
Nexus API 5800 (可配置) Codex CLI/IDE/App 的 API 端点
Web Config Nexus port + 1 浏览器中的 HUD 配置面板

协议翻译流程

┌─────────────┐    POST /v1/responses    ┌──────────────┐
│  Codex CLI  │─────────────────────────▶│  Codex Nexus │
│             │  {model, input,            │              │
│             │   previous_response_id,    │  1. resolveRoute()
│             │   tools, stream}           │  2. responsesToChat()
└─────────────┘                            │  3. reqUpstream()
                                           │      │
                                           │      ▼
                                           │  ┌──────────────┐
                                           │  │ DeepSeek API │
                                           │  │ /chat/comp.  │
                                           │  └──────────────┘
                                           │      │
                                           │  4. createSSEEncoder()
                                           │      │
┌─────────────┐    SSE stream              │      ▼
│  Codex CLI  │◀───────────────────────────│  Responses API
│             │  response.output_text.delta │  event sequence
│             │  response.completed          │
└─────────────┘                            └──────────────┘

API 端点

Nexus API (端口 5800)

方法 路径 说明
POST /v1/responses 核心：Responses API → Chat Completions 翻译
GET /v1/responses/:id 根据 response_id 检索历史响应
POST /v1/chat/completions 直通代理，带路由和映射
GET /v1/models 代理上游模型列表

Web Config API (端口 5801)

方法 路径 说明
GET /nexus-ctrl/config 获取配置 + 提供商列表
POST /nexus-ctrl/config 保存配置，可选热重启
POST /nexus-ctrl/config/reset 恢复默认配置
GET /nexus-ctrl/status 获取运行状态
POST /nexus-ctrl/models 探测上游模型列表
GET /nexus-ctrl/codex-models 获取 Codex 模型补全列表
POST /nexus-ctrl/shutdown 安全停止所有服务

配置详解

所有配置保存在 ~/.codex-nexus/config.json，可通过 Web 界面或手动编辑。

基础配置

{
  "provider": "deepseek",
  "api_key": "sk-xxxxxxxxxxxxxxxx",
  "custom_upstream": "",
  "port": 5800,
  "host": "0.0.0.0",
  "autostart_nexus": true,
  "codex_config_auto": true,
  "codex_config_switch_default": false
}
字段 类型 说明
provider string 默认提供商 ID（deepseek、kimi、qwen...）
api_key string 默认 API Key，当提供商未配置独立密钥时使用
custom_upstream string 自定义上游 URL（当 provider 为 custom 时生效）
port number Nexus API 端口（默认 5800）
host string 监听地址（默认 0.0.0.0）
autostart_nexus boolean 启动时自动启动 Nexus 服务
codex_config_auto boolean 启动时自动注入 ~/.codex/config.toml
codex_config_switch_default boolean 同时将 Codex 默认模型切换为 Nexus 代理

模型路由 (model_routes) ⭐

按 Codex 模型名路由到不同提供商。例如：让 gpt-4.1 走 DeepSeek，o3 走 Kimi：

{
  "model_routes": {
    "gpt-4.1": {
      "provider": "deepseek",
      "model": "deepseek-chat"
    },
    "o3": {
      "provider": "kimi",
      "model": "kimi-k2.6"
    }
  }
}

路由优先级：model_routes[model] > provider default mapping。

提供商独立密钥 (provider_api_keys)

为不同提供商配置独立的 API Key：

{
  "provider_api_keys": {
    "deepseek": "sk-deepseek-xxxx",
    "kimi": "sk-kimi-xxxx",
    "qwen": "sk-qwen-xxxx"
  }
}

密钥优先级：provider_api_keys[provider] > global api_key > client Bearer Token。

Web 配置界面

Codex Nexus 内置了一套完整的 HUD 风格 Web 配置面板。

界面组成

  • 核心链路配置 — 选择提供商、填写 API Key、端口设置
  • 模型路由配置 — Codex 模型 → 提供商 → 上游模型 → 独立密钥
  • 上游模型探测 — 一键获取提供商可用模型列表
  • Codex 模型补全 — 自动补全本地已知模型名
  • 实时预览 — 实时显示将写入的 config.toml 内容
  • 系统状态监控 — 显示服务状态和端点地址

操作按钮

按钮 功能
💾 保存当前部署图纸 保存配置到 ~/.codex-nexus/config.json
🔄 执行保存并热重启 保存并热重启 Nexus
🔄 探测上游模型列表 获取上游可用模型
➕ 新增模型映射 添加路由规则
🗑️ 删除 删除映射规则
⏹ 终止核心服务 安全停止服务
🔃 初始化默认 恢复默认配置

安全说明

  • 密钥存储：API Key 仅保存在本机配置文件和内存中
  • 本地优先：配置和会话保存在 ~/.codex-nexus/
  • 路径防护：Web 静态文件服务阻止路径遍历
  • CORS：Nexus API 支持跨域；Web 配置界面仅监听 127.0.0.1
  • 请求限制：请求体最大 10MB

开发指南

项目结构

codex-nexus/
├── server.js          # 主入口
├── nexus.js           # 核心翻译引擎
├── config.js          # 配置管理
├── providers.json     # 提供商定义
├── public/
│   └── index.html     # Web 配置界面
├── fix-loopback.bat   # Codex App 回环修复脚本
├── start.cmd          # Windows CMD 启动脚本
├── start.ps1          # PowerShell 启动脚本
├── package.json
└── README.md

核心模块

文件 职责
nexus.js 协议翻译、会话存储、SSE 编码、模型路由
server.js 启动 Nexus API + Web Config，管理热重启、关闭和 Codex App 回环豁免
fix-loopback.bat Windows 管理员脚本，为 Codex App 添加 localhost 回环豁免
config.js 配置读写、Codex 配置注入、认证键写入

常见问题

Q: Codex 仍然调用 OpenAI 而不是 Nexus？

检查 ~/.codex/config.toml 中是否包含 [model_providers.codex-nexus] 区块。确保启动时 codex_config_auto: true。

Q: 如何同时使用多个提供商？

配置 model_routes，为不同 Codex 模型指定不同的 provider。每个提供商可单独配置 provider_api_keys。

Q: 本地模型（Ollama/LM Studio）需要 API Key 吗？

不需要。本地模型通常无需认证，留空即可。

Q: Codex App 提示 Missing environment variable: CODEX_NEXUS_KEY？

Nexus 启动时会自动写入 CODEX_NEXUS_KEY 到 ~/.codex/auth.json 和 Windows 用户环境变量。但 Codex App 必须在 Nexus 启动之后重启才能读到新的环境变量。

解决：先启动 node server.js，然后关闭并重新打开 Codex App。

Q: Codex App 显示「正在思考」但没有输出？

原因 1：Windows Store 回环限制。 Codex App 是 Windows Store 应用，默认无法访问 localhost。

解决：右键 fix-loopback.bat → 以管理员身份运行。或以管理员身份启动 node server.js（启动时会自动尝试修复）。

原因 2：上游 API Key 无效（401 错误）。 检查 Nexus 终端日志是否有 Upstream 401: Invalid token 提示，更换有效的 API Key。

卸载

  1. 按 Ctrl+C 停止服务，或点击 Web 界面的 「⏹ 终止核心服务」
  2. 删除项目文件夹
  3. 删除配置目录：rm -rf ~/.codex-nexus/
  4. 编辑 ~/.codex/config.toml，移除 [model_providers.codex-nexus] 区块

许可证

本项目使用自定义 Codex Nexus Use-Only License。

请阅读 LICENSE。使用本项目即表示你同意其中的全部条款。

重点摘要：

  • 允许个人非商业使用
  • 二次修改、发布修改版、集成到其他项目需获得作者书面授权
  • 禁止商用、复制复刻、重新分发或冒充原创
  • 本项目与 OpenAI、DeepSeek、Kimi、Qwen 等第三方无官方关联

Codex Nexus — built as an independent compatibility idea.

独立构思，仅为个人非商业使用和协议兼容探索。

About

Codex Nexus是基于 Web 界面管理的协议翻译中继层，使 Codex 全端生态（CLI/IDE/App）能够接入并使用任何兼容 OpenAI 标准的 AI 模型。

Resources

Readme

License

View license
Activity

Stars

19 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages