docs/user-manual/en/2-providers/2.6-claude-desktop.md
The Claude Desktop panel lets you manage Claude Desktop provider configurations in CC Switch.
Once enabled, you can:
claude-3-5-sonnet) and non-Claude models like DeepSeek / Kimi / DouBao / OpenAI / Gemini all need itClaude 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.
| 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 |
Select Claude Desktop in the app switcher on the left.
If you do not see this entry, go to:
Settings → General → Homepage Display
Make sure Claude Desktop is not hidden.
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.
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:
claude-sonnet-* / claude-opus-* / claude-haiku-*) and can connect directly are imported as direct modeANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL are converted into Desktop Sonnet / Opus / Haiku mappings[1M] suffix is converted into the supports1m flag in the Claude Desktop profileAfter importing, review each provider's model mapping against your actual upstream models. Any model that is not a claude-sonnet-* / claude-opus-* / claude-haiku-* role ID—including non-Claude models like Kimi, DeepSeek, GLM, and DouBao, as well as legacy Claude IDs—usually needs 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.
You can choose:
For native Anthropic Messages API providers that already accept Claude Desktop's three role IDs (claude-sonnet-* / claude-opus-* / claude-haiku-*), you usually only need to:
Click Enable on a provider card.
After switching:
Note: Claude Desktop does not hot-reload configuration like Claude Code. After each provider switch, fully quit and reopen Claude Desktop.
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:
{
"inferenceProvider": "gateway",
"inferenceGatewayBaseUrl": "https://api.example.com",
"inferenceGatewayAuthScheme": "bearer",
"inferenceGatewayApiKey": "your API key"
}
Use this when:
claude-sonnet-*, claude-opus-*, or claude-haiku-* (or the same with the anthropic/claude- prefix)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. Manually entered model names must follow the claude-sonnet-*, claude-opus-*, or claude-haiku-* shape (legacy IDs like claude-3-5-sonnet-… are rejected).
Model mapping mode is for providers whose models are not claude-sonnet-* / claude-opus-* / claude-haiku-* role IDs (including legacy Claude IDs and 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:
http://127.0.0.1:15721/claude-desktop
CC Switch handles:
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 the three role routes: claude-sonnet-*, claude-opus-*, and claude-haiku-*. Real upstream model names are not written directly into the Claude Desktop profile.
| 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 |
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 models outside the Sonnet / Opus / Haiku role families, so CC Switch local routing performs a model mapping pass.
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, filling in just one role's requested model is enough; blank roles automatically inherit the first filled model (Sonnet first), so the Haiku that sub-agents call is always available. Model mapping mode requires at least one requested model.
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
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.
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.
To return to Claude Desktop official sign-in:
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.
CC Switch writes Claude Desktop 3P configuration files.
~/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
%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.
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 model names outside the Sonnet / Opus / Haiku role families | 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 |
Fully quit and restart Claude Desktop. Claude Desktop usually reads the 3P profile on startup and does not hot-reload it after changes.
Check:
Edit the provider, fill in Menu display name in model mapping, then enable the provider again and restart Claude Desktop.
Direct mode requires the provider to expose native Anthropic Messages API and accept Claude Desktop's three role IDs (claude-sonnet-* / claude-opus-* / claude-haiku-*). If the provider uses OpenAI, Gemini, non-Claude model IDs, or legacy Claude IDs (e.g. claude-3-5-sonnet-…)—any ID outside the three roles—direct mode fails, so enable Needs model mapping.
It depends on the mode:
Not in model mapping mode. The Claude Desktop profile only stores safe Sonnet / Opus / Haiku role 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.