Claude/Codex/Gemini API統合OSS「ccx」の仕組みと特徴

Claude Code、Codex、Gemini を併用していると、いつの間にか API キー・ベース URL・認証形式がプロバイダごとにバラバラになり、管理が煩雑になってきた——そんな状況に心当たりはないでしょうか。さらに「Codex から OpenAI 互換の別モデルも試したい」「フェイルオーバーやキーローテーションを自前で実装すべきか」と考え始めると、構成の見通しはどんどん立てづらくなります。

こうした「複数 AI API の分散管理」を 1 つのエントリポイントに集約することを狙った OSS が、本記事で取り上げる ccx（BenedictKing/ccx）です。Go で書かれた単一バイナリで動作し、Claude / OpenAI Chat / OpenAI Images / Codex Responses / Gemini を束ねる API プロキシ兼プロトコル変換ゲートウェイとして公開されています。

ただ、この領域には litellm や new-api といった先行する選択肢も存在します。初見のエンジニアにとって本当に知りたいのは「ccx は何をするのか」だけでなく、「自分の環境に導入すべきか」「litellm などとどう違うのか」「メンテナンスは健全か」という判断材料のはずです。

本記事では、ccx の公式 README やリリース情報といった一次情報をもとに、ccx の仕組み・主要機能・導入方法を整理し、最後に litellm・new-api との違いと「向いているケース・向いていないケース」までを解説します。実際の導入可否を自分で判断できる状態をゴールに据えています（なお本記事は動作検証ではなく、公開情報に基づく整理です）。

ccx とは何か（Claude / Codex / Gemini を束ねる API プロキシ）

ccx が解決する課題（複数 AI API の分散管理）

ccx は、公式リポジトリの説明によれば「Claude / OpenAI Chat / OpenAI Images / Codex Responses / Gemini 向けの高性能 AI API プロキシ兼プロトコル変換ゲートウェイ」と位置づけられています（BenedictKing/ccx）。複数の AI プロバイダの API を 1 つの統一エントリポイントに集約し、Web 管理画面・チャネルオーケストレーション・フェイルオーバー・マルチキー管理・モデルルーティングを提供する、と README で説明されています。

複数の AI プロバイダを併用する際の悩みは、おおむね次の点に集約されます。

• プロバイダごとにエンドポイントのパス・認証方式・リクエスト形式が異なり、クライアント側の設定が散らかる
• 複数の API キーを使い分けたいが、ローテーションや負荷分散を自前で書くのは手間がかかる
• 1 つのキー・チャネルが落ちたときのフェイルオーバーを、クライアントを作り直さずに実現したい

ccx は、こうした「分散しがちな複数 API の入り口」をプロキシとして 1 か所に集約することを基本コンセプトに据えています。

一目で分かる ccx の特徴（対応プロトコル・配布形態・ライセンス・規模）

ccx の現状を、公式情報をもとに表にまとめます。

スター数・言語・ライセンスは執筆時点（2026年5月）の GitHub 上の値です。最新リリースは Releases ページで v2.8.14 が確認できます。リポジトリの更新は同月内にも入っており、現時点では活発にメンテナンスされている状態と見て取れます。

README の Features セクションでは、ccx の特徴として以下が挙げられています（ccx README）。

• バックエンドとフロントエンドを統合し、単一ポートでデプロイできるアーキテクチャ
• PROXY_ACCESS_KEY と任意の ADMIN_ACCESS_KEY によるデュアルキー認証
• チャネル管理・テスト・ログ・モニタリングを行う Web 管理コンソール
• Claude Messages / OpenAI Chat Completions / OpenAI Images / Codex Responses / Gemini への対応
• 優先度・プロモーションウィンドウ・ヘルスチェック・フェイルオーバー・サーキット復旧を備えたスマートスケジューリング
• チャネル単位の API キーローテーション・プロキシ対応・カスタムヘッダ・モデル許可リスト・ルートプレフィックス
• マルチターンワークフロー向けの Responses セッション追跡
• フロントエンド資産を埋め込み、単一バイナリでデプロイできる構成

ここで注目したいのは、ccx が「すべてを 1 つの形式に変換する」のではなく、複数のプロトコルをそれぞれ受け付ける入り口として設計されている点です。この設計思想は、のちほど litellm との比較で重要になります。

ccx の仕組みとアーキテクチャ

単一エントリポイントとエンドポイントマッピング

ccx は、1 つのバックエンドエントリポイント（既定では :3000）にすべての機能を集約します。README の Architecture セクションには、リクエストがどのエンドポイントにマッピングされるかが次のように示されています（出典: ccx README）。

Client -> backend :3000 ->
  |- /                            -> Web UI
  |- /api/*                       -> Admin API
  |- /v1/messages                 -> Claude Messages proxy
  |- /v1/chat/completions         -> OpenAI Chat proxy
  |- /v1/responses                -> Codex Responses proxy
  |- /v1/images/{...}             -> OpenAI Images proxy
  |- /v1/models                   -> Models API
  `- /v1beta/models/*             -> Gemini proxy

この図から分かるのは、各プロバイダのプロトコルがネイティブな形式のまま個別のエンドポイントに割り当てられていることです。Claude Messages は /v1/messages、OpenAI Chat は /v1/chat/completions、Codex の Responses API は /v1/responses、Gemini は /v1beta/models/* といった具合に、各 API が本来持つパス体系に沿ってマッピングされています。

つまり、既存のクライアントが「Claude のエンドポイントに投げているリクエスト」「Gemini のエンドポイントに投げているリクエスト」を、宛先を ccx に向け替えるだけで通せる、というイメージです。クライアントごとに大きくリクエスト形式を作り変える必要が少ない点は、導入後の絵姿を描くうえで把握しておきたいポイントです。

なお README には ARCHITECTURE.md という詳細設計ドキュメントへの言及がありますが、本記事執筆時点ではリポジトリのルートに当該ファイルを確認できなかったため、ここでは README 内の Architecture セクションに記載された範囲に絞って解説しています。バックエンドのより詳しい情報は backend-go/README.md から辿れます。

デュアルキー認証の考え方

ccx は 2 種類のアクセスキーを使い分ける「デュアルキー認証」を採用しています。README の Features では、PROXY_ACCESS_KEY と任意の ADMIN_ACCESS_KEY の組み合わせとして説明されています。

役割を整理すると、おおまかに次のように分かれます。

• PROXY_ACCESS_KEY: クライアントがプロキシ経由で AI API を呼び出すためのキー
• ADMIN_ACCESS_KEY: Web 管理コンソールや Admin API（/api/*）にアクセスするための管理用キー（任意設定）

プロキシ利用と管理操作のキーを分けられるため、「API を叩くアプリケーション側」と「チャネルやログを操作する管理側」で権限を切り分けやすい設計になっています。複数人やチームで運用する場面を想定すると、この分離は把握しておく価値があります。

ccx の主要機能（チャネルオーケストレーション・フェイルオーバー・マルチキー管理）

ここからは、README の Features に挙げられた機能を「自前で実装すると手間がかかる部分を、ccx がどこまで肩代わりするか」という観点で整理します。フェイルオーバーやキーローテーションを自分で書くべきか迷っている場合の判断材料になります。

スマートスケジューリングとフェイルオーバー

README では、ccx のスマートスケジューリングとして「優先度・プロモーションウィンドウ・ヘルスチェック・フェイルオーバー・サーキット復旧」が挙げられています。

複数のチャネル（上流の AI サービス）を登録しておき、優先度に従って振り分けつつ、ヘルスチェックで異常を検知したチャネルを切り離し、復旧したら再び戻す——といった制御を備える、という位置づけです。こうしたフェイルオーバーやサーキットブレーカ相当の挙動を自前で実装するのは決して軽い作業ではないため、標準機能として提供される点は導入価値の一つとして検討できます。

マルチキー管理とチャネル単位の制御

ccx は、チャネル単位で細かな制御を行える点も特徴として挙げています。README の Features には、次のようなチャネル単位の機能が並びます。

• API キーのローテーション
• プロキシ（上流への通信経路）対応
• カスタムヘッダの付与
• モデル許可リスト（allowlist）
• ルートプレフィックス

複数の API キーを 1 か所で管理し、ローテーションや経路設定をチャネルごとに切り替えられるため、「キーが増えてきて管理しきれない」という課題に対する受け皿になります。クライアント側を再デプロイせずに上流の構成を調整できる方向性は、運用の柔軟性として注目できます。

Web 管理コンソールと可観測性

ccx には Web 管理コンソールが同梱されており、README では「チャネル管理・テスト・ログ・モニタリング」を行えると説明されています。チャネルの追加や動作テスト、リクエストログの確認、トラフィック統計の閲覧といった操作を、コードを書かずに画面から行える想定です。

このコンソールはフロントエンド資産としてバイナリに埋め込まれているため、別途フロントエンドをホスティングする必要がなく、単一ポート（既定では :3000）の / で開ける構成になっています。可観測性とデプロイの手軽さを両立させようとしている点が読み取れます。

加えて README には、マルチターンのワークフローに向けた「Responses セッション追跡」も挙げられています。Codex の Responses API（/v1/responses）を扱ううえで、セッションをまたいだ追跡を意識した機能と位置づけられます。

ccx の導入方法（Docker / バイナリ / ソースビルド）

ここでは README の Quick Start を「最短で試すにはどの経路を選ぶか」という観点で整理します。なお、以下はあくまで公式手順の紹介であり、本記事では実際のインストールや動作確認は行っていません。最新の手順は必ず公式リポジトリで確認してください。

導入経路の選び方（Docker / バイナリ / ソース）

README の Quick Start では、おおむね次の導入経路が案内されています。

バイナリ経路では、README に次のような .env の例が示されています（出典: ccx README）。

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

Docker 経路では、README に次の起動例が記載されています（出典: ccx README）。

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

Docker Compose を使う場合は docker compose up -d で起動でき、Watchtower を組み合わせた自動更新の構成も README で案内されています。コンテナイメージが中国のレジストリ（aliyuncs.com）で配布されている点は、ネットワーク環境によって取得可否が変わりうるため、導入前に確認しておくとよいでしょう。

バイナリを直接使いたい場合は、Releases ページから最新の v2.8.14 を取得する流れになります。

押さえておきたいコア環境変数

README の Core Environment Variables には、次の環境変数が示されています（出典: ccx README）。

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=en
LOG_LEVEL=info
REQUEST_TIMEOUT=300000

それぞれの意味を簡単に補足すると、PORT は待ち受けポート、ENABLE_WEB_UI は Web 管理コンソールの有効化、PROXY_ACCESS_KEY / ADMIN_ACCESS_KEY は前述のデュアルキー認証、APP_UI_LANGUAGE は管理画面の表示言語（en で英語）、LOG_LEVEL はログ出力レベル、REQUEST_TIMEOUT はリクエストのタイムアウト（ミリ秒）です。最小構成で試すなら、まず PORT と PROXY_ACCESS_KEY、必要に応じて ENABLE_WEB_UI と APP_UI_LANGUAGE を押さえておけば、最初の一歩を踏み出しやすくなります。

類似 OSS との比較（litellm・new-api との違い）

ここが、初見のエンジニアにとって最も判断に直結する部分です。ccx と同じく「複数の LLM API を束ねる」OSS には、litellm と new-api という代表的な選択肢があります。それぞれとの立ち位置の違いを整理します。

litellm との違い（思想・言語・配布）

litellm は、100 以上のプロバイダを OpenAI 形式に統一する AI ゲートウェイで、Python の SDK と Proxy Server を中心に、コスト追跡・ガードレール・ロードバランシング・ロギングなどを幅広く備えた大規模な OSS です。

ccx との主な違いは次の通りです。

• 言語・配布: litellm は Python（SDK + サーバー）で構成されます。ccx は Go の単一バイナリにフロントエンドを埋め込む形で、ランタイム依存が少なく、軽量にセルフホストしやすい配布形態です。
• プロトコルの扱い方: litellm は「すべてを OpenAI 形式に寄せる」発想が中核にあります。一方 ccx は、Claude Messages・Codex Responses・Gemini・OpenAI をそれぞれネイティブなプロトコルのまま個別のエンドポイントで受ける設計です（前述の /v1/responses や /v1beta/models/* のマッピング）。
• 規模・カバレッジ: litellm は対応プロバイダ数・機能の網羅性ともに大規模です。ccx はより対象を絞り、Claude / Codex / Gemini を中心に「個人〜小チームで束ねる」用途に寄っています。

「とにかく多数のプロバイダを OpenAI 形式で一元化したい」「コスト追跡やガードレールまで含めて作り込みたい」なら litellm が候補になります。逆に「Claude / Codex / Gemini を、各 API のネイティブ形式のまま軽く束ねたい」なら ccx の設計が噛み合いやすい、という整理になります。

new-api との違い（再販ハブ vs 軽量ゲートウェイ）

new-api は、各種 LLM を OpenAI 互換・Claude 互換・Gemini 互換の形式へクロス変換する集中ゲートウェイで、課金・ユーザー管理・トークン配布といった「再販・マルチテナント運用」を含む大規模ハブ志向のプロジェクトです。

ccx との違いを整理すると、次のようになります。

「外部に API を再販したい」「ユーザーごとにトークンを配布して課金管理したい」といった要件があるなら new-api の領域です。一方で「自分やチームの中で複数 AI API を束ねたいだけ」であれば、再販機能を持たず構成がシンプルな ccx のほうが扱いやすい場面が多いと考えられます。

参考までに、CLI ラップ方向のプロジェクトとして CLIProxyAPI もありますが、こちらは Gemini CLI / Codex / Claude Code などを互換 API としてラップする用途で、サーバー常駐のプロキシ + 管理 UI を提供する ccx とは方向性が異なります。

ccx が向いているケース・向いていないケース

ここまでの整理を踏まえ、ccx を「自分の環境に導入すべきか」を判断するための目安をまとめます。

ccx が向いていると考えられるケース

• Claude / Codex / Gemini を個人〜小チームで束ね、入り口を 1 つに集約したい
• Go の単一バイナリや Docker で、軽量にセルフホストしたい
• Codex の Responses API（/v1/responses）経由で、OpenAI 互換の別モデルを試したい
• フェイルオーバー・キーローテーション・管理 UI を自前で実装する手間を避けたい
• 各 API のネイティブなプロトコル形式をなるべく保ったまま中継したい

慎重に検討したほうがよいケース

• 100 以上のプロバイダ網羅や、コスト追跡・ガードレールが主目的（litellm のほうが噛み合いやすい）
• 課金・ユーザー管理・トークン配布など再販/マルチテナント運用が主目的（new-api の領域）
• エンタープライズ規模の SLA や手厚いサポート体制が前提（OSS 単体での担保には限界がある）
• 配布イメージのレジストリ所在やドキュメントの一部未整備（ARCHITECTURE.md 等が辿れない点）を、自社の運用基準に照らして許容できるか確認が必要

ccx は、対象を Claude / Codex / Gemini に絞り、軽量なセルフホストとプロトコルのネイティブ受けを志向した OSS です。スター数 2,410、MIT ライセンス、執筆時点で同月内に更新が入る活発さといった現状を踏まえると、上記の「向いているケース」に当てはまるなら、まずは小さく試してみる価値はあります。

最後に、API プロキシは構成の要となる位置に入るコンポーネントです。導入を検討する際は、本記事の整理を出発点としつつ、必ず公式リポジトリと最新リリースで最新の仕様・対応状況を確認したうえで、自分の構成に当てはめて判断することをおすすめします。