# 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 账号类供应商
- 在 Claude Desktop 官方模式和第三方供应商之间切换

Claude Desktop 与 Claude Code 是两个不同的应用入口。Claude Code 使用 `~/.claude/settings.json`，Claude Desktop 使用自己的 3P 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 面板

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

![Claude Desktop 面板](../../assets/claude-desktop-panel.png)

如果你没有看到该入口，请到：

设置 → 通用 → 应用可见性

确认 Claude Desktop 没有被隐藏。

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

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

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

![从 Claude Code 导入供应商](../../assets/claude-desktop-import-from-claude.png)

如果你已经在 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 添加供应商](../../assets/claude-desktop-add-provider.png)

你可以选择：

- **预设供应商**：从内置 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 Desktop 不会像 Claude Code 那样热重载配置。每次切换供应商后，都需要完全退出并重新打开 Claude Desktop。

## 两种工作模式

### 直连模式

直连模式适合供应商本身已经提供 Anthropic Messages API，并且能被 Claude Desktop 直接访问。

直连模式下，CC Switch 会把 Claude Desktop 的 3P profile 指向供应商接口：

```json
{
  "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 本地网关：

```text
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 模型映射](../../assets/claude-desktop-model-mapping-rows.png)

### 推荐写法

如果你想在 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 本地路由参与请求转换。本地路由是一个强大，同时有一定复杂度的功能，为了避免不需要路由功能的用户误触，主页面的本地路由开关默认隐藏，需要路由功能时，请手动把它显示出来。

打开方式：

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

![显示本地路由开关设置](../../assets/local-routing-display-setting.png)

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

![Claude Desktop 本地路由开关](../../assets/claude-desktop-route-toggle-context.png)

状态说明：

| 状态     | 说明                                           |
| -------- | ---------------------------------------------- |
| 开启     | 本地网关正在运行，地址通常是 `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

```text
~/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

```text
%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
```

配置文件由 CC Switch 自动维护，不建议手动编辑。出现配置不一致时，重新启用当前供应商通常可以修复。

## 状态提示与处理

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

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

## 常见问题

### 切换成功但 Claude Desktop 没变化？

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

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

检查：

- CC Switch 是否仍在运行
- Claude Desktop 本地路由是否已开启
- 供应商 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 运行，并保持 Claude Desktop 本地路由开启

### 是否会把真实上游模型名写入 Claude Desktop？

模型映射模式不会。Claude Desktop profile 中只保存安全的 Sonnet / Opus / Haiku 角色路由和显示名；真实上游模型名保存在 CC Switch 的供应商配置中，请求经过本地网关时再映射。

## 下一步

- [添加供应商](./2.1-add.md)
- [切换供应商](./2.2-switch.md)
- [代理服务](../4-proxy/4.1-service.md)
- [应用路由](../4-proxy/4.2-routing.md)