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`

腳本會安裝依賴、clone 或更新倉庫、複製 .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的博客