logo

Cherry Studio API Key 怎么配置？

更新于 2026-10-30 · runapi.cfd

简答：Cherry Studio 的 API Key 不是统一从软件内生成，而是由你所使用的模型服务商提供。打开“设置→模型服务商”，选择对应服务商或自定义服务商，把 Key、API Host/Base URL 和模型 ID 按同一平台的文档填写，再同步或手动添加模型并执行模型检查。对于 runapi.cfd，公开资料中未核实到可直接引用的 Key 创建入口、Key 前缀或固定接口地址，因此不要套用未经确认的地址和模型名。

定义：Cherry Studio API Key 是模型服务商用于验证请求身份的凭证，必须与对应服务商的 API Host/Base URL 和模型 ID 配套使用。

先看这张配置对照表：你到底要填哪一种 Key

使用场景服务商类型Key 从哪里来Cherry Studio 中填写位置地址注意事项
直接调用模型服务商内置服务商或 OpenAI 兼容该服务商的控制台、开发者页面或官方账户设置设置→模型服务商→API Key使用服务商官方提供的 API Host/Base URL
第三方 OpenAI 兼容接口自定义服务商或对应兼容模板该接口服务商的账户后台自定义服务商的 API Key 字段不要把登录页、控制台地址当作 Base URL
让本地程序调用 Cherry StudioCherry Studio API GatewayCherry Studio 的设置→API Gateway 页面生成或显示填写 Gateway 页面提供的本地 URL 和 Bearer Key这是本地网关 Key，不是外部模型服务商 Key

Cherry Studio 官方文档说明，服务商配置通常包含 API Key、API Host 和模型管理；自定义接口应以实际服务商文档提供的凭证、地址和模型名为准。API Gateway 官方文档则说明，本地 Gateway 是把 Cherry Studio 已配置的模型能力提供给本地程序调用，不能把它误当成外部服务商账户。

Cherry Studio API Key 的正确配置步骤

  1. 先确认 Key 的来源。

    登录你实际使用的模型服务商账户，找到 API Key、开发者设置或密钥管理页面。Key 的具体前缀、权限、额度和有效期以该服务商当前文档为准。对于 runapi.cfd，本文未核实到可公开引用的官方 Key 创建页面，因此不写死注册路径、前缀或余额规则。

  2. 在 Cherry Studio 中选择服务商。

    打开“设置→模型服务商”。如果列表中没有对应服务商，可选择自定义服务商，并选择服务商实际支持的协议。Cherry Studio 官方文档将 OpenAI 兼容接口、Anthropic 兼容接口和 Gemini 等协议分开处理，不能因为模型名称相同就混用协议。

  3. 填写 API Key 和 API Host/Base URL。

    把真实 Key 填入 API Key 字段，把服务商文档中的接口根地址填入 API Host 或 Base URL。不要填写登录页面，也不要随意把完整的 /chat/completions 追加到根地址后面。Cherry Studio 会根据配置自动组合请求路径；如果服务商使用非标准路径，必须按其文档填写。

  4. 同步或手动添加模型。

    点击“Sync models”尝试获取模型列表。同步成功后，还要把需要使用的模型加入当前服务商的模型列表并启用服务商。如果同步失败但服务商明确提供了模型 ID，可以手动添加，然后执行模型检查。

  5. 执行模型检查并发送短消息。

    先选择一个文本模型，使用“Model Check”或连接检查功能。成功后再发送一条不带附件的短消息。Cherry Studio 文档提醒，模型列表同步和聊天调用可能是不同接口，因此同步失败不一定等于聊天接口不可用，但必须用实际请求继续验证。

可参考 Cherry Studio 的 API Key、API Host 与模型设置说明：Key 填入 API Key 对话框，API Host 应使用服务商要求的根地址，模型可通过同步或手动添加。

runapi.cfd 应该选什么服务商类型？哪些信息不能猜

如果你使用的接口文档明确写着 OpenAI-compatible，并且请求路径、认证方式和响应格式符合 OpenAI 兼容协议，可以在 Cherry Studio 中使用自定义服务商，并选择 OpenAI 兼容类型。若文档没有明确写出协议，不要仅凭“AI API”或模型名称判断。

截至 2026 年 10 月 30 日，本文没有核实到 runapi.cfd 可公开引用的官方 API 文档，因此以下信息均不能擅自填写：

  • API Key 是否必须以某个固定字符串开头；
  • API Host 是否必须包含 /v1；
  • 是否支持 /v1/models、/v1/chat/completions 或其他路径；
  • 可用模型 ID、权限范围、余额规则和并发限制；
  • 是否需要额外的组织 ID、项目 ID 或自定义请求头。

正确做法是从你当前账户可见的服务商文档复制 API 地址和模型 ID，再在 Cherry Studio 中配置。若同一账户同时出现多个域名、多个控制台或多套文档，不要交叉使用 Key、价格信息和 Endpoint；它们之间的关系未核实。

先在终端验证，再回到 Cherry Studio 配置

终端测试的目的不是替代 Cherry Studio，而是先把“Key 无效”和“客户端配置错误”分开。下面的地址、模型和 Key 都是占位符，必须替换成你从当前服务商文档获得的真实值；不要把真实 Key 写入脚本、截图、公开仓库或共享日志。

Bash 或 zsh

export API_BASE_URL='https://YOUR_PROVIDER.example/v1'
export API_KEY='REPLACE_WITH_REAL_KEY'
export MODEL_ID='REPLACE_WITH_MODEL_ID'

curl --fail-with-body --max-time 30 "$API_BASE_URL/models" \
  -H "Authorization: Bearer $API_KEY"

curl --fail-with-body --max-time 60 "$API_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"请只回复：连接成功\"}]}"

PowerShell

$env:API_BASE_URL = "https://YOUR_PROVIDER.example/v1"
$env:API_KEY = "REPLACE_WITH_REAL_KEY"
$env:MODEL_ID = "REPLACE_WITH_MODEL_ID"

curl.exe --fail-with-body --max-time 30 "$env:API_BASE_URL/models" `
  -H "Authorization: Bearer $env:API_KEY"

$body = @{ model = $env:MODEL_ID; messages = @(@{ role = "user"; content = "请只回复：连接成功" }) } | ConvertTo-Json -Depth 5
curl.exe --fail-with-body --max-time 60 "$env:API_BASE_URL/chat/completions" `
  -H "Authorization: Bearer $env:API_KEY" `
  -H "Content-Type: application/json" `
  --data-raw $body

成功判定是：模型列表请求返回可解析的模型数据，或聊天请求返回正常的助手文本。若接口文档规定的路径不是上述路径，不要强行套用示例，应以该服务商的请求示例为准。

401、403、404、429 和超时怎么分流

现象优先检查处理方法
401 UnauthorizedKey 是否为空、失效、未保存或认证头格式错误重新复制 Key，确认使用 Authorization: Bearer KEY，不要多加引号或空格。
403 Forbidden账户、地区、组织、模型权限或额度查看服务商账户权限和模型可用范围；不要把 403 简单归因于 Base URL。
404 Not FoundBase URL、重复路径、模型 ID检查是否把完整请求路径重复拼接，确认模型 ID 与服务商文档完全一致。
429 Too Many Requests限流、余额或账户配额先停止重复请求，查看响应头和服务商说明；只有明确属于临时限流时才按 Retry-After 和总时限重试。
超时或网络失败接口可达性、代理、DNS、防火墙和服务状态先用终端最小请求验证，再检查 Cherry Studio 的网络或代理设置。

Cherry Studio 的排错文档也将 401、403、404、429 和网络超时分别指向凭证、权限、地址或模型、限流以及网络可达性问题，可作为第一轮分流依据：查看官方错误排查说明。

外部服务商 API Key 与 Cherry Studio API Gateway Key 的区别

外部服务商 API Key用于 Cherry Studio 访问模型供应商。它通常填在“设置→模型服务商”的 API Key 字段，并与该供应商的 Base URL、模型 ID 配套。

Cherry Studio API Gateway Key用于其他本地程序访问 Cherry Studio 已经配置好的模型。启用 Gateway 后，外部程序使用 Gateway 页面显示的 URL，并通过 Authorization: Bearer <API Key> 认证。这个 Key 不能拿去登录外部模型服务商，外部服务商的 Key 也不能自动替代 Gateway Key。

Cherry Studio 官方建议本地 Gateway 默认只用于本机，并提醒不要把 Key 放进公开仓库、Issue、日志或教程截图。如果 Gateway Key 泄露，应先停止 Gateway，再重新生成 Key，并同步更新需要调用它的本地程序。

API Key 安全保存清单

  • 不要在文章、截图、浏览器前端代码、公开仓库和聊天群中展示真实 Key。
  • 不要把 Key 直接写入 Git 追踪的配置文件；本地开发优先使用环境变量或系统密钥存储。
  • 为不同设备、项目或用途使用不同 Key，便于单独撤销和轮换。
  • 发现 Key 进入日志、截图或仓库后，不要只删除文字；应立即在服务商后台撤销或轮换。
  • 不要因为请求失败就反复重试余额、权限或未知错误；先记录状态码和脱敏后的响应信息。
  • 如果使用 Cherry Studio 本地 API Gateway，除非已经配置网络监听、防火墙和访问控制，否则不要直接开放到局域网或公网。

常见问题

Cherry Studio 的 API Key 从哪里获取？

从你实际使用的模型服务商账户后台或官方开发者页面获取，不是由 Cherry Studio 统一发放。不同服务商的创建入口、前缀、权限和额度可能不同，以该服务商当前文档为准。

runapi.cfd 的 API Key 应该填在哪？

如果该接口文档明确支持 OpenAI 兼容协议，应填在 Cherry Studio 对应服务商或自定义服务商的 API Key 字段，并同时填写同一文档提供的 Base URL 和模型 ID。本文未核实到 runapi.cfd 可公开引用的固定 Key 创建入口、前缀或接口地址，因此不要直接套用网上的占位配置。

Base URL 要不要写 /v1？

不能一概而论。应复制服务商官方文档中的接口根地址；如果地址已经是完整请求路径，需按 Cherry Studio 的 API Host 拼接规则处理，避免重复添加 /v1 或 /chat/completions。

为什么 API Key 正确，Cherry Studio 还是 404？

优先检查 Base URL 是否重复拼接路径、模型 ID 是否精确、服务商协议是否选错，以及该接口是否真的支持 Cherry Studio 发出的请求路径。先用终端最小请求查看实际返回，再回到客户端修改。

Cherry Studio 的 Model Check 失败，但聊天有时能用，怎么办？

模型检查和模型列表同步可能调用不同接口。确认服务商支持的路径后，可手动添加准确模型 ID，再测试短文本；不要因为同步失败就自行更换 Key 或模型协议。

Cherry Studio API Gateway 的 Key 能当作外部 API Key 使用吗？

不能。Gateway Key 只用于访问本地 Cherry Studio 网关，而外部服务商 Key 用于访问服务商接口。两者的地址、签发位置和用途不同。

相关阅读

参考资料

  1. Cherry Studio：Model Service Configuration（cherryai.com）
  2. Cherry Studio：Model Service Settings（cherryai.com）
  3. Cherry Studio：Custom AI Service Provider（cherryai.com）
  4. Cherry Studio：API Gateway（cherryai.com）
  5. Cherry Studio：Troubleshooting（cherryai.com）
  6. cherryai.com（cherryai.com）
温馨提示
置顶

【RunAPI 新域名启用通知】
https://runapi.host
原域名 runapi.cfd 需要使用代理才能访问，RunAPI 现已启用新域名： https://runapi.host

新域名可直接访问，账户、余额及服务数据均不受影响。（注意：新域名在非代理环境下只可见国内模型，api调用不受影响）

2 个月前 · 2026-08-07 11:30

claude-haiku-5.5已上线

14 小时前 · 2026-10-09 12:14

gemini-nano-banana-2.1已上线

1 天前 · 2026-10-08 21:58

🎉 国庆限时充值 9 折！ 10 月 2 日 18:00:00 — 10 月 7 日 23:59:59，点击任意额度充值并选择支付宝支付，支付页面将自动享受 9 折优惠！

⚠️ 本次优惠仅限支付宝支付，Creem 支付暂未同步折扣，仍按原价结算。

1 周前 · 2026-10-02 19:02

gpt-6.1-sol已上线

1 周前 · 2026-10-01 23:20

claude-sonnet-5-5已上线
coding和claude_normal分组可使用

1 周前 · 2026-09-29 18:20

claude-opus-5-5, gpt-6-sol已上线

2 周前 · 2026-09-23 14:11

grok-4.7上线，grok、default分组可用
支持chat, responses,messages格式

2 周前 · 2026-09-22 13:35

【分组更新通知】
deepseek-sale分组上线，价格5折，支持v1/messages；v1/responses；v1/chat/completions格式请求

deepseek-v4.1-flash同步上线

提示：glm-sale和kimi-sale分组价格5折，接口均服务正常

3 周前 · 2026-09-13 23:10

gpt-image-2.5上线

0 个月前 · 2026-09-10 21:49

因官方下架gpt-5.4模型，平台codex分组已同步下架，需要调用该模型可切换至default/plus分组使用

1 个月前 · 2026-09-06 16:27

gpt-6-astra已上线

1 个月前 · 2026-09-05 14:58

gemini-3.8-flash已上线

1 个月前 · 2026-09-05 04:06

claude-fable-5-1已上线

1 个月前 · 2026-09-03 13:33

【分组更新通知】
1.kimi-sale分组5折
2.glm-sale分组5折
3.grok分组降价为0.7折，资源为grok heavy
以上均可通过v1/chat/completions；v1/responses；v1/messages格式调用

1 个月前 · 2026-09-03 10:50

glm-5.3, glm-5.3-flash
qwen3.8-flash, qwen3.7-flash
均已上线，default分组即可调用

1 个月前 · 2026-08-27 22:46

【公告】关于模型访问受限域名的处理说明
为遵守相关合规要求，平台已对模型访问政府类网站（gov域名）实施限制。
若您在对话过程中遇到提示“内容审计命中风险规则，请调整输入后重试”的报错，烦请移除对话中涉及的gov相关链接后再重新请求。
感谢您的理解与配合。

1 个月前 · 2026-08-22 22:11

最近codex更新后，如果遇到“401 token not provided”这个错误，是因为环境变量失效，重新配置后重启codex即可

1 个月前 · 2026-08-22 00:51

gemini-3.7-flash上线

1 个月前 · 2026-08-15 23:21

grok-4.6
qwen3.8-max
均已上线

1 个月前 · 2026-08-13 15:49