Cherry Studio 下载安装与配置教程（2026 V2 最新）：添加自定义服务商、API 地址怎么填、知识库

本文按 2026 年 10 月最新的 v2.1.6 写。V2 和 V1 的界面差别很大，网上多数教程截的还是 V1。地址该怎么填这一节，我们直接读了 Cherry Studio 的源码，配不通的问题大多出在这里。

Cherry Studio 能做什么

它是一个客户端，自己不提供模型，你接什么服务商就用什么模型：

• 一个软件里用多家模型：OpenAI、Claude、Gemini、DeepSeek、Kimi、智谱、Ollama 本地模型等，还可以接任何兼容的 API。同一个问题可以同时问几个模型对比。
• 助手：给不同用途设好提示词，比如「翻译」「改简历」「写周报」，一点就用。
• 知识库：把文件、笔记、网页导进去，让模型基于你的资料回答。
• MCP 工具、翻译、画图、Agent 等进阶功能。
• 数据存在你自己的电脑上：对话、设置、API 密钥都在本地，请求直接发给你配置的服务商。

社区版免费开源（AGPL-3.0）。软件内置的 CherryAI 服务商提供一批免费模型，官方说明名单会动态调整，以软件里「获取模型列表」看到的为准。

下载和安装

不知道 Mac 是什么芯片：左上角苹果菜单 →「关于本机」。不知道 Windows 是不是 ARM：「设置 → 系统 → 系统信息 → 系统类型」。

安装时的两个小坑：

• Windows 提示缺少运行库：安装程序会自动下载微软 VC++ 运行库，自动下载失败时按提示去微软官网装，再重新运行安装程序。
• Mac 提示无法打开：先确认安装包来自官网或 GitHub，再到「系统设置 → 隐私与安全性」里点允许打开。来源不明的安装包不要绕过系统保护。

从 V1 升级到 V2：一定先看这段

V2 换了数据结构，不是普通的覆盖升级。如果你现在用的是 1.x，按官方建议的顺序来：

1. 先把 V1 更新到 1.9.13，正常打开一次。
2. 在 V1 里关闭「精简备份」，做一次完整备份；然后完全退出 Cherry Studio，把整个数据文件夹另外复制一份。
3. 安装 V2.0.2 或更新版本，它会直接迁移 V1 的数据。

要知道的几件事：

• 迁移是单向的：V2 里新产生的内容不会回到 V1，V1 和 V2 的备份也不能互相恢复。
• 升级后要检查：
  • 模型服务、API 密钥和默认模型；
  • Anthropic 的 OAuth 登录不会迁移，要改填 API 密钥；
  • 新添加的服务商默认是关闭的。
• 「设置 → 数据」里的「重新迁移」不要随便点：它会先永久删除当前 V2 的数据，再从 V1 重新导入，只用于第一次迁移失败的情况。

添加服务商

用内置的服务商

OpenAI、Anthropic、Gemini、DeepSeek、智谱、Kimi、阿里云百炼、硅基流动、OpenRouter、Ollama 等都有预设。打开 设置 → 模型服务，选中服务商，粘贴 API 密钥，打开右上角的开关，再点「获取模型列表」。

添加自定义服务商（任何兼容的 API）

公司内部网关、API 聚合平台、自己部署的模型，都用这种方式：

1. 设置 → 模型服务 → + 添加服务商，打开「添加自定义提供商」。

2. 提供商名称：自己起，比如 api.foo。

3. API 密钥：服务商给你的密钥。

4. 端点设置：V2 的新设计是一个服务商可以同时配多种接口格式。默认显示 OpenAI 和 Anthropic 两栏；点「更多设置」还能加 OpenAI Responses、Gemini、图像生成、图像编辑。服务商支持哪种就填哪种。每一栏下面会显示「请求路径」，就是 Cherry Studio 实际会请求的地址，保存前看一眼。

5. 点「添加」，然后打开这个服务商的开关（新服务商默认关闭）。

6. 添加模型：

   • 点「获取模型列表」从服务商拉取；
   • 或者点「+」手动填模型 ID，必须和服务商的写法一字不差。

   每个模型可以选端点类型（OpenAI、OpenAI-Response、Anthropic、Gemini），决定这个模型走哪种接口。

7. 到 设置 → 默认模型 选一个这个服务商的模型，或者在对话框上方切换模型。

服务商页面的「检测」按钮会向选中的模型发真实请求，可能产生少量费用，但它是确认密钥和地址最快的办法。

API 地址怎么填：按源码讲清楚

这是配不通最常见的原因。我们读了 Cherry Studio v2.1.6 的源码（1.9.x 的规则相同），它拼地址的规律是：

总结成三条：

1. 地址里没有版本号，自动补 /v1（Gemini 补 /v1beta）。
2. 地址里已经有版本号（/v1、/v3、/v1beta 等），不再补。
3. 地址末尾加 #，完全按你填的用。软件里的提示原话是「在末尾添加 # 以禁用自动附加的API版本」。服务商的接口路径里没有版本号、又不能补 /v1 时就用这个。

还有一条：不要把完整的接口路径（带 /chat/completions 的）填进去，Cherry Studio 会自己加。

以 api.foo 为例：一个服务商同时用 GPT、Claude、Gemini

添加模型时，Claude 系列选 Anthropic 端点类型，Gemini 系列选 Gemini，其他选 OpenAI。这样 Claude 走的是 Claude 原生接口，不经过 OpenAI 格式转换，思考等 Claude 特有的功能更完整。

我们用测试密钥核对过这几个地址：/v1/chat/completions、/v1/messages、/v1/models 都能到达 api.foo；把完整路径填进地址栏造成的双重路径，会返回下文报错 2 的 404。

知识库：5 分钟入门

左侧导航的「知识库」可以导入文件、笔记、文件夹或网页，然后在对话或 Agent 里关联这个知识库，让模型基于你的资料回答。

• V2 不强制要嵌入模型。不设嵌入模型时用关键词（BM25）检索，第一次用可以先选「不使用」把流程跑通；设了嵌入模型会变成关键词加语义的混合检索，口语化、同义表达找得更准。
• 导入后先做「召回测试」：问几个问题，看能不能找到正确的原文片段，再正式使用。
• 只是临时问一个附件，直接拖进对话框更快，不用建知识库。

常见问题与解决办法

1. 填了 API 密钥，还是不能对话

按官方常见问题的顺序排查：

1. 服务商开关打开了吗？
2. API 地址对吗？看「请求路径」预览。
3. 设置 → 默认模型选的是不是这个服务商下真实存在的模型？
4. 在公司网络里，检查 Cherry Studio 的网络代理设置。

2. 404，路径重复了

{"error":{"message":"Invalid URL (POST /v1/chat/completions/chat/completions)","type":"invalid_request_error"}}

你把完整接口路径填进了地址栏。改回只到域名，或者只到 /v1。

3. 401、无效的令牌

服务商不认你的密钥：复制漏了、多了空格，或者把别家的密钥填进来了。不同服务商的报错文字不一样，api.foo 显示的是「无效的令牌」。更多报错见 报错排查大全。

4. 模型列表里找不到想用的模型

重新点「获取模型列表」，或者用「+」手动加。另外不同功能会按能力筛选模型，比如 Agent、画图、嵌入模型各有自己的列表，聊天模型不会出现在嵌入模型的下拉框里。

5. 检测通过了，某个模型还是报错

「检测」只测你选中的模型。确认出错的模型的端点类型选对了，比如 Claude 模型选成了 Gemini 就会失败。

数据存在哪、怎么备份

C 盘空间紧张的话，可以在「设置 → 数据 → 数据目录」把数据迁移到别的盘，迁移前先备份。备份可以用 WebDAV（比如坚果云）或 S3 兼容存储。

相关阅读

• 大模型 API 是什么？官方平台、云平台、聚合平台怎么选
• API 中转站是什么？怎么选不踩坑
• 报错排查大全