Configuring Claude Desktop in CC Switch

I’ve previously covered the basics of CC Switch. Today, let’s take a closer look at the Claude Desktop panel — added in recent versions specifically for connecting the official Claude Desktop client to third-party providers.

In CC Switch, “Claude” and “Claude Desktop” are two separate panels. They map to Claude Code (the CLI) and Claude Desktop (the desktop client), respectively. Claude Desktop uses its own 3P profile config rather than ~/.claude/settings.json. The two panels are distinguished by a small badge on the icon.

What it does

The Claude Desktop panel keeps things straightforward:

• Connect Claude Desktop to Anthropic-compatible third-party providers
• Set up model mappings for non-Claude models like DeepSeek, Kimi, DouBao, OpenAI, and Gemini
• Reuse Copilot / Codex OAuth-based providers
• Switch between Claude Desktop’s official mode and third-party providers with a single click

macOS and Windows are supported. Linux can’t yet write Claude Desktop 3P configs. You’ll need to restart Claude Desktop after switching — it doesn’t hot-reload the way Claude Code does.

One thing to note: Claude Desktop’s 3P profile does not go through CC Switch’s MCP / Skills sync — those are managed independently on the desktop side.

Getting started

1. Switch to the Claude Desktop panel

Select Claude Desktop from the app switcher on the left.

If you don’t see it, check Settings → General → App Visibility to make sure it isn’t hidden.

2. Import or add a provider

One-click import from Claude Code (recommended)

Most users start by configuring providers in Claude Code, then want to bring the same set over to Claude Desktop. If the panel is empty the first time you open it, just click Import existing providers from Claude Code.

This pulls your Claude Code providers straight into the Claude Desktop panel — no need to re-enter endpoint URLs, API keys, or default models. The import logic works roughly like this:

• Providers with an existing matching ID are skipped
• Providers with direct-connectable, model-name-safe configs are imported in direct mode
• Providers that need model translation are imported in model-mapping mode
• ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL are automatically converted to Desktop’s Sonnet / Opus / Haiku mappings
• Legacy [1M] suffixes become supports1m flags in the Desktop profile
• Providers whose model mappings can’t be determined are skipped

After importing, check each provider’s model mapping against your actual upstream models. Non-Claude models like Kimi, DeepSeek, GLM, and DouBao typically need model-mapping mode.

Add manually

If there’s nothing to import, or you want a different provider just for Claude Desktop, click the + button in the top-right corner.

Three options:

• Preset provider: Pick from built-in presets, only fill in your API key
• Custom provider: Manually enter the name, endpoint, API key, and model settings
• Claude Desktop Official: Revert to Claude Desktop’s official login mode

For standard Anthropic Messages API-compatible providers, the flow is simple: choose a preset or custom → enter API key → confirm the endpoint → turn off “Requires model mapping” → add.

3. Switch and restart Claude Desktop

Click Enable on the provider card, then fully quit and restart Claude Desktop.

Claude Desktop doesn’t hot-reload. Closing the chat window isn’t enough — exit from the tray or make sure the process is completely stopped.

Two working modes

Direct mode

Use this when your provider offers a native Anthropic Messages API. CC Switch points Claude Desktop’s 3P profile directly to the provider’s endpoint:

{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://api.example.com",
  "inferenceGatewayAuthScheme": "bearer",
  "inferenceGatewayApiKey": "your API key"
}

Requirements: the provider exposes a native Anthropic Messages API, uses claude-* or anthropic/claude-* model IDs, and doesn’t need format translation. In direct mode, you don’t need to keep CC Switch’s local routing running.

“Manually specify Claude Desktop model list” is an advanced option. Most native Claude providers don’t need it — Claude Desktop reads /v1/models automatically. Only fill it in if the provider’s /v1/models is unavailable or returns model names Claude Desktop doesn’t recognize.

Model-mapping mode

Use this when your provider doesn’t offer Claude-series models (deepseek, kimi, etc.) or its API format needs translation by CC Switch.

With “Requires model mapping” enabled, Claude Desktop connects to CC Switch’s local gateway:

http://127.0.0.1:15721/claude-desktop

CC Switch acts as middleware: it exposes safe claude-* model routes to Claude Desktop, maps the selected model role to the actual upstream model, translates between Anthropic / OpenAI / Gemini formats as needed, and authenticates using the credentials stored in CC Switch.

Supported formats:

In model-mapping mode, Claude Desktop only sees claude-* routing model names. The real upstream model names stay inside CC Switch’s provider config and never appear in the Claude Desktop profile.

Configuring model mappings

The key idea: Claude Desktop now rejects non-claude-* model names, so you need CC Switch to do a round of role mapping.

For example, using Kimi in Claude Desktop:

Using DeepSeek:

Suggested roles:

If your provider only has one model, just configuring Sonnet is enough. Model-mapping mode requires at least one valid mapping.

Local routing

Model-mapping mode depends on CC Switch’s local routing for request translation. The toggle is hidden by default — you’ll need to enable it manually.

Go to Settings → Routing → Local Routing, and turn on Show local routing toggle on main page.

Back in the Claude Desktop panel, you’ll see the local routing toggle in the top-right corner.

Status meanings:

Only providers with “Requires model mapping” enabled need local routing. Direct providers don’t.

If another app is using proxy takeover, turning off local routing may be blocked. Go to the routing service area in Settings, disable the takeover for that app, then stop local routing.

Reverting to official Claude Desktop

To switch back to official login:

1. Select Claude Desktop Official
2. Click Enable
3. Restart Claude Desktop

CC Switch restores Claude Desktop’s official 1P mode and cleans up the 3P profile. Official mode needs no API key or local routing.

When importing from Claude Code, a Claude Desktop Official entry is automatically added so you can switch back anytime.

Config file locations

CC Switch writes to Claude Desktop’s 3P config directories:

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

Config files are maintained by CC Switch — editing them manually isn’t recommended. If things get out of sync, re-enabling the current provider usually fixes it.

FAQ

I switched but Claude Desktop hasn’t changed?

Fully quit and restart Claude Desktop. It only reads the 3P profile on startup — no hot reload.

Requests fail with a model-mapping provider?

Checklist: Is CC Switch running → Is Claude Desktop local routing on → Are the API key and endpoint correct → Did you fill in the actual request model in the mapping → Did you restart Claude Desktop after switching.

Why am I getting errors in direct mode?

Direct mode requires the provider to offer a native Anthropic Messages API and accept the model names Claude Desktop uses. If your provider uses OpenAI, Gemini, or non-Claude model IDs, turn on “Requires model mapping.”

My custom brand name doesn’t show in the model picker?

Edit the provider, fill in the “Menu display name” in the model mapping, then re-enable the provider and restart Claude Desktop.

Can I close CC Switch?

In direct mode, yes — once Claude Desktop loads the config after restart, you don’t need local routing running. In model-mapping mode, no — CC Switch must stay running with the local routing toggle on.

Will my real upstream model names be written to Claude Desktop?

Not in model-mapping mode. The Claude Desktop profile only contains safe claude-* routes and display names. The actual upstream model names stay in CC Switch’s provider config, and the mapping happens at the local gateway.

Summary

The Claude Desktop panel in CC Switch essentially brings the provider management that was previously CLI-only to the desktop side. If you’ve already set up a bunch of providers in CC Switch, the one-click import from Claude Code is the fastest path.

Direct mode is hassle-free; model-mapping mode is flexible. If you mainly use Claude-series models, direct mode is all you need. If you want to use Kimi, DeepSeek, or other non-Claude models inside Claude Desktop, model-mapping mode with local routing gets it done.