CPAプロキシ導入ガイド:CLIProxyAPI + NewAPIアカウントプール

開発者およびサイト運営者向けの実用的な CPA プロキシ導入ガイド: CLIProxyAPI、NewAPI、アカウント プール、導入、クライアント セットアップ、セキュリティ チェック、およびトラブルシューティング。

ショートバージョン

CPA プロキシを構築する場合、通常、難しい部分は「どのパネルをインストールすべきか?」ということではありません。本当の問題は、Codex、Claude Code、Gemini CLI、Grok Build、または OpenAI互換のアップストリームを、管理、ルーティング、NewAPI、チーム ユーザー、またはコーディング エージェントに渡すことができる安定した API に変える方法です。

一般的な CPA プロキシ アーキテクチャは次のようになります。

flowchart TD upstream("アップストリームアカウント/API") cpa("CLIProxyAPI / CPA") newapi("新しいAPI") clients("クライアント/ユーザー") upstream -->|"OAuth / APIキー"| cpa cpa -->|"統合API"| newapi newapi -->|"ベースURL/トークン"| clients

この設定は、制御可能なアカウント プール 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、請求、およびユーザー管理を追加できるようになります。

導入前

準備する:

  1. 少なくとも 2 つの vCPU と 2 GB RAM を備えた Linux サーバー (できれば Ubuntu 22.04 以降)。
  2. Docker および Docker Compose v2。
  3. 新しい NewAPI またはパブリック API エンドポイントのドメイン。
  4. 使用が許可されているアップストリーム アカウントまたは APIキー。
  5. 低リスクのテスト APIキー。上限のメイン アカウント キーから始めないでください。

推奨ポート:

サービス共通ポートおすすめ
CPA / CLIProxyAPI8317NewAPI または信頼できる IP にのみ公開します
新しいAPI3000HTTPS とドメインをその前に置きます
Nginx / キャディ80 / 443TLS とリバース プロキシを処理する

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.yamlconfig.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

ポイントは、ブロックをやみくもにコピーしないことです。境界を理解する:

  • host127.0.0.1 の場合、CPA はローカル トラフィックのみを受け入れます。これは、NewAPI が同じマシン上で実行される場合に適しています。
  • remote-management.allow-remote をむやみに有効にしないでください。管理 API は、ランタイム構成ファイルと認証ファイルを変更できます。
  • 強力なランダム secret-key を使用します。 admin123456、またはプロジェクト名は使用しないでください。
  • 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-urlapi-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 をデバッグします。

エラーまず確認してください
401CPA APIキーがconfig.yamlと一致するかどうか
404ベースURL に /v1 を含めるかどうか、およびモデル名が存在するかどうか
429上流アカウントがレート制限されているか、クォータを超えているかどうか
502 / 503アップストリームのログイン セッション、プロキシ、ネットワーク、アカウントの健全性
HTML応答リクエストはおそらく間違ったリバース プロキシ アドレスまたはパネル ポートにヒットしました。

ステップ 5: CPA を NewAPI に接続する

NewAPI は CPA を管理可能なチャネルに変えます。一般的なフローは次のとおりです。

  1. NewAPI 管理パネルにログインします。
  2. チャネル管理を開き、新しいチャネルを追加します。
  3. OpenAI互換のチャネル タイプ、または最も近い互換性のあるタイプを選択します。
  4. 「ベースURL」を CPA アドレスに設定します (例: http://127.0.0.1:8317/v1)。
  5. キーを CPA の api-keys のいずれかに設定します。
  6. NewAPI に公開するモデル リストを追加します。
  7. チャネル テストを保存して実行します。
  8. NewAPI トークンを作成し、ユーザーに NewAPI ベースURL とトークンを与えます。

両方のサービスが同じサーバー上で実行されている場合、NewAPI は 127.0.0.1 または Docker ネットワーク サービス名を通じて CPA に到達できます。パブリック ユーザーは CPA キーを直接受信しないでください。 NewAPI が発行したユーザー トークンを受け取る必要があります。

CPA、NewAPI、およびクライアントのフィールド

ベースURL と APIキーの取り違えが最も一般的な失敗の原因です。まずそれらを揃えます。

位置ベースURLAPIキー使用者
CPAローカルテストhttp://127.0.0.1:8317/v1CPA api-keys から config.yaml管理者のセルフテスト
新しいAPIチャネルCPA プライベート/ローカル アドレス (例: http://127.0.0.1:8317/v1)CPA api-keysCPA を呼び出す 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_tokenrequires_openai_authsupports_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 プロキシ アーキテクチャ

プライベート建築

flowchart TD client("ローカルクライアント") cpa("公認会計士") upstream("Codex / Claude Code / Gemini CLI / 互換性のあるアップストリーム") client -->|"市内通話"| cpa cpa -->|"アカウントのルーティング"| upstream

個人開発者の使用に最適です。シンプルなので故障箇所も少ないです。

小規模チームのアーキテクチャ

flowchart TD clients("チームクライアント") newapi("新しいAPI") cpa("公認会計士") upstream("複数のアカウント/アップストリーム") clients -->|"ベースURL/キー"| newapi newapi -->|"クォータ/チャネル"| cpa cpa -->|"アカウントのルーティング"| upstream

2~20名様に最適です。 NewAPI はキーを発行し、クォータを制限し、使用状況を追跡します。 CPA はアカウントプールを管理します。

公共配布アーキテクチャ

flowchart TD users("ユーザー/クライアント") edge("ドメイン / HTTPS / WAF / リバースプロキシ") newapi("新しいAPI") cpa("公認会計士プライベートサービス") upstream("アカウントプール / アップストリーム API / OAuth セッション") users -->|"リクエスト"| edge edge -->|"フォワード"| newapi newapi -->|"チャンネルコール"| cpa cpa -->|"アカウントのルーティング"| upstream

パブリックに配布する場合、難しい部分は CPA を導入することだけではなくなります。また、支払い、悪用、ログ、バックアップ、アカウントの障害、サポートを処理する必要もあります。

発売前チェックリスト

アイテム合格基準
CPA管理API公に公開されていない、強力な秘密、できればローカルホストまたは許可リストに登録されたアクセスのみ
CPA APIキー管理秘密とは別の強力なランダムキー
認証ディレクトリバックアップされ、権限が制御され、パブリック リポジトリにコミットされることはありません
新しいAPIチャネルチャネルテストに合格しました。モデルリストと価格は推測できません
クライアントテスト最小限のリクエストは、curl、Codex、および Claude Code で渡されます。
ログ失敗は表示されますが、平文のユーザー キーは記録されません
不正行為の管理ユーザーごとのクォータ、レート制限、および異常リクエストの処理が存在します
ドメインと証明書HTTPS のみが公開されます

よくある落とし穴

1. CPA と NewAPI ベースURL の混同

CPA パネル アドレス、CPA API アドレス、およびパブリック NewAPI アドレスは同じものではありません。

住所目的
http://127.0.0.1:8317CPAサービスまたは管理パネル
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 / 503CPA アップストリーム ログインの有効期限が切れている、プロキシ/ネットワークの問題、またはアカウントが使用できない
HTML応答リクエストが NewAPI パネル、Nginx のデフォルト ページ、または間違ったドメインにヒットしました
モデルが見つかりませんCPA モデル名、NewAPI モデル マッピング、およびクライアント モデル名が一致していません
カールは機能しますが、Claude Code/Codexは失敗しますプロトコル、ストリーミング、Responses API、または Anthropic互換の動作の不一致

デバッグの順序

何かが失敗した場合は、NewAPI パネルのフィールドを繰り返し変更する代わりに、このチェーンをデバッグします。

  1. アップストリーム アカウントの健全性: ログイン セッション、クォータ、禁止、リージョン、プロキシ。
  2. CPA の健全性: ログ、構成、モデル名、APIキー、認証ディレクトリ。
  3. CPA 最小カール: NewAPI の前に CPA をテストします。
  4. NewAPI チャネル: ベースURL、キー、モデル マッピング、チャネル ステータス。
  5. クライアントの動作: Codex、Claude Code、カーソル プロトコル、および環境変数。
  6. リバース プロキシ: Nginx、Cloudflare、HTTPS、ヘッダー、タイムアウト。

この順序により時間を節約できます。多くの「モデルが利用できない」エラーはクライアント構成のバグのように見えますが、実際の原因は多くの場合、CPA ログイン状態、ベースURL、またはアップストリーム アカウントの健全性です。

推奨される最終セットアップ

使用事例推奨セットアップ境界
プライベート開発者による使用CPA 単独 + ローカルクライアント直接接続アカウント、モデル、クライアントを検証する最も簡単な方法
小さなチームCPA + NewAPI + 内部トークン + 許可リストに登録されたアクセス共有ベースURL、トークン、クォータ管理に適しています
小規模な一般配布プライベート CPA + パブリック NewAPI + HTTPS + クォータ制限 + ログ監査対照試験では可能ですが、規模と上流のリスクを管理下に保ちます
避けるパブリック CPA + 弱い管理シークレット + ユーザー用の直接 CPA キー + 不正行為の制御なしユーザー、クォータ、およびアクセス制御層をバイパスします。実際の運用には適さない

参考文献

CPAプロキシ CLIProxyAPI 新しいAPI アカウントプール APIゲートウェイ ドッカー

関連ツール

関連するエラー

注目のAI APIサービス

チャージ換算率、公式価格との差、アクセス数の3つの観点から代表的なサービスを紹介します。

すべてのサービスを見る