AI API 聚合平台：190+ 大模型、图像与视频模型

Cherry Studio API 服务器怎么配置和使用？

更新于 2026-10-28 · apimart.cyou

简答：Cherry Studio 的 API 服务器通常指 API Gateway：它会把 Cherry Studio 中已经配置好的模型，通过本地 HTTP 接口提供给 OpenAI 兼容客户端调用。最短流程是先在“设置→模型服务”中确认一个模型可用，再到“设置→API 网关”启动服务，复制网关地址和网关 Key，使用 /v1/models 查询模型 ID，最后调用 /v1/chat/completions。注意，网关 Key 不等于上游模型服务商的 API Key，而且调用期间 Cherry Studio 必须保持运行。

定义：Cherry Studio API Gateway 是运行在 Cherry Studio 桌面端上的本地 API 网关，用于把已配置的模型转换为 OpenAI、Anthropic 或 Gemini 等协议，供其他客户端调用。

先看结论：Cherry Studio API 服务器的配置对照表

本文按本文核对到的 Cherry Studio API Gateway 文档整理。Cherry Studio 不是直接把某个上游 API Key 原样转发给客户端，而是由桌面端保存服务商和模型配置，再由网关接收客户端请求并转发给已选模型。

项目应填写或执行的内容容易混淆的地方
上游模型配置设置→模型服务，填写服务商地址、上游 API Key，并确认模型可以正常对话这是 Cherry Studio 连接模型服务商的配置，不是 API 网关地址
启动入口设置→API 网关→启动普通 Cherry Studio 对话不一定需要启动网关
默认 OpenAI Base URLhttp://127.0.0.1:23333/v1如果修改了端口，使用界面显示的端口；不要把上游服务商地址填到这里
网关 API Key在 API 网关页面复制或重新生成的 Key与上游服务商 API Key 是两套凭证
模型 ID先请求 /v1/models 查询，再使用返回的 id模型 ID 通常包含服务商前缀，例如 provider:model
运行条件调用期间保持 Cherry Studio 运行且 API 网关状态为 Running关闭桌面端后，本地网关通常也无法继续提供模型请求

Cherry Studio 的开发文档说明，默认网关端口为 23333，OpenAI 兼容客户端的默认 Base URL 为 http://127.0.0.1:23333/v1；网关的模型列表接口为 GET /v1/models，聊天接口为 POST /v1/chat/completions。可参考 Cherry Studio API Gateway Reference。

Cherry Studio API 服务器的完整使用步骤

第 1 步：先确认至少有一个可用模型

打开 Cherry Studio 的“设置→模型服务”，确认服务商已经启用，并检查 API 地址、API Key 和默认模型。先在 Cherry Studio 内发送一条普通对话，确保上游配置本身可用。如果模型在桌面端都不能正常响应，直接启动 API 网关也不能解决上游认证、配额或模型不可用问题。

官方常见问题建议：API Key 已填写但无法对话时，应依次检查服务商是否启用、API 地址是否正确、连接检查结果以及默认模型是否属于当前服务商；如果模型列表为空，还要检查模型类型和接口是否匹配。参考 Cherry Studio 常见问题。

第 2 步：启动 API Gateway

  1. 打开“设置→API 网关”。
  2. 确认当前状态为停止或未运行。
  3. 如果默认端口 23333 已被占用，改用其他可用端口。
  4. 点击“启动”，等待状态变为 Running。
  5. 复制页面显示的服务器地址和 API Key。

当前公开 API Gateway 文档显示，网关首次激活时会生成网关 API Key；端口设置范围为 1000 至 65535。网关启动后不要关闭 Cherry Studio，否则外部客户端无法继续通过该桌面端转发模型请求。

第 3 步：先查询模型，不要手填猜测值

在运行 Cherry Studio 的同一台电脑上，用下面的命令查询网关实际暴露的模型：

curl http://127.0.0.1:23333/v1/models -H "Authorization: Bearer YOUR_CHERRY_GATEWAY_KEY"

将 YOUR_CHERRY_GATEWAY_KEY 替换为 API 网关页面显示的 Key。如果修改了端口，也要同步修改 URL。成功响应通常是 JSON 列表，读取其中的 data[].id 作为后续请求的模型值。当前网关文档说明，模型 ID 使用 providerId:modelId 形式，例如 anthropic:claude-sonnet-4-6；不要把这个示例直接当成你电脑上的可用模型，必须以 /v1/models 返回结果为准。

第 4 步：发送最小 OpenAI 兼容请求

从模型列表复制一个真实的模型 ID，再执行：

curl http://127.0.0.1:23333/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer YOUR_CHERRY_GATEWAY_KEY" -d '{"model":"YOUR_PROVIDER_MODEL_ID","messages":[{"role":"user","content":"请只回复：连接成功"}],"stream":false}'

其中 YOUR_PROVIDER_MODEL_ID 必须替换为模型列表中的实际 ID。成功判定不是只看 HTTP 状态码，还应确认响应 JSON 中出现 choices 和模型输出内容。若返回 401 或 403，先停止继续尝试，检查网关 Key 和请求头；若返回 404，检查端口、路径和网关状态；若返回模型不存在，重新查询 /v1/models。

第 5 步：在其他 OpenAI 兼容客户端中填写

以支持自定义 OpenAI Base URL 的客户端为例，填写以下三项：

如果客户端要求填写完整请求地址，先确认它是否会自动拼接 /chat/completions。多数 OpenAI 兼容客户端的 Base URL 应停在 /v1，而不是直接填 /v1/chat/completions。如果客户端自身会拼接版本路径，还要根据该客户端的字段说明避免重复出现 /v1/v1。

本机访问、局域网访问与远程设备访问有什么区别？

默认情况下，API Gateway 监听本机回环地址，典型地址是 127.0.0.1，适合让同一台电脑上的 Open WebUI、Chatbox、脚本或其他客户端调用。对于这种本机调用，通常不需要打开网络访问选项。

如果另一台设备要访问 Cherry Studio，需要区分普通 HTTP API 与远程设备配对功能。当前 API Gateway 参考文档说明，开启网络访问后，网关会从回环监听切换到所有 IPv4/IPv6 接口；这会扩大可连接范围，因此不应把网关 Key 放进不受控的客户端，也不要在没有访问控制的网络中随意暴露端口。先确认设备处于可信网络，再按 Cherry Studio 当前设置页面提供的网络访问或设备连接流程操作。

使用场景Base URL 示例是否需要网络访问
同一台电脑上的客户端http://127.0.0.1:23333/v1通常不需要
同一局域网的另一台电脑http://运行 Cherry Studio 的电脑局域网 IP:端口/v1需要按当前版本设置开启并确认防火墙允许
远程设备配对或移动设备按 Cherry Studio 的设备连接流程处理需要设备连接与配对授权，不等同于普通本机 API 调用

如果只是让本机客户端使用模型，不要为了“能连接”而先打开局域网访问；先用 127.0.0.1 完成最小请求，再处理跨设备访问。

常见报错：按证据顺序排查

现象优先检查处理方法
连接被拒绝或超时Cherry Studio 是否运行、API Gateway 是否为 Running、端口是否正确回到 API 网关页面确认状态；再用 GET /v1/models 测试，不要直接反复发送聊天请求
401 Unauthorized请求是否缺少认证头，Key 是否为空或复制不完整OpenAI 兼容接口使用 Authorization: Bearer 网关Key；确认填写的是网关 Key，不是上游 Key
403 ForbiddenKey 是否错误，或网关尚未生成有效 Key从 API 网关页面重新复制或重新生成 Key；不要继续猜测模型和地址
404 Not FoundBase URL 是否重复拼接路径，端口是否对应当前网关先请求 /v1/models；Base URL 通常填写到 /v1，聊天客户端再自动拼接资源路径
模型不存在模型 ID 是否手填、是否遗漏服务商前缀重新读取 /v1/models 的 data[].id，完整复制返回值
端口占用、启动失败其他程序是否占用了默认端口在网关停止状态下更换端口，再用新端口更新客户端 Base URL
网关请求返回上游错误Cherry Studio 内部模型服务商配置、额度、上游网络或模型权限先在 Cherry Studio 内对同一模型发起普通对话；如果桌面端也失败，优先检查上游服务商配置

网关认证规则可概括为：OpenAI 风格请求使用 Authorization: Bearer，也可按协议使用相应的认证头；没有凭证通常返回 401，凭证不匹配通常返回 403。具体响应格式会随 OpenAI、Anthropic 或 Gemini 路径不同而变化，不能把某一协议的错误 JSON 结构直接套到其他协议。

API 网关与普通模型服务商配置，不要混为一谈

普通模型服务商配置解决的是“Cherry Studio 如何连接上游模型”。你需要在 Cherry Studio 中填写服务商地址、上游 API Key 和模型信息，并通过连接检查或实际对话确认配置可用。

API Gateway 配置解决的是“其他客户端如何连接 Cherry Studio”。其他客户端填写的是 Cherry Studio 网关地址、网关 API Key 和网关返回的模型 ID。客户端请求先到 Cherry Studio，再由 Cherry Studio 调用已配置的上游模型。

因此，下面三项不能互换：

如果你只是想在 Cherry Studio 内聊天，不需要为了普通对话启动 API Gateway。官方文档将“其他本地应用使用 Cherry Studio 的模型”和部分需要模型桥接的智能体场景列为网关用途；普通聊天可以不启用网关。可参考 Cherry Studio 使用文档。

安全与复制检查清单

如果你使用的是某个具体客户端，最稳妥的方式是先确认它的 Base URL 是否自动拼接 /v1、是否要求完整模型 ID，以及它发送的是 OpenAI Chat Completions 还是 OpenAI Responses 请求。Cherry Studio 网关文档同时列出了 /v1/chat/completions、/v1/responses、Anthropic 的 /v1/messages 以及 Gemini 的 /v1beta 路径，协议字段不完全相同。

常见问题

Cherry Studio API 服务器默认地址是多少？

当前 API Gateway 参考文档给出的默认本机地址是 http://127.0.0.1:23333/；OpenAI 兼容客户端通常使用 http://127.0.0.1:23333/v1。如果你在设置中修改了端口，应以 API 网关页面显示的地址为准。

Cherry Studio API Key 和上游 API Key 是同一个吗？

不是。上游 API Key 用于 Cherry Studio 连接模型服务商；API Gateway Key 用于其他客户端访问 Cherry Studio 本地网关。调用网关时，应使用 API 网关页面生成或显示的 Key。

为什么客户端提示模型不存在？

不要直接猜模型名称。先用网关 Key 请求 /v1/models，复制返回结果中的 data[].id。Cherry Studio 网关的模型 ID 可能包含服务商前缀，例如 provider:model；实际可用值以你当前网关返回的列表为准。

使用 Cherry Studio API 服务器时必须一直开着软件吗？

通常需要。API Gateway 运行在 Cherry Studio 桌面端上，外部客户端的请求需要经过该网关转发到已配置的模型服务商。关闭 Cherry Studio 或停止 API Gateway 后，依赖它的客户端通常无法继续调用。

同一局域网的另一台电脑如何连接？

先在本机用 127.0.0.1 完成模型列表查询和最小请求，再按当前版本的网络访问设置启用跨设备访问。另一台电脑使用运行 Cherry Studio 的设备局域网 IP、对应端口和网关 Key；同时检查操作系统防火墙及网络范围，不要在不受控网络中暴露接口。

相关阅读

参考资料

  1. Cherry Studio API Gateway Reference
  2. Cherry Studio 常见问题（cherryai.com.cn）
  3. Cherry Studio 使用文档（cherryai.com.cn）