2.6 Claude Desktop¶
功能说明¶
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 profile 配置;在 CC Switch 中也分别显示为「Claude」和「Claude Desktop」,侧栏里的 Claude Desktop 图标右下角会有一个小图标用来区分。
支持范围¶
| 项目 | 说明 |
|---|---|
| 支持系统 | macOS、Windows、Linux |
| Flatpak 说明 | Flatpak 版 CC Switch 固定使用宿主 ~/.config,不跟随自定义 XDG_CONFIG_HOME |
| 生效方式 | 切换供应商后需要重启 Claude Desktop |
| 官方模式 | 使用 Claude Desktop 内置登录,不需要 API Key 和接口地址 |
| 第三方模式 | 写入 CC Switch 管理的 3P profile |
| MCP / Skills | Claude Desktop 3P profile 不走 CC Switch 的 MCP / Skills 同步 |
快速上手¶
第一步:打开 Claude Desktop 页¶
在左侧栏的应用列表中选择 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——通常都需要使用模型映射模式。
如果你已经在 Claude Code 中配置过供应商,优先使用上面的 将 Claude Code 中已有的供应商导入。这是迁移到 Claude Desktop 最省事的路径。
如果没有可导入的配置,或想单独给 Claude Desktop 添加一个供应商,再点击页面右上角的「添加供应商」按钮。
你可以选择:
- 预设供应商:从内置 Claude Desktop 预设中选择,只填写 API Key
- 自定义供应商:手动填写名称、接口地址、API Key 和模型设置
- Claude Desktop Official:恢复 Claude Desktop 官方登录模式
对于已经接受 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 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"
}
适用场景:
- 供应商暴露原生 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-… 会被拒绝)。
模型映射¶
模型映射适合供应商提供的模型不是 claude-sonnet-* / claude-opus-* / claude-haiku-* 三档角色 ID(包括旧式 Claude ID 和 deepseek、kimi 等非 Claude 模型),或接口格式需要 CC Switch 转换。
开启「需要模型映射」后,Claude Desktop 会连接到 CC Switch 本地网关:
CC Switch 会负责:
- 向 Claude Desktop 暴露安全的 Claude 模型路由
- 把 Desktop 选择的模型角色映射到真实上游模型
- 按供应商要求转换 Anthropic / OpenAI / Gemini 请求格式
- 用 CC Switch 中保存的供应商凭据访问上游
支持的 API 格式:
| 格式 | 用途 |
|---|---|
| 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。
配置模型映射¶
字段说明¶
| 字段 | 说明 |
|---|---|
| 模型角色 | Claude Desktop 可识别的 Sonnet / Opus / Haiku 路由 |
| 菜单显示名 | 在 Claude Desktop 模型菜单里显示的名称 |
| 实际请求模型 | 发送给上游供应商的真实模型 ID |
| 1M | 向 Claude Desktop 声明该模型支持 1M 上下文 |
推荐写法¶
如果你想在 Claude Desktop 中使用 Kimi:
| 模型角色 | 菜单显示名 | 实际请求模型 | 1M |
|---|---|---|---|
| Sonnet | Kimi K2 | kimi-k2 |
按供应商能力选择 |
如果你想使用 DeepSeek:
| 模型角色 | 菜单显示名 | 实际请求模型 | 1M |
|---|---|---|---|
| Sonnet | DeepSeek V4 Pro | deepseek-v4-pro |
按供应商能力选择 |
这样做的原因是 Claude Desktop 现在会拒绝不属于 Sonnet / Opus / Haiku 三类角色的模型,所以需要 CC Switch 的路由功能进行一轮模型映射。
多角色映射¶
你可以同时配置 Sonnet、Opus、Haiku 三个角色:
| 模型角色 | 建议用途 |
|---|---|
| Sonnet | 默认主力模型 |
| Opus | 高质量或复杂任务模型 |
| Haiku | 快速、低成本模型 |
如果供应商只有一个模型,只填写一个角色的实际请求模型也可以;留空的角色会自动沿用第一个已填模型(Sonnet 优先),因此 Haiku 等子 agent 调用始终有模型可用。模型映射模式至少需要填写一个实际请求模型。
路由服务¶
模型映射需要 CC Switch 的路由服务转发请求,服务默认监听 127.0.0.1:15721。不需要手动开关:当前供应商是模型映射时,路由服务会自动启动并保持运行;当前供应商是直连时,页面顶部显示「路由服务:当前供应商不需要」。
接入条上的状态:
| 状态 | 说明 |
|---|---|
| 路由服务 运行中 | 本地网关正在运行 |
| 路由服务没能启动 | 点「重试」;端口被占用时点「更改端口」,会跳到「设置 → 本地路由」修改 |
| 路由服务:当前供应商不需要 | 当前供应商是直连,或官方模式 |
如果其它应用正在使用路由或聚合,路由服务无法停止。先到「设置 → 本地路由」,用「全部回到直连」让这些应用回到直连,再停止服务。
恢复官方 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
配置文件位置¶
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
Linux¶
原生安装的 Claude Desktop 使用 $XDG_CONFIG_HOME;未设置时使用 ~/.config:
~/.config/Claude/claude_desktop_config.json
~/.config/Claude-3p/claude_desktop_config.json
~/.config/Claude-3p/configLibrary/_meta.json
~/.config/Claude-3p/configLibrary/00000000-0000-4000-8000-000000157210.json
当 CC Switch 本身通过 Flatpak 安装时,会刻意使用上面的宿主机 ~/.config 路径,不会误用 Flatpak 私有的 XDG_CONFIG_HOME。这是有意的设计边界:CC Switch 不提供配置目录覆盖项,也不会尝试跟随宿主机自定义的 XDG_CONFIG_HOME,因为 Flatpak 会在沙箱内替换该变量,无法可靠地获知其原始值。如果 Claude Desktop 使用自定义 XDG 配置目录,请使用原生 CC Switch 软件包。随附的 Flatpak 当前已授予整个 Home 目录访问权;更严格的自定义 Flatpak 构建必须对 xdg-config/Claude 和 xdg-config/Claude-3p 授予读写权限。
配置文件由 CC Switch 自动维护,不建议手动编辑。出现配置不一致时,重新切换当前供应商通常可以修复。
状态提示与处理¶
Claude Desktop 页顶部可能出现「Claude Desktop 配置需要检查」提示。
| 提示 | 处理方式 |
|---|---|
| 当前平台暂不支持 | 请在 macOS、Windows 或 Linux 上使用 CC Switch |
| profile 中存在非 Sonnet / Opus / Haiku 角色模型名 | 重新切换当前供应商,或编辑供应商改用模型映射 |
| 启用了模型映射但没有有效路由 | 编辑供应商,至少添加一条模型映射 |
| 本地路由 token 尚未生成 | 重新切换该供应商,CC Switch 会写入新的本地 token |
| profile 指向的地址与当前供应商不一致 | 重新切换当前供应商,让 profile 回到正确地址 |
常见问题¶
切换成功但 Claude Desktop 没变化?¶
请完全退出并重启 Claude Desktop。Claude Desktop 读取 3P profile 的时机通常在启动阶段,切换后不会自动热更新。
模型映射供应商请求失败?¶
检查:
- CC Switch 是否仍在运行
- 接入条上的路由服务是否显示「运行中」
- 供应商 API Key 和接口地址是否正确
- 模型映射中是否填写了实际请求模型
- 切换供应商后是否重启了 Claude Desktop
Claude Desktop 模型菜单里看不到我的品牌模型名?¶
编辑供应商,在模型映射中填写「菜单显示名」,然后重新切换到该供应商并重启 Claude Desktop。
直连模式下为什么报错?¶
直连模式要求供应商提供原生 Anthropic Messages API,并接受 Claude Desktop 的三档角色 ID(claude-sonnet-* / claude-opus-* / claude-haiku-*)。如果供应商使用 OpenAI、Gemini、非 Claude 模型 ID,或旧式 Claude ID(如 claude-3-5-sonnet-…)等任何非三档角色 ID,直连都会失败,请开启「需要模型映射」。
可以关闭 CC Switch 吗?¶
取决于模式:
- 直连:Claude Desktop 重启并加载配置后,可以退出 CC Switch
- 模型映射:必须保持 CC Switch 运行,路由服务保持运行(自动管理)
是否会把真实上游模型名写入 Claude Desktop?¶
模型映射不会。Claude Desktop profile 中只保存安全的 Sonnet / Opus / Haiku 角色路由和显示名;真实上游模型名保存在 CC Switch 的供应商配置中,请求经过本地网关时再映射。
辅助模型失败导致工具反复重试怎么办?¶
Auto 模式下,Claude 会先调用安全分类器(通常是 Opus 档位的模型)判断工具能否自动执行。如果分类器所用档位映射到的模型一直失败(例如余额不足返回 402),工具结果会报告「安全分类器暂时不可用」,主模型又会再次尝试,形成持续消耗的循环。
若主对话携带的连续三轮工具结果全部报告已知的「安全分类器暂时不可用」错误,本地路由返回 HTTP 400,停止继续请求主模型。在「模型映射」中把该档位改为该供应商可正常调用的模型,或补足余额后,发送一条新用户消息即可恢复任务。权限检查保持生效。
这不是账单上限:保护依赖客户端保留结构化工具错误、历史和工具列表;不同错误文案、历史压缩、成功工具结果或新用户消息会影响识别。仍应在供应商端设置费用限制。
下一步¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cc/cc-switch