# Cherry Studio 怎么接 GPT？

> 在 Cherry Studio 中接入 GPT、OpenAI 兼容 API、Claude、Gemini 或本地模型。本文讲清 API Key、Base URL、模型 ID、模型列表为空和 401/404 排错。

- Canonical HTML: https://omniakey.com/zh/blog/cherry-studio-api-setup
- Markdown: https://omniakey.com/zh/blog/cherry-studio-api-setup.md
- Published: 2026-09-17 (updated 2026-09-21)
- Author: Kiki, COO at OmniaKey
- Language: zh
- Category: API setup
- Reading time: 12 min
- All posts: https://omniakey.com/blog/llms.txt

---

搜索 **Cherry Studio 怎么接 GPT**，大多数人真正想解决的是：Provider 选哪个、API 地址填哪里、模型列表为什么为空，以及配置后如何确认请求真的成功。

先给最短答案：

> **设置 → 模型服务 → 选择或添加 Provider → 填写凭据和 API 地址 → 获取或手动添加模型 → 启用 Provider → 检测。**

如果你搜索的是“Cherry Studio 怎么接入 API”，核心不是把 ChatGPT 登录到客户端，而是把协议、API Key、Base URL 和模型 ID 配成一组能工作的参数。Cherry Studio 内置 OpenAI、Anthropic、Gemini、DeepSeek、Moonshot、Ollama、LM Studio 等服务，也能通过自定义服务商接入第三方网关和本地服务。字段名称以[官方模型服务说明](https://docs.cherryai.com.cn/pre-basic/providers/providers.md)为准。

## 接入前先准备四项信息

|信息|含义|
|-|-|
|协议|OpenAI 兼容、Anthropic Messages、Gemini，或服务商明确说明的协议|
|API Key|用于鉴权的凭据|
|Base URL|通常是 API 根地址；只有服务商要求时才填完整 endpoint|
|模型 ID|接口实际接受的字符串，不能只填宣传名称|

不要把网页登录密码当 API Key。ChatGPT 订阅、官方 API 和第三方网关是不同的接入方式，必须使用服务商提供的 API 凭据。

## Cherry Studio 接 GPT 的五步配置

### 1. 打开模型服务

启动 Cherry Studio，进入 **设置 → 模型服务**。直接调用 OpenAI 时选择内置 OpenAI；使用聚合平台、自建网关或私有服务时，点击 **添加服务商**，创建单独的自定义配置。

Provider 由**接口协议**决定，不是由模型名字决定。一个名字里带 GPT 的模型，如果服务商要求 Anthropic 协议，也不能套用 OpenAI 配置。

### 2. 填写 Provider 字段

|字段|应该填写|常见错误|
|-|-|-|
|服务商名称|方便识别的名字，例如“我的 GPT 网关”|多个地址使用同一个名字|
|API Key|只粘贴 Key 本身|多空格、引号、`Bearer` 或已撤销的 Key|
|API 类型|按服务商文档选择 OpenAI / Anthropic / Gemini|只看模型名称猜协议|
|API 地址|服务商要求的根地址或完整地址|填后台地址、重复 `/v1` 或粘错路径|

常规 OpenAI 兼容服务通常填写根地址，让 Cherry Studio 自动拼接版本和请求路径。如果文档同时给出 `https://api.example.com` 与 `https://api.example.com/v1/chat/completions`，前者是通常的 Base URL；只有服务商明确要求完整地址时才使用后者。

自定义字段和协议细节可以查看[官方自定义服务商教程](https://docs.cherryai.com.cn/pre-basic/providers/zi-ding-yi-fu-wu-shang.md)。

### 3. 获取或手动添加模型

保存后点击 **获取模型列表**。如果接口支持模型发现，点击模型旁的 `+` 加入当前列表。服务商返回的实际模型 ID 才是准确信息，日期后缀、供应商前缀和版本标签都不要自行删改。

如果服务商不提供模型列表接口，点击 `+` 手动输入准确的模型 ID。服务端返回模型不代表 Cherry Studio 已经启用；加入列表后还要打开 Provider 右上角的开关。

### 4. 用一条短消息检测

点击 **检测**，选择刚添加的模型，再发送：

```text
只回复：连接成功
```

这一步先验证鉴权、模型 ID、普通文本响应和流式输出。长文档、图片、工具和 Agent 都等基础请求成功后再逐项测试。

### 5. 再打开高级能力

文本能回复，不代表当前模型支持图片、工具调用、推理参数或 Responses API。每次只打开一种能力，出错时才知道问题来自模型、协议还是客户端设置。

## 第三方 API 怎么接

### OpenAI 兼容网关

第三方文档明确写着兼容 OpenAI 时，路径通常是 **添加服务商 → OpenAI 兼容类型**，填写它提供的 API 地址和 Key，再获取或手动添加模型。聚合平台、私有网关、vLLM 和不少托管开源模型都属于这一类。

### 同时支持多种协议的网关

NewAPI 类网关可能用一个根地址提供 OpenAI Chat、OpenAI Responses、Anthropic Messages 和 Gemini 接入。Cherry Studio 的 [NewAPI 配置说明](https://docs.cherryai.com.cn/pre-basic/providers/newapi.md)说明了根地址和协议版本路径的关系。符合该约定时优先选 NewAPI；路径有定制时再用自定义 Provider。

### Ollama、LM Studio 和 vLLM

选择对应本地 Provider，或者在自定义服务商里选择 OpenAI。模型列表要填写本地服务实际加载的名称。模型在本机运行，不等于自动支持视觉、工具或长上下文，先用短文本检测。

## 模型列表为空怎么办

按下面顺序排查：

1. 确认服务商是否实现模型发现接口。有些 API 只支持指定模型调用，需要手动添加。
2. 检查地址是否多了一层路径。根地址已有 `/v1` 时，不要再重复拼接。
3. 确认填的是 API 地址，不是服务商后台地址。
4. 逐字符核对模型 ID，展示名称和 API ID 不是一回事。
5. 确认 Provider 右上角已经启用。

## 401、404、400 和超时排查

|现象|常见原因|先检查什么|
|-|-|-|
|`401 Unauthorized`|Key 错误、过期或认证方式不对|重新复制 Key，确认 Provider 协议|
|`403 Forbidden`|账户、项目、余额或 Key 限额|查看服务商权限和额度|
|`404 Not Found`|地址、版本路径或协议端点错误|恢复文档中的根地址|
|`400 Bad Request`|参数或请求格式不支持|去掉自定义参数，重试短文本|
|`model not found`|模型 ID 错或没有加入列表|复制服务端返回的真实 ID|
|文本可以、图片/工具不行|模型或协议不支持该能力|查模型能力，再换路由|
|一直转圈|服务商慢、网络问题或请求太长|单模型、短提示重新测试|

每次只改一个变量。先固定一个 Provider、一个模型和一条短消息，成功后再扩展多模型和工具。

## 多模型切换要注意什么

配置多个 Provider 或同一 Provider 下的多个模型后，可以在对话顶部切换，也可以勾选多个模型回答同一个问题。每个模型都会产生独立请求，这不是自动投票；请求数、成本和资料发送范围会随选择数量增加。先用两款模型，并在提示词里写清准确性、风险和可执行性等评价标准。

## 用 OmniaKey 统一接入

如果不想分别维护 GPT、Claude、Gemini 和其他模型的入口，可以把 OmniaKey 配成 Cherry Studio 的一个 OpenAI 兼容 Provider：

1. 在 [API Keys 页面](https://omniakey.com/zh/dashboard/tokens)创建一把专用于 Cherry Studio 的 Key，并设置额度。
2. 打开 **设置 → 模型服务 → 添加服务商**，选择 OpenAI 兼容类型。
3. 按 [OmniaKey 快速开始](https://docs.omniakey.com/cn/quick-start)填写 Base URL 和 Key。
4. 获取模型列表；没有返回列表时，从[实时模型目录](https://omniakey.com/zh/models)复制准确 ID。
5. 启用 Provider，检测一款模型，再到[用量页面](https://omniakey.com/zh/dashboard/usage)确认调用记录。

当前目录包含 Claude、GPT、Gemini、Grok，也有 Qwen、DeepSeek、GLM、Kimi、MiniMax、MiMo 和混元等模型。目录和能力会变化，实际接入时以实时列表为准。OpenAI 兼容并不意味着所有视觉、工具和推理功能都完全相同。同一个 key 也能用于其他工具，详见[WorkBuddy 配置自定义模型](https://omniakey.com/zh/blog/workbuddy-custom-model-setup)、[Cline 自定义 API Key 配置](https://omniakey.com/zh/blog/cline-custom-api-key)和[用 OmniaKey 跑 Claude Code](https://omniakey.com/zh/blog/claude-code-setup)教程。

## 国内怎么用

OmniaKey 支持人民币直充（支付宝、微信支付），一个 key 就能调用多家模型，包括 [GPT-6.1 Sol](https://omniakey.com/zh/gpt-6-1-sol) 和 [Claude Opus 5.5](https://omniakey.com/zh/claude-opus-5-5)，不用自己再去申请 OpenAI 的 API 账号。按上面的五步配好一个 OpenAI 兼容 Provider，换模型时在对话顶部切换即可。

## 常见问题

### Cherry Studio 能接任意 API 吗？

只有服务商提供 Cherry Studio 支持的协议时才可以。一个没有请求格式、认证方式和模型 ID 说明的 URL 不能直接使用。

### 有 ChatGPT 网页订阅可以直接接吗？

不要把网页登录凭据填进 API Key 输入框。Cherry Studio 需要 API 权限或兼容网关凭据，具体额度和计费取决于对应 API 服务。

### 为什么 GPT 能聊天，Agent 或图片却失败？

基础文本成功不代表模型、协议和客户端路线支持工具或视觉。分别核对模型能力、请求协议和 Cherry Studio 的功能开关。

## 参考资料与更新时间

- [Cherry Studio：模型服务设置](https://docs.cherryai.com.cn/pre-basic/providers/providers.md)
- [Cherry Studio：自定义服务商](https://docs.cherryai.com.cn/pre-basic/providers/zi-ding-yi-fu-wu-shang.md)
- [Cherry Studio：NewAPI](https://docs.cherryai.com.cn/pre-basic/providers/newapi.md)
- [Cherry Studio：多模型对比与消息分支](https://docs.cherryai.com.cn/advanced-basic/chat/model-compare-branches.md)

模型 ID、服务能力和接口路径会变化，配置前请重新打开对应文档确认。