Codex 怎么接入国产大模型？OpenAI 兼容接口与 CodexBridge 使用思路

Wed, 13 May 2026 23:08:28 +0800

CodexBridge 是一个本地桥接工具，目标很直接：把 Codex CLI/SDK 封装成 OpenAI 兼容的 HTTP 服务。这样一来，原本只能在终端里使用的 Codex，可以被 OpenWebUI、Cherry Studio、脚本、自动化系统或任何兼容 OpenAI Chat Completions 的客户端调用。

它提供的核心接口是 /v1/chat/completions 和 /v1/models。前者负责对话，支持普通同步返回和 SSE 流式输出；后者让客户端能像读取模型列表一样发现可用模型。对已经接过 OpenAI API 的工具来说，这种设计的好处是改动小，通常只需要改 base URL、API key 和模型名。

项目地址：https://github.com/begonia599/CodexBridge

适合什么场景

CodexBridge 适合想把 Codex 接入现有 AI 客户端或工作流的人。例如：

想在 OpenWebUI、Cherry Studio 里直接选择 Codex 模型。
想用 curl、Python、Node.js 等脚本调用本机 Codex。
想让同一个前端同时接 OpenAI、Ollama、其他兼容接口和 Codex。
想保留 Codex 的本地线程、沙箱、工作目录和审批能力。
想给内部工具提供一个统一的 /v1/chat/completions 入口。

它不是一个新的大模型，也不是替代 Codex CLI 的完整前端。更准确地说，它是一个适配层：上游仍然是 Codex，本地桥接器负责把 OpenAI 风格的请求转换成 Codex 能理解的会话输入。

基本环境

运行前需要准备：

Node.js 18 或更高版本。
已安装并登录的 Codex CLI。
npm，或者按自己的习惯换成 pnpm / yarn。

源码部署的基本步骤如下：

git clone https://github.com/begonia599/CodexBridge
cd codexbridge
npm install
cp .env.example .env
cp .env .env.local

然后编辑 .env 或 .env.local，设置 API key、默认模型、工作目录、沙箱模式、联网权限等配置。

启动 HTTP 服务：

`1`	`npm run codex:server`

默认端口是 8080，可以通过 PORT 修改。服务启动后，可以访问：

1
2
3

GET /health
POST /v1/chat/completions
GET /v1/models

CLI 对话模式

除了 HTTP 服务，CodexBridge 也保留了一个轻量 CLI：

`1`	`npm run codex:chat`

CLI 里可以直接输入自然语言与 Codex 对话。常用命令有两个：

/reset：创建新的 Codex 线程。
/exit：退出 CLI。

当前线程 ID 会保存在 .codex_thread.json。下次启动 CLI 时，如果这个文件还在，就能继续之前的对话。

HTTP 调用示例

最基础的请求可以这样写：

curl http://localhost:8080/v1/chat/completions \
  -H "content-type: application/json" \
  -H "authorization: Bearer 123321" \
  -d '{"model":"gpt-5-codex:medium","session_id":"demo","messages":[{"role":"user","content":"ls"}]}'

这里有几个点需要注意：

authorization 里的 token 要和 CODEX_BRIDGE_API_KEY 一致。
model 可以带推理等级，例如 gpt-5-codex:medium 或 gpt-5-codex:high。
session_id 用来绑定会话，方便复用同一个 Codex 线程。

如果需要流式输出，加上 stream: true：

curl -N http://localhost:8080/v1/chat/completions \
  -H "content-type: application/json" \
  -H "authorization: Bearer 123321" \
  -d '{"model":"gpt-5-codex:high","session_id":"stream","stream":true,"messages":[{"role":"user","content":"一步步介绍如何创建 Node.js 项目"}]}'

对支持 OpenAI 流式响应的客户端来说，这种返回方式更接近正常聊天体验。

会话持久化怎么做

CodexBridge 的一个重点是会话映射。请求里可以通过这些字段传入会话 ID：

session_id
conversation_id
thread_id
user

也可以从请求头传：

x-session-id
session-id
x-conversation-id
x-thread-id
x-user-id

生产环境建议开启：

`1`	`CODEX_REQUIRE_SESSION_ID=true`

这样所有请求都必须带会话 ID，避免不同用户或不同聊天窗口混到同一个临时上下文里。会话映射保存在 .codex_threads.json，删除这个文件可以重置桥接层的映射关系；Codex 自身线程仍然保存在 ~/.codex/sessions。

如果 CODEX_REQUIRE_SESSION_ID=false 且请求没有提供会话 ID，桥接器会把当前 messages 展开成一次性输入发给 Codex。这种方式适合临时调用，但不适合长期对话。

多模态输入

CodexBridge 支持 OpenAI 风格的内容块，并会把图片转换成 Codex 可用的 local_image 输入。

远程图片可以写成：

{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/demo.png"
  }
}

本地图片可以写成：

{
  "type": "local_image",
  "path": "./images/demo.png"
}

远程资源会先下载到临时目录，回合结束后清理。实际使用时要注意请求体大小，尤其是把图片转成 base64 发送时，可能需要增大 CODEX_JSON_LIMIT。

结构化输出

如果客户端支持 response_format，可以让 CodexBridge 映射到 Codex 的 outputSchema。这适合让 Codex 返回固定 JSON 结构，例如检查结果、摘要、分类结果或自动化任务报告。

最小思路是：

{
  "model": "gpt-5-codex",
  "session_id": "lint",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "lint_report",
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["ok", "action_required"]
          }
        },
        "required": ["summary", "status"],
        "additionalProperties": false
      }
    }
  },
  "messages": [
    {
      "role": "user",
      "content": "检查 src/ 的 lint 问题，并以 JSON 返回结果"
    }
  ]
}

需要注意，type: "json_schema" 必须提供 schema，否则服务会直接返回 400。

关键环境变量

常用配置可以分成几类。

服务与鉴权：

1
2
3

PORT=8080
CODEX_BRIDGE_API_KEY=123321
CODEX_JSON_LIMIT=10mb

默认模型：

1
2

CODEX_MODEL=gpt-5-codex
CODEX_REASONING=medium

Codex 运行环境：

CODEX_WORKDIR=
CODEX_SANDBOX_MODE=read-only
CODEX_APPROVAL_POLICY=never
CODEX_SKIP_GIT_CHECK=true

联网能力：

1
2

CODEX_NETWORK_ACCESS=false
CODEX_WEB_SEARCH=false

如果只是给前端聊天用，默认关闭联网更稳。只有明确需要让 Codex 执行 curl、git clone 或使用 Web 搜索时，再单独打开对应开关。

Docker 和一键脚本

项目也提供 Docker 方式，适合想把服务常驻起来的场景：

1
2

docker compose up -d
docker compose logs -f codexbridge

也可以用项目提供的 Linux 安装脚本：

`1`	`curl -fsSL https://raw.githubusercontent.com/begonia599/CodexBridge/master/scripts/install.sh \| bash`

脚本会安装依赖、克隆或更新仓库、复制 .env.example，并通过 Docker Compose 启动服务。它需要 sudo 权限，适合在干净服务器上快速部署。已经有复杂 Node.js、Docker 或 Codex 环境的机器，建议先读脚本内容再执行。

常见问题

请求返回 413

通常是请求体太大，常见于 base64 图片。可以增大：

`1`	`CODEX_JSON_LIMIT=20mb`

提示 API key 无效

检查请求头是否带了：

`1`	`Authorization: Bearer <你的 CODEX_BRIDGE_API_KEY>`

或者使用 x-api-key。

Codex 报 Git 仓库限制

如果运行目录不是可信仓库，可能会触发 Codex 的检查。只在确认安全的环境中使用：

`1`	`CODEX_SKIP_GIT_CHECK=true`

想清空会话

桥接层会话映射在 .codex_threads.json，Codex 自身线程在 ~/.codex/sessions。停掉服务后删除对应文件或目录即可重置。

使用建议

本地试用时，可以先用默认 API key 和 read-only 沙箱跑通流程。确认 OpenWebUI、Cherry Studio 或脚本能正常调用后，再逐步调整 CODEX_WORKDIR、CODEX_SANDBOX_MODE、CODEX_NETWORK_ACCESS 和 CODEX_APPROVAL_POLICY。

如果要给多人使用，建议至少做三件事：

强制要求 session_id。
修改默认 API key。
明确限制工作目录和沙箱权限。

CodexBridge 的价值不在于功能复杂，而在于把 Codex 放进了现有 OpenAI 兼容生态里。只要客户端能改 base URL，它就有机会把 Codex 当成一个普通聊天模型来接入，同时保留本地线程、沙箱和工具调用这些 Codex 自身的能力。

OpenAI API on KnightLi的博客