跳转至

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 供应商,通常只需要:

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

第三步:切换并重启 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 本地网关:

http://127.0.0.1:15721/claude-desktop

CC Switch 会负责:

  1. 向 Claude Desktop 暴露安全的 Claude 模型路由
  2. 把 Desktop 选择的模型角色映射到真实上游模型
  3. 按供应商要求转换 Anthropic / OpenAI / Gemini 请求格式
  4. 用 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 官方登录:

  1. 选择 Claude Desktop Official
  2. 点击「切换」
  3. 重启 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