Cherry Studio 提示身份验证失败，请检查 API 密钥是否正确怎么办？
简答：先不要反复重填 API Key：在 Cherry Studio 的“设置→模型服务”中确认服务商已启用、密钥已保存且未带空格，再核对 API Host 是否填写根地址、模型 ID 是否属于该服务商。若“模型检查”通过但发送消息仍返回 401，应继续检查实际请求路径、默认模型、账户权限和服务商端配置。
定义：Cherry Studio 的“身份验证失败”通常表示服务商在认证或请求阶段拒绝了当前凭据，但具体原因还可能是 API Host、模型、权限、额度或网络配置不匹配。
先按这个顺序检查：不要只盯着 API Key
Cherry Studio 的错误提示把多种情况都概括成了“身份验证失败”。真正排查时，应先区分是连接检查失败，还是连接检查通过、实际聊天失败。官方文档说明，模型检查使用当前服务商配置中的模型；检查成功只代表这一组“服务商、密钥、地址和测试模型”能够完成该次请求，并不代表所有模型都可用。
| 现象 | 优先检查 | 处理方向 |
|---|---|---|
| 模型检查直接失败，返回 401 | Key 是否完整、保存、启用 | 重新添加密钥，并确认使用的是对应服务商的 Key |
| 模型检查失败，返回 403 | 账户、地区、组织或模型权限 | 到服务商账户页面确认 API 权限和目标模型权限 |
| 返回 404 | API Host、接口路径、模型 ID | 检查是否重复填写 /v1/chat/completions 或模型名称错误 |
| 返回 429 | 额度、限流、并发 | 停止连续重试，确认账户额度和服务商限制 |
| 检查通过但聊天失败 | 实际使用的模型、默认模型、请求路径 | 把聊天模型切换为刚刚检查成功的模型，再查看详细错误 |
| 超时或网络失败 | 代理、系统网络、服务商可达性 | 检查 Cherry Studio 的代理模式和服务商地址是否可访问 |
Cherry Studio 官方排障表也建议将 401、403、404、429 和网络失败分开处理，而不是把所有问题都归因于密钥错误。Cherry Studio 官方排障说明
第一步：重新保存并启用 API Key
- 打开 Cherry Studio，进入“设置→模型服务”。
- 打开出现错误的服务商配置，不要只在聊天页面切换模型。
- 删除当前 Key 后，通过“添加 API Key”重新粘贴，再点击保存。
- 检查密钥前后是否混入空格、换行或不可见字符；不要把完整 Key 粘贴到日志、工单或截图中。
- 确认右上角服务商开关已开启。服务商未启用时，即使密钥已经保存，模型也可能不会出现在聊天模型列表中。
- 点击“模型检查”，优先选择一个由该服务商确认支持的文本模型。
Cherry Studio 文档说明，API Key 可能被称为 Key、API Key 或 Token；在配置页面中它们都用于服务商认证。文档还明确要求先保存密钥，并在配置完成后启用服务商。Cherry Studio 模型服务设置文档
如果你配置了多个 Key，也要确认分隔符是英文逗号，而不是中文逗号或换行。排查时建议暂时只保留一个已确认有效的 Key，避免轮换密钥导致每次请求使用的凭据不同。
第二步：核对 API Host，避免重复拼接请求路径
API Host 是最容易填错的字段之一。对于 OpenAI 兼容服务，服务商文档可能展示完整请求地址，例如 https://example.com/v1/chat/completions，但 Cherry Studio 通常要求填写根地址，而不是把完整路径全部复制进去。
例如服务商文档给出：
https://example.com/v1/chat/completions常规情况下，Cherry Studio 的 API Host 应填写：
https://example.com如果你填写成：
https://example.com/v1/chat/completions软件可能再次拼接请求路径，最终形成错误地址。Cherry Studio 官方文档说明：当服务商给出完整的 /v1/chat/completions 地址时，通常只填写根地址；如果服务商使用非标准路径，则应按照服务商文档使用以斜杠或 # 结尾的特殊写法。
不要凭经验给所有平台都加上 /v1。有些服务商的接口版本、协议或路径不同，最终应以该服务商当前公开文档为准。API Host 路径拼接规则见 Cherry Studio 官方文档
第三步：确认模型 ID、协议类型和默认模型一致
密钥正确，不代表任意模型都能调用。Cherry Studio 官方文档将服务商按协议区分为 OpenAI-compatible、Anthropic-compatible、Gemini、Azure OpenAI、本地推理和特殊网关等类型。模型名称相同或相似，也不代表不同平台可以共用同一个模型 ID。
- 在服务商页面点击“同步模型”，看平台返回的模型列表。
- 如果同步失败，按照服务商公开文档手动添加准确的模型 ID。
- 确认模型是聊天模型，而不是仅支持 embedding、图像或其他任务的模型。
- 在聊天页面手动选择刚刚完成连接检查的模型，不要继续使用旧的默认模型。
- 如果只配置了自定义服务商，确认选择的协议类型与服务商提供的接口格式一致。
官方说明指出，模型同步接口和聊天接口可能不是同一个接口；同步失败不一定意味着模型无法聊天，可以手动添加服务商提供的准确模型 ID，然后单独执行模型检查。Cherry Studio 错误码与模型排障说明
连接检查通过，但发送消息仍然提示 401，怎么办？
这类情况不能简单判断为“Key 一定有效”。连接检查与实际聊天可能使用不同模型、不同请求参数，甚至不同的服务商配置。公开的 Cherry Studio 问题记录中，就出现过 API Key 验证通过，但聊天请求仍返回 401 的案例；该记录还显示了实际请求路径和 OpenAI 兼容调用栈，因此排查重点应从“重新安装软件”转向实际请求配置。Cherry Studio 公开问题记录
- 把聊天页面的模型切换为连接检查成功的同一个模型。
- 确认聊天页面没有选择同名但属于另一个服务商的模型。
- 重新打开服务商配置，检查 API Host 和服务商开关是否仍然有效。
- 如果是自定义服务商，核对它使用的是 OpenAI-compatible、Anthropic-compatible 还是其他协议。
- 查看错误详情中的 HTTP 状态码、请求地址和模型名称；只保留脱敏后的信息，不要提交完整 API Key。
- 如果只有某一个模型失败，优先判断模型权限或模型 ID 问题；如果所有模型都失败，再回到 Key、Host、账户权限和网络检查。
不要把“重启、卸载、重装”作为第一步。重装无法修复服务商撤销 Key、账户没有 API 权限、模型不可用或 API Host 错误等服务端问题。
按错误码分支处理：401、403、404、429 和超时
401：未授权或认证凭据未被接受
优先检查 Key 是否完整、有效、已保存并已启用；再检查服务商是否对应、API Host 是否正确，以及是否把网页端登录信息误当成 API Key。网页端会员状态和 API 调用权限不是同一个配置项，具体是否需要单独开通 API，以服务商当前说明为准。
403：有凭据，但没有访问权限
403 更像是账户、地区、组织、模型权限或服务商策略问题。此时继续复制粘贴同一个 Key 通常没有帮助，应到服务商账户页面确认 API 权限、组织选择和目标模型可用性。
404：地址或模型不存在
检查 Base URL 是否重复拼接路径，模型 ID 是否完全匹配服务商文档，以及协议类型是否选错。Cherry Studio 官方排障说明把基础地址、接口和模型 ID列为 404 的优先检查项。
429：请求过多或额度限制
停止连续点击发送，等待限制恢复后再测试，并检查账户额度、并发限制和服务商当前政策。不要通过不断重试来验证 Key，这可能让限流持续更久。
超时、连接失败或代理错误
如果错误不是 HTTP 401，而是超时、连接失败或 API request failed，应检查 Cherry Studio 的“设置→通用→代理模式”。官方文档说明，系统代理、手动代理和不使用代理会影响模型 API 请求的网络路径；具体选择应与当前系统网络环境一致。Cherry Studio 代理设置文档
自定义 OpenAI 兼容接口的最小配置清单
如果你使用的是自定义网关或兼容接口，可以按下面的最小字段逐项核对：
| 字段 | 应该核对什么 | 常见错误 |
|---|---|---|
| 服务商类型 | 是否选择了服务商实际支持的协议 | 把 Anthropic 接口当成 OpenAI 接口 |
| API Key | 是否为该服务商签发、已保存、未撤销 | 使用网页登录密码或其他平台的 Key |
| API Host | 是否为服务商要求的根地址或固定路径 | 重复填写 /v1/chat/completions |
| 模型 ID | 是否为服务商真实支持的完整 ID | 只填写展示名称或使用其他平台的模型名 |
| 启用状态 | 服务商和模型是否都已启用 | 配置保存了，但开关仍关闭 |
| 测试模型 | 是否为可进行文本对话的模型 | 使用 embedding、图像或无权限模型测试 |
Cherry Studio 的自定义服务商文档建议从“设置→模型服务”进入自定义服务商，填写 API Key、API Host，并通过同步或手动方式添加模型；具体地址和模型名称必须以服务商文档为准。Cherry Studio 自定义服务商文档
仍未解决时，如何安全收集信息？
- 记录错误码，例如 401、403、404、429 或超时，不要只记录“身份验证失败”。
- 记录脱敏后的服务商名称、协议类型、模型 ID 和 API Host 域名。
- 记录连接检查是否成功，以及连接检查和实际聊天是否使用同一个模型。
- 截图时遮盖 API Key、Authorization、Token、Cookie 和完整请求头。
- 如果提交反馈，保留软件版本、操作系统、错误详情和请求路径，但删除密钥及其片段。
如果你需要同时管理多个 OpenAI 兼容接口，建议把每个服务商的 Base URL、模型 ID 和 Key 分开保存，先用最小请求验证，再接入 Cherry Studio，避免把客户端界面问题与服务商端权限问题混在一起。
常见问题
Cherry Studio 提示身份验证失败，一定是 API Key 错了吗？
不一定。401 常与 Key 不完整、未保存、已撤销或服务商不匹配有关，但 API Host 重复拼接、模型不属于该服务商、协议类型错误，也可能让请求失败。先查看 HTTP 状态码和错误详情，再决定是否更换 Key。
为什么 Cherry Studio 的模型检查通过，聊天时仍然提示 401？
模型检查通过只说明测试时使用的那组服务商、Key、地址和模型能够完成请求。聊天页面可能选择了另一个服务商、默认模型或不同配置。请把聊天模型切换为检查成功的同一个模型，并重新核对 API Host、模型 ID 和服务商开关。
API Host 应该填写到 /v1/chat/completions 吗？
通常不应直接复制完整请求地址。若服务商给出 https://example.com/v1/chat/completions，Cherry Studio 通常填写 https://example.com/，由软件补充路径。非标准接口应按服务商文档和 Cherry Studio 的路径规则填写。
网页端能登录，为什么 Cherry Studio 仍然无法调用？
网页端登录、订阅资格和 API Key 是不同的认证方式。Cherry Studio 调用模型时需要服务商支持的 API 凭据或账户连接方式；是否有独立 API 权限、额度和模型权限，应以对应服务商当前说明为准。
重新安装 Cherry Studio 能解决身份验证失败吗？
如果原因是本地配置损坏，重启或重建配置可能有帮助；但如果问题来自 Key 被撤销、账户无权限、模型不可用、API Host 错误或服务商限流，重装通常不会改变结果。建议先按 401、403、404、429 和网络错误分支排查。
相关阅读
参考资料
- Cherry Studio Model Service Settings（cherryai.com）
- Cherry Studio Model Service Configuration（cherryai.com）
- Cherry Studio Custom AI Service Provider（cherryai.com）
- Cherry Studio General Settings and Proxy Mode（cherryai.com）
- Cherry Studio 官方错误码排障说明
- Cherry Studio 公开认证失败问题记录