Cherry Studio 身份验证失败：API 密钥、Base URL 与模型排查步骤

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

简答：Cherry Studio 出现“身份验证失败，请检查 API 密钥是否正确”时，先重新保存一个未泄露、无空格和换行的 API Key，再确认服务商类型、Base URL 和模型 ID 完全匹配。若使用 OpenAI 兼容接口，先用简短纯文本测试；401 查 Key，403 查权限，404 查地址或模型，429 查额度和限流。

定义：Cherry Studio 身份验证失败，是客户端向模型服务发起请求时，服务端拒绝了密钥、权限、请求地址或模型组合，不一定代表 API Key 本身已经失效。

先做这 6 步：最快区分 API Key、地址还是模型问题

本文是第三方接入排查说明，不代表任何模型服务或 API 网关的官方页面。需要注意的是，公开资料中可以查到使用 https://runapi.ai/v1 的 Cherry Studio 配置示例，但 runapi.cfd 与 runapi.ai 是否属于同一服务、同一入口或同一账户体系，本文未能从公开资料确认。不要因为名称相似，就交叉使用密钥、文档、价格或 Base URL。

在服务商控制台重新复制 API Key，去掉首尾空格、换行和多余引号；不要把完整 Key 发到群聊、截图或工单中。
在 Cherry Studio 打开“设置 → 模型服务”，服务商类型选择 OpenAI，并确认服务商已启用。
API 地址只填写服务商文档要求的 Base URL。对于公开配置示例，地址是 https://runapi.ai/v1，不要再手动追加 /chat/completions。
手动添加一个服务商明确支持的模型 ID。模型名称相似时，以模型管理页面显示的实际 API 模型 ID 为准。
点击保存，再用已保存的单个模型执行连接检查；不要一开始同时启用多个 Key、多个模型或多个服务商。
新建对话，在顶部确认选中的是当前服务商和模型，发送“只回复 connected。”作为最终验证。

Cherry Studio 官方文档说明，连接检查依赖已选择的模型；配置完成后还必须打开服务商的启用开关，模型才会出现在选择列表中。查看 Cherry Studio 模型服务设置说明。

配置项怎么填：不要把完整接口地址当成 Base URL

配置项	建议填写或检查	常见错误
服务商类型	`OpenAI` 或 OpenAI 兼容类型	误选 Anthropic、Gemini 或本地服务商类型
API Key	从当前服务商控制台复制，确认有效、完整并已保存	复制了网页登录密码、带空格的 Key、被撤销的旧 Key
API 地址	填写文档规定的根地址或 Base URL	重复填写 `/v1`，或手动追加 `/chat/completions`
模型 ID	使用服务商实际支持的 identifier	只看展示名称，填入不存在或不支持的模型 ID
启用状态	打开服务商启用开关	配置保存了，但聊天窗口没有使用该服务商
当前对话	顶部选择目标服务商下的目标模型	仍选中了 Ollama、其他云服务商或旧模型

Cherry Studio 的配置文档说明，API 地址通常应按服务商文档填写；模型列表中的实际 API 模型 ID 需要单独核对，只有加入模型列表的模型才会出现在选择器中。查看官方模型服务设置文档。

如果你参考的是 runapi.ai 的公开 Cherry Studio 页面，该页面要求使用自定义 OpenAI 服务商、填写 https://runapi.ai/v1，并强调 Cherry Studio 会自动补充 Chat Completions 路径。由于你的搜索词指向 runapi.cfd，实际地址仍应以你当前账户对应的服务文档为准，无法核实时不要照抄。查看公开配置示例。

按错误现象分流：401、403、404、429 分别查什么

401 或 Authentication failed：优先检查 API Key 是否完整、有效、已保存并启用。确认没有把 Key 粘贴到错误的服务商，也要检查当前对话是否仍使用旧配置。
403：重点检查账户、组织、地区、目标模型或权限限制。只重新生成 Key，未必能解决权限拒绝。
404：重点检查 Base URL、请求路径和模型 ID，尤其排查是否重复拼接了 /v1 或 /chat/completions。
429：检查账户额度、请求频率和服务商限流。不要连续点击发送或盲目重试；先等待限制恢复，并确认账户状态。
网络失败或超时：检查当前网络是否能访问服务商地址、代理设置是否冲突，以及是否只有 Cherry Studio 无法连接。

Cherry Studio 官方常见问题将 401、403、404、429 分别归因到认证、权限、地址或模型、限流等不同方向；这意味着看到“API 密钥不正确”时，不能跳过状态码和请求详情。查看 Cherry Studio 官方错误排查表。

连接检查成功，但实际聊天仍然失败怎么办

回到服务商设置，重新编辑 API Key 并点击保存；只关闭窗口不一定代表密钥编辑已经保存。
暂时只保留一个 API Key、一个模型和一个服务商，避免多 Key 轮询或模型切换掩盖真实问题。
在聊天窗口顶部重新选择该服务商下的模型，不要只依赖全局默认模型。
先发送不带附件、不调用工具的短文本，例如“只回复 connected。”；文字成功后，再测试图片、工具或长上下文。
如果连接检查通过、短文本仍返回 401，记录 Cherry Studio 版本、请求使用的模型和服务商，不要公开完整 API Key，然后检查客户端更新与已知问题。

连接检查成功只能说明检查时使用的服务商、Key 和模型组合能够完成一次测试请求；实际聊天可能因为当前对话选了不同模型、配置未保存、请求能力不同或客户端问题而失败。Cherry Studio 的公开问题记录中曾出现“Key 检查通过但聊天请求仍失败”的案例，因此应把“检查成功”和“当前对话成功”分开验证；该记录本身不证明所有用户都会遇到同样问题。查看相关公开问题记录。

不要把 Ollama、本地模型和云端 API 混在一起

连接方式	API Key	Base URL	排查重点
云端 OpenAI 兼容服务	通常需要服务商提供的 API Key	按服务商文档填写	Key、地址、模型 ID、权限和限流
Ollama 本地模型	通常不是云端 Key 场景	按本机 Ollama 配置填写	本地服务是否启动、端口是否可访问、当前模型是否存在
其他云端服务商	使用对应服务商的 Key	不能直接套用另一家的地址	服务商类型、协议路径和模型能力

如果你原本想调用本地 Ollama，却在 Cherry Studio 顶部选中了某个云端服务商的模型，客户端就可能向云端发送请求并返回认证错误。解决方法是先确认当前对话顶部显示的服务商，再分别检查本地服务或云端 Key；不要只根据模型名称判断连接来源。

最后的安全检查：确认能用后也不要暴露 Key

不要在截图、日志、公开仓库或问题帖中粘贴完整 API Key。
如果 Key 已经泄露，优先在服务商控制台撤销并重新生成，而不是继续观察是否被使用。
排障时只保留一个临时测试 Key，测试结束后清理不再使用的配置。
命令行或脚本测试时避免把 Key 直接写进 Shell 历史、共享终端记录或公开配置文件。
无法确认服务域名归属时，先停止输入真实 Key，核对账户后台、文档域名和 API 地址是否属于同一服务。

完成“单 Key、单模型、单服务商、短文本”的最小验证后，如果仍失败，再根据具体状态码联系对应服务商或 Cherry Studio 官方反馈渠道。不要把模糊的“身份验证失败”直接等同于密钥失效。

常见问题

Cherry Studio 显示身份验证失败，一定是 API Key 错了吗？

不一定。401 通常优先查 API Key，但 Base URL、当前服务商、配置保存状态、模型选择和客户端请求路径也可能导致认证失败。先用单个 Key、单个模型和短文本请求复现。

API 地址应该填到 /chat/completions 吗？

通常不要直接追加完整的 /chat/completions。OpenAI 兼容服务一般要求填写服务商规定的 Base URL，由 Cherry Studio 自动拼接请求路径；但如果当前服务商文档明确要求完整地址，应以该文档为准。

为什么连接检查成功，聊天还是提示 API 密钥不正确？

常见原因是连接检查和实际聊天使用了不同模型或服务商，配置没有真正保存，启用了多 Key 轮询，或者客户端版本存在兼容问题。重新保存配置，暂时只留一个 Key 和模型，再在新对话中发送短文本。

模型选择器为空，应该先换 API Key 吗？

不一定。先确认服务商已启用，再同步模型列表或手动添加准确的模型 ID。某些服务商的模型列表接口和对话接口可能独立，列表同步失败不必然代表对话接口不可用。

Ollama 本地模型也需要云端 API Key 吗？

如果你调用的是本机 Ollama，排查重点通常是本地服务是否启动、地址和模型是否存在；如果 Cherry Studio 实际选中了云端服务商模型，则仍会按照云端服务商的认证规则请求。先确认当前对话顶部的服务商名称。

Run API