# 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 models outside the three role IDs: legacy Claude IDs (e.g. `claude-3-5-sonnet`) and non-Claude models like DeepSeek / Kimi / DouBao / OpenAI / Gemini all need it
- Reuse Copilot / Codex OAuth / xAI 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
- Providers whose model names are the three role IDs (`claude-sonnet-*` / `claude-opus-*` / `claude-haiku-*`) and can connect directly are imported as direct mode
- Providers whose model names are not the three role IDs (including legacy Claude IDs), or that need format 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. 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.

![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 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:

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 are Claude Desktop-recognized role names: `claude-sonnet-*`, `claude-opus-*`, or `claude-haiku-*` (or the same with the `anthropic/claude-` prefix)
- 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. 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

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:

```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 the three role routes: `claude-sonnet-*`, `claude-opus-*`, and `claude-haiku-*`. 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 models outside the Sonnet / Opus / Haiku role families, 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, 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.

## 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 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 |

## 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 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**.

### 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 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.

## 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)
