CC-Switch

CC-Switch は、クロスプラットフォーム対応のローカル設定管理ツールで、Claude Code や Codex などのコーディングツール用に複数の Providerを保存し、現在有効な設定を対応するツールの設定ファイルに書き込むことができます。これにより、ファイルを毎回手動で編集することなく、AGTCloud とその他の保存済みの設定を切り替えることができます。

このチュートリアルでは、Claude CodeとCodex向けのアプリケーション別Providerのみを扱います。リクエストは、Local Proxy、Failover、プロトコル変換、Universal Provider、CC-Switch を有効にせずに、各コーディングツールからAGTCloudへ直接送信されます。

切り替え操作によりローカルツールの設定が変更されます

CC-Switch は、Claude Code または Codex のライブ設定ファイルを更新します。初めて使用する前に、既存の設定が正しくインポートされていることを確認し、AGTCloud を追加する前にバックアップをエクスポートしてください。

事前準備

開始前に、次の項目を確認してください。

Claude Code または Codex をインストールし、基本的な起動を完了します。
AGTCloudに登録してログインします。
API Keys ページに AGTCloud API Keyを作成します。
モデルマーケットプレイスから、現在のAPI Keyで利用可能かつ対象ツールのプロトコルに対応するモデルIDをコピーします。
機密コードや本番用認証情報が含まれていないテストプロジェクトを準備します。

Claude CodeではAnthropic Messages対応モデルを、CodexではOpenAI Responses対応モデルを選択してください。 MODEL_IDは置換用のプレースホルダーであり、実際のモデル名ではありません。

CC-Switchをダウンロードしてインストールする

CC-Switch 公式ウェブサイトまたは GitHub Releases からのみインストールパッケージを取得します。 CC-Switch 自体のトップアップ、支払い、ログイン認証情報の提出を必要とする Web サイトやクライアントは、公式チャネルではありません。

一般インストールでは、GitHub リリースの Windows MSI の現在のバージョンが選択されます。
インストールしたくない場合は、Windows Portable ZIP を選択できます。
ポータブルバージョンは解凍されて CC-Switch.exe を実行します。
Windows がブロックする場合は、まずファイルソースとデジタル署名を確認し、システムセキュリティ機能をオフにしないでください。

CC-Switchは設定を管理しますが、Claude Code や Codex 自体を置き換えることはありません。まず、ターゲットのコーディングツールが正常に起動できることを確認してください。

初回起動とバックアップ

自動インポート結果を確認する

初回起動時に、CC-SwitchはローカルにあるClaude CodeやCodexなどの既存設定をインポートします。各アプリケーションのページを開き、元の公式設定またはカスタムProviderが一覧に表示されていることを確認します。

元のProviderを保持

自動的にインポートされた公式設定は削除しないでください。後で AGTCloud を終了する必要がある場合は、Providerを再度有効にして、元の接続方法を復元できます。

データのバックアップをエクスポートする

設定 → 詳細設定 → データ管理 を開き、現在のバージョンのエクスポート機能でバックアップを保存します。バックアップには API Key やその他の機密性の高い Provider 情報が含まれる場合があります。信頼できる場所に保存し、リポジトリや公開クラウドストレージにはアップロードしないでください。

このチュートリアルでは、設定ファイルを直接編集する必要はありません。

CC-Switch は、対応するツールの設定を書き込む役割を果たします。他のプラットフォームの例を適用するために ~/.claude/settings.json、~/.codex/auth.json、または ~/.codex/config.toml をオーバーライドしないでください。

AGTCloud Providerを追加する

上部で設定対象のアプリケーションを選択し、右上の追加ボタンをクリックして、「アプリケーション固有の Provider」のカスタム設定を使用します。Claude Code と Codex ではプロトコルと Base URL が異なるため、Provider をそれぞれ作成してください。

Claude Code Provider ページを開く

CC-Switch の上部にある Claude Code を選択し、「Providerの追加」をクリックして、「カスタム」または現在のバージョンに対応するカスタム Provider エントリを選択します。

接続情報を入力します

フィールド	内容を入力してください
`Provider Name`	`AGTCloud`
`Base URL`	`https://api.agtcloud.cn`
`API Key`	`your-api-key`
`Primary Model`	`MODEL_ID`
`Authentication`	API Keyを使用し、`ANTHROPIC_AUTH_TOKEN` は使用しないでください。

Base URL このページに表示されている API Origin のみを入力し、/v1 は追加しません。 Claude Code は /v1/messages 自体をリクエストします。

モデルマッピングを設定する

使用中のバージョンで Haiku、Sonnet、Opus のロールマッピングが表示される場合、初回の確認では 3 つのロールをすべて、Anthropic Messages に対応する同じ MODEL_ID に割り当てて構いません。各モデルの実際の対応範囲を確認してから、必要に応じて別々のモデルを設定してください。

保存しますが、まだプロキシを有効にしてません

Providerを保存します。 Local Proxy、Failover、プロトコル変換、またはその他の高度なルーティング機能を有効にしないでください。

API Key 認証を使用する

AGTCloud の Claude Code 設定は、ANTHROPIC_API_KEY の対応する API Key 認証を使用します。 ANTHROPIC_AUTH_TOKEN または Bearer Token を使用する他のプラットフォームから設定をコピーしないでください。

設定を有効化して確認する

AGTCloud を有効にする

対応するアプリのProvider リストに戻るには、AGTCloud カードの [有効にする] をクリックします。確認カードには、「現在有効」または現在のバージョンでの同等の内容が表示されます。

ターゲットツールをリロードする

Claude Code 設定変更は通常検出できますが、検証のために新しいセッションを開くことをお勧めします。
Codex 現在のターミナルウィンドウを閉じ、ターミナルを再度開き、Codex を起動する必要があります。

切り替えが成功したかどうかを判断するために、すでにリクエストを送信済みの古いセッションを使用しないでください。

現在の設定を確認する

ターゲットツールで実行:

/status

Provider、Base URL、認証元、モデルIDを確認してください。 Claude Code には重複した /v1 を表示しないでください。 Codex の Base URL は単一の /v1 で終わる必要があります。

読み取り専用テストを開始する

README.md を含むセキュリティテストプロジェクトに次のように開きます。

README.mdを読み、プロジェクトの目的を3点で要約してください。ファイルは変更しないでください。

結果が正常に返され、許可していない変更が行われていなければ、基本的な接続を確認できます。この手順では通常の API 利用量が発生します。

システムトレイからすばやく切り替える

CC-Switch システムトレイ内のさまざまなアプリケーションに対して個別の Provider リストを提供します。トレイアイコンを右クリックして、Claude または Codex サブメニューに入り、有効にする Providerを選択します。

トレイの切り替えは単なる設定項目の 1 つであり、Local Proxy を有効にする必要はありません。 Codex を切り替えた後もターミナルを再度開く必要があります。

元の設定に戻す

CC-Switch で Claude Code または Codex ページを開きます。
最初の起動時にインポートされた公式の Providerを見つけます。
「有効にする」をクリックします。
Claude Code 新しいセッションを開いて回復を確認します。Codex 端末を再度開いて回復を確認します。

Claude Code と Codex の Providerは相互に分離されています。 Claude Code を切り替えても Codex は自動的に変更されませんし、その逆も同様です。

よくある質問

現象	優先して確認する項目	対処方法
適切なインストールパッケージが見つかりません	ソース、オペレーティングシステム、プロセッサアーキテクチャをダウンロード	`ccswitch.io` または公式 GitHub リリースからのみ現在のバージョンを取得してください
オリジナルの Providerは表示されませんでした	最初のインポート結果と元のツール設定パス	まず Claude Code または Codex がインストールおよび構成されていることを確認してから、CC-Switch を再度開きます
設定を有効化すると書き込めない	設定ファイルの権限と占有ステータス	実行中のターゲットツールを閉じ、ユーザー設定ディレクトリの権限を確認して、再試行してください。
`401` を返す	API Key 内容と認証方法	有効な API Keyを使用してください。 Claude Code は `ANTHROPIC_AUTH_TOKEN` を使用しないでください
`403` を返す	キーのステータス、アカウント権限、モデル権限	コンソールで現在の API Key とモデルの利用可能な範囲を確認します。
`404` を返す	Base URL、重複 `/v1`、完全なエンドポイントおよびモデルID	Claude Code `https://api.agtcloud.cn` を使用します。 Codex `https://api.agtcloud.cn/v1` を使用し、完全なリクエストパスを入力しないでください
モデルリストをロードできません	`/v1/models` サポート、ネットワーク接続、API Key	現在のAPI Keyで利用可能な完全なモデルIDをモデルマーケットプレイスからコピーし、手動で入力します。
Claude Codeが古い設定を使い続ける	有効なProviderと古いセッションのキャッシュ	AGTCloud カードが現在有効であることを確認し、新しい Claude Code セッションを開いて `/status` を実行します。
Codexが古い設定を使い続ける	端末が再起動されているかどうか	現在のターミナルウィンドウを閉じ、ターミナルを再度開き、Codexを再度起動します
通常の会話は成功しますが、ツールの呼び出しは失敗します	モデルプロトコルとツール呼び出し機能	Claude Code には、Anthropic Messages およびツール呼び出しをサポートするモデルを選択します。 Codex の場合は、Responses をサポートするモデルを選択してください
Base URL が `/v1/v1` になります	アプリケーションの種類とURLの入力方法	Claude Code `/v1` を削除します。 Codex 1 つだけ保持します `/v1`

特定できない問題が発生した場合は、対象ツール、リクエスト時間、Base URL、モデルID、HTTP ステータス、および機密情報を除いたエラー情報を記録し、エラーとトラブルシューティングを確認してください。完全なAPI Key または CC-Switch データのバックアップを送信しないでください。

セキュリティ上の推奨事項

スクリーンショット、ログ、リポジトリ、または共有設定に API Keyを含めないでください。
CC-Switch データのエクスポートには機密 Provider 情報が含まれる可能性があるため、認証情報のバックアップとして適切に保管する必要があります。
CC-Switch は公式チャネルからのみダウンロードしてインストールし、プラットフォームのログイン認証情報をサードパーティクライアントに送信しないでください。
初回確認には安全なテストプロジェクトを使用し、Claude CodeとCodexの操作承認を有効なままにします。
API Keyの漏えいの疑いがある場合は、コンソールで直ちに無効にするか削除し、新しいキーを作成します。