Skip to content

195440/codex-to-cursor

BranchesTags

Repository files navigation

codex-to-cursor

将 Codex 侧常见的 Chat Completions（/v1/chat/completions）上游，桥接为 Cursor 等客户端可走 POST /v1/responses 或 POST /v1/chat/completions 的 Node.js 代理服务（前者翻译为上游 Chat Completions 并桥接回 Responses；后者经兼容处理后转发上游）。

推荐架构

整体链路建议为：

  1. Sub2API（推荐前置）
    开源 AI API 网关，可把 Codex 等订阅统一成可访问的 OpenAI 兼容端点，便于拿到稳定的 Base URL + API Key。官方说明与部署方式见仓库 README。

  2. 本仓库（codex-to-cursor）
    监听本地或内网端口，接收 Cursor 发往 POST /v1/responses、POST /v1/chat/completions，以及可选的快速线路 POST /fast/v1/responses、POST /fast/v1/chat/completions 的请求；还可使用组合前缀 POST /{fast|default|normal}/<reasoning_effort>/v1/responses 与对应的 .../chat/completions（见下文）。对 Responses 路径会翻译成上游 /v1/chat/completions 并把结果桥接回 Responses；对 Chat Completions 路径则做兼容后转发上游。/fast/v1/* 与路径中第一段为 fast 的组合前缀会在转发到上游前强制写入 service_tier: "priority"。

  3. Cursor
    将 OpenAI 兼容 Base URL 指向本服务（见下文示例），在客户端里选用 Responses 或 Chat Completions 线路均可（视 Cursor 版本与设置项名称而定）。

  Cursor
    ├─ POST /v1/responses
    ├─ POST /v1/chat/completions
    ├─ POST /fast/v1/responses
    ├─ POST /fast/v1/chat/completions
    ├─ POST /default/high/v1/responses   （示例：普通线路 + 路径默认思考强度）
    └─ POST /fast/high/v1/chat/completions （示例：快速线路 + 路径默认思考强度）
           │
           ▼
  codex-to-cursor ──POST /v1/chat/completions──► Sub2API / Codex 上游

默认行为说明

  • 监听端口：3060（可用环境变量修改）
  • 上游地址：OPENAI_BASE_URL 或 UPSTREAM_BASE_URL（未设置时保留代码内默认示例地址，部署请务必改成你的 Sub2API 或 Codex 网关地址）
  • 鉴权（以客户端为准、env 为备选）：
    • 客户端（如 Cursor）请求头里携带 Authorization: Bearer <token> 时，以该 token 为准并原样透传给上游，本服务不再做等值校验。
    • 客户端未携带 Authorization 时，回退使用环境变量 OPENAI_API_KEY 作为上游凭证。
    • 既未携带 Authorization、且 OPENAI_API_KEY 也未配置时，返回 401 missing_api_key。
    • Authorization 存在但不是 Bearer <非空 token> 形式，返回 401 invalid_api_key（用于辅助排错，不会回落到环境变量）。
  • 上游 User-Agent：默认使用 codex-tui 样式 UA，可通过 UPSTREAM_USER_AGENT 覆盖
  • Wire API：对外表现为 responses（健康检查 GET /healthz 会返回 wire_api: "responses"）
  • 状态：previous_response_id 等多轮上下文依赖进程内内存；多实例部署时需保持单实例或使用外部状态方案（见 PM2 说明）

快速开始

npm install
cp .env.example .env
# 编辑 .env：填写上游 Sub2API/Codex 的地址。
# OPENAI_API_KEY 为可选的回退凭证：
# - 在 Cursor 端按上游要求配置 API Key 即可，本服务会原样透传到上游；
# - 仅当 Cursor 未携带 Authorization 时，才会回退使用 .env 里的 OPENAI_API_KEY。
npm run build
npm run start

环境变量（.env）

变量 说明
PORT 本服务监听端口，默认 3060
OPENAI_BASE_URL 上游 OpenAI 兼容根地址（与 Sub2API 文档中的服务地址一致，不要带路径后缀如 /v1）
UPSTREAM_BASE_URL 与 OPENAI_BASE_URL 二选一，后者优先
OPENAI_API_KEY 可选；上游回退凭证。客户端携带 Authorization: Bearer ... 时本服务原样透传到上游，不再做等值校验；客户端未携带 Authorization 时回退使用本变量。两者都缺失时返回 401 missing_api_key。
DEFAULT_MODEL 默认模型名称；请求未显式传入 model 时使用，默认 gpt-5.4
STATE_TTL_SECONDS 内存中对话状态保留时间，默认 86400
BODY_LIMIT_MB 单个请求体大小上限，默认 20
UPSTREAM_USER_AGENT 转发到上游时携带的 User-Agent，未设置时使用内置默认值
LOG_LEVEL 日志级别，默认 debug

Cursor 侧配置思路

将 Cursor 的 OpenAI 兼容 Base URL 设为本服务地址：

  • 普通线路使用带 /v1 的地址，例如 http://127.0.0.1:3060/v1
  • 快速线路使用带 /fast/v1 的地址，例如 http://127.0.0.1:3060/fast/v1
  • 组合前缀（在 Base URL 中一次性选定线路与默认思考强度）：http://127.0.0.1:3060/fast/high/v1 或 http://127.0.0.1:3060/default/xhigh/v1。第一段为 fast 时等同快速线路（强制 service_tier: "priority"）；default 与 normal 等同普通线路（不强制 priority）。第二段为路径默认 reasoning_effort，取值为 none、minimal、low、medium、high、xhigh。若请求体里已包含 reasoning / reasoning_effort，则以请求体为准。

在 Cursor 的 API Key 中填写 能被上游接受 的 Key 即可：本服务会以客户端传入的 Authorization: Bearer ... 为准，原样透传给上游，不会与服务端 .env 中的值做等值校验。可直接理解为：Cursor 侧填的是本服务的接口前缀，所以要写成带对应路径前缀的地址；上游 OPENAI_BASE_URL / UPSTREAM_BASE_URL 则仍然不要带 /v1 或 /fast/v1。

如果 Cursor 端未填写 API Key（请求未携带 Authorization），本服务会回退使用 .env 中的 OPENAI_API_KEY 调用上游；若 .env 中也未配置，则返回 401 missing_api_key。如果 Authorization 存在但不是合法的 Bearer <非空 token> 形式，会直接返回 401 invalid_api_key，不会回落到环境变量（用于辅助客户端定位配置错误）。

提示：如果你的服务部署在公网，不要在 .env 中配置 OPENAI_API_KEY 作为隐式回退——否则任何未携带 Authorization 的请求都会消耗你配置的上游额度。建议要么留空、要么在网关层另行限制访问。

若配置项中有 Wire API / API 形态 等选项，可按需选择 Responses 或 Chat Completions（含 /v1、/fast/v1 与 /{tier}/{effort}/v1 等形式）；本服务在 /healthz 中仍会报告 wire_api: "responses"，表示对 Responses 线路的适配能力。

若请求未显式传入 model，本服务默认使用 gpt-5.4；若未显式传入思考强度，则默认使用 xhigh。若使用 /fast/v1 前缀访问，则本服务还会在转发到上游前强制写入 service_tier: "priority"。

推荐在 Cursor 中额外增加一个自定义模型名称，填写为 gpt 5.4（注：此处按展示名称书写，中间不加 -；实际默认模型 ID 仍为 gpt-5.4）。

具体 UI 名称以 Cursor 版本为准；核心是：客户端无论打上述哪条路径，最终都由本服务对接上游 Chat Completions。

图片 MCP

若你在 Cursor 中为图片理解额外接入了图片 MCP（例如项目内的 project-image-vision），请特别注意：

  • 可读取的图片来源：仅限本地路径的图片文件（例如仓库里的截图、设计稿、示意图等）。
  • 行为约束：图片内容应通过图片 MCP 读取与理解，不应绕过 MCP 直接读图。
  • 配置位置：图片 MCP 的环境变量配置在 .cursor/mcp.json。

图片 MCP 配置

图片 MCP 环境变量（.cursor/mcp.json）

变量 说明
WORKSPACE_ROOT 工作区根目录，供图片 MCP 解析并限制可访问的项目内文件路径；通常填写 ${workspaceFolder}
OPENAI_BASE_URL 图片 MCP 调用的模型服务根地址
OPENAI_API_KEY 图片 MCP 调用的模型服务 API Key
OPENAI_MODEL 图片 MCP 使用的模型名称
OPENAI_PROMPT 图片 MCP 发给模型的默认提示词

若以上变量缺失、填写错误，或图片 MCP 服务未正常启动，则图片读取流程会失败；即使配置正确，也仍然只支持项目内图片文件，不支持直接粘贴到对话框中的图片。

配置截图

下图分别对应 Cursor 官方站点中的使用记录页面，以及 Cursor IDE 中接入本服务后的实际使用界面，可作为配置位置与接入效果的参考。

图 1：Cursor 站点记录

Cursor 站点记录

图 2：Cursor IDE 使用

Cursor IDE 使用

暴露的 HTTP 接口

  • GET /healthz — 健康检查
  • POST /v1/responses — 将 Responses 请求翻译为上游 Chat Completions 并返回 Responses 形态结果（含流式子集）
  • POST /v1/chat/completions — 对部分 Chat Completions 请求做兼容处理后转发上游（便于调试或混合客户端）
  • POST /fast/v1/responses — 与 /v1/responses 相同，但会在转发前强制设置 service_tier: "priority"
  • POST /fast/v1/chat/completions — 与 /v1/chat/completions 相同，但会在转发前强制设置 service_tier: "priority"
  • POST /{fast|default|normal}/<reasoning_effort>/v1/responses — 行为同 /v1 或 /fast/v1（由第一段决定），并以路径中的 <reasoning_effort> 作为未在请求体中指定时的默认思考强度
  • POST /{fast|default|normal}/<reasoning_effort>/v1/chat/completions — 同上，针对 Chat Completions 入站

其它路径会返回 404 说明。

使用 PM2 常驻（单实例）

previous_response_id 等状态在内存中维护，因此示例配置使用 fork 模式、单进程，避免多实例导致上下文不一致。

npm install
cp .env.example .env
npm run build
npm run pm2:start
npm run pm2:save

在目标机器上首次设置开机自启：

npx pm2 startup

按终端提示执行其生成的命令（通常需 sudo）。之后进程列表有变更时继续使用 npm run pm2:save。

代码或环境变更后：

npm run build
npm run pm2:restart
npm run pm2:save

常用命令：npm run pm2:status、npm run pm2:logs、npm run pm2:stop、npm run pm2:delete。

能力范围

已支持（子集）

  • 文本输入
  • 图文混合的用户消息
  • instructions
  • 通过进程内存储重放实现的 previous_response_id
  • text.format 中的 json_object 与 json_schema
  • 函数工具与自定义工具
  • 非流式与流式 SSE 的部分场景

不支持

  • Responses 内置工具，例如 web_search、file_search、computer_use、code_interpreter、mcp
  • conversation、prompt、include、background、max_tool_calls 等
  • 音频/文件等多模态（非本文本/图片子集）

免责声明

使用第三方网关或中转可能涉及各服务商的用户协议与合规要求，请自行评估风险；本仓库仅提供技术桥接实现，不对上游服务可用性或账号状态负责。

许可

本项目采用 GNU Affero General Public License v3.0（AGPL-3.0）授权，完整条文见仓库根目录 LICENSE。概要说明见 GNU AGPL-3.0 官方页面。

About

将 Codex Chat Completions 上游桥接为 Cursor 可用的 /v1/responses（OpenAI Responses 形态）

Resources

Readme

License

AGPL-3.0 license
Activity

Stars

33 stars

Watchers

1 watching

Forks

3 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages