← 返回 V-API 是什么？功能、接入步骤与使用注意事项 首页

Cherry Studio 本地 API：从开启网关到成功调用

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

简答：Cherry Studio 本地 API 不是本地推理引擎，而是把 Cherry Studio 已配置的模型通过本机 HTTP 网关提供给其他程序。打开“设置→API 网关”并启动后，用页面显示的网关密钥、OpenAI 兼容 Base URL 和带 provider 前缀的模型 ID，即可先用 curl 验证，再接入 Python 或其他兼容客户端。

定义：Cherry Studio 本地 API 指 Cherry Studio API 网关提供的本机兼容接口，用于让脚本、编辑器或其他客户端调用 Cherry Studio 中已经配置好的模型。

先试这一步：5 分钟确认 Cherry Studio 本地 API 能否调用

本文面向已经安装 Cherry Studio、并且至少配置了一个可正常对话的模型服务的用户。Cherry Studio 的 API 网关默认不是普通聊天必需功能，需要外部程序调用时再启动；官方参考文档说明，网关可提供 OpenAI、Anthropic 和 Gemini 等兼容协议，默认本机地址为 http://127.0.0.1:23333。

先在 Cherry Studio 中完成以下最小闭环：

  1. 打开“设置→模型服务”，确认至少一个服务商已启用，API 地址、API Key 和模型可以通过连接检查。
  2. 打开“设置→API 网关”，确认端口未被占用，点击“启动”，等待状态变为“运行中”。
  3. 复制 API 网关页面显示的 URL 和网关密钥。这个密钥不是 OpenAI、Claude、Gemini 或其他上游服务商的 API Key。
  4. 在 OpenAI 兼容客户端中，Base URL 通常填写 http://127.0.0.1:23333/v1；如果你修改了端口，应使用页面显示的实际端口。
  5. 先查询模型列表，再发送一条简短请求。模型列表能读取且短文本返回成功，就说明本地 API 的地址、授权和模型路由基本正确。
项目应该填写什么容易混淆的地方
网关地址http://127.0.0.1:23333 或页面显示的实际地址这是 Cherry Studio 本机网关，不是上游服务商地址
OpenAI Base URLhttp://127.0.0.1:23333/v1OpenAI 兼容客户端通常需要带 /v1
授权密钥API 网关页面生成或显示的密钥不要填上游模型服务商的 Key
模型名从 /v1/models 返回结果中复制通常包含 provider:model 前缀格式
Cherry Studio 状态保持“运行中”关闭网关或退出应用后，本机客户端可能无法继续调用

上述入口、启动流程、网关密钥与上游凭证的区别，可参考 Cherry Studio API 网关文档 和 Cherry Studio API Gateway Reference。

curl 最小请求：先查模型，再调用聊天接口

下面的示例用于本机验证。请将 YOUR_GATEWAY_KEY 替换为 Cherry Studio API 网关密钥，不要把真实密钥提交到代码仓库、截图、Issue 或共享日志中。模型名不要凭印象填写，先从模型列表响应中的 id 复制。

1. 查询可用模型

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

成功判定：返回 JSON，并且能看到模型数组及模型 id。如果返回 401，优先检查密钥和请求头；如果连接被拒绝，优先检查 Cherry Studio 是否正在运行、网关状态是否为“运行中”、端口是否填写正确。

2. 发送一条最小聊天请求

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

把 provider:model-id 替换成模型列表返回的完整 ID。当前 API Gateway Reference 说明，OpenAI Chat 路由为 POST /v1/chat/completions，模型字段使用 providerId:modelId 形式；例如文档示例中的模型 ID 带有服务商前缀。具体模型是否可用，仍取决于 Cherry Studio 中对应的服务商和模型配置。

如果你的 Shell 对单引号或换行处理不同，请按当前终端语法调整 JSON。不要在命令行历史中直接写长期有效的真实密钥；更安全的做法是使用本机环境变量或由客户端的安全凭证存储管理。

Python 和 OpenAI 兼容客户端怎么填

只要客户端支持 OpenAI 兼容接口，通常需要三项：Base URL、API Key、模型名。Base URL 填 Cherry Studio 网关的 /v1 地址，API Key 填网关密钥，模型名填 /v1/models 返回的完整 ID。不要把“Cherry Studio 网关密钥”和“上游服务商 API Key”混用。

Python OpenAI SDK 示例

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CHERRY_GATEWAY_KEY"],
    base_url="http://127.0.0.1:23333/v1",
)

response = client.chat.completions.create(
    model="provider:model-id",
    messages=[
        {"role": "user", "content": "请只回复：连接成功"}
    ],
)

print(response.choices[0].message.content)

请先设置 CHERRY_GATEWAY_KEY，并将模型名替换为实际列表中的 ID。若 SDK 报模型不存在，不要先改请求路径，先重新执行 GET /v1/models，确认模型 ID、服务商前缀和 Cherry Studio 当前配置是否一致。

配置项对照

客户端字段推荐值核对方法
Base URLhttp://127.0.0.1:端口/v1以 API 网关页面当前显示的端口为准
API KeyCherry Studio API 网关密钥在 API 网关设置页重新复制，不使用上游 Key
Modelprovider:model-id从 /v1/models 的 id 字段复制
Stream先使用 false最小请求成功后再测试流式输出

Cherry Studio 的本地模型与本地 API 不是同一个概念。官方文档将本地模型描述为可下载、在本机离线运行且不需要服务商 API Key 的模型能力；API 网关则是把 Cherry Studio 已配置的模型能力通过 HTTP 提供给其他程序。因此，配置了本地嵌入或 OCR 模型，并不等于已经有一个可供 OpenAI 兼容客户端调用的聊天 API。可参考 Cherry Studio 本地模型说明。

401、403、404、连接拒绝和端口冲突排查表

排查时不要同时修改地址、密钥和模型名。建议按照“网关状态→模型列表→最小聊天请求”的顺序逐层确认。

现象常见原因处理步骤
连接被拒绝、无法建立连接Cherry Studio 未运行、网关未启动、端口填写错误或端口冲突打开“设置→API 网关”，确认状态为“运行中”；停止网关后换用未占用端口，再重新启动
401 Unauthorized使用了上游 Key、网关 Key 已变化、Bearer 格式错误或存在多余空格重新复制网关密钥，确认请求头为 Authorization: Bearer YOUR_GATEWAY_KEY
403 Forbidden请求被当前网关权限或客户端访问边界拒绝先用本机回环地址测试，不要先开放局域网；检查 API 文档和当前设置页的访问控制
404 Not FoundBase URL 多写或少写路径、端点与协议不匹配OpenAI 兼容客户端通常使用带 /v1 的 Base URL；不要把完整的 /v1/chat/completions 再重复拼接
模型不存在模型名未使用 provider 前缀、模型已在 Cherry Studio 中移除或服务商未启用先请求 /v1/models，复制返回的完整 id，再确认模型服务连接检查通过
端口无法启动默认端口已被其他程序占用停止网关后修改端口；选择可用端口并用页面显示的 URL 更新客户端

Cherry Studio 常见问题页面也建议在 API Key 正确但无法对话时，检查服务商是否启用、API 地址是否正确、默认模型是否属于该服务商，并在网关无法启动时检查端口占用和本机安全软件拦截。可参考 Cherry Studio 常见问题。

如果需要让其他设备访问，不要直接把本机网关暴露到局域网或公网。先确认当前版本的网络访问设置、监听范围、防火墙规则和访问控制；只给确实需要调用的程序使用密钥。若密钥疑似泄露，先停止网关，再按当前设置页提供的重新生成方式轮换密钥，并同步更新本机客户端。

常见问题

Cherry Studio 本地 API 和 Ollama、LM Studio 是一回事吗？

不是。Ollama、LM Studio 等通常承担本地模型推理或模型服务；Cherry Studio API 网关负责把 Cherry Studio 中已经配置好的模型能力转换成可供其他程序调用的 HTTP 接口。Cherry Studio 也有独立的本地嵌入和 OCR 模型，两者不等于聊天 API。

Cherry Studio 本地 API 的地址应该填 127.0.0.1:23333 还是带 /v1？

如果客户端字段叫 Base URL，并且客户端使用 OpenAI 兼容接口，通常填写 http://127.0.0.1:23333/v1。普通网关地址则是 http://127.0.0.1:23333/。端口被修改后，以 API 网关页面当前显示的端口为准。

为什么我把 OpenAI API Key 填进去仍然返回 401？

因为本地 API 的授权对象是 Cherry Studio 网关。请求必须使用 API 网关页面提供的密钥，并通过 Authorization: Bearer 密钥发送；OpenAI、Claude 或其他上游服务商的 Key 只用于 Cherry Studio 内部连接上游服务。

Cherry Studio 关闭后，其他客户端还能继续调用吗？

通常不能。API 网关运行在 Cherry Studio 本机进程中，外部程序调用期间应保持 Cherry Studio 和网关处于运行状态。先请求 /v1/models，再发送短文本，可以快速确认网关是否仍可用。

模型列表里没有我想要的模型怎么办？

先在 Cherry Studio 的模型服务设置中同步或手动添加模型，确认服务商已启用并通过连接检查；然后重新请求 /v1/models。模型名应使用返回结果中的完整 id，不能只凭上游平台的模型名称猜测。

相关阅读

参考资料

  1. Cherry Studio API 网关文档
  2. Cherry Studio API Gateway Reference
  3. Cherry Studio 本地模型说明
  4. Cherry Studio 常见问题（cherryai.com.cn）