> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Desktop App

> Claude Desktop App 集成指南：原生支持第三方推理 / Gateway，无需改包或反代

<Warning>
  适用版本：Claude Desktop **2025.6 及以上**（原生支持第三方推理 / Gateway，无需改包或反代）。
</Warning>

## 一、配置步骤

### 第 1 步：开启开发者模式

1. 打开 Claude Desktop。
2. 顶部菜单栏 → Help → Troubleshooting → Enable Developer Mode。
3. 开启后 Claude Desktop 会**自动重启**，重启后顶部菜单栏出现 Developer 菜单。

### 第 2 步：进入第三方推理配置

1. 菜单栏 → Developer → Configure third-party inference。
2. 在弹出的窗口中，连接方式选择 **Gateway**。

<img src="https://mintcdn.com/gravitexai/jgbA1YeZO82Wd_Vh/images/claude-desktop-app-1.jpg?fit=max&auto=format&n=jgbA1YeZO82Wd_Vh&q=85&s=4a2fdc22ba130bd5d2c1a0a03dcf393d" alt="开启开发者模式并进入第三方推理配置" width="2156" height="1280" data-path="images/claude-desktop-app-1.jpg" />

<img src="https://mintcdn.com/gravitexai/jgbA1YeZO82Wd_Vh/images/claude-desktop-app-2.jpg?fit=max&auto=format&n=jgbA1YeZO82Wd_Vh&q=85&s=18ed9cd1e70c54be0ddd624c4e77bbbe" alt="连接方式选择 Gateway" width="2239" height="1280" data-path="images/claude-desktop-app-2.jpg" />

### 第 3 步：填写 Gateway 信息

| **字段**                | **填写内容**                                         | **说明**      |
| --------------------- | ------------------------------------------------ | ----------- |
| Gateway base URL      | `https://api.gravitex.ai`                        | 见下方「填写规则」   |
| Gateway API key       | GravitexAI 控制台-密钥管理中复制 API Key（格式：sk-xxxxxxxxxx） | 明文保存在本机，勿泄露 |
| Gateway extra headers | 一般留空                                             | 除非明确要求额外请求头 |

<img src="https://mintcdn.com/gravitexai/jgbA1YeZO82Wd_Vh/images/claude-desktop-app-3.jpg?fit=max&auto=format&n=jgbA1YeZO82Wd_Vh&q=85&s=f9bc78743477781b96c45dd353cceff2" alt="填写 Gateway 信息" width="2239" height="1280" data-path="images/claude-desktop-app-3.jpg" />

<Warning>
  **Gateway base URL 填写规则（最常见错误）：**

  * `最终请求 = 你填的 base URL + "/v1/messages"`
  * 实际接收地址若为 `https://api.gravitex.ai/v1/messages`，则 **base URL 填 `https://api.gravitex.ai`**
  * **不要**自己带 `/v1/messages` 尾巴，否则会变成 `.../v1/messages/v1/messages` 导致 404。
</Warning>

### 第 4 步：配置模型（Model）

支持 2 种方式，选其中一种即可：

**第一种：** 推荐开启 **Model discovery（模型发现）**：

* 勾选 Auto-populate the model picker from `{base URL}`/v1/models at launch。
* 点击 **Test model discovery**，确认能拉取到支持的模型列表。
* 模型下拉框会自动只显示支持的模型，避免模型名填错。

**第二种：** 手动指定，在 Model list 中点击 **+ Add** 添加模型，填写规则如下：

| **字段**                       | **填写说明**                                                                                               |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Model ID**                 | 必须和 GravitexAI 支持的模型 ID 完全一致（带版本号），例如 `claude-haiku-4-5-20251001`、`claude-fable-5`。                    |
| **Display name**             | 模型在下拉框中显示的名称，可自定义，例如 `Claude Opus 4.5`。                                                                |
| **Offer 1M-context variant** | 如果该模型支持 1M 上下文版本，可开启；普通模型保持关闭。                                                                         |
| **Tier alias**               | **必填。** 选择该模型对应的 Claude 档位，例如 `opus`、`sonnet`、`haiku`、`fable`。Claude Desktop 后台会用这些档位别名调度轻量/强力任务及兜底回退。 |

<img src="https://mintcdn.com/gravitexai/jgbA1YeZO82Wd_Vh/images/claude-desktop-app-4.jpg?fit=max&auto=format&n=jgbA1YeZO82Wd_Vh&q=85&s=c37ac4faf68267b617942a4f17a2619b" alt="配置模型 Model discovery" width="1086" height="768" data-path="images/claude-desktop-app-4.jpg" />

**Tier alias 为什么重要？**

Claude Desktop 内部会用 opus / sonnet / haiku / fable 这些档位别名来分配不同类型的调用（例如轻量摘要任务可能走 haiku，复杂推理走 opus）。如果你把 claude-opus-4-8 的 Tier alias 设为 opus，客户端就知道把它当 Opus 档位用；留空或选错会导致 Invalid: Model list 错误。

📌 Model list 中**第一项为默认模型**。建议把常用模型（如 Sonnet）放在最上面。

<Warning>
  **常见报错：底部提示 Invalid: Model list**

  通常是以下原因之一：

  * Tier alias 未选择；
  * Model ID 与已有条目重复；
  * Model ID 格式不被客户端接受（含空格、特殊字符等）。

  修复后先点 **Save Changes**，再点 **Apply Changes**。
</Warning>

### 第 5 步：应用并重启

1. 点击 **Apply Changes**。
2. **完全退出** Claude Desktop（macOS：Claude 菜单 → Quit Claude / Cmd+Q，并用活动监视器确认无 Claude 进程）。
3. 重新打开 Claude Desktop。
4. 发送一条测试消息验证。

## 二、验证是否成功

* Claude Desktop 能正常启动，左下角显示 你的账号 · Gateway。
* 发送消息后无 `authentication` / `invalid api key` / `gateway unavailable` / `model_not_found` 等报错。

## 三、常见问题排查

| **现象**                           | **原因**                | **处理**                                                                      |
| -------------------------------- | --------------------- | --------------------------------------------------------------------------- |
| Invalid API key / 401            | Key 错误、过期、被禁用         | 重新生成 Key 并填写                                                                |
| Gateway unavailable              | 地址错误或网络不通             | 检查 base URL、网络；确认域名可被访问                                                     |
| 404 ... /v1/messages/v1/messages | base URL 多带了尾巴        | 去掉 /v1/messages 后缀                                                          |
| model\_not\_found：模型无可用渠道        | 模型 ID 不被支持            | 用 Model discovery 拉取真实列表；模型名用带版本号完整 ID（如 `claude-haiku-4-5-20251001`），勿用裸别名 |
| Preparing session... 长时间卡住       | 模型不支持 / 后端无响应 / 未完全重启 | 检查模型 ID、curl 测接口、完全退出重启                                                     |
| Apply locally 后不生效               | 仅关闭窗口未退出进程            | 完全退出 Claude 进程后重启；必要时改用导出 .mobileconfig（macOS）/ .reg（Windows）导入             |

## 四、安全须知

* **API Key 等同于密码**，不要写入公开文档、截图或代码仓库。
* 导出的配置文件（.mobileconfig / .reg / .json）可能含明文 Key，仅短期保存在可信设备，用完删除。
* 若 Key 已在聊天、截图或日志中暴露，应立即作废并重新生成。