Codex は中国系 LLM とどう接続する？OpenAI 互換 API と 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 風のモデル一覧として利用できます。すでに OpenAI API に対応しているツールなら、基本的には base URL、API key、モデル名を変更するだけで済みます。

プロジェクト：https://github.com/begonia599/CodexBridge

向いている用途

CodexBridge は、Codex を既存の AI クライアントやワークフローに組み込みたい場合に向いています。たとえば：

OpenWebUI や Cherry Studio で Codex を直接選びたい。
curl、Python、Node.js などのスクリプトからローカル Codex を呼びたい。
1 つのフロントエンドから OpenAI、Ollama、他の互換 API、Codex を同時に扱いたい。
Codex のローカルスレッド、サンドボックス、作業ディレクトリ、承認ポリシーを維持したい。
社内ツールに統一された /v1/chat/completions 入口を提供したい。

これは新しい LLM ではなく、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 サービスのほかに、軽量な CLI も用意されています。

`1`	`npm run codex:chat`

CLI では自然言語を直接入力して Codex と対話できます。よく使うコマンドは次の 2 つです：

/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 の重要な機能の 1 つがセッションマッピングです。リクエストでは次のフィールドからセッション 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 風の content block をサポートし、画像を 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 にマッピングできます。チェック結果、要約、分類結果、自動化レポートなど、固定 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 <your 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 を段階的に調整します。

複数人で使う場合は、少なくとも次の 3 点を行うべきです：

session_id を必須にする。
デフォルト API key を変更する。
作業ディレクトリとサンドボックス権限を明確に制限する。

CodexBridge の価値は機能の多さではなく、Codex を既存の OpenAI 互換エコシステムに入れられる点にあります。クライアントが base URL を変更できるなら、Codex を通常のチャットモデルのように扱いつつ、ローカルスレッド、サンドボックス、ツール利用といった Codex 本来の機能を維持できます。

ローカルデプロイ on KnightLiブログ