简介Cherry Studio 是一款支持 Windows、macOS、Linux 多平台的 AI 桌面客户端面向希望借助 AI 提升日常效率的个人用户与企业团队成员。它集成 OpenAI、Gemini、Anthropic 等云端模型并可通过 Ollama 运行本地模型内置 300 多个覆盖写作、编程、设计等领域的预配置助手同时提供文档处理、OCR 识别、WebDAV 备份、全局搜索与 AI 翻译等实用能力可服务于内容创作、代码辅助、知识学习与团队协作等场景。资源包共 1 个 docx 文档约 16KB以文字形式系统梳理了模型支持、功能特点、应用场景与获取途径便于快速了解工具全貌。目前已有 536 人浏览学习适合想构建高效 AI 工作流、比较不同模型输出或探索本地部署方案的读者参考。1. 装 Cherry Studio 之前先把版本和依赖这件事想清楚很多人第一次装 Cherry Studio都是被“多模型聚合”这个点吸引来的——一个客户端里同时挂 OpenAI、Gemini、Anthropic还能通过 Ollama 拉本地模型跑听起来确实省事。但我见过太多人上来就下载安装包双击、下一步、完成然后打开发现模型列表是空的或者本地模型连不上又或者 WebDAV 备份怎么配都报 401。问题不在 Cherry Studio 本身而在于装之前没把环境理清楚。Cherry Studio 覆盖 Windows、macOS、Linux 三个平台版本迭代比较快不同版本对系统版本、运行库、Ollama 版本的要求有差异。如果你只是把它当普通桌面软件装大概率会在配置环节翻车。这篇笔记面向的是准备在自己机器上把 Cherry Studio 跑起来、并且要接上云端模型和本地模型的开发者从版本选择、安装、配置到验证一步步走完。装不好会怎样最典型的就是界面能打开但对话一直转圈或者本地模型加载失败却看不出原因。下面按我实际部署的顺序来写。2. 环境准备与版本选择装哪个包、依赖什么运行时2.1 三个平台的系统版本底线Cherry Studio 官方发布渠道是官网和 GitHub Releases下载时优先选最新稳定版。但“最新”不等于“最适合”我一般会看 Release Notes 里有没有标注 breaking change。以下是各平台的实际底线低于这个版本建议先升级系统再装平台最低系统版本安装包格式备注WindowsWindows 10 1809 及以上.exe 安装包需要 WebView2 运行时macOSmacOS 11 Big Sur 及以上.dmg 磁盘映像Apple Silicon 和 Intel 分开下载LinuxUbuntu 20.04 / Fedora 36 及以上.AppImage 或 .debAppImage 需赋予执行权限Windows 上最容易忽略的是 WebView2。Cherry Studio 的界面基于 Web 技术渲染如果系统里没有 WebView2 Runtime安装完打开可能是白屏。Win10 1809 之后的版本通常自带但部分精简版系统会缺。判断方法很简单装完后如果窗口一片空白先去“设置 → 应用 → 已安装的应用”里搜 WebView2没有就去微软官方页面装一个 Evergreen 版本。macOS 这边Apple SiliconM 系列芯片和 Intel 芯片要下对应的包。虽然 Rosetta 能转译运行 Intel 版但本地模型推理场景下性能损失明显我一般建议直接下 arm64 版本。Linux 用户如果用 AppImage记得先chmod x否则双击没反应。2.2 Ollama 的安装与版本匹配如果你只打算用云端模型这一节可以跳过。但只要你想在 Cherry Studio 里跑本地模型Ollama 就是必须的前置依赖。Cherry Studio 通过 Ollama 的本地 API默认http://127.0.0.1:11434来调用本地模型所以 Ollama 必须先装好并且服务在跑。# Linux / macOS 安装 Ollama官方脚本方式 curl -fsSL https://ollama.com/install.sh | sh # 安装完成后验证服务是否启动 ollama --version # 预期输出类似ollama version 0.5.x # 拉一个轻量模型做连通性测试 ollama pull qwen2.5:7b # 确认模型列表 ollama list这段命令的逻辑是先通过官方脚本安装 Ollama 二进制并注册系统服务然后用--version确认安装成功接着拉一个 7B 级别的模型作为测试载体。选 qwen2.5:7b 是因为它对硬件要求适中8GB 内存的机器就能跑量化版。ollama list用来确认模型已经落到本地仓库后面在 Cherry Studio 里配置时能直接看到。Windows 用户去 Ollama 官网下.exe安装包装完后 Ollama 会常驻系统托盘。这里有个坑如果你装了多个版本的 Ollama或者之前手动编译过端口 11434 可能被旧进程占用。验证方法是浏览器访问http://127.0.0.1:11434看到 “Ollama is running” 就对了。2.3 云端模型 API Key 的准备工作Cherry Studio 本身不提供模型它是个客户端你需要自己有对应平台的 API Key。常见做法是提前在 OpenAI、Gemini、Anthropic 各自的控制台里生成 Key并确认账户有余额或免费额度。我一般会把 Key 先记在密码管理器里因为 Cherry Studio 配置多个提供商时来回切换很频繁。有一点要注意部分提供商的 API 端点需要单独确认。比如 OpenAI 的默认端点是https://api.openai.com/v1但如果你用的是兼容 OpenAI 协议的其他服务端点地址和模型名称都要按实际填。Cherry Studio 支持自定义端点这个后面配置章节会细说。3. 安装 Cherry Studio从下载到首次启动3.1 Windows 安装与 WebView2 补全Windows 的安装流程最直接去官网或 GitHub Releases 下载.exe双击运行。安装向导里有一个选项是“为所有用户安装”还是“仅当前用户”我一般选仅当前用户避免权限问题导致后续 WebDAV 备份写入失败。装完后首次启动如果出现白屏或者界面加载到一半卡住按这个顺序排查# 检查 WebView2 是否已安装PowerShell Get-ItemProperty -Path HKLM:\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5} -ErrorAction SilentlyContinue # 如果没有输出说明 WebView2 未安装 # 去微软官方下载 Evergreen Bootstrapper 安装即可这段注册表查询是用来确认 WebView2 Runtime 是否存在的。{F3017226-...}是 WebView2 的固定产品 GUID查不到就说明缺运行时。补装之后重启 Cherry Studio界面应该正常渲染。另一个 Windows 上的常见问题是安装路径带中文或空格。虽然大多数情况下没问题但如果你后续要配 WebDAV 同步或者用命令行启动路径里的空格可能导致参数解析异常。我一般会装到C:\Apps\CherryStudio这种纯英文无空格路径下。3.2 macOS 安装与 Gatekeeper 处理macOS 下载.dmg后拖入 Applications 文件夹即可。首次打开时如果提示“无法验证开发者”或“已损坏”这是因为 Gatekeeper 拦截了未签名或签名过期的应用。解决方式# 移除应用的隔离属性把路径替换成实际安装路径 xattr -cr /Applications/Cherry\ Studio.app # 如果还是打不开检查系统设置 → 隐私与安全性 → 仍要打开xattr -cr的作用是清除文件的所有扩展属性其中com.apple.quarantine就是 Gatekeeper 用来标记“从网络下载”的隔离标签。清除后系统就不再拦截。这个操作在每次更新版本后可能需要重做一次因为新下载的包会重新带上隔离属性。Apple Silicon 用户注意如果你下载的是 Intel 版本系统会提示安装 Rosetta。虽然能跑但本地模型推理速度会打折扣。确认自己芯片类型的方法左上角苹果菜单 → 关于本机 → 芯片显示 Apple M 系列就下 arm64 包。3.3 Linux 安装与桌面集成Linux 下有两种主流方式AppImage 和.deb。AppImage 的好处是不依赖系统包管理器坏处是不会自动创建桌面快捷方式。# AppImage 方式 chmod x CherryStudio-x.x.x.AppImage ./CherryStudio-x.x.x.AppImage # 如果想集成到应用菜单手动创建 desktop 文件 cat ~/.local/share/applications/cherry-studio.desktop EOF [Desktop Entry] NameCherry Studio Exec/home/你的用户名/Apps/CherryStudio-x.x.x.AppImage Icon/home/你的用户名/Apps/cherry-studio.png TypeApplication CategoriesDevelopment;Utility; EOFchmod x赋予执行权限这是 AppImage 能运行的前提。后面的 desktop 文件是为了让应用出现在系统应用菜单里Exec和Icon路径要改成实际路径。如果你用的是.deb包直接sudo dpkg -i安装桌面集成会自动完成。Linux 上还有一个容易忽略的点如果系统缺少libfuse2AppImage 会报 “dlopen(): error loading libfuse.so.2”。Ubuntu 22.04 之后默认没有 libfuse2需要手动装sudo apt install libfuse2。4. 配置模型与助手云端接入和本地 Ollama 对接4.1 添加云端模型提供商Cherry Studio 首次启动后左侧栏找到“设置”→“模型服务”这里列出了所有支持的提供商。以 OpenAI 为例点进去填入 API Key然后点“检查”按钮验证连通性。如果检查通过下方会列出该 Key 可用的模型列表按需勾选。这里有个细节Cherry Studio 的模型列表是动态拉取的但部分提供商的/models端点返回的列表可能不完整。如果你确认某个模型可用但列表里没有可以手动添加模型 ID。比如 OpenAI 的gpt-4o在某些区域可能不在默认列表里手动填入即可。Gemini 和 Anthropic 的配置逻辑类似区别在于端点地址和认证头格式。Cherry Studio 已经内置了这些提供商的适配层你只需要填 Key。但如果遇到 401 或 403先确认 Key 是否过期、账户是否有对应模型的权限。4.2 对接本地 Ollama 模型回到“模型服务”页面找到 Ollama 提供商。默认端点填的是http://127.0.0.1:11434如果 Ollama 装在本机且服务在跑直接点“检查”就能看到已拉取的模型列表。# 如果 Cherry Studio 里检查失败先在终端确认 Ollama 服务状态 curl http://127.0.0.1:11434/api/tags # 正常应返回 JSON 格式的模型列表 # 如果服务没跑手动启动 ollama serve/api/tags是 Ollama 的模型列表接口返回 JSON 说明服务正常。如果 curl 也连不上说明 Ollama 服务本身有问题跟 Cherry Studio 无关。常见原因是 Ollama 安装后没有注册为系统服务或者防火墙拦截了本地回环端口。Linux 下用systemctl status ollama查看服务状态Windows 下检查系统托盘图标是否在。Ollama 对接成功后在 Cherry Studio 的对话界面顶部模型选择器里就能看到本地模型和云端模型并列。我一般会把常用的几个模型固定在顶部避免每次下拉找。4.3 助手与知识库的初始配置Cherry Studio 内置了 300 多个预配置助手涵盖写作、编程、翻译等场景。首次使用时左侧栏“助手”页面可以直接搜索并添加。每个助手本质上是一段预设的 system prompt 加上推荐的模型参数你可以直接改。知识库功能需要额外配置嵌入模型。如果你用云端嵌入比如 OpenAI 的text-embedding-3-small确保对应提供商的 Key 有嵌入权限。如果用本地嵌入需要 Ollama 拉一个嵌入模型# 拉取本地嵌入模型 ollama pull nomic-embed-text # 在 Cherry Studio 知识库设置里选择该模型nomic-embed-text是一个轻量级嵌入模型适合本地知识库场景。拉取后在 Cherry Studio 的知识库设置里选中它然后导入文档支持 PDF、TXT、Markdown 等格式。导入时 Cherry Studio 会自动分块并生成向量索引文档大的话需要等一会儿。5. 避坑与排查装完打不开、连不上、同步失败的常见原因5.1 启动白屏或界面卡死现象双击图标后窗口出现但内容空白或者一直停在加载动画。 原因Windows 上大概率是 WebView2 运行时缺失或版本过旧macOS 上可能是 Gatekeeper 拦截了渲染进程Linux 上可能是缺少图形库依赖。 解决Windows 补装 WebView2 Evergreen 运行时macOS 执行xattr -cr清除隔离属性Linux 确认libfuse2和libgtk-3已安装。5.2 Ollama 检查通过但对话报错现象在设置里点“检查”显示连接成功但实际对话时提示模型加载失败或超时。 原因Ollama 虽然服务在跑但模型没有完全下载完或者模型对内存要求超过机器实际可用内存。 解决终端执行ollama run 模型名手动测试看是否能正常对话。如果报 OOM换更小的量化版本比如从 7B 换到 3B 或 1.5B。5.3 WebDAV 备份返回 401现象配置 WebDAV 备份时填入地址、用户名、密码点测试连接返回 401 Unauthorized。 原因多数 WebDAV 服务需要单独的应用密码而不是账户登录密码。另外部分服务要求使用 HTTPS 且路径必须精确到目录。 解决在 WebDAV 服务端生成一个应用专用密码地址栏填完整目录路径比如https://example.com/dav/cherry-backup/确保末尾有斜杠。5.4 多模型同时对话时部分模型无响应现象开启多模型对比对话后有的模型正常返回有的一直转圈。 原因不同提供商的 API 并发限制不同或者某个模型的 Key 额度已耗尽。 解决逐个在单模型模式下测试确认是 Key 问题还是并发问题。如果是并发限制减少同时对话的模型数量或者升级提供商套餐。5.5 版本更新后配置丢失现象从旧版本升级到新版本后之前配置的 API Key 和助手不见了。 原因Cherry Studio 的配置数据存在用户目录下跨大版本升级时数据结构可能不兼容。 解决升级前先通过 WebDAV 或本地导出功能备份配置。如果已经丢失检查用户目录下的 Cherry Studio 数据文件夹是否有旧版备份文件。6. 装完怎么验证跑通三条链路逐一确认装完不等于跑通。我一般会按三条链路逐一验证全部通过才算这套环境真正可用。第一条链路是云端模型。打开 Cherry Studio新建对话模型选择器里选一个云端模型比如 GPT-4o 或 Gemini Pro发一句“用一句话说明当前模型名称”。如果正常返回且模型自报名称匹配说明云端链路通了。这一步验证的是 API Key、端点地址、网络连通性三件事。第二条链路是本地模型。同样新建对话模型选择器切到 Ollama 下的本地模型发同样的测试语句。本地模型首次加载需要时间7B 模型在普通机械硬盘上可能要等十几秒SSD 上通常 3 到 5 秒。如果超过 30 秒没响应去终端看ollama ps确认模型是否在加载中。返回结果后再测试一下流式输出是否正常——Cherry Studio 默认开启流式如果文字是一整段蹦出来而不是逐字显示说明流式配置有问题。第三条链路是知识库。新建一个知识库导入一个几页的 PDF等索引完成后提问一个文档里明确写到的细节。比如 PDF 里写了“项目截止日期是 2025 年 3 月”你就问“项目截止日期是什么时候”。如果回答准确说明嵌入模型、分块策略、检索链路都正常。如果回答胡编乱造检查嵌入模型是否选对、文档是否真的索引成功。# 验证 Ollama 模型是否在运行对话无响应时用 ollama ps # 输出会显示当前加载的模型、占用内存、运行时长 # 查看 Cherry Studio 日志Linux 下路径示例 tail -f ~/.config/CherryStudio/logs/main.logollama ps能看到模型是否真的被加载到内存里。如果列表为空但你在 Cherry Studio 里发了消息说明请求根本没到 Ollama问题出在 Cherry Studio 的端点配置上。日志文件则能帮你定位是网络超时还是认证失败。三条链路都通过之后还有一个小习惯我强烈建议把当前配置导出备份。Cherry Studio 支持导出设置存一份到本地或者 WebDAV。从那以后我每次装新机器或者升级版本之前都强制走一遍导出流程因为配置丢失重新填十几个 API Key 和助手参数这件事经历过一次就不想再来第二次。希望帮到你。本文还有配套的精品资源点击获取
