Cherry Studio 配置 AI API 时，最容易出错的不是软件安装，而是服务商地址、密钥和模型名称没有对应填写。本文以 Cherry Studio 的自定义 OpenAI 兼容服务为例，说明 Base URL、API Key 和模型 ID 的填写位置，并给出连接测试和常见报错的排查方法。
🧩 Cherry Studio 配置 AI API 前需要准备什么
- 一个可用的 AI API 中转服务账号和 API Key
- 服务商提供的 Base URL，以及对应的接口格式说明
- 服务商实际开放的模型 ID，例如 Claude、GPT 或 Gemini 模型名称
- 已经安装 Cherry Studio，并准备在设置中添加自定义服务
不同中转平台的地址和模型列表并不完全相同。配置前建议先确认服务商是否兼容 OpenAI API 格式，以及 Base URL 是否已经包含正确的版本路径。关于地址、额度和倍率的区别，可以先阅读AI API 的 Base URL、额度和倍率解释。Cherry Studio 的版本功能和配置字段如有变化，也可以对照Cherry Studio 官方 GitHub 项目查看最新说明。
🛠️ Cherry Studio 添加自定义 AI API
打开 Cherry Studio 的设置或模型服务管理页面，选择添加自定义服务。服务类型通常选择 OpenAI Compatible、OpenAI 或兼容 OpenAI 的自定义接口，具体名称以当前版本界面为准。
- 在服务商后台复制 API Key，不要把密钥粘贴到公开文章、截图或聊天群中。
- 将服务商提供的 Base URL 填入 API 地址字段，不要把完整的聊天请求路径重复拼接两次。
- 在模型列表中填写服务商实际支持的 Model ID，名称和大小写要与平台文档一致。
- 保存服务配置，选择刚添加的服务和模型作为当前对话模型。
- 新建一个简单对话发送测试消息，确认返回内容和消耗记录正常。
🔑 Base URL、API Key 和模型 ID 怎么填
Base URL 是客户端访问 API 服务的基础地址，例如服务商给出的 OpenAI 兼容接口域名。Cherry Studio 或服务商可能会自动补充请求路径，因此不要看到示例地址就机械地再加一层 /v1；应以服务商的配置说明和客户端字段提示为准。
API Key 是身份验证凭证，通常以 sk- 或服务商自定义前缀开头。保存后不要将它提交到 Git 仓库，也不要在录屏或截图中完整展示。如果怀疑密钥泄露，应立即在服务商后台撤销并重新生成。
Model ID 必须是服务商真正提供的模型标识，而不是营销名称。可以从服务商的模型列表、API 文档或模型查询接口中复制。想了解 Claude API 的配置思路，也可以参考Claude API 国内接入教程。
🧭 连接失败时的排查顺序
- 401：检查 API Key 是否过期、复制不完整，或是否填入了错误的服务配置。
- 403：检查账号权限、地区限制、模型权限和服务商的访问策略。
- 404：重点检查 Base URL、版本路径和 Model ID，避免重复添加
/v1。 - 429：检查额度、速率限制和并发请求数量，必要时降低请求频率。
如果仍然无法连接，可以先用服务商提供的最小请求示例测试，再回到 Cherry Studio 检查同一组参数。更多错误状态码的含义和处理方法，参见AI API 401、403、404、429 错误解决方法；需要选择服务商时，可以查看AI API 中转平台推荐。
🛡️ 使用 Cherry Studio 的安全建议
不要在不可信的第三方客户端中输入长期有效的主账号密钥。优先使用可设置额度、有效期和权限范围的 API Key，并定期查看调用记录。配置完成后，如果 Cherry Studio 支持本地安全存储或系统密钥链，应优先启用，而不是把密钥写进普通文本文件。
💡 常见问题
Cherry Studio 可以添加自定义 API 吗？
可以。Cherry Studio 通常支持添加 OpenAI 兼容或其他兼容格式的自定义服务，具体字段名称以当前版本界面为准。
Base URL 后面要不要加 /v1？
不一定。应以服务商文档和 Cherry Studio 的字段说明为准，避免服务商已经提供完整路径时再次重复添加 /v1。
模型 ID 填错会出现什么问题？
模型 ID 不正确时常见 404、模型不存在或无权限错误。请从服务商模型列表复制实际标识，不要只填写模型的宣传名称。
