Jason
09101e2a2d
Document the xAI OAuth flow (discovery, device, token, and API endpoints) in the zh/en/ja manuals. State explicitly that the integration reuses the public OAuth client identity and scopes registered for the official Grok CLI rather than a CC Switch registration, and strengthen the shared account-backed proxy note back to an explicit warning covering account restriction and suspension risk.
18 KiB
2.6 Claude Desktop
機能概要
Claude Desktop パネルでは、CC Switch 上で Claude Desktop のプロバイダー設定を管理できます。
有効にすると、次のことができます。
- Claude Desktop でサードパーティの Anthropic 互換プロバイダーを使う
- 三つの役割 ID 以外のモデルにマッピングを設定する：旧式 Claude ID（例：
claude-3-5-sonnet）や DeepSeek / Kimi / DouBao / OpenAI / Gemini などの非 Claude モデルはいずれも必要 - Copilot / Codex OAuth / xAI OAuth のアカウント型プロバイダーを再利用する
- Claude Desktop 公式モードとサードパーティプロバイダーを切り替える
Claude Desktop と Claude Code は別々のアプリ入口です。Claude Code は ~/.claude/settings.json を使い、Claude Desktop は専用の 3P profile 設定を使います。CC Switch 上でも「Claude」と「Claude Desktop」として別々に表示され、アイコン右下の小さなバッジで区別できます。
対応範囲
| 項目 | 説明 |
|---|---|
| 対応システム | macOS、Windows |
| 未対応 | Linux での Claude Desktop 3P 設定書き込み |
| 反映方法 | プロバイダー切り替え後に Claude Desktop を再起動 |
| 公式モード | Claude Desktop 内蔵サインインを使用。API Key やエンドポイント URL は不要 |
| サードパーティモード | CC Switch が管理する 3P profile に書き込み |
| MCP / Skills | Claude Desktop 3P profile は CC Switch の MCP / Skills 同期を使いません |
クイックスタート
ステップ 1：Claude Desktop パネルへ切り替える
左側のアプリ切り替えから Claude Desktop を選択します。
この入口が見つからない場合は、次を確認してください。
設定 → 一般 → ホームページ表示
Claude Desktop が非表示になっていないことを確認します。
ステップ 2：プロバイダーをインポートまたは追加する
推奨：Claude Code から一括インポート
多くのユーザーはまず Claude Code 側でプロバイダーを設定し、その同じプロバイダー群を Claude Desktop に持ち込みたいはずです。CC Switch の初回起動時、または Claude Desktop パネルを初めて開いたときにプロバイダーがまだない場合は、Claude Code の既存プロバイダーをインポート をクリックします。
Claude Code 側に多くのプロバイダーがすでにある場合、この機能で Claude Desktop パネルへ一括インポートできます。エンドポイント URL、API Key、デフォルトモデルを一つずつ入力し直す必要がありません。
インポートルール：
- 同じ ID のプロバイダーがすでにある場合は上書きしません
- モデル名が三つの役割 ID（
claude-sonnet-*/claude-opus-*/claude-haiku-*）で直接接続できるプロバイダーは直結モードとしてインポートされます - モデル名が三つの役割 ID でない（旧式 Claude ID を含む）、または形式変換が必要なプロバイダーは、可能な場合モデルマッピングモードとしてインポートされます
ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODELは Desktop の Sonnet / Opus / Haiku マッピングに変換されます- 旧形式の
[1M]サフィックスは Claude Desktop profile のsupports1mフラグに変換されます - モデルマッピングを判断できないプロバイダーはスキップされます
インポート後は、各プロバイダーのモデルマッピングが実際のアップストリームモデルと合っているか確認してください。claude-sonnet-* / claude-opus-* / claude-haiku-* の三つの役割 ID 以外のモデル——Kimi、DeepSeek、GLM、DouBao などの非 Claude モデルや旧式 Claude ID を含む——は通常、モデルマッピングモードが必要です。
すでに Claude Code でプロバイダーを設定している場合は、まず Claude Code の既存プロバイダーをインポート を使ってください。Claude Desktop へ移行する最も簡単な方法です。
インポートできる設定がない場合、または Claude Desktop 専用にプロバイダーを追加したい場合は、右上の + ボタンをクリックします。
選べる方法：
- プリセットプロバイダー：内蔵の Claude Desktop プリセットから選び、API Key だけ入力する
- カスタム設定：名前、エンドポイント URL、API Key、モデル設定を手動入力する
- Claude Desktop Official：Claude Desktop の公式サインインモードへ戻す
Claude Desktop の三つの役割 ID（claude-sonnet-* / claude-opus-* / claude-haiku-*）をすでに受け付けるネイティブ Anthropic Messages API プロバイダーでは、基本的に次の手順だけで十分です。
- プリセットまたはカスタムプロバイダーを選ぶ
- API Key を入力する
- API エンドポイント を確認する
- モデルマッピングが必要 をオフのままにする
- 追加 をクリックする
ステップ 3：切り替えて Claude Desktop を再起動する
プロバイダーカードで 有効化 をクリックします。
切り替え後：
- 直結プロバイダー：Claude Desktop を再起動すると反映されます
- ルーティングが必要なプロバイダー：CC Switch を起動したまま、Claude Desktop ローカルルーティングをオンにし、Claude Desktop を再起動します
注意：Claude Desktop は Claude Code のように設定をホットリロードしません。プロバイダーを切り替えるたびに、Claude Desktop を完全に終了して再度開く必要があります。
2 つの動作モード
直結モード
直結モードは、プロバイダー自身が Anthropic Messages API を提供しており、Claude Desktop から直接アクセスできる場合に適しています。
直結モードでは、CC Switch が Claude Desktop の 3P profile をプロバイダーのエンドポイントへ向けます。
{
"inferenceProvider": "gateway",
"inferenceGatewayBaseUrl": "https://api.example.com",
"inferenceGatewayAuthScheme": "bearer",
"inferenceGatewayApiKey": "your API key"
}
適したケース：
- プロバイダーがネイティブの Anthropic Messages API を公開している
- モデル ID が Claude Desktop の認識できる役割名：
claude-sonnet-*、claude-opus-*、claude-haiku-*（またはanthropic/claude-接頭辞の同種名） - 形式変換が不要
- 使用中に CC Switch のローカルルーティングを起動し続ける必要がない
直結モードの「Claude Desktop モデルを手動指定」は高度な任意設定です。多くのネイティブ Claude モデルプロバイダーでは不要で、Claude Desktop が /v1/models を自動取得します。
プロバイダーの /v1/models が使えない、または返されるモデル名を Claude Desktop が認識できない場合だけ手動で追加してください。手動で入力するモデル名は claude-sonnet-*、claude-opus-*、claude-haiku-* の形式である必要があります（claude-3-5-sonnet-… のような旧式 ID は拒否されます）。
モデルマッピングモード
モデルマッピングモードは、プロバイダーのモデルが claude-sonnet-* / claude-opus-* / claude-haiku-* の三つの役割 ID でない場合（旧式 Claude ID や DeepSeek、Kimi などの非 Claude モデルを含む）、または CC Switch による API 形式変換が必要な場合に適しています。
モデルマッピングが必要 をオンにすると、Claude Desktop は CC Switch のローカルゲートウェイへ接続します。
http://127.0.0.1:15721/claude-desktop
CC Switch は次を担当します。
- Claude Desktop に安全な Claude モデルルートを公開する
- Desktop で選択したモデル役割を実際のアップストリームモデルへマッピングする
- プロバイダーに合わせて Anthropic / OpenAI / Gemini のリクエスト形式を変換する
- CC Switch に保存されたプロバイダー認証情報でアップストリームへアクセスする
対応 API 形式：
| 形式 | 用途 |
|---|---|
| Anthropic Messages | ネイティブまたは互換 Anthropic リクエスト |
| OpenAI Chat Completions | OpenAI 互換 /chat/completions |
| OpenAI Responses API | OpenAI Responses 互換エンドポイント |
| Gemini Native generateContent | Gemini ネイティブ API |
モデルマッピングモードでは、Claude Desktop から見えるのは claude-sonnet-* / claude-opus-* / claude-haiku-* の 3 種類の役割ルートだけです。実際のアップストリームモデル名は Claude Desktop profile に直接書き込まれません。
モデルマッピングを設定する
フィールド説明
| フィールド | 説明 |
|---|---|
| モデル役割 | Claude Desktop が認識できる Sonnet / Opus / Haiku ルート |
| メニュー表示名 | Claude Desktop のモデルメニューに表示される名前 |
| リクエストモデル | プロバイダーへ送信する実際のアップストリームモデル ID |
| 1M | Claude Desktop に 1M コンテキスト対応を宣言 |
推奨設定
Kimi を使う場合：
| モデル役割 | メニュー表示名 | リクエストモデル | 1M |
|---|---|---|---|
| Sonnet | Kimi K2 | kimi-k2 |
プロバイダー能力に合わせる |
DeepSeek を使う場合：
| モデル役割 | メニュー表示名 | リクエストモデル | 1M |
|---|---|---|---|
| Sonnet | DeepSeek V4 Pro | deepseek-v4-pro |
プロバイダー能力に合わせる |
理由は、現在の Claude Desktop が Sonnet / Opus / Haiku の役割ファミリー以外のモデルを拒否するためです。そのため CC Switch のルーティング機能で一度モデルマッピングを行います。
複数役割のマッピング
Sonnet、Opus、Haiku の 3 つを同時に設定できます。
| モデル役割 | 推奨用途 |
|---|---|
| Sonnet | デフォルトの主力モデル |
| Opus | 高品質または複雑なタスク |
| Haiku | 高速・低コストモデル |
プロバイダーにモデルが 1 つしかない場合は、1 つの役割のリクエストモデルだけ入力すれば十分です。空欄の役割は最初に入力したモデル（Sonnet 優先）を自動的に引き継ぐため、サブ agent が呼び出す Haiku なども常に利用できます。モデルマッピングモードでは少なくとも 1 つのリクエストモデルが必要です。
ローカルルーティング切り替え
モデルマッピングモードでは、リクエスト変換のために CC Switch ローカルルーティングが必要です。ローカルルーティングは強力ですが少し複雑な機能でもあるため、ルーティングを必要としないユーザーの誤操作を避けるために、メインページのルーティング切り替えはデフォルトで非表示です。必要なときだけ手動で表示してください。
開き方：
設定 → ルーティング → ローカルルーティング → メインページにルーティング切り替えを表示 をオン
表示スイッチをオンにしたら Claude Desktop パネルへ戻ります。メインページ右上に Claude Desktop ローカルルーティング切り替えが表示されます。
状態説明：
| 状態 | 説明 |
|---|---|
| オン | ローカルゲートウェイが起動中。通常は 127.0.0.1:15721 |
| オフ | 直結プロバイダーは利用可能。モデルマッピングプロバイダーは正常に動作しません |
| 読み込み中 | ルーティングサービスの起動または停止中 |
モデルマッピングが必要 なプロバイダーだけがローカルルーティングに依存します。直結プロバイダーではこの切り替えは不要です。
他のアプリがプロキシ接管を使用している場合、ローカルルーティングの停止がブロックされることがあります。先にルーティングサービス設定で該当アプリの接管をオフにしてから、ローカルルーティングを停止してください。
公式 Claude Desktop に戻す
Claude Desktop の公式サインインへ戻す場合：
- Claude Desktop Official を選択する
- 有効化 をクリックする
- Claude Desktop を再起動する
CC Switch は Claude Desktop の公式 1P モードを復元し、CC Switch が管理する 3P profile を削除します。
公式モードでは API Key もローカルルーティングも不要です。
Claude Code からプロバイダーをインポートするとき、CC Switch は自動的に Claude Desktop Official も追加します。
設定ファイルの場所
CC Switch は Claude Desktop の 3P 設定ディレクトリに書き込みます。
macOS
~/Library/Application Support/Claude/claude_desktop_config.json
~/Library/Application Support/Claude-3p/claude_desktop_config.json
~/Library/Application Support/Claude-3p/configLibrary/_meta.json
~/Library/Application Support/Claude-3p/configLibrary/00000000-0000-4000-8000-000000157210.json
Windows
%LOCALAPPDATA%\Claude\claude_desktop_config.json
%LOCALAPPDATA%\Claude-3p\claude_desktop_config.json
%LOCALAPPDATA%\Claude-3p\configLibrary\_meta.json
%LOCALAPPDATA%\Claude-3p\configLibrary\00000000-0000-4000-8000-000000157210.json
これらのファイルは CC Switch が自動管理します。手動編集はおすすめしません。設定の不整合が起きた場合は、現在のプロバイダーを再度有効化すると通常は修復できます。
ステータス表示と対処
Claude Desktop パネル上部に「Claude Desktop 設定の確認が必要です」と表示されることがあります。
| 表示 | 対処方法 |
|---|---|
| 現在のプラットフォームは未対応 | 3P 設定の書き込みは現在 macOS / Windows のみ対応 |
| profile に Sonnet / Opus / Haiku の役割ファミリー以外のモデル名がある | 現在のプロバイダーへ再度切り替える、またはモデルマッピングを使うよう編集する |
| モデルマッピングが有効だが有効なルートがない | プロバイダーを編集し、少なくとも 1 件のモデルマッピングを追加する |
| ローカルルーティング token が未生成 | そのプロバイダーへ再度切り替えると、CC Switch が新しい token を書き込みます |
| profile の URL が現在のプロバイダーと一致しない | 現在のプロバイダーへ再度切り替え、profile を正しい URL に戻します |
よくある質問
切り替え成功と表示されたのに Claude Desktop が変わらない？
Claude Desktop を完全に終了して再起動してください。Claude Desktop は通常、起動時に 3P profile を読み込み、切り替え後に自動でホットリロードしません。
モデルマッピングプロバイダーのリクエストが失敗する？
次を確認してください。
- CC Switch が起動したままになっている
- Claude Desktop ローカルルーティングがオンになっている
- プロバイダーの API Key とエンドポイント URL が正しい
- モデルマッピングにリクエストモデルが入力されている
- プロバイダー切り替え後に Claude Desktop を再起動した
Claude Desktop のモデルメニューにブランド名が表示されない？
プロバイダーを編集し、モデルマッピングの メニュー表示名 を入力してください。その後、プロバイダーを再度有効化し、Claude Desktop を再起動します。
直結モードでエラーになるのはなぜ？
直結モードでは、プロバイダーがネイティブの Anthropic Messages API を提供し、Claude Desktop の三つの役割 ID（claude-sonnet-* / claude-opus-* / claude-haiku-*）を受け入れる必要があります。プロバイダーが OpenAI、Gemini、非 Claude モデル ID、または旧式 Claude ID（例：claude-3-5-sonnet-…）など三つの役割 ID 以外を使う場合は失敗するため、モデルマッピングが必要 をオンにしてください。
CC Switch を閉じてもよい？
モードによります。
- 直結モード：Claude Desktop が再起動して設定を読み込んだ後は、ローカルルーティングを起動し続ける必要はありません
- モデルマッピングモード：CC Switch を起動したままにし、Claude Desktop ローカルルーティングもオンにしておく必要があります
実際のアップストリームモデル名は Claude Desktop に書き込まれる？
モデルマッピングモードでは書き込まれません。Claude Desktop profile には安全な Sonnet / Opus / Haiku 役割ルートと表示名だけが保存されます。実際のアップストリームモデル名は CC Switch のプロバイダー設定に保存され、ローカルゲートウェイを通るリクエスト時にマッピングされます。