CC Switch Claude Desktop 面板实战：用直连与模型映射两种模式把第三方模型接入 Claude Desktop

2026-09-06 17:06:37作者：翟萌耘Ralph

A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io

项目地址：https://gitcode.com/GitHub_Trending/cc/cc-switch

CC Switch 的 Claude Desktop 面板负责管理 Claude Desktop 应用的供应商配置，核心是「直连模式」与「模型映射模式」两条链路：前者把 3P profile 直接指向原生 Anthropic Messages API 供应商，后者经由 CC Switch 本地网关（http://127.0.0.1:15721/claude-desktop）完成模型角色到真实上游模型的映射与 API 格式转换。读完本文，你将掌握供应商导入/添加的完整操作、两种模式的适用边界与配置差异、本地路由开关的启用方式，并能对照 CC Switch 源码理解 3P profile 的写入、校验与回滚机制。

功能定位：Claude Desktop 与 Claude Code 是两条独立入口

Claude Desktop 面板用于在 CC Switch 中管理 Claude Desktop 的供应商配置。开启后你可以：

在 Claude Desktop 中使用第三方 Anthropic 兼容供应商；
为三档角色 ID 之外的模型配置映射——旧式 Claude ID（如 claude-3-5-sonnet）以及 DeepSeek / Kimi / DouBao / OpenAI / Gemini 等非 Claude 模型都需要走映射；
复用 Copilot / Codex OAuth / xAI OAuth 账号类供应商；
在 Claude Desktop 官方模式和第三方供应商之间切换。

需要特别注意：Claude Desktop 与 Claude Code 是两个不同的应用入口。Claude Code 使用 ~/.claude/settings.json，Claude Desktop 使用自己的 3P（third-party）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_config.rs 中的 is_supported_platform() 通过 cfg!(any(target_os = "macos", windows)) 判断平台，非 mac/Windows 平台会返回明确的「第一阶段仅支持 macOS 和 Windows」错误（见 unsupported_platform_error）。

快速上手

第一步：切换到 Claude Desktop 面板

在左侧应用切换器中选择 Claude Desktop。

如果没有看到该入口，请到 设置 → 通用 → 应用可见性，确认 Claude Desktop 没有被隐藏。

第二步：导入或添加供应商

优先使用：从 Claude Code 一键导入

很多用户最开始是在 Claude Code 里配置供应商，然后才想把同一批供应商带到 Claude Desktop。第一次启动 CC Switch，或第一次进入 Claude Desktop 面板时，如果这里还没有供应商，可以直接点击 将 Claude Code 中已有的供应商导入。

如果你已经在 Claude Code 那边配置了很多供应商，这个功能可以一键把它们导入到 Claude Desktop 面板，省掉逐个重新填写接口地址、API Key 和默认模型的工作。

导入规则：

已存在同 ID 供应商时不会覆盖；
模型名为三档角色 ID（claude-sonnet-* / claude-opus-* / claude-haiku-*）且能直连的供应商会导入为直连模式；
模型名非三档角色 ID（含旧式 Claude ID）或需要格式转换的供应商会尝试导入为模型映射模式；
ANTHROPIC_DEFAULT_SONNET_MODEL、ANTHROPIC_DEFAULT_OPUS_MODEL、ANTHROPIC_DEFAULT_HAIKU_MODEL 会转换为 Desktop 的 Sonnet / Opus / Haiku 映射；
旧的 [1M] 后缀会转换为 Claude Desktop profile 中的 supports1m 标记；
无法判断模型映射的供应商会被跳过。

导入后请检查每个供应商的模型映射是否符合你的实际上游模型。任何不是 claude-sonnet-* / claude-opus-* / claude-haiku-* 三档角色 ID 的模型——包括 Kimi、DeepSeek、GLM、DouBao 等非 Claude 模型，以及旧式 Claude ID——通常都需要使用模型映射模式。

这条决策链在 import_claude_desktop_providers_from_claude 中可以直接对应：先跳过 Desktop 表中已存在的同 ID 供应商，再用 is_compatible_direct_provider 与「模型名是否安全」两个条件判定直连模式，否则尝试生成建议的模型路由（suggested_claude_desktop_routes）落为 Proxy 模式，都失败则跳过该供应商。此外该命令在导入结束后还会补回 claude-desktop-official 种子供应商，保证官方入口始终存在。

如果没有可导入的配置，或想单独给 Claude Desktop 添加一个供应商，再点击右上角 + 按钮添加供应商：

你可以选择：

预设供应商：从内置 Claude Desktop 预设中选择，只填写 API Key；
自定义供应商：手动填写名称、接口地址、API Key 和模型设置；
Claude Desktop Official：恢复 Claude Desktop 官方登录模式。

预设清单定义在 claudeDesktopProviderPresets.ts 中，每个预设包含 baseUrl、mode（direct / proxy）、apiFormat（anthropic / openai_chat / openai_responses / gemini_native）以及可选的 modelRoutes。例如 DeepSeek、Kimi、Gemini Native 等预设默认就是 mode: "proxy" 并预置了 brandedRoutes（上游品牌名写入 labelOverride 与 upstreamModel）；而 PackyCode、ZetaAPI 等原生 Claude 兼容网关则是 mode: "direct"。

对于已经接受 Claude Desktop 三档角色 ID（claude-sonnet-* / claude-opus-* / claude-haiku-*）的原生 Anthropic Messages API 供应商，通常只需要：

选择预设或自定义供应商；
填写 API Key；
确认 接口地址；
保持「需要模型映射」关闭；
点击「添加」。

第三步：切换并重启 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 指向供应商接口：

{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://api.example.com",
  "inferenceGatewayAuthScheme": "bearer",
  "inferenceGatewayApiKey": "你的 API Key"
}

从源码看，build_gateway_profile 生成的 profile 除了上述字段，还固定包含 disableDeploymentModeChooser: true 与 coworkEgressAllowedHosts: ["*"]；同时在 apply_provider_to_paths_inner 中，两份 claude_desktop_config.json（1P 与 3P 目录）的 deploymentMode 都会被写为 "3p"，configLibrary/_meta.json 中登记 profile 条目并把 appliedId 指向 CC Switch 的固定 profile ID。

直连模式还有一条硬性凭据要求：从 direct_gateway_credentials 可见，它只从供应商 env 中读取 ANTHROPIC_BASE_URL 与 ANTHROPIC_AUTH_TOKEN（Bearer Token），缺少任一字段即校验失败。这也解释了为什么直连模式只支持 Bearer 认证的 Anthropic Messages 端点。

适用场景：

供应商暴露原生 Anthropic Messages API；
模型 ID 为 Claude Desktop 可识别的角色名：claude-sonnet-*、claude-opus-*、claude-haiku-*（或带 anthropic/claude- 前缀的同类名）；
不需要格式转换；
不需要 CC Switch 在使用期间保持本地路由。

直连模式的「手动指定 Claude Desktop 模型列表」是高级选项。多数原生 Claude 模型供应商不需要填写，Claude Desktop 会自动读取 /v1/models。

仅当供应商的 /v1/models 不可用，或返回的模型名不能被 Claude Desktop 识别时，再手动添加模型。手动填写的模型名必须是 claude-sonnet-*、claude-opus-* 或 claude-haiku-* 形态（旧式 claude-3-5-sonnet-… 会被拒绝）。这个判定由 is_claude_safe_model_id 实现：模型名必须带 claude- 或 anthropic/claude- 前缀，其后必须紧跟 sonnet- / opus- / haiku- 角色前缀且还有实际模型标识；[1m] 后缀、claude-3-5-sonnet-20241022 这类旧式 ID、以及 claude-sonnet- 这种退化值都会被拒绝（对应单测 claude_desktop_rejects_1m_suffix_as_model_id）。另外直连模式不允许把角色 ID 映射到不同的上游模型——direct_inference_model_specs 会直接报错「非 Claude 官方模型请使用本地路由模式」。

模型映射模式

模型映射模式适合供应商提供的模型不是 claude-sonnet-* / claude-opus-* / claude-haiku-* 三档角色 ID（包括旧式 Claude ID 和 deepseek、kimi 等非 Claude 模型），或接口格式需要 CC Switch 转换。

开启「需要模型映射」后，Claude Desktop 会连接到 CC Switch 本地网关：

http://127.0.0.1:15721/claude-desktop

网关地址不是硬编码常量：proxy_gateway_base_url_from_db 读取当前代理配置的监听地址与端口再拼接 /claude-desktop 前缀；若监听端口为 0（尚未解析的临时端口）会直接报错，避免写出 :0 这样的非法 URL（有对应单测覆盖）。测试中的默认值即 http://127.0.0.1:15721/claude-desktop。

CC Switch 会负责：

向 Claude Desktop 暴露安全的 Claude 模型路由；
把 Desktop 选择的模型角色映射到真实上游模型；
按供应商要求转换 Anthropic / OpenAI / Gemini 请求格式；
用 CC Switch 中保存的供应商凭据访问上游。

支持的 API 格式（与 validate_proxy_provider 中的白名单一致）：

格式	用途
Anthropic Messages	原生或兼容 Anthropic 请求
OpenAI Chat Completions	OpenAI 兼容 `/chat/completions`
OpenAI Responses API	OpenAI Responses 兼容接口
Gemini Native generateContent	Gemini 原生接口

模型映射模式下，Claude Desktop 只看到 claude-sonnet-* / claude-opus-* / claude-haiku-* 三类角色路由；真实模型名不会直接写进 Claude Desktop profile。这一点有单测直接验证：profile 内容断言了 inferenceModels 为 [{"name": "claude-sonnet-4-6", "labelOverride": "Kimi K2", "supports1m": true}]，同时整个 profile 字符串中不包含 kimi-k2（见 claude_desktop_proxy_apply_writes_local_gateway_profile_with_safe_models）。profile 中的 API Key 也不是你的上游 Key，而是 CC Switch 生成的本地网关 token——get_or_create_gateway_token 以 ccs- 为前缀生成 UUID token 并持久化在本地设置中，请求经本地网关时才使用真正的供应商凭据访问上游。

请求侧的映射逻辑在 map_proxy_request_model，按优先级依次为：精确匹配已配置 route ID → Opus 版本别名互认 → 遗留原始路由表 → 角色关键词回落。角色回落解决的是这类问题：Claude Desktop 的子 agent 会请求带发布日期后缀的完整官方名（如 claude-haiku-4-5-20251001），与 profile 暴露的简短 route ID（claude-haiku-4-5）不精确相等，此时按 opus/haiku/fable/sonnet 关键词归入同档已配置路由（单测 claude_desktop_proxy_maps_dated_role_alias_via_keyword 验证了 claude-haiku-4-5-20251001 → deepseek-v4-flash）。匹配前还会先剥离 [1m] 本地标记；不含任何角色关键词的模型名（如 gpt-5）仍会精确报错，不会被误映射。

配置模型映射

字段说明

字段	说明
模型角色	Claude Desktop 可识别的 Sonnet / Opus / Haiku 路由
菜单显示名	在 Claude Desktop 模型菜单里显示的名称
实际请求模型	发送给上游供应商的真实模型 ID
1M	向 Claude Desktop 声明该模型支持 1M 上下文

这四个字段与后端结构一一对应：provider meta 中的 claude_desktop_model_routes 以 route ID 为键，值为 ClaudeDesktopModelRoute，包含 model（实际请求模型）、label_override（菜单显示名）与 supports_1m。写入 profile 时，只有当 supports_1m 为 true 或存在 label_override 时，模型条目才展开为对象（携带 labelOverride / supports1m 字段），否则退化为纯字符串（见 inference_model_json）。

本地路由暴露给 Desktop 的默认角色目录定义在 DEFAULT_PROXY_ROUTES：Sonnet（claude-sonnet-5）、Opus（claude-opus-5）、Haiku（claude-haiku-4-5）与 Fable（claude-fable-5），并各自对应 Claude Code env 中的 ANTHROPIC_DEFAULT_*_MODEL 键名。

模型角色	菜单显示名	实际请求模型	1M
Sonnet	Kimi K2	`kimi-k2`	按供应商能力选择

模型角色	菜单显示名	实际请求模型	1M
Sonnet	DeepSeek V4 Pro	`deepseek-v4-pro`	按供应商能力选择

多角色映射

你可以同时配置 Sonnet、Opus、Haiku 三个角色：

模型角色	建议用途
Sonnet	默认主力模型
Opus	高质量或复杂任务模型
Haiku	快速、低成本模型

如果供应商只有一个模型，只填写一个角色的实际请求模型也可以；留空的角色会自动沿用第一个已填模型（Sonnet 优先），因此 Haiku 等子 agent 调用始终有模型可用。模型映射模式至少需要填写一个实际请求模型——这一点由 validate_proxy_provider 中的「至少需要一个模型路由映射」错误保证：Proxy 模式下 claude_desktop_model_routes 缺失或全部为空都会阻止写入。

本地路由开关

模型映射模式需要 CC Switch 本地路由参与请求转换。本地路由是一个强大，同时有一定复杂度的功能，为了避免不需要路由功能的用户误触，主页面的本地路由开关默认隐藏，需要路由功能时，请手动把它显示出来。

打开方式：

设置 → 路由 → 本地路由 → 开启「在主页面显示本地路由开关」

打开显示开关后，回到 Claude Desktop 面板，主界面右上角会看到 Claude Desktop 本地路由开关。

状态说明：

状态	说明
开启	本地网关正在运行，地址通常是 `127.0.0.1:15721`
关闭	直连供应商仍可使用；模型映射供应商无法正常工作
正在加载	路由服务正在启动或停止

只有「需要模型映射」的供应商必须依赖本地路由。直连供应商不需要打开这个开关。

如果其它应用正在使用代理接管，关闭本地路由可能会被阻止。请先到设置中的路由服务区域关闭对应应用接管，再停止本地路由。

面板顶部的健康状态由 get_status 汇总：它检查 profile 是否存在（configured）、appliedId 归属、profile 中 inferenceGatewayBaseUrl 与当前供应商期望地址是否一致（expected_base_url vs actual_base_url）、inferenceModels 中是否存在非安全模型名（stale_raw_models）、Proxy 模式但路由缺失（missing_route_mappings），以及本地网关 token 是否已生成（gateway_token_configured）。前端展示的「配置需要检查」提示即来自这些字段。

恢复官方 Claude Desktop

如果你想回到 Claude Desktop 官方登录：

选择 Claude Desktop Official；
点击「启用」；
重启 Claude Desktop。

CC Switch 会恢复 Claude Desktop 的官方 1P 模式，并移除 CC Switch 管理的 3P profile。

官方模式不需要 API Key，也不需要本地路由。

从 Claude Code 导入供应商的时候，会自动添加一个 Claude Desktop Official。

对应实现是 restore_official_at_paths_inner：把两份 claude_desktop_config.json 的 deploymentMode 改回 "1p"、删除 3p 配置中的 enterpriseConfig 网关字段、删除 CC Switch 的 profile 文件，并清理 _meta.json 中对应的条目与 appliedId。该行为有专门单测覆盖（claude_desktop_restore_switches_to_1p_and_removes_cc_switch_profile）。

配置文件位置

CC Switch 会写入 Claude Desktop 的 3P 配置目录。

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

这些路径由 current_platform_paths 解析：macOS 直接使用 ~/Library/Application Support 下的 Claude 与 Claude-3p 目录；Windows 从 %LOCALAPPDATA% 出发，且 pick_windows_claude_dir 会在目录不存在精确名称时，按「以 Claude 开头且包含/不包含 -3p」的规则在候选目录中挑选（按名称排序取第一个），以兼容不同版本的目录命名。profile 文件名中的 00000000-0000-4000-8000-000000157210 就是 PROFILE_ID，profile 显示名为「CC Switch」（PROFILE_NAME）。

配置文件由 CC Switch 自动维护，不建议手动编辑。出现配置不一致时，重新启用当前供应商通常可以修复。值得一提的是，写入本身带有完整性保障：with_rollback 在每次 apply 前先对四个文件做内容快照，任一步写入失败即回滚到快照，测试 claude_desktop_apply_rolls_back_when_profile_write_fails 验证了失败后配置保持原样。

状态提示与处理

Claude Desktop 面板顶部可能出现「Claude Desktop 配置需要检查」提示。

提示	处理方式
当前平台暂不支持	目前仅 macOS / Windows 支持写入 3P 配置
profile 中存在非 Sonnet / Opus / Haiku 角色模型名	重新切换当前供应商，或编辑供应商改用模型映射
启用了模型映射但没有有效路由	编辑供应商，至少添加一条模型映射
本地路由 token 尚未生成	重新切换该供应商，CC Switch 会写入新的本地 token
profile 指向的地址与当前供应商不一致	重新切换当前供应商，让 profile 回到正确地址

这些提示与 get_status 返回的字段一一对应：平台不支持对应 supported: false，非安全模型名对应 stale_raw_models，路由缺失对应 missing_route_mappings，token 缺失对应 gateway_token_configured: false，地址不一致对应 expected_base_url 与 actual_base_url 的比较结果。「重新切换当前供应商」之所以能修复，是因为 apply 流程是幂等重写：profile、_meta.json 的 appliedId 与 deploymentMode 都会按当前供应商状态重建。

常见问题

切换成功但 Claude Desktop 没变化？

请完全退出并重启 Claude Desktop。Claude Desktop 读取 3P profile 的时机通常在启动阶段，切换后不会自动热更新。

模型映射供应商请求失败？

检查：

CC Switch 是否仍在运行；
Claude Desktop 本地路由是否已开启；
供应商 API Key 和接口地址是否正确；
模型映射中是否填写了实际请求模型；
切换供应商后是否重启了 Claude Desktop。

Claude Desktop 模型菜单里看不到我的品牌模型名？

编辑供应商，在模型映射中填写「菜单显示名」（即 label_override），然后重新启用供应商并重启 Claude Desktop。显示名随 profile 中的 labelOverride 字段下发，重新启用即触发 profile 重写。

直连模式下为什么报错？

直连模式要求供应商提供原生 Anthropic Messages API，并接受 Claude Desktop 的三档角色 ID（claude-sonnet-* / claude-opus-* / claude-haiku-*）。如果供应商使用 OpenAI、Gemini、非 Claude 模型 ID，或旧式 Claude ID（如 claude-3-5-sonnet-…）等任何非三档角色 ID，直连都会失败，请开启「需要模型映射」。从校验逻辑看（validate_direct_provider），直连模式同样拒绝 openai_chat 等非常规 api_format、Copilot/Codex OAuth/xAI OAuth 账号类供应商（is_compatible_direct_provider 中显式拦截这三类 provider_type）以及完整 URL 端点配置。