agent/cc-switch
1
0
Fork 0
mirror of https://github.com/farion1231/cc-switch.git synced 2026-06-16 13:34:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add Claude Desktop user guide docs

Browse Source 
- Add the Claude Desktop provider guide in English, Chinese, and Japanese.
- Add localized screenshots for import, provider setup, model mapping, and local routing.
- Link the guide from the v3.15.0 release notes and user manual indexes.
This commit is contained in:
Jason
2026-05-16 20:18:49 +08:00
Unverified
parent c460a404dc
commit 4f0f103a8a
28 changed files with 984 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/release-notes/v3.15.0-en.md
+10
View File
@@ -24,6 +24,16 @@
---
## Claude Desktop Guide
The headline feature in this release is the **first-class Claude Desktop management panel**. If you already have many providers configured for Claude Code, start here:
**[Use CC Switch to configure, manage, and switch Claude Desktop providers in one place](../user-manual/en/2-providers/2.6-claude-desktop.md)**
The guide walks through one-click import from Claude Code, adding Claude Desktop-specific providers, direct mode vs. model-mapping mode, showing the hidden local-routing toggle, and returning to Claude Desktop's official sign-in mode.
---
## Overview
CC Switch v3.15.0 is a major release following the v3.14.x line, centered on **promoting Claude Desktop to a first-class managed surface**. It ships third-party provider switching through the in-app proxy gateway, role-based model mapping (`sonnet` / `opus` / `haiku`) with a `supports1m` long-context flag, Copilot/Codex OAuth provider reuse, a redesigned Claude Code import flow, app-switcher differentiation between "Claude Code" and "Claude Desktop", and 44 provider presets translated from the Claude Code catalog into the new Claude Desktop surface.
docs/release-notes/v3.15.0-ja.md
+10
View File
@@ -24,6 +24,16 @@
---
## Claude Desktop 利用ガイド
本リリースの主役は **Claude Desktop の一等管理パネル**です。すでに Claude Code 側で多くのプロバイダーを設定している場合は、まずこのガイドをご覧ください：
**[CC Switch で Claude Desktop プロバイダーを一括設定・管理・切り替える](../user-manual/ja/2-providers/2.6-claude-desktop.md)**
このガイドでは、Claude Code から既存プロバイダーを一括インポートする方法、Claude Desktop 専用プロバイダーの追加、直結 / モデルマッピングの 2 モード、非表示のローカルルーティング切り替えを表示する設定、Claude Desktop 公式サインインモードへの復帰までを説明しています。
---
## 概要
CC Switch v3.15.0 は v3.14.x に続く大型バージョンアップで、コアの焦点は **Claude Desktop を一等管理パネルに昇格させること**にあります。これに合わせて、内蔵プロキシゲートウェイを介したサードパーティプロバイダーの切り替え、ロールベースのモデルマッピング（sonnet / opus / haiku）+ `supports1m` ロングコンテキストフラグ、Copilot / Codex OAuth プロバイダーの再利用、再設計された Claude Code インポートフロー、App スイッチャーでの「Claude Code」と「Claude Desktop」の視覚的な区別、そして Claude Code プリセットディレクトリから翻訳された 44 個の Claude Desktop プリセットを提供します。
docs/release-notes/v3.15.0-zh.md
+10
View File
@@ -24,6 +24,16 @@
---
## Claude Desktop 使用攻略
本版本最主打的能力是 **Claude Desktop 一等管理面板**。如果你已经在 Claude Code 里配置了很多供应商，建议先阅读这篇攻略：
**[使用 CC Switch，一键配置、管理和切换 Claude Desktop 供应商](../user-manual/zh/2-providers/2.6-claude-desktop.md)**
攻略覆盖从 Claude Code 一键导入已有供应商、添加 Claude Desktop 专属供应商、直连 / 模型映射两种模式、本地路由开关显示设置，到恢复 Claude Desktop 官方登录模式的完整流程。
---
## 概览
CC Switch v3.15.0 是 v3.14.x 之后的一次大版本更新，核心聚焦在**把 Claude Desktop 升级为一等管理面板**，并配套提供第三方供应商通过内置代理网关进行切换、按角色的模型映射（sonnet / opus / haiku）+ `supports1m` 长上下文标志、Copilot/Codex OAuth 供应商复用、重新设计的 Claude Code 导入流程、App 切换器对"Claude Code"和"Claude Desktop"的可视化区分，以及 44 个从 Claude Code 预设目录翻译而来的 Claude Desktop 预设。
docs/user-manual/README.md
+3 -3
View File
@@ -12,9 +12,9 @@
## Version / 版本 / バージョン
- Documentation version: v3.13.0
- Last updated: 2026-04-08
- Compatible with CC Switch v3.13.0+
- Documentation version: v3.15.0
- Last updated: 2026-05-16
- Compatible with CC Switch v3.15.0+
## Links
docs/user-manual/assets/claude-desktop-add-provider-en.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 85 KiB

docs/user-manual/assets/claude-desktop-add-provider-ja.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 69 KiB

docs/user-manual/assets/claude-desktop-add-provider.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 63 KiB

docs/user-manual/assets/claude-desktop-import-from-claude-en.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

docs/user-manual/assets/claude-desktop-import-from-claude-ja.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 48 KiB

docs/user-manual/assets/claude-desktop-import-from-claude.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

docs/user-manual/assets/claude-desktop-model-mapping-rows-en.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 63 KiB

docs/user-manual/assets/claude-desktop-model-mapping-rows-ja.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 82 KiB

docs/user-manual/assets/claude-desktop-model-mapping-rows.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 58 KiB

docs/user-manual/assets/claude-desktop-panel-en.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 68 KiB

docs/user-manual/assets/claude-desktop-panel-ja.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 69 KiB

docs/user-manual/assets/claude-desktop-panel.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

docs/user-manual/assets/claude-desktop-route-toggle-context-en.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.2 KiB

docs/user-manual/assets/claude-desktop-route-toggle-context-ja.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.2 KiB

docs/user-manual/assets/claude-desktop-route-toggle-context.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.2 KiB

docs/user-manual/assets/local-routing-display-setting-en.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

docs/user-manual/assets/local-routing-display-setting-ja.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 65 KiB

docs/user-manual/assets/local-routing-display-setting.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

docs/user-manual/en/2-providers/2.6-claude-desktop.md
+306
View File
@@ -0,0 +1,306 @@
# 2.6 Claude Desktop
## Overview
The Claude Desktop panel lets you manage Claude Desktop provider configurations in CC Switch.
Once enabled, you can:
- Use third-party Anthropic-compatible providers in Claude Desktop
- Configure model mapping for non-Claude models such as DeepSeek, Kimi, DouBao, OpenAI, and Gemini
- Reuse Copilot / Codex OAuth account-based providers
- Switch between Claude Desktop official mode and third-party providers
Claude Desktop and Claude Code are separate app entry points. Claude Code uses `~/.claude/settings.json`, while Claude Desktop uses its own 3P profile configuration. In CC Switch they appear as separate apps: "Claude" and "Claude Desktop"; the icon badge in the bottom-right corner helps distinguish them.
## Support Scope
| Item | Description |
|------|-------------|
| Supported systems | macOS, Windows |
| Not supported yet | Writing Claude Desktop 3P configuration on Linux |
| Takes effect | Restart Claude Desktop after switching providers |
| Official mode | Uses Claude Desktop built-in sign-in; no API key or endpoint URL required |
| Third-party mode | Writes the 3P profile managed by CC Switch |
| MCP / Skills | Claude Desktop 3P profiles do not use CC Switch MCP / Skills sync |
## Quick Start
### Step 1: Open the Claude Desktop Panel
Select **Claude Desktop** in the app switcher on the left.
![Claude Desktop panel](../../assets/claude-desktop-panel-en.png)
If you do not see this entry, go to:
Settings → General → Homepage Display
Make sure Claude Desktop is not hidden.
### Step 2: Import or Add Providers
#### Recommended: Import from Claude Code
Many users configure providers in Claude Code first, then want to bring the same provider set into Claude Desktop. On first launch, or when entering the Claude Desktop panel for the first time, if no providers exist here, click **Import existing providers from Claude Code**.
![Import providers from Claude Code](../../assets/claude-desktop-import-from-claude-en.png)
If you already have many providers configured in Claude Code, this one-click import saves you from re-entering endpoint URLs, API keys, and default models one by one.
Import rules:
- Existing providers with the same ID are not overwritten
- Claude Code providers that can connect directly and use safe model names are imported as direct mode
- Providers that need model conversion are imported as model mapping mode when possible
- `ANTHROPIC_DEFAULT_SONNET_MODEL`, `ANTHROPIC_DEFAULT_OPUS_MODEL`, and `ANTHROPIC_DEFAULT_HAIKU_MODEL` are converted into Desktop Sonnet / Opus / Haiku mappings
- The legacy `[1M]` suffix is converted into the `supports1m` flag in the Claude Desktop profile
- Providers whose model mapping cannot be inferred are skipped
After importing, review each provider's model mapping against your actual upstream models. Non-Claude models such as Kimi, DeepSeek, GLM, and DouBao usually need model mapping mode.
If you already configured providers in Claude Code, prefer **Import existing providers from Claude Code**. This is the easiest migration path to Claude Desktop.
If there is nothing to import, or if you want to add a provider only for Claude Desktop, click the **+** button in the top-right corner.
![Add Claude Desktop provider](../../assets/claude-desktop-add-provider-en.png)
You can choose:
- **Preset provider**: choose from built-in Claude Desktop presets and fill in only the API key
- **Custom configuration**: manually enter name, endpoint URL, API key, and model settings
- **Claude Desktop Official**: restore Claude Desktop official sign-in mode
For ordinary Anthropic Messages API-compatible providers, you usually only need to:
1. Choose a preset or custom provider
2. Fill in **API Key**
3. Confirm **API Endpoint**
4. Keep **Needs model mapping** off
5. Click **Add**
### Step 3: Switch and Restart Claude Desktop
Click **Enable** on a provider card.
After switching:
- Direct providers: restart Claude Desktop for the change to take effect
- Providers that need routing: keep CC Switch running, turn on Claude Desktop local routing, then restart Claude Desktop
> Note: Claude Desktop does not hot-reload configuration like Claude Code. After each provider switch, fully quit and reopen Claude Desktop.
## Two Modes
### Direct Mode
Direct mode is for providers that already expose the Anthropic Messages API and can be reached by Claude Desktop directly.
In direct mode, CC Switch points the Claude Desktop 3P profile to the provider endpoint:
```json
{
"inferenceProvider": "gateway",
"inferenceGatewayBaseUrl": "https://api.example.com",
"inferenceGatewayAuthScheme": "bearer",
"inferenceGatewayApiKey": "your API key"
}
```
Use this when:
- The provider exposes native Anthropic Messages API
- Model IDs use `claude-*` or `anthropic/claude-*`
- No format conversion is needed
- CC Switch local routing does not need to stay running while in use
The "Manually specify Claude Desktop models" option in direct mode is advanced. Most native Claude model providers do not need it because Claude Desktop can fetch `/v1/models` automatically.
Only fill it in when the provider's `/v1/models` is unavailable, or when the returned model names cannot be recognized by Claude Desktop.
### Model Mapping Mode
Model mapping mode is for providers that expose non-Claude models, such as DeepSeek and Kimi, or when CC Switch needs to convert the API format.
After **Needs model mapping** is enabled, Claude Desktop connects to the CC Switch local gateway:
```text
http://127.0.0.1:15721/claude-desktop
```
CC Switch handles:
1. Exposing safe Claude model routes to Claude Desktop
2. Mapping the model role selected in Desktop to the real upstream model
3. Converting Anthropic / OpenAI / Gemini request formats as required by the provider
4. Using the provider credentials saved in CC Switch to call upstream
Supported API formats:
| Format | Usage |
|--------|-------|
| Anthropic Messages | Native or compatible Anthropic requests |
| OpenAI Chat Completions | OpenAI-compatible `/chat/completions` |
| OpenAI Responses API | OpenAI Responses-compatible endpoints |
| Gemini Native generateContent | Gemini native API |
In model mapping mode, Claude Desktop only sees `claude-*` style models. Real upstream model names are not written directly into the Claude Desktop profile.
## Configure Model Mapping
### Field Reference
| Field | Description |
|-------|-------------|
| Model role | Sonnet / Opus / Haiku route recognizable by Claude Desktop |
| Menu display name | Name shown in the Claude Desktop model menu |
| Requested model | Real upstream model ID sent to the provider |
| 1M | Declares 1M context support to Claude Desktop |
![Claude Desktop model mapping](../../assets/claude-desktop-model-mapping-rows-en.png)
### Recommended Setup
For Kimi:
| Model role | Menu display name | Requested model | 1M |
|------------|-------------------|-----------------|----|
| Sonnet | Kimi K2 | `kimi-k2` | Match provider capability |
For DeepSeek:
| Model role | Menu display name | Requested model | 1M |
|------------|-------------------|-----------------|----|
| Sonnet | DeepSeek V4 Pro | `deepseek-v4-pro` | Match provider capability |
The reason is that Claude Desktop now rejects non-`claude-*` models, so CC Switch local routing performs a model mapping pass.
### Multiple Role Mapping
You can configure Sonnet, Opus, and Haiku at the same time:
| Model role | Recommended usage |
|------------|-------------------|
| Sonnet | Default main model |
| Opus | Higher quality or complex tasks |
| Haiku | Fast, lower-cost model |
If the provider only has one model, one role is enough. Model mapping mode requires at least one valid mapping.
## Local Routing Toggle
Model mapping mode needs CC Switch local routing to convert requests. Local routing is powerful but more complex, so the main-page routing toggle is hidden by default to avoid accidental clicks by users who do not need routing. When you need routing, show it manually.
Open:
Settings → Routing → Local Routing → enable **Show Routing Toggle on Main Page**
![Show local routing toggle setting](../../assets/local-routing-display-setting-en.png)
After enabling this display switch, return to the Claude Desktop panel. The Claude Desktop local routing toggle appears in the top-right area of the main page.
![Claude Desktop local routing toggle](../../assets/claude-desktop-route-toggle-context-en.png)
Status reference:
| Status | Description |
|--------|-------------|
| On | Local gateway is running, usually at `127.0.0.1:15721` |
| Off | Direct providers still work; model mapping providers cannot work normally |
| Loading | Routing service is starting or stopping |
Only providers with **Needs model mapping** depend on local routing. Direct providers do not need this toggle.
If another app is using proxy takeover, stopping local routing may be blocked. First disable that app's takeover in the routing service settings, then stop local routing.
## Restore Official Claude Desktop
To return to Claude Desktop official sign-in:
1. Select **Claude Desktop Official**
2. Click **Enable**
3. Restart Claude Desktop
CC Switch restores Claude Desktop's official 1P mode and removes the 3P profile managed by CC Switch.
Official mode does not need an API key or local routing.
When importing from Claude Code, CC Switch automatically adds **Claude Desktop Official**.
## Configuration File Locations
CC Switch writes Claude Desktop 3P configuration files.
### 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
```
These files are maintained automatically by CC Switch. Manual edits are not recommended. If configuration becomes inconsistent, enabling the current provider again usually repairs it.
## Status Messages
The Claude Desktop panel may show "Claude Desktop configuration needs attention".
| Message | How to handle |
|---------|---------------|
| Current platform is not supported | Only macOS / Windows currently support writing 3P configuration |
| Profile contains non-`claude-*` model names | Switch to the current provider again, or edit the provider to use model mapping |
| Model mapping is enabled but no valid route exists | Edit the provider and add at least one model mapping |
| Local routing token has not been generated | Switch to the provider again; CC Switch will write a new local token |
| Profile URL does not match the current provider | Switch to the current provider again so the profile points to the expected URL |
## FAQ
### Switched successfully, but Claude Desktop did not change?
Fully quit and restart Claude Desktop. Claude Desktop usually reads the 3P profile on startup and does not hot-reload it after changes.
### Model mapping provider request failed?
Check:
- CC Switch is still running
- Claude Desktop local routing is enabled
- Provider API key and endpoint URL are correct
- Requested model is filled in the model mapping
- Claude Desktop was restarted after switching providers
### Why does my branded model name not appear in the Claude Desktop model menu?
Edit the provider, fill in **Menu display name** in model mapping, then enable the provider again and restart Claude Desktop.
### Why does direct mode fail?
Direct mode requires the provider to expose native Anthropic Messages API and accept Claude-safe model names used by Claude Desktop. If the provider uses OpenAI, Gemini, or non-Claude model IDs, enable **Needs model mapping**.
### Can I close CC Switch?
It depends on the mode:
- Direct mode: after Claude Desktop restarts and loads the profile, local routing does not need to keep running
- Model mapping mode: CC Switch must keep running, and Claude Desktop local routing must stay on
### Are real upstream model names written into Claude Desktop?
Not in model mapping mode. The Claude Desktop profile only stores safe `claude-*` routes and display names. Real upstream model names stay in the CC Switch provider configuration and are mapped when requests pass through the local gateway.
## Next Steps
- [Add Provider](./2.1-add.md)
- [Switch Provider](./2.2-switch.md)
- [Proxy Service](../4-proxy/4.1-service.md)
- [App Takeover](../4-proxy/4.2-routing.md)
docs/user-manual/en/README.md
+11 -5
View File
@@ -19,7 +19,8 @@ CC Switch User Manual
│ ├── 2.2 Switch Provider
│ ├── 2.3 Edit Provider
│ ├── 2.4 Sort & Duplicate
│ └── 2.5 Usage Query
│ ├── 2.5 Usage Query
│ └── 2.6 Claude Desktop
│
├── 3. Extensions
│ ├── 3.1 MCP Server Management
@@ -63,6 +64,7 @@ CC Switch User Manual
| [2.3-edit.md](./2-providers/2.3-edit.md) | Edit configuration, modify API Key, backfill mechanism |
| [2.4-sort-duplicate.md](./2-providers/2.4-sort-duplicate.md) | Drag-to-reorder, duplicate provider, delete |
| [2.5-usage-query.md](./2-providers/2.5-usage-query.md) | Usage query, remaining balance, multi-plan display |
| [2.6-claude-desktop.md](./2-providers/2.6-claude-desktop.md) | Claude Desktop third-party providers, direct mode, and model mapping |
### 3. Extensions
@@ -98,17 +100,21 @@ CC Switch User Manual
- **New users**: Start with [1.1 Introduction](./1-getting-started/1.1-introduction.md)
- **Installation issues**: See [1.2 Installation Guide](./1-getting-started/1.2-installation.md)
- **Configure providers**: See [2.1 Add Provider](./2-providers/2.1-add.md)
- **Use Claude Desktop**: See [2.6 Claude Desktop](./2-providers/2.6-claude-desktop.md)
- **Using proxy**: See [4.1 Proxy Service](./4-proxy/4.1-service.md)
- **Having trouble**: See [5.2 FAQ](./5-faq/5.2-questions.md)
## Version Information
- Documentation version: v3.13.0
- Last updated: 2026-04-08
- Applicable to CC Switch v3.13.0+
- Documentation version: v3.15.0
- Last updated: 2026-05-16
- Applicable to CC Switch v3.15.0+
### v3.13.0 Highlights
### v3.15.0 Highlights
- **First-class Claude Desktop panel**: supports third-party providers, direct / model mapping modes, Copilot / Codex OAuth reuse, and 3P profile writing. See [2.6 Claude Desktop](./2-providers/2.6-claude-desktop.md)
- **Role-based model mapping**: adapts Claude Desktop model validation with Sonnet / Opus / Haiku routes and `supports1m`
- **Claude Desktop local routing**: provides a local gateway at `127.0.0.1:15721/claude-desktop` for providers that need conversion
- **Lightweight Mode**: Destroys the main window when minimizing to tray — near-zero idle footprint. See [1.5 Personalization](./1-getting-started/1.5-settings.md)
- **Quota & Balance Display**: Official subscriptions (Claude/Codex/Gemini/Copilot/Codex OAuth) auto-display quotas; Token Plan and third-party balances use built-in templates with one-click enable — see [2.5 Usage Query](./2-providers/2.5-usage-query.md)
- **Codex OAuth Reverse Proxy**: Reuse your ChatGPT account's Codex service inside Claude Code — see [2.1 Add Provider](./2-providers/2.1-add.md)
docs/user-manual/ja/2-providers/2.6-claude-desktop.md
+306
View File
@@ -0,0 +1,306 @@
# 2.6 Claude Desktop
## 機能概要
Claude Desktop パネルでは、CC Switch 上で Claude Desktop のプロバイダー設定を管理できます。
有効にすると、次のことができます。
- Claude Desktop でサードパーティの Anthropic 互換プロバイダーを使う
- 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 のプロバイダーがすでにある場合は上書きしません
- 直接接続でき、モデル名が安全な Claude Code プロバイダーは直結モードとしてインポートされます
- モデル変換が必要なプロバイダーは、可能な場合モデルマッピングモードとしてインポートされます
- `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` は Desktop の Sonnet / Opus / Haiku マッピングに変換されます
- 旧形式の `[1M]` サフィックスは Claude Desktop profile の `supports1m` フラグに変換されます
- モデルマッピングを判断できないプロバイダーはスキップされます
インポート後は、各プロバイダーのモデルマッピングが実際のアップストリームモデルと合っているか確認してください。Kimi、DeepSeek、GLM、DouBao などの非 Claude モデルは通常、モデルマッピングモードが必要です。
すでに 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 の公式サインインモードへ戻す
通常の 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-*` または `anthropic/claude-*`
- 形式変換が不要
- 使用中に CC Switch のローカルルーティングを起動し続ける必要がない
直結モードの「Claude Desktop モデルを手動指定」は高度な任意設定です。多くのネイティブ Claude モデルプロバイダーでは不要で、Claude Desktop が `/v1/models` を自動取得します。
プロバイダーの `/v1/models` が使えない、または返されるモデル名を Claude Desktop が認識できない場合だけ手動で追加してください。
### モデルマッピングモード
モデルマッピングモードは、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-*` 形式のモデルだけです。実際のアップストリームモデル名は 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 が非 `claude-*` モデルを拒否するためです。そのため CC Switch のルーティング機能で一度モデルマッピングを行います。
### 複数役割のマッピング
Sonnet、Opus、Haiku の 3 つを同時に設定できます。
| モデル役割 | 推奨用途 |
|------------|----------|
| Sonnet | デフォルトの主力モデル |
| Opus | 高品質または複雑なタスク |
| Haiku | 高速・低コストモデル |
プロバイダーにモデルが 1 つしかない場合は、1 つの役割だけでも構いません。モデルマッピングモードでは少なくとも 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 に非 `claude-*` モデル名がある | 現在のプロバイダーへ再度切り替える、またはモデルマッピングを使うよう編集する |
| モデルマッピングが有効だが有効なルートがない | プロバイダーを編集し、少なくとも 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 が使う Claude 安全モデル名を受け入れる必要があります。プロバイダーが OpenAI、Gemini、または非 Claude モデル ID を使う場合は **モデルマッピングが必要** をオンにしてください。
### CC Switch を閉じてもよい？
モードによります。
- 直結モード：Claude Desktop が再起動して設定を読み込んだ後は、ローカルルーティングを起動し続ける必要はありません
- モデルマッピングモード：CC Switch を起動したままにし、Claude Desktop ローカルルーティングもオンにしておく必要があります
### 実際のアップストリームモデル名は Claude Desktop に書き込まれる？
モデルマッピングモードでは書き込まれません。Claude Desktop profile には安全な `claude-*` ルートと表示名だけが保存されます。実際のアップストリームモデル名は CC Switch のプロバイダー設定に保存され、ローカルゲートウェイを通るリクエスト時にマッピングされます。
## 次のステップ
- [プロバイダーの追加](./2.1-add.md)
- [プロバイダーの切り替え](./2.2-switch.md)
- [プロキシサービス](../4-proxy/4.1-service.md)
- [アプリケーション接管](../4-proxy/4.2-routing.md)
docs/user-manual/ja/README.md
+11 -5
View File
@@ -19,7 +19,8 @@ CC Switch ユーザーマニュアル
│ ├── 2.2 プロバイダーの切り替え
│ ├── 2.3 プロバイダーの編集
│ ├── 2.4 並べ替えと複製
│ └── 2.5 使用量クエリ
│ ├── 2.5 使用量クエリ
│ └── 2.6 Claude Desktop
│
├── 3. 拡張機能
│ ├── 3.1 MCP サーバー管理
@@ -63,6 +64,7 @@ CC Switch ユーザーマニュアル
| [2.3-edit.md](./2-providers/2.3-edit.md) | 設定の編集、API Key の変更、バックフィル機能 |
| [2.4-sort-duplicate.md](./2-providers/2.4-sort-duplicate.md) | ドラッグで並べ替え、プロバイダーの複製、削除 |
| [2.5-usage-query.md](./2-providers/2.5-usage-query.md) | 使用量クエリ、残額表示、複数プラン表示 |
| [2.6-claude-desktop.md](./2-providers/2.6-claude-desktop.md) | Claude Desktop サードパーティプロバイダー、直結モード、モデルマッピング |
### 3. 拡張機能
@@ -98,17 +100,21 @@ CC Switch ユーザーマニュアル
- **初めての方**：[1.1 ソフトウェア紹介](./1-getting-started/1.1-introduction.md) からお読みください
- **インストールの問題**：[1.2 インストールガイド](./1-getting-started/1.2-installation.md) をご確認ください
- **プロバイダーの設定**：[2.1 プロバイダーの追加](./2-providers/2.1-add.md) をご確認ください
- **Claude Desktop の利用**：[2.6 Claude Desktop](./2-providers/2.6-claude-desktop.md) をご確認ください
- **プロキシの使用**：[4.1 プロキシサービス](./4-proxy/4.1-service.md) をご確認ください
- **お困りの方**：[5.2 FAQ](./5-faq/5.2-questions.md) をご確認ください
## バージョン情報
- ドキュメントバージョン：v3.13.0
- 最終更新：2026-04-08
- CC Switch v3.13.0+ 対応
- ドキュメントバージョン：v3.15.0
- 最終更新：2026-05-16
- CC Switch v3.15.0+ 対応
### v3.13.0 の注目機能
### v3.15.0 の注目機能
- **Claude Desktop の一等管理パネル**：サードパーティプロバイダー、直結 / モデルマッピングの 2 モード、Copilot / Codex OAuth 再利用、3P profile 書き込みに対応 — 詳細は [2.6 Claude Desktop](./2-providers/2.6-claude-desktop.md)
- **役割別モデルマッピング**：Sonnet / Opus / Haiku ルートと `supports1m` フラグで Claude Desktop のモデル検証に対応
- **Claude Desktop ローカルルーティング**：変換が必要なプロバイダー向けに `127.0.0.1:15721/claude-desktop` のローカルゲートウェイを提供
- **軽量モード**：トレイへ最小化時にメインウィンドウを破棄、アイドル時のリソース使用量をほぼゼロに — 詳細は [1.5 個人設定](./1-getting-started/1.5-settings.md)
- **クォータ・残高表示**：公式サブスクリプション系（Claude/Codex/Gemini/Copilot/Codex OAuth）はカードに自動表示、Token Plan および第三者残高は内蔵テンプレートでワンクリック有効化 — 詳細は [2.5 使用量クエリ](./2-providers/2.5-usage-query.md)
- **Codex OAuth リバースプロキシ**：ChatGPT アカウントで Claude Code 内から Codex サービスを再利用 — 詳細は [2.1 プロバイダーの追加](./2-providers/2.1-add.md)
docs/user-manual/zh/2-providers/2.6-claude-desktop.md
+306
View File
@@ -0,0 +1,306 @@
# 2.6 Claude Desktop
## 功能说明
Claude Desktop 面板用于在 CC Switch 中管理 Claude Desktop 的供应商配置。
开启后，你可以：
- 在 Claude Desktop 中使用第三方 Anthropic 兼容供应商
- 为 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 和接口地址 |
| 第三方模式 | 写入 CC Switch 管理的 3P profile |
| MCP / Skills | Claude Desktop 3P profile 不走 CC Switch 的 MCP / Skills 同步 |
## 快速上手
### 第一步：切换到 Claude Desktop 面板
在左侧应用切换器中选择 **Claude Desktop**。
![Claude Desktop 面板](../../assets/claude-desktop-panel.png)
如果你没有看到该入口，请到：
设置 → 通用 → 应用可见性
确认 Claude Desktop 没有被隐藏。
### 第二步：导入或添加供应商
#### 优先使用：从 Claude Code 一键导入
很多用户最开始是在 Claude Code 里配置供应商，然后才想把同一批供应商带到 Claude Desktop。第一次启动 CC Switch，或第一次进入 Claude Desktop 面板时，如果这里还没有供应商，可以直接点击 **将 Claude Code 中已有的供应商导入**。
![从 Claude Code 导入供应商](../../assets/claude-desktop-import-from-claude.png)
如果你已经在 Claude Code 那边配置了很多供应商，这个功能可以一键把它们导入到 Claude Desktop 面板，省掉逐个重新填写接口地址、API Key 和默认模型的工作。
导入规则：
- 已存在同 ID 供应商时不会覆盖
- 能直连且模型名安全的 Claude Code 供应商会导入为直连模式
- 需要模型转换的供应商会尝试导入为模型映射模式
- `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 会转换为 Desktop 的 Sonnet / Opus / Haiku 映射
- 旧的 `[1M]` 后缀会转换为 Claude Desktop profile 中的 `supports1m` 标记
- 无法判断模型映射的供应商会被跳过
导入后请检查每个供应商的模型映射是否符合你的实际上游模型。尤其是 Kimi、DeepSeek、GLM、DouBao 这类非 Claude 模型，通常需要使用模型映射模式。
如果你已经在 Claude Code 中配置过供应商，优先使用上面的 **将 Claude Code 中已有的供应商导入**。这是迁移到 Claude Desktop 最省事的路径。
如果没有可导入的配置，或想单独给 Claude Desktop 添加一个供应商，再点击右上角 **+** 按钮添加供应商。
![Claude Desktop 添加供应商](../../assets/claude-desktop-add-provider.png)
你可以选择：
- **预设供应商**：从内置 Claude Desktop 预设中选择，只填写 API Key
- **自定义供应商**：手动填写名称、接口地址、API Key 和模型设置
- **Claude Desktop Official**：恢复 Claude Desktop 官方登录模式
对于普通 Anthropic Messages API 兼容供应商，通常只需要：
1. 选择预设或自定义供应商
2. 填写 **API Key**
3. 确认 **接口地址**
4. 保持「需要模型映射」关闭
5. 点击「添加」
### 第三步：切换并重启 Claude Desktop
在供应商卡片上点击「启用」。
切换成功后：
- 直连供应商：重启 Claude Desktop 后生效
- 需要路由的供应商：保持 CC Switch 运行，开启 Claude Desktop 本地路由，然后重启 Claude Desktop
> 注意：Claude Desktop 不会像 Claude Code 那样热重载配置。每次切换供应商后，都需要完全退出并重新打开 Claude Desktop。
## 两种工作模式
### 直连模式
直连模式适合供应商本身已经提供 Anthropic Messages API，并且能被 Claude Desktop 直接访问。
直连模式下，CC Switch 会把 Claude Desktop 的 3P profile 指向供应商接口：
```json
{
"inferenceProvider": "gateway",
"inferenceGatewayBaseUrl": "https://api.example.com",
"inferenceGatewayAuthScheme": "bearer",
"inferenceGatewayApiKey": "你的 API Key"
}
```
适用场景：
- 供应商暴露原生 Anthropic Messages API
- 模型 ID 使用 `claude-*` 或 `anthropic/claude-*`
- 不需要格式转换
- 不需要 CC Switch 在使用期间保持本地路由
直连模式的「手动指定 Claude Desktop 模型列表」是高级选项。多数原生 Claude 模型供应商不需要填写，Claude Desktop 会自动读取 `/v1/models`。
仅当供应商的 `/v1/models` 不可用，或返回的模型名不能被 Claude Desktop 识别时，再手动添加模型。
### 模型映射模式
模型映射模式适合供应商提供的不是 Claude 系列模型（比如 deepseek, kimi 等），或接口格式需要 CC Switch 转换。
开启「需要模型映射」后，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 原生接口 |
模型映射模式下，Claude Desktop 只看到 `claude-*` 形式的模型；真实模型名不会直接写进 Claude Desktop profile。
## 配置模型映射
### 字段说明
| 字段 | 说明 |
| ------------ | -------------------------------------------------- |
| 模型角色 | Claude Desktop 可识别的 Sonnet / Opus / Haiku 路由 |
| 菜单显示名 | 在 Claude Desktop 模型菜单里显示的名称 |
| 实际请求模型 | 发送给上游供应商的真实模型 ID |
| 1M | 向 Claude Desktop 声明该模型支持 1M 上下文 |
![Claude Desktop 模型映射](../../assets/claude-desktop-model-mapping-rows.png)
### 推荐写法
如果你想在 Claude Desktop 中使用 Kimi：
| 模型角色 | 菜单显示名 | 实际请求模型 | 1M |
| -------- | ---------- | ------------ | ---------------- |
| Sonnet | Kimi K2 | `kimi-k2` | 按供应商能力选择 |
如果你想使用 DeepSeek：
| 模型角色 | 菜单显示名 | 实际请求模型 | 1M |
| -------- | --------------- | ----------------- | ---------------- |
| Sonnet | DeepSeek V4 Pro | `deepseek-v4-pro` | 按供应商能力选择 |
这样做的原因是 Claude Desktop 现在会拒绝非 `claude-*` 模型，所以需要 CC Switch 的路由功能进行一轮模型映射。
### 多角色映射
你可以同时配置 Sonnet、Opus、Haiku 三个角色：
| 模型角色 | 建议用途 |
| -------- | -------------------- |
| Sonnet | 默认主力模型 |
| Opus | 高质量或复杂任务模型 |
| Haiku | 快速、低成本模型 |
如果供应商只有一个模型，也可以只配置一个角色。模型映射模式至少需要一条有效映射。
## 本地路由开关
模型映射模式需要 CC Switch 本地路由参与请求转换。本地路由是一个强大，同时有一定复杂度的功能，为了避免不需要路由功能的用户误触，主页面的本地路由开关默认隐藏，需要路由功能时，请手动把它显示出来。
打开方式：
设置 → 路由 → 本地路由 → 开启 **在主页面显示本地路由开关**
![显示本地路由开关设置](../../assets/local-routing-display-setting.png)
打开显示开关后，回到 Claude Desktop 面板，主界面右上角会看到 Claude Desktop 本地路由开关。
![Claude Desktop 本地路由开关](../../assets/claude-desktop-route-toggle-context.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 导入供应商的时候，会自动添加一个 **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 配置需要检查」提示。
| 提示 | 处理方式 |
| ------------------------------------ | ------------------------------------------------ |
| 当前平台暂不支持 | 目前仅 macOS / Windows 支持写入 3P 配置 |
| profile 中存在非 `claude-*` 模型名 | 重新切换当前供应商，或编辑供应商改用模型映射 |
| 启用了模型映射但没有有效路由 | 编辑供应商，至少添加一条模型映射 |
| 本地路由 token 尚未生成 | 重新切换该供应商，CC Switch 会写入新的本地 token |
| profile 指向的地址与当前供应商不一致 | 重新切换当前供应商，让 profile 回到正确地址 |
## 常见问题
### 切换成功但 Claude Desktop 没变化？
请完全退出并重启 Claude Desktop。Claude Desktop 读取 3P profile 的时机通常在启动阶段，切换后不会自动热更新。
### 模型映射供应商请求失败？
检查：
- CC Switch 是否仍在运行
- Claude Desktop 本地路由是否已开启
- 供应商 API Key 和接口地址是否正确
- 模型映射中是否填写了实际请求模型
- 切换供应商后是否重启了 Claude Desktop
### Claude Desktop 模型菜单里看不到我的品牌模型名？
编辑供应商，在模型映射中填写「菜单显示名」，然后重新启用供应商并重启 Claude Desktop。
### 直连模式下为什么报错？
直连模式要求供应商提供原生 Anthropic Messages API，并接受 Claude Desktop 使用的 Claude 安全模型名。如果供应商使用 OpenAI、Gemini 或非 Claude 模型 ID，请开启「需要模型映射」。
### 可以关闭 CC Switch 吗？
取决于模式：
- 直连模式：Claude Desktop 重启并加载配置后，可以不保持本地路由运行
- 模型映射模式：必须保持 CC Switch 运行，并保持 Claude Desktop 本地路由开启
### 是否会把真实上游模型名写入 Claude Desktop？
模型映射模式不会。Claude Desktop profile 中只保存安全的 `claude-*` 路由和显示名；真实上游模型名保存在 CC Switch 的供应商配置中，请求经过本地网关时再映射。
## 下一步
- [添加供应商](./2.1-add.md)
- [切换供应商](./2.2-switch.md)
- [代理服务](../4-proxy/4.1-service.md)
- [应用路由](../4-proxy/4.2-routing.md)
docs/user-manual/zh/README.md
+11 -5
View File
@@ -19,7 +19,8 @@
│ ├── 2.2 切换供应商
│ ├── 2.3 编辑供应商
│ ├── 2.4 排序与复制
│ └── 2.5 用量查询
│ ├── 2.5 用量查询
│ └── 2.6 Claude Desktop
│
├── 3. 扩展功能
│ ├── 3.1 MCP 服务器管理
@@ -63,6 +64,7 @@
| [2.3-edit.md](./2-providers/2.3-edit.md) | 编辑配置、修改 API Key、回填机制 |
| [2.4-sort-duplicate.md](./2-providers/2.4-sort-duplicate.md) | 拖拽排序、复制供应商、删除 |
| [2.5-usage-query.md](./2-providers/2.5-usage-query.md) | 用量查询、剩余额度、多套餐显示 |
| [2.6-claude-desktop.md](./2-providers/2.6-claude-desktop.md) | Claude Desktop 第三方供应商、直连与模型映射 |
### 3. 扩展功能
@@ -98,17 +100,21 @@
- **新用户**：从 [1.1 软件介绍](./1-getting-started/1.1-introduction.md) 开始
- **安装问题**：查看 [1.2 安装指南](./1-getting-started/1.2-installation.md)
- **配置供应商**：查看 [2.1 添加供应商](./2-providers/2.1-add.md)
- **使用 Claude Desktop**：查看 [2.6 Claude Desktop](./2-providers/2.6-claude-desktop.md)
- **使用代理**：查看 [4.1 代理服务](./4-proxy/4.1-service.md)
- **遇到问题**：查看 [5.2 FAQ](./5-faq/5.2-questions.md)
## 版本信息
- 文档版本：v3.13.0
- 最后更新：2026-04-08
- 适用于 CC Switch v3.13.0+
- 文档版本：v3.15.0
- 最后更新：2026-05-16
- 适用于 CC Switch v3.15.0+
### v3.13.0 亮点
### v3.15.0 亮点
- **Claude Desktop 一等管理面板**：支持第三方供应商、直连 / 模型映射两种模式、Copilot / Codex OAuth 复用与 3P profile 写入 — 详见 [2.6 Claude Desktop](./2-providers/2.6-claude-desktop.md)
- **按角色的模型映射**：用 Sonnet / Opus / Haiku 路由和 `supports1m` 标志适配 Claude Desktop 的模型校验
- **Claude Desktop 本地路由**：通过 `127.0.0.1:15721/claude-desktop` 为需要转换的供应商提供本地网关
- **轻量模式**：退出到托盘时销毁主窗口，空闲占用接近零 — 详见 [1.5 个性化配置](./1-getting-started/1.5-settings.md)
- **配额与余额展示**：官方订阅类（Claude/Codex/Gemini/Copilot/Codex OAuth）自动展示剩余额度；Token Plan 和第三方余额通过内置模板一键启用 — 详见 [2.5 用量查询](./2-providers/2.5-usage-query.md)
- **Codex OAuth 反向代理**：用 ChatGPT 账号在 Claude Code 中复用 Codex 服务 — 详见 [2.1 添加供应商](./2-providers/2.1-add.md)