# Claude Desktop 接入

[Claude Desktop](https://claude.com/download) 是 Anthropic 官方的桌面应用（Windows / macOS / Linux），可以替代 claude.ai 网页版本地处理 PPT、Excel、文档、MCP 工作流等任务。最近桌面版新增了 **Configure Third-Party Inference**（第三方推理）入口，允许用户在不登录 Anthropic 账号的情况下，把任意 Anthropic 兼容网关配置为推理后端。本文介绍如何在 Claude Desktop 中接入 QCode.cc，**省去 Pro 订阅消耗、复用同一份 QCode 配额**。

## 为什么用第三方 API

- **省 Pro 订阅消耗**：桌面端的 PPT/Excel/MCP 类工作流复用 QCode 套餐配额，不再单独付 Pro
- **解锁 Cowork 协作模式**：原本面向 Pro / Team 订阅的 [Claude Cowork](https://support.claude.com/en/articles/14680741-install-and-configure-claude-cowork-with-third-party-platforms)（沙盒 + Skills + MCP + 文件操作）通过 QCode 接入后**无需 Pro 即可使用**——详见下方 Claude Cowork 章节
- **统一配额**：Claude Desktop 与 Claude Code、Codex CLI、Gemini CLI 共用同一个 QCode API Key
- **完整模型矩阵**：QCode.cc 网关同时暴露 Anthropic（Opus 5 / 4.7、Sonnet 5 / 4.6、Haiku 4.5）、OpenAI、Google Gemini 三家共 25+ 模型
- **团队批量部署**：配置面板支持 Export 配置 JSON，通过 Jamf / Intune / Group Policy 下发到团队成员

## 前置条件

- 已安装 Claude Desktop（[官方下载](https://claude.com/download)，Windows / macOS / Linux）
- 拥有 QCode.cc API Key（`cr_` 开头），在 [控制台](https://qcode.cc/dashboard) 获取
- Windows 10/11 用户：首次安装可能提示开启 Virtual Machine Platform 后重启（一次性操作）

## 配置步骤

### 第 1 步：首次启动，先不要登录

> 小提示：未登录状态下左上角菜单按钮可能点击无响应。鼠标点一下邮箱输入框获得焦点，然后键盘 **Tab** 跳到菜单按钮，回车展开。

### 第 2 步：启用开发者模式

依次点击 **菜单 → Help → Troubleshooting → Enable Developer Mode**。

![启用开发者模式](/static/images/claude-desktop/1-help-menu.png)

启用后顶部菜单会多出一个 **Developer** 项。

### 第 3 步：打开第三方推理配置

依次点击 **菜单 → Developer → Configure Third-Party Inference...**。

![进入第三方推理配置](/static/images/claude-desktop/2-dev-menu.png)

### 第 4 步：填写 Gateway 凭据

在 Connection 区块选择 **Gateway**（Anthropic-compatible）模式，按下表填写：

![Gateway 凭据填写](/static/images/claude-desktop/3-config.png)

| 字段 | 值 |
|------|-----|
| Gateway base URL | `https://asia.qcode.cc/api` |
| Gateway API key | 你的 QCode.cc API Key（`cr_` 开头） |
| Gateway auth scheme | **保持默认 `bearer`**（QCode.cc 网关同时接受 bearer 与 x-api-key，无需改动） |
| Gateway extra headers | 留空 |

> base URL 末尾**不要**加 `/`，Claude Desktop 会自动拼 `/v1/messages`、`/v1/models` 等路径。

### 第 5 步：应用配置

点击右下 **Apply locally** 按钮——配置写入本机生效，模型下拉框会自动拉取 QCode.cc 提供的 25+ 模型列表。在主界面新建一个对话即可开始使用。

## Gateway base URL 选择

> **注意**：根据你所在地区选择接入域：

| 用户位置 | Gateway base URL |
|------|-----------------|
| 中国大陆（推荐）| `https://asia.qcode.cc/api` |
| 中国大陆（备用）| `https://api.qcode.cc/api` |
| 海外用户 | `https://api.qcode.cc/api` |

完整接入点说明、协议路径、地理路由规则参见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

## 模型列表说明

正常情况下 Claude Desktop 会调 `/v1/models` 自动拉取模型列表，下拉框直接显示完整选项，**无需任何额外操作**。

如果下拉框为空（极少数环境会触发），可以手工补全：

1. 点击配置面板右下 **Export ▾ → 在文件管理器中打开**，定位到 Claude Desktop 配置 JSON
2. 在 JSON 中加入 `inferenceModels` 数组：

```json
{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://asia.qcode.cc/api",
  "inferenceGatewayApiKey": "cr_xxxxxxxx",
  "inferenceModels": [
    "claude-opus-5",
    "claude-opus-4-7",
    "claude-sonnet-5",
    "claude-haiku-4-5"
  ]
}
```

3. 保存后**完全退出并重启** Claude Desktop（非简单关闭窗口）

## 团队部署（MDM）

配置面板右下的 **Export ▾** 可导出当前配置为 JSON，配合企业 MDM 工具批量下发，免去每位成员手工配：

- macOS：Jamf / Mosyle 下发用户级配置文件
- Windows：Intune / Group Policy 推送 `%APPDATA%\Claude\` 配置
- Linux：Ansible / Puppet 写入 `~/.config/Claude/`

详细 MDM 集成指引以 [Anthropic 官方文档](https://support.claude.com/en/articles/14680741-install-and-configure-claude-cowork-with-third-party-platforms) 为准。

## 共享配额

Claude Desktop 与 Claude Code CLI、Codex CLI、Gemini CLI 使用同一个 QCode.cc API Key，**共享同一份套餐配额**，多端登录不会重复扣费。具体计费规则参见 [计费说明](/docs/reference/billing)。

## Claude Cowork 协作模式

[Claude Cowork](https://support.claude.com/en/articles/14680741-install-and-configure-claude-cowork-with-third-party-platforms) 是 Claude Desktop 的协作沙盒模式，让 Claude 在隔离的 Linux 环境中执行 Skills、调用 MCP、读写本地文件、运行 shell——非常适合 PPT/Excel/PDF 处理、批量文件整理、跑代码沙盒等工作流。Cowork 此前主要面向 Pro / Team 订阅用户。

> Anthropic 官方现已支持 [Cowork 与第三方推理网关组合使用](https://support.claude.com/en/articles/14680741-install-and-configure-claude-cowork-with-third-party-platforms)，意味着按本文配置完成后，QCode.cc 用户**无需 Pro 订阅即可使用 Cowork 沙盒**。

### QCode 接入后能做什么

- **Skills 执行**：用 Cowork 沙盒跑官方 Skills 库（PPT 制作、Excel 批改、PDF 解析、图像处理等），底层模型走 QCode 的 Opus 5 / Sonnet 5
- **MCP 工作流**：Cowork 中加载 MCP server（本地文件、GitHub、自定义工具），与 QCode 模型协作
- **文件与终端操作**：Claude 在沙盒内直接读写文件、执行 shell 命令——适合复制大段内容让 AI 整理、批量重命名、跑脚本等
- **共享配额**：Cowork 推理消耗 QCode 配额，与 Claude Code、Codex、Gemini CLI 共用同一份套餐余额

### 边界与建议

- **部分 connectors 仍需 Anthropic 账号**：Google Drive、Notion 等"上层"connector 可能仍需登录 Anthropic 账号配置，具体以 [官方支持文档](https://support.claude.com/en/articles/14680741-install-and-configure-claude-cowork-with-third-party-platforms) 为准
- **模型选择**：进入 Cowork 任务后建议手动选 `claude-opus-5` 或 `claude-sonnet-5`（`claude-opus-4-7` 仍在售），避免默认选到不合适的模型
- **首次启用**：Cowork 沙盒首次会下载 runtime（数百 MB），耐心等待启动

## 限制与差异

- **claude.ai 网页版不支持**：第三方 API 是 Desktop 独有功能，浏览器端仍走 Anthropic 官方账号
- **Windows 首次启用**：可能提示开启 Virtual Machine Platform 后重启（一次性）

## 常见问题

### 模型下拉框为空？

1. 检查 base URL 末尾**没有** `/`
2. 确认 API Key 完整且 `cr_` 开头
3. 仍然为空时按"模型列表说明"手工填 `inferenceModels` JSON

### 报错 401 Unauthorized

1. API Key 必须 `cr_` 开头且无前后空格
2. 到 [qcode.cc/dashboard](https://qcode.cc/dashboard) 检查密钥是否仍有效
3. Gateway auth scheme 保持默认 `bearer` 即可，不要改成 `x-api-key`

### "Apply locally" 和 "Export" 区别

- **Apply locally**：写入本机配置文件，立即对当前用户生效
- **Export**：导出 JSON，用于团队 MDM 批量下发或备份

### 桌面版和 CLI 能同时用吗

可以。Claude Desktop 和 Claude Code / Codex CLI 各自独立读取配置（桌面版读自身 JSON，CLI 读 `~/.claude/settings.json` 或 `~/.codex/config.toml`），共用同一个 QCode API Key 与配额，互不冲突。

### 和 CC Switch 是什么关系

[CC Switch](/docs/ide/cc-switch) 管理 CLI 工具（Claude Code、Codex 等）的 base URL 与凭据切换；Claude Desktop 走自身的开发者模式独立配置。两者面向不同形态的客户端，各管各的。

## 下一步

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — QCode.cc 三协议四接入域全表
- [Claude Code 完整教程](/docs/getting-started/claude-code-tutorial) — CLI 端完整用法
- [CC Switch 配置](/docs/ide/cc-switch) — 同时管理多个 CLI 的 base URL
- [计费说明](/docs/reference/billing) — 套餐配额规则