Codex は中国系 LLM とどう接続する？CCX で OpenAI 互換 API を一元管理する

Wed, 13 May 2026 23:20:40 +0800

CCX は AI API プロキシ兼プロトコル変換ゲートウェイです。Claude Messages、OpenAI Chat Completions、OpenAI Images、Codex Responses、Gemini API を 1 つのサービス入口にまとめ、チャネル、キー、モデルマッピング、優先度、フェイルオーバー、トラフィック監視を設定する Web 管理画面も提供します。

Claude、OpenAI、Gemini、Codex を同時に使っている場合や、OpenAI API 互換の上流サービスを複数維持している場合、CCX の価値は入口と管理の一元化にあります。クライアントは 1 つのサービスアドレスへ接続し、後続の上流チャネルは CCX が選択します。

プロジェクト：https://github.com/BenedictKing/ccx

CCX が解決すること

複数の AI API を混在させると、次の問題が起きやすくなります。

プロバイダーごとにパス、認証方式、リクエスト形式が異なる。
同じ種類のモデルでも複数の上流があり、base URL や API key を手動で切り替える必要がある。
ある key やチャネルが失敗したとき、クライアント側では自動でバックアップへ切り替わらないことが多い。
チーム利用では、モデル許可リスト、プロキシ、カスタムヘッダー、呼び出しログの集中管理が難しい。
Claude、Gemini、OpenAI Chat、画像 API、Codex Responses を同時に扱うと設定が散らばる。

CCX はこれらの差異をプロキシ層へ集約します。フロントエンドツール、スクリプト、業務サービスは CCX だけにアクセスし、CCX が API 種別、モデル、チャネル状態、優先度、ヘルス状態に基づいて適切な上流へ転送します。

対応エンドポイント

CCX は統一されたバックエンド入口を提供します。デフォルトポートは 3000 です。主なパスは次の通りです：

GET  /                         -> Web 管理画面
GET  /health                   -> ヘルスチェック
/api/*                         -> 管理 API
POST /v1/messages              -> Claude Messages プロキシ
POST /v1/chat/completions      -> OpenAI Chat プロキシ
POST /v1/responses             -> Codex Responses プロキシ
POST /v1/images/generations    -> OpenAI Images 生成
POST /v1/images/edits          -> OpenAI Images 編集
POST /v1/images/variations     -> OpenAI Images バリエーション
GET  /v1/models                -> モデル一覧
POST /v1beta/models/*          -> Gemini プロキシ

つまり、1 種類のプロトコルだけをプロキシするのではなく、Messages、Chat、Responses、Gemini、Images というよく使われる AI API 種別を個別のチャネルとして管理します。プロトコルごとにヘルス状態やログ空間が分かれるため、トラブルシュートしやすくなります。

アーキテクチャの考え方

CCX は Go バックエンドと Vue 3 フロントエンドで構成されています。フロントエンドのビルド成果物はバックエンドバイナリに埋め込まれるため、単一ポートでデプロイできます。同じサービスが Web UI、管理 API、プロキシ API を提供します。

リクエストの流れは概ね次の通りです：

`1`	`Client -> Auth Middleware -> Route Handler -> Channel Scheduler -> Provider / Converter -> Upstream API -> Metrics / Channel Logs -> Client Response`

主要モジュールの役割：

handlers: 各プロトコルのリクエストと管理操作を受け付ける。
providers: 上流 API のリクエストとレスポンス処理をラップする。
converters: Responses などの場面でプロトコル変換を行う。
scheduler: 優先度、プロモーション期間、ヘルス状態、サーキットブレーカー状態、セッション親和性に基づいてチャネルを選ぶ。
metrics: リクエスト数、成功率、遅延、ログ、サーキットブレーカー状態を記録する。
config: ランタイム設定を管理し、ホットリロードとバックアップをサポートする。

この設計の要点は、すべての API を無理に 1 つの形式へ変換することではありません。プロトコル種別ごとに代理し、管理、スケジューリング、ログ、認証を統一することです。

CCX と CodexBridge の違い

CCX と CodexBridge はどちらも Codex と OpenAI 互換 API に関係しますが、解決する問題が違います。

CodexBridge は専用の Codex ブリッジに近いツールです。目的は Codex CLI/SDK を OpenAI 互換の /v1/chat/completions サービスとして公開し、OpenWebUI、Cherry Studio、スクリプト、その他の OpenAI 互換クライアントからローカル Codex を呼び出せるようにすることです。つまり、CodexBridge の焦点は「Codex を外へ出す」ことです。

CCX は統一 AI API ゲートウェイに近いツールです。Codex Responses だけでなく、Claude Messages、OpenAI Chat、OpenAI Images、Gemini API も扱い、Web 管理画面、チャネル優先度、フェイルオーバー、ログ監視、複数 key 管理を提供します。つまり、CCX の焦点は「複数のモデルとプロバイダーをまとめて管理する」ことです。

簡単な比較：

項目	CodexBridge	CCX
中心的な位置づけ	Codex ローカルブリッジ	マルチプロトコル AI API ゲートウェイ
主な目的	Codex を OpenAI 互換エンドポイントにする	Claude、OpenAI、Gemini、Codex などのチャネルを一元管理する
管理画面	API サービス自体が中心	Web 管理画面を提供
複数チャネル調度	主目的ではない	チャネル優先度、フェイルオーバー、ログ監視に対応
向いている場面	ローカルまたは単一サービスで Codex を呼ぶ	チーム、多数の key、複数プロバイダー、複数プロトコル

Codex を OpenWebUI や Cherry Studio に接続したいだけなら CodexBridge のほうが直接的です。Codex、Claude、Gemini、DeepSeek、Qwen、Kimi など複数の上流をまとめて管理したいなら CCX が向いています。

クイックデプロイ

最も簡単なのはバイナリをダウンロードする方法です。ダウンロード後、同じディレクトリに .env を作成します：

PROXY_ACCESS_KEY=your-proxy-access-key
PORT=3000
ENABLE_WEB_UI=true
APP_UI_LANGUAGE=zh-CN

起動後、次へアクセスします：

`1`	`http://localhost:3000`

Windows で WSL、Docker、PowerShell などから localhost に接続できない場合は、Windows ホストの LAN IPv4 アドレスを使います。例：

`1`	`http://192.168.1.23:3000`

CCX はデフォルトで :PORT により全ネットワークインターフェースを待ち受けるため、LAN に公開する場合はアクセス制御に注意してください。

Docker デプロイ

Docker は常駐サービスに向いています：

docker run -d \
  --name ccx \
  -p 3000:3000 \
  -e PROXY_ACCESS_KEY=your-proxy-access-key \
  -e APP_UI_LANGUAGE=zh-CN \
  -v $(pwd)/.config:/app/.config \
  crpi-i19l8zl0ugidq97v.cn-hangzhou.personal.cr.aliyuncs.com/bene/ccx:latest

リポジトリに docker-compose.yml がある場合は次でも起動できます：

`1`	`docker compose up -d`

自動更新が必要なら Watchtower 設定を重ねます：

`1`	`docker compose -f docker-compose.yml -f docker-compose.watchtower.yml up -d`

デプロイ後、.config ディレクトリにはランタイム設定と永続データが保存されます。コンテナ再作成時に設定を失わないよう、ホストへマウントするのがおすすめです。

ソースから実行

開発またはカスタムビルドではソースから実行できます：

git clone https://github.com/BenedictKing/ccx
cd ccx
cp backend-go/.env.example backend-go/.env
make run

よく使うコマンド：

make dev
make run
make build
make frontend-dev

フロントエンドのみの開発：

1
2
3

cd frontend
bun install
bun run dev

バックエンドのみの開発：

1
2

cd backend-go
make dev

主な環境変数

最小構成は通常次のようになります：

PORT=3000
ENV=production
ENABLE_WEB_UI=true
PROXY_ACCESS_KEY=your-proxy-access-key
ADMIN_ACCESS_KEY=your-admin-secret-key
APP_UI_LANGUAGE=zh-CN
LOG_LEVEL=info
REQUEST_TIMEOUT=300000

ポイント：

PROXY_ACCESS_KEY はプロキシ API 用で、必ず変更します。
ADMIN_ACCESS_KEY は Web 管理画面と /api/* 用で、プロキシ用キーとは分けるべきです。
ENABLE_WEB_UI は管理画面の有効化を制御します。
REQUEST_TIMEOUT はリクエストタイムアウトです。長文コンテキストや画像タスクでは増やせます。
LOG_LEVEL はログレベルです。本番環境では通常 info または warn を使います。

リクエスト本文サイズを制限したい場合：

`1`	`MAX_REQUEST_BODY_SIZE_MB=50`

画像編集、base64 画像、マルチモーダルリクエストでは本文サイズが大きくなりがちです。

チャネル編成とフェイルオーバー

CCX の管理画面では複数チャネルを設定でき、各チャネルに次のような項目を指定できます：

上流サービス種別。
API key または複数 key のローテーション。
プロキシアドレス。
カスタムリクエストヘッダー。
モデル許可リスト。
ルートプレフィックス。
優先度。
ヘルスチェックとサーキットブレーカー復旧。

スケジューリングでは、チャネル状態、優先度、プロモーション期間、Trace 親和性、サーキットブレーカー状態、利用可能な key を総合的に考慮します。簡単に言うと：

通常は優先度の高いチャネルが先に使われる。
あるチャネルが失敗するとバックアップへフェイルオーバーできる。
サーキットブレーカーにより、明らかに使えない上流へ打ち続けることを避ける。
Trace 親和性により、同種のセッションをなるべく適切なチャネルに維持する。

これは複数 key、複数プロバイダー、複数地域の上流がある場合に便利です。個人の軽量利用なら、1 つのチャネルだけを設定して Web UI 付きプロキシ層として使うこともできます。

ログと監視

CCX はチャネル指標とリクエストログを提供します。確認できるもの：

リクエスト数。
成功率。
失敗率。
平均遅延。
モデル別の履歴データ。
チャネル状態とサーキットブレーカー状態。

本番環境では控えめなログ設定がよいです：

ENV=production
LOG_LEVEL=info
ENABLE_REQUEST_LOGS=true
ENABLE_RESPONSE_LOGS=false

これにより基本的なリクエスト情報を残しつつ、完全なレスポンス内容をログに書かないようにできます。調査時には一時的に詳細ログを有効化できますが、終わったら戻すべきです。特に本番でリクエスト本文とレスポンス本文を長期出力し続けるのは避けます。

セキュリティ上の注意

CCX はプロキシゲートウェイであり、上流 API key を保存します。したがって「動けばよい」だけで終わらせるべきではありません。少なくとも：

デフォルトまたは短すぎる PROXY_ACCESS_KEY を使わない。
ADMIN_ACCESS_KEY を別に設定する。
Web 管理画面を直接インターネットへ公開しない。
公開が必要な場合は、リバースプロキシ、VPN、アクセス制御、SSO の後ろに置く。
.env、.config、ログファイルを Git にコミットしない。
本番環境で完全なリクエスト本文とレスポンス本文のログを長期的に有効化しない。

ランダムキーは次のように生成できます：

1
2

PROXY_ACCESS_KEY=$(openssl rand -base64 32)
ADMIN_ACCESS_KEY=$(openssl rand -base64 32)

向いている人

CCX は次のような場面に向いています：

Claude、OpenAI、Gemini、Codex、画像 API を同時に維持している。
複数の API key があり、ローテーション、分流、フェイルオーバーが必要。
設定ファイルを手で編集するのではなく Web UI で上流チャネルを管理したい。
各チャネルの成功率、遅延、リクエストログを観察したい。
チームへ統一された AI API 入口を提供したい。

自分のマシンで単一モデルをたまに呼ぶだけなら、公式 SDK や単一の OpenAI 互換プロキシのほうが簡単です。CCX の強みは、複数チャネル、複数プロトコル、統一運用にあります。

まとめ

CCX は AI API ゲートウェイであり、特定モデルのクライアントではありません。Claude Messages、OpenAI Chat、OpenAI Images、Codex Responses、Gemini を 1 つのプロキシ層にまとめ、チャネル編成、フェイルオーバー、ログ監視、Web 管理画面を提供します。

個人利用では API アドレスやキーの切り替えを減らせます。チームや長期運用サービスでは、軽量な AI ゲートウェイに近い存在です。本番導入前には、モデル設定だけでなく、キー、管理入口、ログレベル、チャネル優先度、フェイルオーバー戦略も整える必要があります。

参考

GitHub プロジェクト：https://github.com/BenedictKing/ccx
アーキテクチャ説明：https://github.com/BenedictKing/ccx/blob/main/ARCHITECTURE.md
環境変数説明：https://github.com/BenedictKing/ccx/blob/main/ENVIRONMENT.md

CCX on KnightLiブログ