# Cherry Studio 接入 NezhaGate：10 分钟上手教程

零基础照着做：在 Cherry Studio 添加 NezhaGate 作为模型服务商，选模型、验证连接、开始对话。附推荐模型和常见报错的解决办法。

> https://nezhagate.com/docs/integrations/cherry-studio

## 开始前你需要

- Cherry Studio 2.x 桌面版（Windows、macOS、Linux 都有），在 Cherry Studio 官网或 GitHub 下载安装即可。

- 一个 NezhaGate 账号和 API Key（第 1 步教你拿）。

- 大约 10 分钟。

## 第 1 步：注册 NezhaGate，创建 API Key

1. 打开 [nezhagate.com](https://nezhagate.com/)，点右上角「免费注册」。可以用邮箱注册，也可以用 Google / GitHub 一键登录。

2. 登录后进入「控制台」→「API Keys」。在「创建 API Key」里给 Key 起个名字（比如 `cherry`），「单 Key 限额」填 0 表示不限，然后点「创建 Key」。

3. 页面会显示一串以 `sk-` 开头的 Key，**马上点复制**，它只显示这一次。

余额在「账单」页查看和充值。按实际用量计费，请求失败不扣费。各模型价格见 [定价页](https://nezhagate.com/pricing)。

## 第 2 步：把 NezhaGate 添加为服务商

1. 打开 Cherry Studio，点左侧栏下方的齿轮「**设置**」，进入「**模型服务**」。

2. 在服务商列表下方点「**+ 添加服务商**」。

3. 在弹出的「添加自定义提供商」窗口里填：

   - 「提供商名称」：`NezhaGate`

   - 「API 密钥」：粘贴第 1 步复制的 Key

   - 「端点设置」里的「**OpenAI**」一栏：填下面的地址。「Anthropic」一栏留空。

```
https://nezhagate.com/v1
```

1. 输入框下方会预览「请求路径：https://nezhagate.com/v1/chat/completions」，和这里一致就对了。点「**添加**」。

## 第 3 步：选模型、验证、启用

1. 接着会弹出「**选择模型**」，列表是从 NezhaGate 自动拉取的。

2. **不要点「全选」**：列表里也有生图、生视频模型，放进聊天里用不了。只勾几个你要用的对话模型，比如 `deepseek-v4.1-flash`、`kimi-k3`、`glm-5.3`、`qwen3.7-max`、`claude-opus-5`。

3. 点「**添加所选模型**」。Cherry Studio 会自动「验证」模型（发一次真实请求），然后「启用服务商」，最后点「**完成**」。

别点「跳过」。跳过之后服务商是关闭状态，要到服务商页面右上角手动打开开关，开关打开后列表里的 NezhaGate 会亮绿点。

以后想加模型：在 NezhaGate 服务商页面点「同步模型」；列表里没有的，用「手动添加模型」直接填模型 ID。想再测一次连接：点「检测」，选一个模型，点「开始」，看到「连接成功」即可。

## 第 4 步：开始对话

1. 回到聊天页面，打开模型选择器，在「NezhaGate」分组下选一个模型。

2. 在输入框里发一句「你好」。收到回复就全部完成了。

## 推荐模型

| 用途 | 模型 ID | 说明 |
| --- | --- | --- |
| 日常对话、翻译、总结 | `deepseek-v4.1-flash` | 便宜、快，性价比最高。 |
| 长文档、多文件分析 | `kimi-k3` | 长文本理解强，支持提示缓存，同一份长文档反复提问更省。 |
| 写代码、复杂推理 | `glm-5.3`、`qwen3.7-max` | 都会先思考再回答，回复稍慢但更准。 |
| 最难的任务 | `claude-opus-5`、`gpt-6-astra` | 旗舰级，价格更高。 |
| 写小说、长文 | `claude-fable-5` | 叙事和长文写作最强。 |

价格随时可在 [定价页](https://nezhagate.com/pricing) 查看。

## 地址怎么填才对

- `https://nezhagate.com/v1`、`https://nezhagate.com` 都可以：没有写版本号时，Cherry Studio 会自己补上 `/v1`。

- **不要**填到 `/v1/chat/completions`，否则路径会重复，报 404。

- 地址末尾的 `#` 表示「不要自动补版本号」，接 NezhaGate 用不到。

还在用 1.x 旧版？界面不一样：添加服务商时「提供商类型」选 OpenAI，「API 地址」填 `https://nezhagate.com`，再点「管理」添加模型、点「检查」测试连接。建议直接升级到 2.x。

## 常见问题和报错

| 现象 | 怎么办 |
| --- | --- |
| 「服务商未返回任何可用模型」或「拉取模型失败」 | 检查地址和 Key 是否正确（Key 前后不要有空格）；或者用「手动添加模型」直接填模型 ID。 |
| 「模型请求失败」（验证那一步） | 先确认账户有余额。思考型模型（如 `qwen3.7-max`）有时回复较慢、验证会超时，换 `deepseek-v4.1-flash` 再验证一次。 |
| 聊天里看不到 NezhaGate 的模型 | 服务商没有启用。到「设置 → 模型服务 → NezhaGate」打开右上角的开关。 |
| 404 | 地址重复了 `/v1` 或多写了 `/chat/completions`，改成 `https://nezhagate.com/v1`。 |
| 401 | Key 错误或已删除。回控制台重新创建并复制。 |
| 402 | 余额不足，或这个 Key 超过了你设的限额。到「账单」充值，或在控制台调高限额。 |
| 400 | 一般是参数不支持、上下文太长或图片太大。新建一个助手（默认设置）再试；给不支持看图的模型发图片也会报这个错。 |

还有问题？看 [接入文档](https://nezhagate.com/docs-guide) 或 [常见问题](https://nezhagate.com/faq)。