CC Switch で Claude Code の接続先を切り替える手順とハマりどころ

この記事は AIHubMix が作成しました。CC Switch v4.0.26（2026年11月）時点の画面と設定を説明しています。以降のリリースではボタン名が変わることがありますが、設定の仕組みは安定しています。

Claude Code の接続先をプロバイダー間で切り替えるとき、通常は ~/.claude/settings.json を編集します。ベース URL、API キー、場合によってはモデル。1つならまだ管理できますが、2つ、3つになると小さな保守作業になります。しかも失敗は静かです。シェルに残った ANTHROPIC_* の export が、直前に編集したファイルを上書きすることがあります。

CC Switch は、この切り替えをクリックできるカードにします。組み込みの AiHubMix プリセットがエンドポイントを埋め、API キーを1つ貼るだけです。Claude Code は通常、再起動なしで変更を読み込みます。本記事ではセットアップの全体、CC Switch が実際に書き換えるもの、環境変数の罠、direct モードで足りる場面を説明します。

TL;DR

• CC Switch の AiHubMix プリセットなら、Claude Code の接続先はカードのクリックで切り替わります
• プリセットが設定するのは ANTHROPIC_API_KEY と ANTHROPIC_BASE_URL の2つです。モデルは自分で追加します
• ベース URL に /v1 は付けません。Claude Code は Anthropic Messages を話し、パスを自分で組み立てます
• 切り替えが効かないように見える典型的な原因は、シェルプロファイルに残った ANTHROPIC_* の export です
• 完了確認は claude -p "1+1, output only the answer" --model claude-sonnet-5-5 が 2 を返すことです

CC Switch とは

CC Switch は、Claude Code、Codex、Gemini CLI、OpenCode などのコーディングツールのプロバイダー設定を管理するオープンソースのデスクトップアプリです（MIT、Tauri + Rust + React）。90以上のプロバイダープリセットを同梱し、カスタムプロバイダーにも対応します。リポジトリとユーザーマニュアルは github.com/farion1231/cc-switch にあります。

単なるキーの切り替えツールではありません。3つのモードがあります。

• direct モード：クライアントの設定ファイルにあるキーのフィールドを書き換え、クライアントがプロバイダーと直接通信します。
• ルーティングモード：127.0.0.1:15721 でローカルゲートウェイを動かし、API 形式の変換、フェイルオーバー、ヘルスチェック、リクエストログを提供します。
• アグリゲーションモード：複数プロバイダーのモデルを1つの /model リストにまとめます。

配布元は ccswitch.io と GitHub Releases だけです。支払いやアカウント情報を求めるサイトは公式の配布元ではありません。

前提

• Claude Code がターミナルから実行できること。 claude --version で確認します。未インストールの場合は公式インストーラー curl -fsSL https://claude.ai/install.sh | bash、または Node.js 22以上の環境で npm i -g @anthropic-ai/claude-code を使います。
• AIHubMix のアカウントと API キー。 AIHubMix コンソール で作成します。キーは通常 sk- で始まります。
• CC Switch のインストーラー。 上記の公式配布元から取得します。

ステップ1：CC Switch をインストールする

OS	インストール方法
macOS 12 Monterey 以降	brew install --cask cc-switch、または署名・公証済みの .dmg
Windows 10 以降	.msi インストーラー、またはポータブル .zip
Debian / Ubuntu	.deb パッケージ
Fedora / RPM 系	.rpm パッケージ
Arch Linux	paru -S cc-switch-bin
その他の Linux	.AppImage（glibc 2.35以上と WebKitGTK 4.1 が必要）

初回起動時、CC Switch は既存の Claude Code 設定を default という名前のプロバイダーとしてインポートし、公式プロバイダーを追加します。元の設定は失われず、いつでも戻せます。

Claude Code がまだインストールされていない場合は、CC Switch の Apps ページからインストールまたはアップグレードできます。

ステップ2：AIHubMix の API キーを作成する

AIHubMix の API キーページを開き、キーを作成してコピーします。

ドキュメント内のプレースホルダー AIHUBMIX_API_KEY は実際のキーではありません。そのまま貼り付けると、リクエストは 401 invalid key: AIHUBMIX_API_KEY で失敗します。

ステップ3：Claude Code に AIHubMix を追加する

1. 左サイドバーで Claude Code を選択します。
2. 右上の + ボタンをクリックします。
3. AiHubMix を検索するか、サードパーティプラットフォームのカテゴリから選びます。
4. 名前とエンドポイントが自動入力されます。https://aihubmix.com です。API Key にキーを貼り付けます。
5. Add をクリックします。

プリセットが保存する環境変数は2つです。

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com"
  }
}

プリセットはモデルを設定しません。AIHubMix のガイドは ANTHROPIC_MODEL を中心となる変数として扱っているため、切り替える前に同じ env ブロックへ追加します。

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5"
  }
}

モデルを設定しないと、Claude Code は自身のデフォルトモデル ID を送ります。それが AIHubMix の提供するモデルとは限りません。

ここで押さえておきたい点が2つあります。

ベース URL に /v1 を付けない。 Claude Code は Anthropic Messages プロトコルを話し、リクエストパスを自分で組み立てます。https://aihubmix.com が正解です。https://aihubmix.com/v1 は他のクライアント向けの OpenAI 互換ベースで、Claude Code はそこに自身の /v1/messages を追加してしまいます。

プリセットは ANTHROPIC_API_KEY を使い、AIHubMix 自身の Claude Code ガイドは ANTHROPIC_AUTH_TOKEN を使います。 AIHubMix はどちらも受け付けます。ANTHROPIC_AUTH_TOKEN は Bearer ヘッダーを送り、ANTHROPIC_API_KEY は x-api-key を送ります。どちらか一方を選び、異なる値で両方を埋めないでください。設定の詳細、モデル ID、エラーのリファレンスは AIHubMix の Claude Code ドキュメント にあります。

プリセットが見つからない場合（古いリリース、またはカードを削除した場合）は、Custom Configuration を選び、上の JSON を貼り付けます。プロバイダーカードのエンドポイントマネージャーはレイテンシーをテストできます。プリセットには、aihubmix.com が解決できない場合の代替エンドポイント https://api.aihubmix.com も含まれています。

ステップ4：切り替えて確認する

Direct タブで AiHubMix カードの Switch をクリックします。設定の書き込みが完了すると、ボタンは In use に変わります。

Claude Code は設定を自動で再読み込みします。通常、再起動は不要です。現在のセッションが古いプロバイダーを使い続ける場合は、いったん終了して起動し直します。

エンドツーエンドの経路を確認します。

claude -p "1+1, output only the answer" --model claude-sonnet-5-5

2 が返れば、リクエストは AIHubMix に届いています。対話セッションでは、/status の Anthropic base URL 行が https://aihubmix.com を示すはずです。

素早く切り替えたいときはシステムトレイを使います。CC Switch のアイコンを右クリックし、Claude Code サブメニューでプロバイダーをクリックします。サブメニューのタイトルには、有効なプロバイダーとクォータの概要が表示されます。

公式プロバイダーに戻すには、Claude Official に切り替え、Claude Code を再起動し、ログインフローを完了します。

切り替えが実際に変えるもの

direct モードでは、CC Switch は ~/.claude/settings.json の接続と互換性のフィールドだけを置き換えます。ANTHROPIC_*、AWS_*、CLAUDE_CODE_USE_BEDROCK のようなプロトコルセレクター、model、apiKeyHelper、そして CLAUDE_CODE_DISABLE_ARTIFACT やコンテキストウィンドウのようなプロバイダー単位の互換オプションです。

permissions、hooks、enabledPlugins、statusLine、MCP 設定、コメント、その他追加したものはそのまま残ります。正確なリストは 設定ファイルのリファレンス にあります。

ツール設定の初回書き換えの前に、CC Switch は元のファイルを ~/.cc-switch/backups/live-first-write/ にバックアップします。JSON が壊れている場合は書き込みを拒否し、行と列を報告し、ファイルを変更しません。

モデルエイリアスを設定する

ANTHROPIC_MODEL を設定すると、Claude Code のデフォルトは Sonnet 5.5 になります。/model のエイリアス（opus、sonnet、haiku、fable）は、AIHubMix のモデル ID に解決するために別途マッピングが必要です。env の中に次のキーを追加します。

役割	変数	AIHubMix のモデル ID
デフォルト	ANTHROPIC_MODEL	claude-sonnet-5-5
Opus エイリアス	ANTHROPIC_DEFAULT_OPUS_MODEL	claude-opus-5-5
Sonnet エイリアス	ANTHROPIC_DEFAULT_SONNET_MODEL	claude-sonnet-5-5
Haiku エイリアス	ANTHROPIC_DEFAULT_HAIKU_MODEL	claude-haiku-5-5
Fable エイリアス	ANTHROPIC_DEFAULT_FABLE_MODEL	claude-fable-5-1

プロバイダー設定の全体は次のようになります。

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-your-key",
    "ANTHROPIC_BASE_URL": "https://aihubmix.com",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-5-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5-1"
  }
}

モデル選択の優先順位は、高い順に /model <name> → claude --model <name> → ANTHROPIC_MODEL → settings.json の model フィールドです。モデル ID は AIHubMix のモデル一覧 からコピーしてください。大文字と小文字は区別されます。

ハマりどころ

カードは In use なのに、リクエストが古いエンドポイントへ行く

以前に手動セットアップのガイドに従い、export ANTHROPIC_BASE_URL=... や export ANTHROPIC_AUTH_TOKEN=... を ~/.zshrc や ~/.bash_profile に追加した場合、それらの変数が CC Switch が書き込んだ値を上書きすることがあります。カードを AIHubMix に切り替えても、リクエストは古いエンドポイントへ送られます。

CC Switch はこの競合を検出します。ウィンドウ上部の黄色いバナーが、環境変数が設定を上書きする可能性を警告し、詳細には変数名、値、ソースが表示されます。Delete Selected を押すとそれらが削除され、その前に ~/.cc-switch/backups/env-backup-<timestamp>.json へバックアップが書き込まれます。

手動で確認するには、次のコマンドを実行します。

grep -n "ANTHROPIC" ~/.zshrc ~/.bash_profile 2>/dev/null

古い export をコメントアウトし、source ~/.zshrc を実行するか新しいターミナルを開きます。AIHubMix のドキュメントも、CC Switch が設定を管理する場合はグローバルの ANTHROPIC_* 変数を削除することを推奨しています。競合のワークフロー全体は 環境変数のリファレンス にあります。

ベース URL に /v1 を付けてしまう

https://aihubmix.com が正解です。https://aihubmix.com/v1 は他のクライアント向けの OpenAI 互換ベースで、Claude Code はそこに自身の /v1/messages を追加してしまいます。Claude Code は Anthropic Messages を話し、パスを自分で組み立てるため、OpenAI 互換のベースを渡す場所ではありません。

接続テストが通ってもリクエストが失敗する

カードの接続テストは、エンドポイントに到達できるかだけを確認します。API キーやモデルは検証しません。テストが通っても、キーが無効だったりモデル ID が間違っていたりすれば、リクエストは失敗します。最終確認は claude -p のエンドツーエンド実行です。

モデル ID が設定されていない、または一致しない

プリセットはモデルを設定しません。ANTHROPIC_MODEL を追加しないと、Claude Code は自身のデフォルトモデル ID を送ります。それが AIHubMix の提供するモデルとは限りません。400 Incorrect model ID が返る場合は、モデル一覧から完全な ID をコピーしてください。大文字と小文字は区別されます。

ログイン画面が出る、または Not logged in と表示される

/status を確認します。Settings → App config → Claude Code の Skip Claude Code first-run confirmation を有効にし、再起動し、キーが入力されていることを確認します。

macOS で claude コマンドが見つからない

公式インストーラーは通常、claude を ~/.local/bin/claude に配置します。シェルプロファイルに export PATH="$HOME/.local/bin:$PATH" を追加し、新しいターミナルを開きます。

AIHubMix が返すエラー

次の文字列は AIHubMix の Claude Code ドキュメントからの引用です。

エラー	対処
401 no key provided	ベース URL を確認し、古い環境変数を消します
401 invalid key: AIHUBMIX_API_KEY	プレースホルダーではなく実際のキーを使います
401 this key is not enabled	コンソールでキーとクォータを確認します
400 Incorrect model ID	モデル一覧から完全な ID をコピーします

ルーティングとアグリゲーションが必要なとき

AIHubMix では direct モードを使うのが基本です。エンドポイントはすでに Anthropic Messages を話すため、プロトコル変換は不要です。

ルーティングは、フェイルオーバーのキューが必要なとき、または OpenAI 形式のプロバイダーを Claude Code の背後に置きたいときに使います。Claude Code の接続先を http://127.0.0.1:15721 に向け、設定内のキーを PROXY_MANAGED に置き換え、実際のキーは CC Switch から注入します。アプリは動かし続ける必要があり、CC Switch を終了すると direct の設定が書き戻されます。公式の Claude サブスクリプションはルーティングを通りません。それらには direct モードを使ってください。

アグリゲーションは、複数プロバイダーのモデルを1つの /model リストにまとめたいときに使います。デフォルトプロバイダーがプレフィックスなしのリクエストを処理し、他のプロバイダーのモデルは ccs- プレフィックス付きで表示されます。フェイルオーバーは行いません。Claude Code と Codex のみで利用でき、Claude の公式サブスクリプションはサポートされません。ccs- のモデルリストには Claude Code 2.1.243以降が必要です。Claude Code はモデルリストの変更を即座に反映しますが、Codex は完全な再起動が必要です。

この記事で確認できないこと

• CC Switch のビルド。 手順は v4.0.26（2026年11月）に基づきます。以降のリリースではボタン名が変わる可能性がありますが、設定の仕組みは安定しています。古いリリースに AiHubMix プリセットがない場合は Custom Configuration を使います。
• Claude Code が再読み込みしたか。 カードは設定が書き込まれたことを示します。リクエスト経路は /status とエンドツーエンドのコマンドで確認します。セッションが古いプロバイダーを保持する場合は再起動します。
• カードの接続確認。 到達性だけをテストし、API キーやモデルは検証しません。合格はエンドツーエンドの合格ではありません。
• アカウントの状態とモデル ID。 キーが有効でクォータがあるかは AIHubMix コンソールで確認します。モデル ID はモデル一覧からコピーし、大文字小文字を保ちます。カードの接続確認はモデル ID を検証しません。
• エラー文字列の出典。 AIHubMix の Claude Code ドキュメントからの引用で、読者の環境が生成したものではありません。
• 配布元の正当性。 ccswitch.io と GitHub Releases だけが公式の配布元です。支払いやアカウント情報を求めるサイトは公式ではありません。

まとめ

• CC Switch の AiHubMix プリセットは、ベース URL と API キーの2つを設定します。モデルは自分で追加します
• ベース URL は https://aihubmix.com です。/v1 は付けません
• シェルに残った ANTHROPIC_* の export は、書き込まれた設定を上書きすることがあります
• In use は書き込みの完了を示します。リクエスト経路は /status と claude -p で確認します
• AIHubMix では direct モードで足ります。ルーティングとアグリゲーションは別の要件に答えます

AIHubMix の Claude Code エンドポイントは https://aihubmix.com です。API キーを作成して AiHubMix カードに貼り付け、claude -p の確認で 2 が返るところまで進めてください。

参考

1. CC Switch repository（GitHub）
2. CC Switch ユーザーマニュアル: Add Provider（CC Switch）
3. CC Switch ユーザーマニュアル: Switch Provider（CC Switch）
4. CC Switch ユーザーマニュアル: Configuration Files（CC Switch）
5. AIHubMix ドキュメント: Claude Code（AIHubMix）