CPAプロキシ導入ガイド:CLIProxyAPI + NewAPIアカウントプール
開発者およびサイト運営者向けの実用的な CPA プロキシ導入ガイド: CLIProxyAPI、NewAPI、アカウント プール、導入、クライアント セットアップ、セキュリティ チェック、およびトラブルシューティング。
ショートバージョン
CPA プロキシを構築する場合、通常、難しい部分は「どのパネルをインストールすべきか?」ということではありません。本当の問題は、Codex、Claude Code、Gemini CLI、Grok Build、または OpenAI互換のアップストリームを、管理、ルーティング、NewAPI、チーム ユーザー、またはコーディング エージェントに渡すことができる安定した API に変える方法です。
一般的な CPA プロキシ アーキテクチャは次のようになります。
この設定は、制御可能なアカウント プール API ゲートウェイを必要とする開発者、小規模チーム、サイト オペレーターに最も役立ちます。個人的に使用したり、チーム内で配布したり、さまざまな上流をテストしたり、プロキシ サプライ チェーンがどのように機能するかを研究したりできます。公開する予定がある場合は、ユーザーを公開する前に、不正行為の制御、資格情報の分離、アクセス制御、およびポリシーの境界についてよく検討してください。
CPAプロキシとは何ですか?
CPA は、一般的に CLIProxyAPI の短縮形として使用されます。このプロジェクトでは、CLIProxyAPI を、CLI ツールに OpenAI、Gemini、Claude、Codex、および Grok と互換性のある API エンドポイントを提供するプロキシ サーバーとして説明します。 OAuth ログイン、マルチアカウント ローテーション、ストリーミング応答、関数呼び出し、マルチモーダル入力、OpenAI互換のアップストリーム プロバイダーをサポートします。
CPA + NewAPI アーキテクチャでは、通常、役割は次のとおりです。
| 層 | 責任 |
|---|---|
| アカウント層 | Codex、Claude Code、Gemini CLI、Grok Build、AI Studio、OpenAI互換のアップストリーム |
| CPA層 | アカウント、OAuth セッション、またはアップストリーム キーを統合 API に変換します |
| 新しいAPIレイヤー | チャネル、ユーザー、トークン、クォータ、モデルの価格設定、およびパブリック エンドポイントを管理します |
| クライアント層 | Claude Code、Codex、カーソル、OpenCode、Cherry Studio、SDK |
完全な CPA プロキシには通常 2 つの層があります。 CPA は、「アカウントはどのようにして API になるのでしょうか?」という質問に答えます。 NewAPI は、「その API をユーザーにどのように配布すればよいですか?」という質問に答えます。私的使用のみが必要な場合は、CPA のみから始めてください。複数のユーザーがアクセスする必要がある場合は、配布レイヤーを追加します。
CPA + NewAPI を使用する場合
初日からシステムが重くならないようにしてください。 CPA + NewAPI はチームの分散を解決できますが、構成、セキュリティ、およびデバッグのコストも追加されます。
| ゴール | 推奨されるセットアップ |
|---|---|
| 1 つのアカウントを自分用の API に変換する | CPAのみを導入する |
| 2 ~ 10 人のチームに 1 つの統一キーを発行します | CPA + NewAPI、または CPA + 軽量パネル |
| Codex、Claude Code、Gemini CLI、およびその他のソースを組み合わせる | CPA + NewAPI の方が適しています |
| 登録、チャージ、クォータ、および価格設定を実行する | 通常、NewAPI などのディストリビューション レイヤーが必要です |
| サブスクリプション アカウントの容量を一般に再販する | プラットフォームの用語、リスク管理、資格情報の分離を理解するまでは、これを避けてください。 |
最初の展開では、自分だけがアクセスできるローカル バージョンまたはプライベート バージョンを構築します。 1 つのアカウント、1 つのモデル、および 1 つのクライアントを使用します。 CPA 呼び出しが機能すると、NewAPI チャネル テストに合格し、クライアントがエンドポイントを確実に使用できるようになり、ドメイン、Cloudflare、請求、およびユーザー管理を追加できるようになります。
導入前
準備する:
- 少なくとも 2 つの vCPU と 2 GB RAM を備えた Linux サーバー (できれば Ubuntu 22.04 以降)。
- Docker および Docker Compose v2。
- 新しい NewAPI またはパブリック API エンドポイントのドメイン。
- 使用が許可されているアップストリーム アカウントまたは APIキー。
- 低リスクのテスト APIキー。上限のメイン アカウント キーから始めないでください。
推奨ポート:
| サービス | 共通ポート | おすすめ |
|---|---|---|
| CPA / CLIProxyAPI | 8317 | NewAPI または信頼できる IP にのみ公開します |
| 新しいAPI | 3000 | HTTPS とドメインをその前に置きます |
| Nginx / キャディ | 80 / 443 | TLS とリバース プロキシを処理する |
CPA と NewAPI が同じサーバー上で実行される場合は、CPA をローカルホストまたはプライベート ネットワークにバインドすることを優先します。通常、パブリック エントリ ポイントは CPA 管理インターフェイスではなく、NewAPI である必要があります。
ステップ 1: CLIProxyAPI (CPA レイヤー) をデプロイする
公式プロジェクトは、macOS、Linux、Windows、Docker、Docker Compose をサポートしています。サイト運営者が使用する場合、構成、認証ファイル、バックアップを検討しやすいため、Docker Compose が最も明確なオプションとなることがよくあります。
最小限の Docker コマンドは次のようになります。
docker run --rm \
-p 8317:8317 \
-v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml \
-v /path/to/your/auth-dir:/root/.cli-proxy-api \
eceasy/cli-proxy-api:latest
Docker Compose を使用する場合、通常のフローは、リポジトリのクローンを作成し、config.example.yaml を config.yaml にコピーし、サービスを開始することです。
git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
cp config.example.yaml config.yaml
docker compose up -d
まずログを確認します。
docker compose logs -f
NewAPI をすぐに接続しないでください。まず CPA 自体が正しく起動することを確認してから、アカウントのログインとアップストリームの構成を処理します。
ステップ 2: 基本的な CPA セキュリティを構成する
CPA は、リクエストの認証、構成、アカウント資格情報を処理します。通常のブログ管理パネルよりも真剣に扱ってください。
config.yaml では、まず次のフィールドを確認します。
host: "127.0.0.1"
port: 8317
remote-management:
allow-remote: false
secret-key: "replace-with-a-strong-random-admin-secret"
auth-dir: "~/.cli-proxy-api"
api-keys:
- "replace-with-a-strong-random-key-for-newapi"
debug: false
logging-to-file: true
usage-statistics-enabled: true
ポイントは、ブロックをやみくもにコピーしないことです。境界を理解する:
hostが127.0.0.1の場合、CPA はローカル トラフィックのみを受け入れます。これは、NewAPI が同じマシン上で実行される場合に適しています。remote-management.allow-remoteをむやみに有効にしないでください。管理 API は、ランタイム構成ファイルと認証ファイルを変更できます。- 強力なランダム
secret-keyを使用します。admin、123456、またはプロジェクト名は使用しないでください。 api-keysは CPA サービス認証層です。 NewAPI は、CPA を呼び出すときにこれらのキーのいずれかを使用します。auth-dirは資格情報を保存します。慎重にバックアップし、権限をしっかりと保ちます。
NewAPI と CPA が異なるサーバー上にある場合は、ポート 8317 をインターネット全体に公開しないでください。少なくとも、ファイアウォールのホワイトリスト、リバース プロキシ認証、強力なキー、およびログ監査を使用します。
ステップ 3: ログインまたはアップストリーム アカウントの追加
CPA はいくつかのアップストリーム タイプをサポートしています。最も一般的なサイト運営者のターゲットは、Codex、Claude Code、Gemini CLI、および OpenAI互換プロバイダーです。
Docker Compose デプロイメントの場合、公式ログイン コマンドには次のものが含まれます。
# OpenAI Codex
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login
# Claude Code
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --claude-login
# Gemini CLI
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --login
-no-browser はログイン URL を出力します。これはサーバー上で役立ちます。ログイン後、認証ファイルはマウントされた auth-dir に書き込まれます。そのディレクトリはアカウント プールの中核資産です。
OpenRouter や別の互換性のあるベースURL などの OpenAI互換のアップストリームを使用する場合は、base-url、api-key、モデル リスト、およびエイリアスを含むプロバイダー構成を追加します。
ステップ 4: NewAPI を追加する前に CPA をテストする
NewAPI に接続する前に、可能な限り最小の CPA リクエストを作成します。 CPA がローカル ポート 8317 で利用可能であり、CPA_API_KEY を設定したと仮定します。
export CPA_BASE_URL="http://127.0.0.1:8317/v1"
export CPA_API_KEY="the api key from config.yaml"
curl -sS "$CPA_BASE_URL/chat/completions" \
-H "Authorization: Bearer $CPA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5-codex",
"messages": [
{
"role": "user",
"content": "Reply with exactly: cpa-ok"
}
],
"stream": false
}'
これが失敗した場合は、まだ NewAPI を調整しないでください。最初に CPA をデバッグします。
| エラー | まず確認してください |
|---|---|
| 401 | CPA APIキーがconfig.yamlと一致するかどうか |
| 404 | ベースURL に /v1 を含めるかどうか、およびモデル名が存在するかどうか |
| 429 | 上流アカウントがレート制限されているか、クォータを超えているかどうか |
| 502 / 503 | アップストリームのログイン セッション、プロキシ、ネットワーク、アカウントの健全性 |
| HTML応答 | リクエストはおそらく間違ったリバース プロキシ アドレスまたはパネル ポートにヒットしました。 |
ステップ 5: CPA を NewAPI に接続する
NewAPI は CPA を管理可能なチャネルに変えます。一般的なフローは次のとおりです。
- NewAPI 管理パネルにログインします。
- チャネル管理を開き、新しいチャネルを追加します。
- OpenAI互換のチャネル タイプ、または最も近い互換性のあるタイプを選択します。
- 「ベースURL」を CPA アドレスに設定します (例:
http://127.0.0.1:8317/v1)。 - キーを CPA の
api-keysのいずれかに設定します。 - NewAPI に公開するモデル リストを追加します。
- チャネル テストを保存して実行します。
- NewAPI トークンを作成し、ユーザーに NewAPI ベースURL とトークンを与えます。
両方のサービスが同じサーバー上で実行されている場合、NewAPI は 127.0.0.1 または Docker ネットワーク サービス名を通じて CPA に到達できます。パブリック ユーザーは CPA キーを直接受信しないでください。 NewAPI が発行したユーザー トークンを受け取る必要があります。
CPA、NewAPI、およびクライアントのフィールド
ベースURL と APIキーの取り違えが最も一般的な失敗の原因です。まずそれらを揃えます。
| 位置 | ベースURL | APIキー | 使用者 |
|---|---|---|---|
| CPAローカルテスト | http://127.0.0.1:8317/v1 | CPA api-keys から config.yaml | 管理者のセルフテスト |
| 新しいAPIチャネル | CPA プライベート/ローカル アドレス (例: http://127.0.0.1:8317/v1) | CPA api-keys | CPA を呼び出す NewAPI |
| エンドユーザークライアント | パブリック NewAPI アドレス (例: https://api.example.com/v1) | NewAPI発行のユーザートークン | Codex、Claude Code、カーソル、SDK |
| 避ける | 公開された公認会計士の住所 | CPA の低レベルキー | エンドユーザー |
一文の要約: CPA キーをエンド ユーザーではなく NewAPI に渡します。エンド ユーザーは NewAPI ベースURL とトークンを使用する必要があります。
ステップ 6: 開発者クライアントから使用する
CPA プロキシのポイントは、開発者ツールが確実に接続できるようにすることです。各クライアントには独自のプロトコルの詳細があります。
Codex
公式の Codex クライアント構成には、通常、~/.codex/config.toml および ~/.codex/auth.json が含まれます。 CPA に直接接続する場合、base_url は通常次のようになります。
model_provider = "cliproxyapi"
model = "gpt-5.5"
model_reasoning_effort = "high"
[model_providers.cliproxyapi]
name = "cliproxyapi"
base_url = "http://127.0.0.1:8317/v1"
wire_api = "responses"
auth.json:
{
"OPENAI_API_KEY": "sk-dummy"
}
ユーザーが NewAPI を使用する場合は、base_url をパブリック NewAPI アドレスに置き換え、キーを NewAPI トークンに置き換えます。
OAuth ログイン モードを使用する場合、公式の例には、experimental_bearer_token、requires_openai_auth、supports_websockets などのフィールドも含まれる場合があります。すべてのオプションを一度に混合しないでください。モードを 1 つ選択して検証し、モデルと推論レベルを調整します。
Claude・コード
Claude Codeは通常、次のような環境変数を使用します。
export ANTHROPIC_BASE_URL="http://127.0.0.1:8317"
export ANTHROPIC_AUTH_TOKEN="your working key"
export ANTHROPIC_DEFAULT_OPUS_MODEL="gpt-5-codex(high)"
export ANTHROPIC_DEFAULT_SONNET_MODEL="gpt-5-codex(medium)"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="gpt-5-codex(low)"
重要: 通常の OpenAI チャット リクエストが機能することは、Claude Code が機能することを証明するものではありません。 Claude Code は、モデル名、ストリーミング動作、および Anthropic互換の動作に対してより敏感です。別途テストしてください。
CC Switch
公式 API、NewAPI、CPA、ローカル モデルを頻繁に切り替える場合は、検証済みのベースURL とキーを CC スイッチに入力します。順序は重要です。最初に手動で確認してから、構成をプロファイル マネージャーに渡します。
一般的な CPA プロキシ アーキテクチャ
プライベート建築
個人開発者の使用に最適です。シンプルなので故障箇所も少ないです。
小規模チームのアーキテクチャ
2~20名様に最適です。 NewAPI はキーを発行し、クォータを制限し、使用状況を追跡します。 CPA はアカウントプールを管理します。
公共配布アーキテクチャ
パブリックに配布する場合、難しい部分は CPA を導入することだけではなくなります。また、支払い、悪用、ログ、バックアップ、アカウントの障害、サポートを処理する必要もあります。
発売前チェックリスト
| アイテム | 合格基準 |
|---|---|
| CPA管理API | 公に公開されていない、強力な秘密、できればローカルホストまたは許可リストに登録されたアクセスのみ |
| CPA APIキー | 管理秘密とは別の強力なランダムキー |
| 認証ディレクトリ | バックアップされ、権限が制御され、パブリック リポジトリにコミットされることはありません |
| 新しいAPIチャネル | チャネルテストに合格しました。モデルリストと価格は推測できません |
| クライアントテスト | 最小限のリクエストは、curl、Codex、および Claude Code で渡されます。 |
| ログ | 失敗は表示されますが、平文のユーザー キーは記録されません |
| 不正行為の管理 | ユーザーごとのクォータ、レート制限、および異常リクエストの処理が存在します |
| ドメインと証明書 | HTTPS のみが公開されます |
よくある落とし穴
1. CPA と NewAPI ベースURL の混同
CPA パネル アドレス、CPA API アドレス、およびパブリック NewAPI アドレスは同じものではありません。
| 住所 | 目的 |
|---|---|
http://127.0.0.1:8317 | CPAサービスまたは管理パネル |
http://127.0.0.1:8317/v1 | 共通の OpenAI互換 CPA API アドレス |
https://api.example.com/v1 | ユーザー向けのパブリック NewAPI エンドポイント |
クライアントが間違ったアドレスを使用すると、多くの場合、404、HTML 応答、またはモデルの欠落などの症状が発生します。
2. CPA キーをユーザーに直接与える
サイトを運営している場合は、低レベルの CPA キーをエンド ユーザーに与えないでください。ユーザーは NewAPI トークンを受け取る必要があります。 CPA キーが漏洩すると、誰かがユーザー、クォータ、および課金レイヤーをバイパスする可能性があります。
3. 応答するかどうかのみをテストする
プロキシが 1 つの簡単なメッセージに応答できれば、最小のチャット リクエストだけを証明したことになります。開発者は次のこともテストする必要があります。
- ストリーミングが安定しているかどうか。
- Codex Response API の動作が機能するかどうか。
- Claude Code Anthropic と互換性のある変数が有効かどうか。
- 長いコンテキストが切り捨てられるかどうか。
- NewAPI の使用量と請求が、返された使用量とほぼ一致しているかどうか。
4. リモート管理を有効にするのが早すぎる
CLIProxyAPI の管理 API は、ランタイム構成ファイルと認証ファイルを管理できます。公式ドキュメントには、管理 API リクエストには管理シークレットが必要であるとも記載されています。遠隔管理は禁止されていませんが、裸でインターネットに公開するのは無謀です。
5. アカウントプールを SLA として扱う
複数アカウントのローテーションにより、単一アカウントのレート制限を下げることができますが、それは信頼性と同じではありません。アップストリーム ルールの変更、アカウント リスク制御、OAuth の有効期限、モデルの削除によっても、CPA プロキシが突然壊れる可能性があります。
一般的なエラーのトラブルシューティング
| 症状 | まず確認してください |
|---|---|
| 401 不正 | 間違ったキー、または直接 CPA テストで NewAPI ユーザー キーが使用されました |
| 404 見つかりません | ベースURL レベルが間違っています。/v1 が欠落しているか、パネル アドレスにヒットしていることがよくあります |
| 429 リクエストが多すぎます | アップストリーム アカウントがレート制限されているか、クォータを超えているか、クライアントの再試行が過剰である |
| 502 / 503 | CPA アップストリーム ログインの有効期限が切れている、プロキシ/ネットワークの問題、またはアカウントが使用できない |
| HTML応答 | リクエストが NewAPI パネル、Nginx のデフォルト ページ、または間違ったドメインにヒットしました |
| モデルが見つかりません | CPA モデル名、NewAPI モデル マッピング、およびクライアント モデル名が一致していません |
| カールは機能しますが、Claude Code/Codexは失敗します | プロトコル、ストリーミング、Responses API、または Anthropic互換の動作の不一致 |
デバッグの順序
何かが失敗した場合は、NewAPI パネルのフィールドを繰り返し変更する代わりに、このチェーンをデバッグします。
- アップストリーム アカウントの健全性: ログイン セッション、クォータ、禁止、リージョン、プロキシ。
- CPA の健全性: ログ、構成、モデル名、APIキー、認証ディレクトリ。
- CPA 最小カール: NewAPI の前に CPA をテストします。
- NewAPI チャネル: ベースURL、キー、モデル マッピング、チャネル ステータス。
- クライアントの動作: Codex、Claude Code、カーソル プロトコル、および環境変数。
- リバース プロキシ: Nginx、Cloudflare、HTTPS、ヘッダー、タイムアウト。
この順序により時間を節約できます。多くの「モデルが利用できない」エラーはクライアント構成のバグのように見えますが、実際の原因は多くの場合、CPA ログイン状態、ベースURL、またはアップストリーム アカウントの健全性です。
推奨される最終セットアップ
| 使用事例 | 推奨セットアップ | 境界 |
|---|---|---|
| プライベート開発者による使用 | CPA 単独 + ローカルクライアント直接接続 | アカウント、モデル、クライアントを検証する最も簡単な方法 |
| 小さなチーム | CPA + NewAPI + 内部トークン + 許可リストに登録されたアクセス | 共有ベースURL、トークン、クォータ管理に適しています |
| 小規模な一般配布 | プライベート CPA + パブリック NewAPI + HTTPS + クォータ制限 + ログ監査 | 対照試験では可能ですが、規模と上流のリスクを管理下に保ちます |
| 避ける | パブリック CPA + 弱い管理シークレット + ユーザー用の直接 CPA キー + 不正行為の制御なし | ユーザー、クォータ、およびアクセス制御層をバイパスします。実際の運用には適さない |
参考文献
関連ツール
関連するエラー
注目のAI APIサービス
チャージ換算率、公式価格との差、アクセス数の3つの観点から代表的なサービスを紹介します。






