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.

In the world of AI programming tools, Claude Code is undoubtedly one of the most powerful choices today. However, with major cloud service providers launching their own LLM APIs, how to conveniently switch between different providers has become a practical need. Today, I’ll introduce two tools: cc switch and cc desktop switch, which help you quickly switch Claude Code model providers.

Project Links:

• cc switch: farion1231/cc-switch (54.9k ⭐)
• cc desktop switch: lonr-6/cc-desktop-switch

What is cc switch

cc switch is a cross-platform desktop application specifically designed for managing provider configurations for five major AI programming CLI tools: Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw.

Core Features

1. Unified Management: One app manages provider configurations for five CLI tools simultaneously
2. 50+ Provider Presets: Built-in presets for AWS Bedrock, NVIDIA NIM, and numerous community relay services - copy your API key and import with one click
3. One-click Switching: Switch providers from main interface or system tray
4. Unified MCP & Skills Management: One panel to manage MCP servers and Skills across four apps with bidirectional sync
5. Proxy & Failover: Local proxy supports format conversion, auto-failover, circuit breaker, provider health monitoring
6. Usage & Cost Tracking: Dashboard shows spending, requests, and token trend charts
7. Session Manager: Browse, search, and restore conversation history across all apps
8. Cloud Sync: Sync configurations via Dropbox, OneDrive, iCloud, NAS, or WebDAV servers
9. Cross-Platform: Native desktop app for Windows, macOS, and Linux, built with Tauri 2

Supported Apps

• Claude Code: Anthropic’s AI programming assistant
• Codex: OpenAI’s programming CLI tool
• Gemini CLI: Google’s AI CLI tool
• OpenCode: Open-source AI programming tool
• OpenClaw: Emerging AI programming tool

Installing cc switch

macOS Users

# Install via Homebrew (Recommended)
brew tap farion1231/ccswitch
brew install --cask cc-switch

# Update
brew upgrade --cask cc-switch

Or download CC-Switch-v{version}-macOS.dmg from the Releases page.

Windows Users

Download from Releases:

• CC-Switch-v{version}-Windows.msi installer
• CC-Switch-v{version}-Windows-Portable.zip portable version

Linux Users

# Arch Linux
paru -S cc-switch-bin

# Or download deb/rpm/AppImage from Releases

What is cc desktop switch

cc desktop switch is a lightweight configuration tool specifically for the Claude Desktop official desktop client. Unlike cc switch which targets CLI users, cc desktop switch focuses on the desktop version of Claude Desktop.

Core Features

1. Multiple API Providers: DeepSeek, Kimi, Zhipu GLM, Alibaba Cloud Bailian, SiliconFlow, and more
2. One-click Config Write: Write selected provider config directly to Claude Desktop’s local configuration
3. Direct Connection Mode: Anthropic-compatible interfaces use direct connection by default; Claude Desktop can continue working after closing the app
4. Experimental Compatibility Mode: Retains local forwarding support for OpenAI/new-api/reverse-proxy interfaces
5. Basic Connectivity Testing: Tests basic connectivity to provider API addresses
6. Bilingual Interface: Supports Chinese/English interface and light/dark mode

Basic Usage

cc switch Usage

1. Add Provider: Click “Add Provider” → Choose a preset or create custom configuration
2. Switch Provider:
   • Main UI: Select provider → Click “Enable”
   • System Tray: Click provider name directly (instant effect)
3. Takes Effect: Restart your terminal or the corresponding CLI tool (Claude Code does not require restart)
4. Back to Official: Add “Official Login” preset, restart CLI tool, then follow its login/OAuth flow

cc desktop switch Usage

1. Launch CC Desktop Switch
2. Operate in the popup desktop window
3. Select a quick preset, fill in your API key, adjust model mapping if needed
4. Click “Apply to Claude Desktop”
5. Fully restart Claude Desktop to test

Note: Simply closing the chat window is usually not enough. Please exit Claude from the system tray, or confirm no Claude processes remain in the task manager.

Practical Usage Experience

I’ve been using cc switch for a while, and the overall experience is quite good. Here are my thoughts:

Advantages

1. Convenient switching: More intuitive than manually editing config files
2. Multi-app support: Supports Claude Code, Codex, Gemini CLI, and more simultaneously
3. Cost monitoring: Clearly shows usage of each provider
4. Tray operation: Minimizes to tray without consuming too many resources
5. Rich presets: Built-in 50+ provider presets, no manual configuration needed

Conclusion

cc switch and cc desktop switch provide convenient provider management solutions for Claude Code users. Their focus is slightly different:

• cc switch: For CLI users, unified management of Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw
• cc desktop switch: For Claude Desktop desktop client users, more lightweight, focused on desktop client

Whether you need to test different model effects or find the most cost-effective provider, these tools can meet your needs. If you’re using Claude Code, give these tools a try - I’m sure they’ll give you a great experience.

If you’re interested in AI programming tools, you can also check out my previous articles: Neovim Beginner’s Guide Series, which contains a lot of content about editor configuration and AI integration.