# 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 のアカウント型プロバイダーを再利用する
- 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 パネル](../../assets/claude-desktop-panel-ja.png)

この入口が見つからない場合は、次を確認してください。

設定 → 一般 → ホームページ表示

Claude Desktop が非表示になっていないことを確認します。

### ステップ 2：プロバイダーをインポートまたは追加する

#### 推奨：Claude Code から一括インポート

多くのユーザーはまず Claude Code 側でプロバイダーを設定し、その同じプロバイダー群を Claude Desktop に持ち込みたいはずです。CC Switch の初回起動時、または Claude Desktop パネルを初めて開いたときにプロバイダーがまだない場合は、**Claude Code の既存プロバイダーをインポート** をクリックします。

![Claude Code からプロバイダーをインポート](../../assets/claude-desktop-import-from-claude-ja.png)

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 プロバイダーを追加](../../assets/claude-desktop-add-provider-ja.png)

選べる方法：

- **プリセットプロバイダー**：内蔵の Claude Desktop プリセットから選び、API Key だけ入力する
- **カスタム設定**：名前、エンドポイント URL、API Key、モデル設定を手動入力する
- **Claude Desktop Official**：Claude Desktop の公式サインインモードへ戻す

Claude Desktop の三つの役割 ID（`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`）をすでに受け付けるネイティブ Anthropic Messages API プロバイダーでは、基本的に次の手順だけで十分です。

1. プリセットまたはカスタムプロバイダーを選ぶ
2. **API Key** を入力する
3. **API エンドポイント** を確認する
4. **モデルマッピングが必要** をオフのままにする
5. **追加** をクリックする

### ステップ 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 をプロバイダーのエンドポイントへ向けます。

```json
{
  "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 のローカルゲートウェイへ接続します。

```text
http://127.0.0.1:15721/claude-desktop
```

CC Switch は次を担当します。

1. Claude Desktop に安全な Claude モデルルートを公開する
2. Desktop で選択したモデル役割を実際のアップストリームモデルへマッピングする
3. プロバイダーに合わせて Anthropic / OpenAI / Gemini のリクエスト形式を変換する
4. 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 コンテキスト対応を宣言 |

![Claude Desktop モデルマッピング](../../assets/claude-desktop-model-mapping-rows-ja.png)

### 推奨設定

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 ローカルルーティングが必要です。ローカルルーティングは強力ですが少し複雑な機能でもあるため、ルーティングを必要としないユーザーの誤操作を避けるために、メインページのルーティング切り替えはデフォルトで非表示です。必要なときだけ手動で表示してください。

開き方：

設定 → ルーティング → ローカルルーティング → **メインページにルーティング切り替えを表示** をオン

![ローカルルーティング切り替えを表示](../../assets/local-routing-display-setting-ja.png)

表示スイッチをオンにしたら Claude Desktop パネルへ戻ります。メインページ右上に Claude Desktop ローカルルーティング切り替えが表示されます。

![Claude Desktop ローカルルーティング切り替え](../../assets/claude-desktop-route-toggle-context-ja.png)

状態説明：

| 状態 | 説明 |
|------|------|
| オン | ローカルゲートウェイが起動中。通常は `127.0.0.1:15721` |
| オフ | 直結プロバイダーは利用可能。モデルマッピングプロバイダーは正常に動作しません |
| 読み込み中 | ルーティングサービスの起動または停止中 |

**モデルマッピングが必要** なプロバイダーだけがローカルルーティングに依存します。直結プロバイダーではこの切り替えは不要です。

他のアプリがプロキシ接管を使用している場合、ローカルルーティングの停止がブロックされることがあります。先にルーティングサービス設定で該当アプリの接管をオフにしてから、ローカルルーティングを停止してください。

## 公式 Claude Desktop に戻す

Claude Desktop の公式サインインへ戻す場合：

1. **Claude Desktop Official** を選択する
2. **有効化** をクリックする
3. 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

```text
~/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

```text
%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 のプロバイダー設定に保存され、ローカルゲートウェイを通るリクエスト時にマッピングされます。

## 次のステップ

- [プロバイダーの追加](./2.1-add.md)
- [プロバイダーの切り替え](./2.2-switch.md)
- [プロキシサービス](../4-proxy/4.1-service.md)
- [アプリケーション接管](../4-proxy/4.2-routing.md)