Cherry Studio 常见问题排查，从安装到运行 6 类高频问题
安装类问题
| 问题 | 可能原因 | 解决 |
|---|---|---|
| Windows SmartScreen 警告 | 新签名未被 SmartScreen 信任 | 点「更多信息」→「仍要运行」 |
| macOS 无法验证开发者 | 同 Windows | 系统设置 → 隐私与安全性 → 拉到底部点「仍要打开」 |
| Linux AppImage 无法运行 | 没加可执行权限 | chmod +x CherryStudio-*.AppImage |
| 安装后启动黑屏 | GPU 加速问题 | 设置里关掉硬件加速，或更新显卡驱动 |
模型连接类问题
| 问题 | 可能原因 | 解决 |
|---|---|---|
| 添加服务商后模型列表空 | 端点类型没配对 | 文本模型要选"文本生成（OpenAI）"，图像模型要选"图像生成（OpenAI）" |
| API Key 报错 401 / 403 | Key 无效或权限不够 | 重新生成 Key、检查服务商账户余额、确认 Key 有 API 调用权限 |
| 聚合网关连不上 | 网关端点地址填错 | 确认网关文档里的标准端点地址，和 Cherry Studio 文档里的示例对照 |
| 切换模型后对话里还是用旧模型 | 助手模型设置覆盖了全局默认 | 打开助手设置 → 模型，确认当前助手绑定的是什么模型 |
Ollama 本地模型问题
| 问题 | 可能原因 | 解决 |
|---|---|---|
| Cherry Studio 找不到 Ollama | 服务没在跑 / 端口不对 | curl http://localhost:11434/api/tags 测试；改 Ollama 监听端口后同步 Cherry Studio |
| Ollama 模型加载慢 | 显存不够 / 模型太大 | 用量化版本（4bit / Q4）、减小上下文 |
| 本地模型对话质量差 | 7B 模型能力有限 | 日常对话够用，复杂推理切云端；想本地好效果要上 70B 模型 |
知识库问题
| 问题 | 可能原因 | 解决 |
|---|---|---|
| 索引卡住不动 | 大文件 + OCR 慢 | 分批次添加、手动转扫描 PDF |
| 检索命中不准 | 嵌入模型选的不好 / 切分粒度不对 | 换 BGE-M3 / Qwen Embedding；调切分粒度到 300-500 字 |
| OCR 扫描 PDF 读不到 | 没配多模态模型 | 确保知识库索引时用的嵌入模型能读图像（或先手动转可搜索 PDF） |
| 知识库挂载助手后没效果 | 检索没命中内容 | 在对话历史里看有没有知识库来源标注；没有就是检索精度问题 |
划词助手 / 快捷助手问题
| 问题 | 可能原因 | 解决 |
|---|---|---|
| macOS 上划词助手不弹 | 辅助功能权限没开 | 系统设置 → 隐私与安全性 → 辅助功能 → 勾选 Cherry Studio |
| 快捷键和其他应用冲突 | 默认快捷键被占 | 设置 → 快捷键 → 改成不冲突的（比如 Alt+E） |
| Windows 上划词在 UWP 应用里不弹 | UWP 安全限制 | 换用快捷键触发模式或快捷助手 |
V1 → V2 升级问题
| 问题 | 可能原因 | 解决 |
|---|---|---|
| 升级后对话全丢了 | 没做 V1 备份 / 迁移脚本没跑 | 用升级前的 V1 备份手动恢复 |
| 知识库升级后全空了 | V2 知识库格式变了，需重新索引 | 打开知识库 → 重新索引全部数据源 |
| API Key 要重新填 | V2 加密方式变了 | 重新登录服务商拿新 Key |
排查的标准流程
遇到问题按这个顺序查：
- 重启 Cherry Studio——解决一半的小问题
- 检查版本号——是不是最新版（旧版本 bug 可能在新版本里修了）
- 查 Cherry Studio 日志——帮助定位具体报错
- 看官方文档对应章节——大多数常见问题都有 FAQ
- 最后才考虑重装——重装前先备份数据目录