Cherry Studio 怎么配置 OpenAI API？自定义接口与模型设置

更新于 2026-10-30 · gpt.boats

简答：在 Cherry Studio 中配置 OpenAI API，核心是进入“设置→模型服务”，选择或新建服务商，填写 API Key 和正确的 Base URL，再获取或手动添加模型并点击“检测”。如果使用官方 OpenAI 接口，优先选择内置 OpenAI 服务商；如果使用中转、网关或本地 OpenAI 兼容服务，则选择“自定义服务商”，接口类型选 OpenAI 兼容，并根据服务端要求填写根地址或特殊路径。

定义：Cherry Studio 的 OpenAI API 配置，是把服务商的认证密钥、接口地址、协议类型和模型 ID保存到模型服务设置中，再由客户端按对应接口发起模型请求。

先看这张表：你应该选哪种配置方式

先判断 API 来源，再决定使用内置服务商还是自定义服务商。不要把“模型名称”当成“接口类型”：选择 OpenAI 代表请求格式，实际模型仍要填写服务端提供的模型 ID。

Cherry Studio 文档说明，模型服务设置通常包括 API 密钥、API 地址、获取模型列表、手动添加模型和连接检测；配置完成后还要打开服务商的启用开关。查看模型服务设置文档

Cherry Studio 配置 OpenAI API 的完整步骤

1. 打开模型服务设置。启动 Cherry Studio，进入“设置→模型服务”。不同版本的菜单文字可能略有差异，但目标是找到 Provider 或模型服务列表。
2. 确认使用内置还是自定义服务商。如果是官方 OpenAI API，优先使用列表中的 OpenAI 服务商；如果是网关、中转、本地推理服务或列表中没有的接口，选择“自定义服务商”。Cherry Studio 的文档将自定义服务商用于 OpenAI、Anthropic、Gemini 等兼容端点。查看自定义服务商文档
3. 填写 API Key。将服务端创建的密钥粘贴到 API 密钥字段。不要把真实密钥写入文章、截图、代码仓库或公开日志；如果怀疑密钥泄露，应按服务商流程撤销并重新创建。OpenAI 官方建议使用环境变量、避免把密钥放进客户端代码，并监控用量。查看 OpenAI API Key 安全建议
4. 填写 Base URL。优先填写服务商要求的根地址，而不是直接粘贴完整的 /chat/completions 请求地址。Cherry Studio 文档指出，常规情况下客户端会自动补充版本路径和接口路径；如果服务商明确要求非标准路径，才考虑填写完整地址并在末尾加 #，防止自动拼接。查看 Base URL 和 # 的说明
5. 选择正确的接口类型。普通聊天接口选择 OpenAI Chat 或 OpenAI 兼容类型；如果服务端明确提供 OpenAI Responses、Anthropic Messages 或 Gemini 协议，应选择与服务端实际协议一致的选项。协议选错时，即使 API Key 正确，也可能出现 404、参数不兼容或无法生成回复。
6. 获取模型列表。点击“获取模型列表”或类似按钮，等待服务端返回模型。Cherry Studio 文档说明，只有加入模型列表的模型才会出现在模型选择器中。模型名称相似时，要核对显示名称下方的实际 API 模型 ID，不要只看展示名称。查看模型列表与模型 ID说明
7. 获取失败时手动添加模型。点击添加模型，填写服务端真实支持的模型 ID。显示名称可以自定义，但模型 ID必须与服务端识别的值一致；如果服务商文档写的是带日期、前缀或版本后缀的 ID，不要擅自简写。
8. 设置模型类型和能力。普通文本对话选择聊天模型；只有服务端确认支持视觉、推理、嵌入或其他能力时，才在 Cherry Studio 中启用对应能力。能力开关与模型名称不是一回事，客户端勾选视觉并不会让不支持图片的模型自动获得视觉能力。
9. 启用服务商并检测。打开服务商右上角的启用开关，选择刚添加的模型，点击“检测”。成功判定应至少包括：检测请求返回成功、模型没有被识别为不存在、发送一条短消息能够正常得到回复。
10. 设为默认模型。如果检测成功但新建对话仍使用旧模型，检查当前对话的模型选择器和默认模型设置。默认模型只决定新对话或特定功能的初始选择，不会修复错误的 API 地址或失效密钥。

Base URL 到底填根地址、/v1 还是完整接口地址？

这是 Cherry Studio 配置中最容易出错的部分。可以按下面顺序判断：

1. 先看服务端文档给的调用示例。重点确认它要求的是根地址、带版本的地址，还是完整接口路径。
2. 如果 Cherry Studio 会自动拼接路径，避免重复填写。例如服务端给出的完整示例是 https://api.example.com/v1/chat/completions，而 Cherry Studio 文档说明该服务商会自动补全路径时，通常应尝试填写 https://api.example.com 或文档要求的根地址，而不是把完整路径再次粘贴进去。
3. 是否包含 /v1 不能一概而论。某些 OpenAI 兼容服务要求 https://api.example.com/v1，另一些服务会自动追加 /v1。如果出现 /v1/v1、404 或路径不存在，优先检查这里。
4. 只有明确需要时才使用 #。Cherry Studio 文档把地址末尾的 # 定义为停止自动拼接版本路径的特殊写法。例如服务端明确要求无版本路径，才考虑使用 https://api.example.com#。普通配置不要为了“保险”随意添加。

官方 OpenAI、兼容网关和本地服务的差异

官方 OpenAI API：优先使用 Cherry Studio 内置的 OpenAI 服务商，填写官方 API Key，保留默认 API 地址，使用官方文档列出的模型 ID。模型能否使用还取决于项目权限、账户状态和服务端当前可用范围，Cherry Studio 的“检测”只能验证当前配置能否完成请求，不能替代账户权限检查。

OpenAI 兼容网关：“兼容”通常表示请求格式接近 OpenAI，并不意味着所有字段、模型能力、流式行为和错误格式完全相同。必须以网关文档为准，分别核对 Base URL、协议类型、模型 ID、是否需要额外请求头，以及是否支持模型列表。

本地服务：如果 Cherry Studio 与模型服务运行在同一台电脑上，可以尝试使用 127.0.0.1 或 localhost；如果 Cherry Studio 运行在另一台设备，localhost 指向的是 Cherry Studio 所在设备，不是模型服务器，此时需要使用局域网可访问地址，并确认服务端监听地址和防火墙规则。移动端与桌面端的菜单和地址访问限制也可能不同，不能直接照搬界面路径。

Cherry Studio 还提供自定义服务商和多种协议适配，但实际请求仍由所选服务商、模型和端点共同决定。查看 Provider 总览

最小验证闭环：不要只看“保存成功”

保存配置不代表 API 已经可用。建议按照“凭证可见模型→最小请求→成功判定→错误分流”的顺序验证：

1. 确认 API Key 没有多余空格、换行或复制残留字符。
2. 确认 Base URL 使用 https:// 或服务端明确要求的 http://，端口和路径没有重复。
3. 先点击“获取模型列表”；如果列表接口不支持，不要立即判断 Key 无效，可以手动添加已知模型 ID。
4. 点击“检测”，使用一个最简单的文本模型。
5. 新建对话，只发送一句短消息，例如“请回复：连接成功”。
6. 确认返回内容、模型 ID和请求日志中的地址都符合预期。

如果检测成功但对话失败，优先检查当前对话是否仍选中了旧服务商或旧模型；如果检测和对话都失败，再检查错误码和网络。

401、404、超时和无法对话怎么排查？

• 401 Unauthorized：先检查 API Key 是否为空、复制不完整、已撤销、已过期或不属于当前项目；再检查 Cherry Studio 选择的服务商是否与密钥对应。若使用 IP 白名单，还要确认当前出口 IP 已被允许。OpenAI 文档说明，IP 不在允许范围时，即使密钥有效，也可能返回 401。查看 OpenAI IP 白名单说明
• 403 Forbidden：常见方向是项目或账户权限不足、模型未授权、组织策略限制或服务端拒绝当前请求。不要通过反复重试解决权限问题，应先核对服务商控制台中的项目、模型和权限。
• 404 Not Found：优先检查 Base URL、协议类型、自动追加的 /v1、是否重复填写 /chat/completions，以及模型 ID是否真实存在。Cherry Studio 文档明确提醒，非标准请求路径需要按服务商要求使用完整地址和 #。
• 429 Too Many Requests：可能是限速、并发、余额或账户配额问题。先查看服务端返回信息和 Retry-After，不要对余额、权限或未知错误盲目重试；只有确认是临时限流时，才按服务端建议减少并发或延迟重试。
• 连接超时：检查域名解析、代理、防火墙、端口、TLS证书和本地服务监听地址。若服务端在另一台设备上，不要把 localhost 当作远程设备地址。
• 检测成功但无法正常对话：检查当前对话选中的模型、模型类型、上下文长度、工具或视觉能力设置。某些兼容服务只实现了基础文本接口，开启不受支持的参数可能导致请求失败。
• 模型能添加但列表中找不到：确认已点击模型右侧的添加按钮，并检查服务商右上角是否已启用。Cherry Studio 文档说明，只有加入模型列表且服务商已启用，模型才会出现在选择器中。查看模型启用和检测说明

API Key 和第三方接口的安全注意事项

Cherry Studio 是桌面客户端，API Key会被保存到本地配置中，因此不要把配置文件、屏幕截图、调试日志或导出的设置文件公开上传。OpenAI 官方建议不要把 API Key部署到浏览器、移动端或其他用户可直接查看的客户端环境中；生产场景更适合由自己的后端保存密钥，再由客户端访问后端。查看 API Key 安全最佳实践

如果使用第三方兼容接口，除了确认接口能否调用，还应核对其隐私政策、数据处理范围、日志保存方式、模型路由、用量记录和密钥撤销机制。本文不对无法核实的服务状态、价格或稳定性下结论；费用、限速、并发和可用模型应以当前服务商文档和控制台显示为准。

本文由非官方资料整理站编写，不代表 Cherry Studio 或 OpenAI 官方；菜单名称会随客户端版本变化，本文核验日期为 2026年10月30日。

一份可保存的配置自查清单

• 我是否已经进入“设置→模型服务”，而不是普通聊天设置？
• 我选择的是官方内置服务商，还是自定义 OpenAI 兼容服务商？
• API Key 是否属于当前服务商、项目和账户？
• Base URL 是否是服务端要求的根地址？是否重复填写了 /v1 或 /chat/completions？
• 接口类型是否与实际协议一致？
• 模型 ID是否来自模型列表或服务端文档，而不是凭名称猜测？
• 模型是否已经添加到列表，服务商是否已经启用？
• “检测”是否成功？新建对话是否选中了同一个服务商和模型？
• 出现 401、403、404、429 或超时时，我是否先按对应分支排查，而不是反复点击发送？

如果以上项目都通过，Cherry Studio 的 OpenAI API 配置通常就完成了。若仍失败，保留错误码、请求路径、服务商类型和模型 ID，向接口提供方提交最小复现信息，不要直接发送真实 API Key。

推荐入口

如果你希望把多个 AI 模型接口统一到一个更易管理的调用入口，可以了解犀速-AI提供的 AI API 接入方案；具体模型、价格、限速与可用范围请以官网当前说明为准。

常见问题

Cherry Studio 里的 OpenAI API 地址应该填什么？

优先按服务商文档填写根地址。若 Cherry Studio 会自动补充 /v1 和 /chat/completions，不要重复粘贴完整接口地址；只有服务商明确要求非标准路径时，才考虑填写完整地址并在末尾加 #。

API Key 填好了，为什么模型列表为空？

模型列表为空不一定代表密钥无效，也可能是模型列表接口不支持、协议类型选错、权限不足或 Base URL错误。可以先核对地址和接口类型，再根据服务端文档手动添加模型 ID，并点击“检测”。

Cherry Studio 检测成功但聊天仍然报错怎么办？

先确认当前对话选中的服务商和模型与检测时相同，再检查模型类型、视觉或工具能力、上下文设置和请求参数。兼容接口可能只支持基础文本对话，开启未实现的能力会导致请求失败。

什么时候需要在 Base URL 末尾加 #？

只有服务端明确要求客户端不要自动追加 /v1 或其他版本路径时才使用。普通 OpenAI 兼容服务不要随意加 #，否则可能造成请求路径与服务端实际路径不一致。

Cherry Studio 可以直接使用 localhost 连接远程电脑上的模型吗？

不能把 localhost 当作远程地址。localhost 通常指向运行 Cherry Studio 的设备；如果模型服务运行在另一台电脑，应使用局域网可访问地址，并确认服务端监听地址、端口和防火墙设置。

相关阅读

• Continue 配置 OpenAI API 的方法
• Cursor 配置 OpenAI API 与 401/404 排查
• LangChain 接入 OpenAI 兼容 API
• OpenAI API 401 错误排查
• OpenAI API 404 模型不存在排查

参考资料

1. Cherry Studio Docs：模型服务设置
2. Cherry Studio 官方文档：自定义服务商（docs.cherry-studio-ai.com）
3. Cherry Studio Docs：Provider 总览
4. OpenAI Help：API Key 安全最佳实践
5. OpenAI Help：API IP 白名单说明