# 项目简介
关注我们的社交账号：[推特(X)](https://x.com/CherryStudioHQ)、[小红书](https://www.xiaohongshu.com/user/profile/662b6853000000000b031d9a)、[微博](https://weibo.com/u/7975656228)、[哔哩哔哩](https://space.bilibili.com/3546657515898892)、[抖音](https://www.douyin.com/user/MS4wLjABAAAAmw9A54m5J0hHVMQY5eGrVJ-EHDoOS0hgJ6M1F9MN2Tn2V163A0xrC4_KVzfmQSxC)
加入我们的社群：[QQ 群](https://qm.qq.com/q/lo0D4qVZKi)、[Telegram](https://t.me/CherryStudioAI)、[Discord](https://discord.gg/wez8HtpxqQ)、[微信群](https://www.cherry-ai.com/#Community)
***
Cherry Studio 是一款集多模型对话、智能体 Agent、知识库管理、AI 绘画、翻译等功能于一体的全能 AI 工作台。Cherry Studio 高度自定义的设计、强大的扩展能力和友好的用户体验，使其成为专业用户和 AI 爱好者的理想选择。无论是零基础用户还是开发者，都能在 Cherry Studio 中找到适合自己的 AI 功能，提升工作效率和创造力。
***
### **核心功能与特色**
#### **1. 基础对话功能**
* **一问多答**：支持同一问题通过多个模型同时生成回复，方便用户对比不同模型的表现，详见 对话界面。
* **自动分组**：每个助手的对话记录会自动分组管理，便于用户快速查找历史对话。
* **对话导出**：支持将完整对话或部分对话导出为多种格式（如 Markdown、Word 等），方便储存与分享。
* **高度自定义参数**：除了基础参数调整外，还支持用户填写自定义参数，满足个性化需求。
* **预设助手**：可在对话中的助手模块浏览和使用预设助手，涵盖翻译、编程、写作等场景，同时支持用户自定义助手。
* **多种格式渲染**：支持 Markdown 渲染、公式渲染、HTML 实时预览等功能，提升内容展示效果。
#### **2. 智能体与自动化**
* **智能体（Agent）**：可在 **工作** 页面中读取文件、运行命令并完成多步任务，详见 工作。
* **技能（Skill）**：为助手或智能体加装的"专业能力包"（如做小红书图文、画流程图），开箱即用，详见 技能。
* **MCP**：通过 Model Context Protocol 接入外部工具与服务（数据库、Notion、GitHub 等），详见 [MCP 使用教程](/advanced-basic/extensions/mcp)。
* **频道**：将智能体派驻到飞书 / 微信 / Telegram / Discord 等 IM 平台担任群机器人，详见 频道。
* **定时任务**：让智能体按计划自动运行（如每日新闻简报、每周汇总），详见 定时任务。
#### **3. 多种特色功能集成**
* **AI 绘画**：提供专用绘画面板，用户可通过自然语言描述生成高质量图像。
* **AI 小程序**：集成多种免费 Web 端 AI 工具，无需切换浏览器即可直接使用。
* **翻译功能**：支持专用翻译面板、对话翻译、提示词翻译等多种翻译场景。
* **笔记**：内置 Markdown 编辑器，支持与对话内容互通，便于沉淀整理。
* **文件管理**：对话、绘画和知识库中的文件统一分类管理，避免繁琐查找。
* **全局搜索**：支持快速定位历史记录和知识库内容，提升工作效率。
#### **4. 多服务商统一管理机制**
* **服务商模型聚合**：支持 OpenAI、Gemini、Anthropic、Azure 等主流服务商的模型统一调用。
* **模型自动获取**：一键获取完整模型列表，无需手动配置。
* **多秘钥轮询**：支持多个 API 秘钥轮换使用，避免速率限制问题。
* **精准头像匹配**：为每个模型自动匹配专属头像，提升辨识度。
* **自定义服务商**：支持符合 OpenAI、Gemini 、Anthropic 等规范的三方服务商接入，兼容性强。
#### **5. 高度自定义界面和布局**
* **自定义 CSS**：支持全局样式自定义，打造专属界面风格。
* **自定义对话布局**：支持列表或气泡样式布局，并可自定义消息样式（如代码片段样式）。
* **自定义头像**：支持为软件和助手设置个性化头像。
* **自定义侧边栏菜单**：用户可根据需求隐藏或排序侧边栏功能，优化使用体验。
#### **6. 本地知识库系统**
* **多种格式支持**：支持 PDF、DOCX、PPTX、XLSX、TXT、MD 等多种文件格式导入。
* **多种数据源支持**：支持本地文件、网址、站点地图甚至手动输入内容作为知识库源。
* **知识库导出**：支持将处理好的知识库导出并分享给他人使用。
* **支持搜索检查**：知识库导入后，用户可实时检索测试，查看处理结果和分段效果。
#### **7. 特色聚焦功能**
* **快捷问答**：在任何场景（如微信、浏览器）中呼出快捷助手，快速获取答案。
* **划词助手**：在任意应用选中文字后，通过浮动工具栏一键调用 AI 做翻译、解释、优化、总结等操作。
* **快捷翻译**：支持快速翻译其他场景中的词汇或文本。
* **内容总结**：对长文本内容进行快速总结，提升信息提取效率。
* **解释说明**：无需复杂提示词，一键解释说明不懂的问题。
#### **8. 数据保障**
* **多种备份方案**：支持本地备份、WebDAV 备份和定时备份，确保数据安全。
* **数据安全**：支持全本地场景使用，结合本地大模型，避免数据泄漏风险。
***
### **项目优势**
1. **小白友好**：Cherry Studio 致力于降低技术门槛，零基础用户也能快速上手，让用户专注于工作、学习或者创作。
2. **文档完善**：提供详细的使用文档和常见问题处理手册，帮助用户快速解决问题。
3. **持续迭代**：项目团队积极响应用户反馈，持续优化功能，确保项目健康发展。
4. **开源与扩展性**：支持用户通过开源代码进行定制和扩展，满足个性化需求。
***
### **适用场景**
* **知识管理与查询**：通过本地知识库功能，快速构建和查询专属知识库，适用于研究、教育等领域。
* **多模型对话与创作**：支持多模型同时对话，帮助用户快速获取信息或生成内容。
* **翻译与办公自动化**：内置翻译助手和文件处理功能，适合需要跨语言交流或文档处理的用户。
* **AI 绘画与设计**：通过自然语言描述生成图像，满足创意设计需求。
### Star History
## 关注我们的社交账号
# 下载与安装教程
请先从 [官方下载页](https://cherryai.com.cn/download/v2) 下载与系统和芯片匹配的安装包。
## 选择系统
* [Windows 安装教程](/cherry-studio/installation/windows)
* [macOS 安装教程](/cherry-studio/installation/macos)
* [Linux 安装教程](/cherry-studio/installation/linux)
## 安装完成
能够正常打开 Cherry Studio，即表示客户端安装完成。随后继续完成快速开始，配置模型服务并发送第一条消息。
***
### 💡 获取帮助与提交反馈
如果在安装、配置或使用过程中遇到问题，或有功能改进建议，请通过 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道提交。
提交安装问题时，请附上操作系统版本、芯片架构、安装包名称和完整错误提示，便于定位问题。
# Windows 安装
Windows 版本安装教程
## 1. 下载安装包
打开 [官方下载页](https://cherryai.com.cn/download/v2)，选择 **Windows**。
*官网的 Windows 下载选项*
大多数 Intel / AMD 电脑选择 **Windows 标准版**；Windows ARM 设备选择带有 **ARM** 标记的版本。如需不安装到系统的便携使用方式，再选择相同架构的便携版。
不确定设备架构时，打开 Windows 的“设置 → 系统 → 系统信息”，查看“系统类型”。
## 2. 安装并启动
1. 双击下载的安装程序；
2. Windows 显示用户账户控制提示时，确认文件来自官方渠道后选择继续；
3. 按安装向导完成安装；
4. 从开始菜单启动 Cherry Studio。
## 常见问题
### 提示缺少运行库
安装程序会检测与设备架构匹配的 Microsoft Visual C++ 运行库；缺少时会自动下载并安装。
如果自动下载或安装失败，请根据错误提示打开微软官方下载地址，完成安装后重新运行 Cherry Studio 安装程序：
* [x64 运行库](https://aka.ms/vs/17/release/vc_redist.x64.exe)
* [ARM64 运行库](https://aka.ms/vs/17/release/vc_redist.arm64.exe)
### 无法启动
先确认安装包的架构与设备匹配，并检查安全软件是否拦截。仍无法启动时，请在反馈中附上 Windows 版本、设备架构、安装包名称和完整错误提示。
## 下一步
看到 Cherry Studio 主界面后，继续完成快速开始。
# macOS 安装
macOS 版本安装教程
## 1. 确认芯片类型并下载安装包
打开 [官方下载页](https://cherryai.com.cn/download/v2)。Apple 芯片（M 系列）选择 **macOS · ARM64**；Intel Mac 选择页面下方的 **Intel 芯片** 下载项。
*官网默认显示 Apple 芯片下载选项*
不确定芯片类型时，点击屏幕左上角 ** → 关于本机** 查看。
## 2. 安装应用
1. 双击打开下载的 `.dmg` 文件；
2. 将 Cherry Studio 拖到 **Applications（应用程序）** 文件夹；
3. 从“应用程序”文件夹打开 Cherry Studio。
## 首次启动提示
如果 macOS 阻止打开应用，请先确认安装包来自官方渠道，再到“系统设置 → 隐私与安全性”中按提示允许打开。不要为来源不明的安装包关闭系统安全保护或执行终端命令。
## 下一步
看到 Cherry Studio 主界面后，继续完成快速开始。
# Linux
Linux 版本安装教程
## 1. 下载安装包
打开 [官方下载页](https://cherryai.com.cn/download/v2)，选择 **Linux**。官网会按系统和架构提供不同格式的安装包：
| 使用场景 | 选择建议 |
| ------------------------ | ----------------------- |
| Ubuntu、Debian、Linux Mint | 选择与架构匹配的 `.deb` 包。 |
| Fedora、RHEL、openSUSE | 选择与架构匹配的 `.rpm` 包。 |
| 其他发行版或需要便携运行 | 选择与架构匹配的 `.AppImage` 包。 |
Intel / AMD 设备通常选择 x64（或 x86\_64）版本；ARM 设备选择 ARM64（或 aarch64）版本。不确定架构时，在终端运行 `uname -m`：`x86_64` 对应 x64，`aarch64` 或 `arm64` 对应 ARM64。
## 2. 安装并启动
* `.deb` 和 `.rpm`：优先使用发行版的软件安装器或包管理器打开安装包，再从应用菜单启动 Cherry Studio。
* `.AppImage`：为文件授予可执行权限后，双击运行；也可以在终端运行 `chmod +x 文件名.AppImage` 后启动。
## 无法启动
先确认安装包与系统架构匹配。AppImage 无法启动且提示 `FUSE` 或 `libfuse` 相关错误时，请按当前发行版的官方文档安装相应兼容组件。
仍无法启动时，请在反馈中附上发行版、桌面环境、设备架构、安装包名称和完整错误提示。
## 下一步
看到 Cherry Studio 主界面后，继续完成快速开始。
# 升级与降级
选择版本切换路径，并在操作前保护好 V1 与 V2 数据。
根据当前版本和目标选择对应说明。V1 与 V2 使用不同的数据结构，跨大版本切换前必须先备份。
{% hint style="danger" %}
V1 与 V2 的数据和备份格式不互通。V2 中新增的会话、Agent、设置和文件不会自动回写到 V1。
{% endhint %}
## V2.0.2 升级与迁移
{% hint style="warning" %}
需要保留 V1 数据时，正确路径是：**V1.9.13 → V2.0.2（直接完成数据迁移）**。不再需要先安装 V2.0.0。
{% endhint %}
| 当前情况 | 应该怎么做 |
| --------------- | ------------------------------------ |
| 仍在 V1，需要保留数据 | 将 V1 更新到 1.9.13，再直接安装 V2.0.2 完成迁移。 |
| 已经在使用 V2 | 正常升级 V2.0.2，继续使用当前 V2 数据；不要点击【重新迁移】。 |
| 之前迁移 V1 失败或遗漏数据 | 完整备份当前 V2 后，才可在【设置】→【数据】使用【重新迁移】。 |
| 不需要 V1 数据 | 可以选择【忽略并使用默认值】，但 V1 数据不会迁入。 |
{% hint style="danger" %}
【重新迁移】会永久删除当前 V2 数据，再从原始 V1 数据重新导入，不会合并或保留两边的数据。除非此前 V1 迁移失败或遗漏数据，否则一定不要点击。
{% endhint %}
## 选择路径
## 切换前准备
1. 结束正在运行的对话、Agent、知识库导入和文件处理任务。
2. 为当前版本创建一份新的完整备份，并保存在应用数据目录之外。
3. 记录当前应用数据目录；使用自定义目录或外置磁盘时，确认路径可以正常访问。
{% hint style="warning" %}
不要为了“彻底卸载”手动删除应用数据。数据库处理只适用于明确放弃全部 V2 数据或重新迁移的情况，详见 [【V2 降级到 V1】](/cherry-studio/installation/v2-to-v1-downgrade)。
{% endhint %}
## 下载入口
* [Cherry Studio V2 官方下载](https://cherryai.com.cn/download)
* [Cherry Studio V1 官方下载](https://cherryai.com.cn/download/v1)
* V2.0.2 发布页：[GitCode](https://gitcode.com/CherryHQ/cherry-studio/releases/v2.0.2) · [GitHub](https://github.com/CherryHQ/cherry-studio/releases/tag/v2.0.2)
# 破坏性更新提醒
升级 V2 前必须了解的数据迁移、版本路径和回退限制。
V2 不是普通的覆盖更新。它更换了数据结构，也调整了助手、Agent、知识库、网络搜索和文件等功能的入口与行为。
{% hint style="danger" %}
V1 数据只能单向迁移到 V2。V2 中新增的会话、Agent、设置和文件不会同步回 V1，V1 与 V2 的备份也不能互相恢复。
{% endhint %}
## V2.0.2 可以直接迁移 V1
需要保留 V1 数据时，按 **V1.9.13 → V2.0.2（直接完成数据迁移）** 操作，不再需要 V2.0.0 中转。
| 当前情况 | 应该怎么做 |
| --------------- | --------------------------------- |
| 仍在 V1，需要保留数据 | 将 V1 更新到 1.9.13，完整备份后直接安装 V2.0.2。 |
| 已经在使用 V2 | 正常升级 V2.0.2，继续使用当前 V2 数据。 |
| 之前迁移 V1 失败或遗漏数据 | 先完整备份当前 V2，再考虑使用【重新迁移】。 |
| 不需要 V1 数据 | 可以选择【忽略并使用默认值】，但 V1 数据不会迁入。 |
{% hint style="danger" %}
正常升级 V2.0.2 不需要点击【重新迁移】。该操作会永久删除当前 V2 数据，再从原始 V1 数据重新导入；除非此前 V1 迁移失败或遗漏数据，否则一定不要点击。
{% endhint %}
## 升级前必须完成
1. 将 V1 更新到 1.9.13，并至少正常启动一次。
2. 关闭【精简备份】，创建 V1 完整备份。
3. 完全退出 Cherry Studio，再复制整个 V1 数据目录。
4. 使用自定义目录或外置磁盘时，确认路径已挂载且可以读写。
迁移向导读取当前 V1 数据目录，不读取备份 ZIP。备份用于意外恢复，不能代替原数据目录参与迁移。
## 【重新迁移】不是数据合并
V2.0.2 在【设置】→【数据】中增加【重新迁移】。它只用于修复此前 V1 迁移失败或遗漏数据的情况。
操作前会要求确认以下事项：
* 当前 V2 数据将被永久删除，且无法撤销。
* 原始 V1 数据会保留，并在重启后重新导入。
* 必须先为当前 V2 创建完整备份。
完整备份不会让 V1 与 V2 数据自动合并。需要保留的 V2 新内容，请先单独导出或保留完整备份。
{% hint style="danger" %}
【设置】→【数据】→【清除缓存】中的【v1 版本遗留数据】会删除【重新迁移】所需的原始 V1 数据。确认迁移结果完整并保留独立备份前，不要清理这一项。
{% endhint %}
## 升级后重点检查
* 模型服务、API Key 和默认模型；Anthropic OAuth 不会迁移，需要改用 API Key。
* 助手分组、提示词顺序、Agent 工具权限和知识库绑定。
* 知识库失败来源、网络搜索的关键词搜索与网址读取服务。
* 自定义 CSS、侧栏收藏和缺失文件。
完整对照见 [【功能差异】](/cherry-studio/installation/v1-v2-feature-differences)。
## 迁移失败或需要回退
* 优先使用【重试】，修复数据目录、磁盘或数据问题后继续。
* 【保存问题信息】只会保存到本地；文件可能包含路径、内容或凭据，只提供给 Cherry Studio 支持团队。
* 【忽略并使用默认值】会从默认配置开始，V1 数据不会迁入。
* 正常返回 V1 不需要删除数据库，也不要把 V2 备份恢复到 V1。
{% hint style="danger" %}
不要自行删除或替换数据库。误操作、无法确认数据目录，或需要重新迁移时，请先保留所有备份和数据目录，再联系 Cherry Studio 支持团队。
{% endhint %}
## 继续阅读
## 下载入口
* [V1 官方下载](https://cherryai.com.cn/download/v1)
* V2.0.2 发布页：[GitCode](https://gitcode.com/CherryHQ/cherry-studio/releases/v2.0.2) · [GitHub](https://github.com/CherryHQ/cherry-studio/releases/tag/v2.0.2)
* [V2 官方下载](https://cherryai.com.cn/download)
# 功能差异
对照 V1 与 V2 的主要功能、数据处理方式和升级后复核项。
V2 调整了数据结构和多项功能入口。升级前先看需要重新配置的项目；具体步骤见 [【V1 升级到 V2】](/cherry-studio/installation/v1-to-v2-migration)。
## V2.0.2 迁移变化
| 情况 | V2.0.2 的处理方式 | 注意事项 |
| --------- | ----------------------- | ------------------------------ |
| 首次从 V1 迁移 | 可以从 V1.9.13 直接安装 V2.0.2 | 不再需要先安装 V2.0.0。 |
| 正常升级 V2 | 直接升级并继续使用当前 V2 数据 | 不要点击【重新迁移】。 |
| 重新迁移 V1 | 在【设置】→【数据】选择【重新迁移】 | 当前 V2 数据会被永久删除，只用于此前迁移失败或遗漏数据。 |
{% hint style="danger" %}
【重新迁移】不会把 V1 数据补充合并到当前 V2。它会先删除当前 V2 数据，再从保留的 V1 数据重新导入。不是 V1 迁移失败或遗漏数据时，一定不要点击。
{% endhint %}
## 数据如何处理
| 处理方式 | 数据范围 | 升级后要做什么 |
| ---- | --------------------------------------------------------------------- | ------------- |
| 自动迁移 | 设置、模型服务与模型、助手与分组、会话与消息、Agent 与会话、MCP、知识库及有效索引、文件、绘画、翻译、笔记、提示词、用量记录 | 抽查常用项目能否正常打开。 |
| 需要复核 | Anthropic 凭据、网络搜索默认服务、Agent 工具权限与知识库绑定、提示词顺序、知识库失败项、自定义 CSS、侧栏收藏、缺失文件 | 按下表重新确认。 |
| 不会继承 | Agent 定时任务历史记录、旧版站点地图展开结果、部分临时图片引用、笔记当前打开状态、已移除功能的配置 | 需要时重新创建。 |
{% hint style="info" %}
迁移不会删除 V1 原始数据。V2 新数据不会同步回 V1，两个版本的备份也不能相互恢复。
{% endhint %}
## 主要差异
| 功能 | V1 | V2 | 升级后要做什么 |
| --------------- | ------------------------------- | --------------------------------------------- | -------------------------------- |
| 助手与提示词 | 独立助手库；快捷短语可与助手关联 | 助手在聊天和 Agent 中管理；快捷短语合并为全局提示词 | 检查助手分组和提示词顺序。 |
| Agent | 部分配置和工作区跟随会话；旧授权可自动批准工具 | 身份、记忆和主要配置归 Agent；会话创建后工作区固定；工具可能重新请求授权 | 检查模型、工作区、工具和权限。 |
| Agent 知识库 | 知识工具可能访问全局知识库 | 只访问显式绑定的知识库 | 为每个 Agent 重新核对知识库绑定。 |
| 知识库检索 | 可手动选择检索模式和站点地图来源 | 无嵌入模型时使用 BM25，有嵌入模型时使用混合检索；站点地图按普通网址处理 | 检查嵌入与重排序模型；重建失败来源。 |
| 网络搜索 | 可在助手或输入区选择服务；含本地搜索、RAG 压缩和订阅黑名单 | 在【设置】→【网络搜索】分别配置关键词搜索和网址读取；相关旧选项移除 | 重新选择两项默认服务并检查凭据。 |
| MCP | 已添加服务和第三方发现市场并存 | 已添加服务继续迁移；旧第三方发现市场不再提供 | 检查服务状态；新服务从当前市场或 JSON 添加。 |
| 模型服务 | Anthropic 可保存 OAuth 凭据 | Anthropic OAuth 不迁移；AWS Bedrock 区域保留；新增服务默认关闭 | 为 Anthropic 重新填写 API Key，按需启用服务。 |
| 文件 | 文件副本与业务对象的引用关系较弱 | 托管文件按引用管理；最后一个引用删除后会延迟清理托管副本 | 长期保留的文件放入【文件】或导出；用户原文件不会被删除。 |
| 绘画、Mini App 与侧栏 | 参数和入口位于旧版区域 | 绘画参数移到提示词工具栏；Mini App 在顶部标签栏；侧栏收藏重置 | 熟悉新入口并重新设置收藏。 |
| 自定义 CSS | V1 选择器直接生效 | 内容保留，但迁移后默认禁用 | 按 V2 选择器适配后再启用。 |
| Code CLI | 可选择 iFlow | iFlow 由 Qoder 替代 | 需要相关工作流时改用 Qoder。 |
## 开发者兼容性
API 与外部集成有哪些变化？
* API Gateway 的模型标识由 `provider::model` 改为 `provider:model`。
* Knowledge API 返回条目使用 V2 字段。
* MCP-over-HTTP 端点已移除，不影响应用内 MCP。
* SSE 启动失败可能直接返回普通 HTTP 错误，客户端需同时兼容 HTTP 与 SSE 错误路径。
* 定时任务接口参数已变化，历史运行记录不会迁移。
## 参考资料
* [V1 升级到 V2](/cherry-studio/installation/v1-to-v2-migration)
* [Cherry Studio V2 官方下载](https://cherryai.com.cn/download)
* V2.0.2 发布页：[GitCode](https://gitcode.com/CherryHQ/cherry-studio/releases/v2.0.2) · [GitHub](https://github.com/CherryHQ/cherry-studio/releases/tag/v2.0.2)
# V1 升级到 V2
备份 V1 数据，直接使用 V2.0.2 完成迁移，并检查需要重新配置的项目。
{% hint style="danger" %}
迁移是单向的：V1 数据可以进入 V2，V2 新数据不会同步回 V1。升级前请同时保留 V1 完整备份和完全退出应用后复制的整个 V1 数据目录。
{% endhint %}
{% hint style="warning" %}
保留数据的正确路径是：**V1.9.13 → V2.0.2（直接完成数据迁移）**。不再需要先安装 V2.0.0。
{% endhint %}
## 根据当前情况选择
| 当前情况 | 操作 |
| --------------- | ------------------------------------ |
| 仍在 V1，需要保留数据 | 将 V1 更新到 1.9.13，按本页步骤直接安装 V2.0.2。 |
| 已经在使用 V2 | 正常升级 V2.0.2，继续使用当前 V2 数据；不要点击【重新迁移】。 |
| 之前迁移 V1 失败或遗漏数据 | 完整备份当前 V2 后，才可使用【重新迁移】从 V1 重新开始。 |
| 不需要 V1 数据 | 可以选择【忽略并使用默认值】，从默认配置开始；V1 数据不会迁入。 |
## 升级前确认
* V1 不低于 1.9.12，建议先更新到最终版 1.9.13 并至少启动一次。
* 首次迁移可以直接使用 V2.0.2。
* 自定义数据目录或外置磁盘可以正常读写。
* 对话、Agent、知识库导入和文件处理任务均已结束。
{% hint style="warning" %}
迁移向导读取当前 V1 数据目录，不读取 V1 备份 ZIP。备份用于意外恢复，不能代替原数据目录参与迁移。
{% endhint %}
## 操作步骤
{% stepper %}
{% step %}
### 更新并备份 V1
将 V1 更新到 1.9.13。在数据备份页面关闭【精简备份】，创建完整备份，并把备份保存在应用数据目录之外。
{% endstep %}
{% step %}
### 复制整个 V1 数据目录
在 V1 的数据设置中确认目录位置，完全退出 Cherry Studio 后复制整个目录。不要只复制数据库文件。
{% endstep %}
{% step %}
### 检查自定义目录
使用移动硬盘、网络卷或其他自定义位置时，确认路径已挂载且可读写。路径不可访问时不要改用默认目录继续迁移。
{% endstep %}
{% step %}
### 首次启动 V2.0.2
从 [V2 官方下载](https://cherryai.com.cn/download) 获取匹配系统和芯片的 V2.0.2 安装包，也可以使用 [GitCode 发布页](https://gitcode.com/CherryHQ/cherry-studio/releases/v2.0.2) 或 [GitHub 发布页](https://github.com/CherryHQ/cherry-studio/releases/tag/v2.0.2)。完全退出 V1 后安装并启动。
{% endstep %}
{% step %}
### 完成【数据迁移向导】
核对向导显示的数据位置，再选择【开始迁移】。迁移期间不要关闭应用、移动数据目录或断开外置磁盘。
{% endstep %}
{% step %}
### 查看结果并重启
迁移完成后先展开警告信息，再选择【重启应用】。
{% endstep %}
{% endstepper %}
## 升级后检查
* 检查常用模型服务、API Key 和默认模型。
* 检查助手分组、提示词、Agent 权限和知识库绑定。
* 打开常用会话、知识库和文件；只重建显示失败的知识来源。
* 在【设置】→【网络搜索】重新确认关键词搜索和网址读取服务。
* 检查侧栏收藏和自定义 CSS。
* 在【设置】→【数据】创建新的 V2 完整备份。
更多入口变化见 [【功能差异】](/cherry-studio/installation/v1-v2-feature-differences)。
## 只有迁移失败才使用【重新迁移】
如果此前 V1 迁移失败或遗漏数据，V2.0.2 可在【设置】→【数据】选择【重新迁移】。该操作会重启应用，并从保留的 V1 数据重新执行迁移。
{% hint style="danger" %}
【重新迁移】会永久删除当前 V2 数据，不会把 V1 与 V2 数据合并。除非此前 V1 迁移失败或遗漏数据，否则一定不要点击。操作前必须创建当前 V2 的完整备份；需要保留的 V2 新内容还应单独导出。
{% endhint %}
## 迁移失败时
| 选项 | 什么时候用 | 注意事项 |
| ---------- | --------------- | ---------------------------------------------- |
| 【重试】 | 修复目录、磁盘或临时数据问题后 | 优先选择，不会退出迁移流程。 |
| 【保存问题信息】 | 重试仍失败，需要求助 | 文件只保存到本地，可能包含路径、内容或凭据，只提供给 Cherry Studio 支持团队。 |
| 【忽略并使用默认值】 | 明确放弃导入 V1 数据 | 清除本次已写入的部分 V2 数据并从默认配置开始；之后不再自动提示迁移。 |
| 【继续使用 V1】 | 暂时无法迁移，需要恢复工作 | 重新安装 V1 并继续使用原 V1 数据目录。 |
{% hint style="danger" %}
迁移失败或误选【忽略并使用默认值】时，不要自行删除数据库，也不要反复覆盖安装。保留 V1 原数据与备份并联系 Cherry Studio 支持团队。
{% endhint %}
## 常见问题
只有 V1 备份 ZIP，可以直接迁移吗？
不可以。先在兼容的 V1 中恢复并确认数据正常，再保留完整数据目录，然后启动 V2 迁移。
知识库都要重建索引吗？
不需要。有效索引会迁移；只处理显示失败、缺少嵌入模型或无法读取的来源。
## 参考资料
* [Cherry Studio V2 官方下载](https://cherryai.com.cn/download)
* [Cherry Studio V1 官方下载](https://cherryai.com.cn/download/v1)
* V2.0.2 发布页：[GitCode](https://gitcode.com/CherryHQ/cherry-studio/releases/v2.0.2) · [GitHub](https://github.com/CherryHQ/cherry-studio/releases/tag/v2.0.2)
* [官方迁移设计说明](https://github.com/CherryHQ/cherry-studio/blob/main/src/main/data/migration/v2/README.md#version-compatibility-gate)
* [问题反馈与功能建议](/question-contact/suggestions)
# V2 降级到 V1
返回原 V1 数据，并安全处理 V2 备份、数据库和 Agent 数据。
降级适合 V2 暂时影响关键工作、且你仍保留可用 V1 数据的情况。它不会把 V2 数据转换成 V1 格式。
{% hint style="danger" %}
V2 中新增的会话、Agent、设置和文件不会回到 V1。V2 备份也不能恢复到 V1；降级前请分别保留最新 V2 备份和原始 V1 备份或数据目录副本。
{% endhint %}
## 正常降级
{% stepper %}
{% step %}
### 停止任务并备份 V2
结束正在运行的对话、Agent 和文件处理任务。在【设置】→【数据】创建新的 V2 完整备份，并保存到应用数据目录之外。
{% endstep %}
{% step %}
### 确认 V1 数据仍在
找到升级前保留的 V1 数据目录副本或 V1 备份。只有 V1 备份时，需在兼容的 V1 中恢复，不能导入 V2。
{% endstep %}
{% step %}
### 下载并安装 V1
完全退出 V2，从 [V1 官方下载](https://cherryai.com.cn/download/v1) 获取与当前系统匹配的安装包并完成安装。
{% endstep %}
{% step %}
### 使用原 V1 数据启动
启动 V1，并使用升级前的 V1 数据目录。不要用 V2 数据库或 V2 备份覆盖它。
{% endstep %}
{% step %}
### 检查后再继续工作
检查常用会话、模型服务、知识库和文件。确认 V1 数据正常前，不要删除任何 V1 或 V2 备份。
{% endstep %}
{% endstepper %}
{% hint style="info" %}
正常降级不需要删除数据库。保留 V2 数据可以方便以后返回 V2，也能避免误删尚未导出的内容。
{% endhint %}
{% hint style="danger" %}
V2.0.2 中的【设置】→【数据】→【重新迁移】不是降级入口。它会永久删除当前 V2 数据，再从原始 V1 数据重新导入；除非此前 V1 迁移失败或遗漏数据，否则一定不要点击。
{% endhint %}
## 什么时候才处理 V2 数据库
只有以下情况才需要处理：
* 明确放弃当前全部 V2 数据，只保留 V1 数据；
* 需要重新执行一次 V1 → V2 迁移。
这不是普通降级步骤。操作会影响 V2 的全部会话、Agent、设置和其他数据，不是只清理某一批测试记录。
### 安全处理方法
1. 完全退出 V1 和 V2，确认没有后台任务。
2. 打开 V1 1.9.13 的【设置】→【数据】→【应用数据】，进入当前应用数据目录。
3. 将以下项目移到桌面或其他安全位置，不要直接删除：
* `Data/cherrystudio.sqlite`
* `Data/cherrystudio.sqlite-shm` 和 `Data/cherrystudio.sqlite-wal`（如存在）
* `Data/Agents/.claude`
4. 启动 V1 并检查原 V1 数据。需要重新迁移时，再启动 V2 完成迁移。
5. 只有确认 V1 数据可用、V2 备份也能找到后，才决定是否删除此前移出的文件。
{% hint style="danger" %}
不要在应用运行时移动数据库，不要只移动 `cherrystudio.sqlite` 而遗漏同目录下的 `-shm` 或 `-wal` 文件，也不要把 V2 数据库替换成 V1 数据库。无法判断当前数据目录或文件用途时，停止操作并联系 Cherry Studio 支持团队。
{% endhint %}
## 常见问题
V2 的新对话可以带回 V1 吗？
不可以。请在 V2 中导出需要保留的内容，V1 只继续使用原 V1 数据。
下载 V1 会自动转换 V2 数据吗？
不会。安装包只安装应用，不会转换数据或备份格式。
可以直接删除数据库再试吗？
不建议。先移出并保留，完成验证后再决定是否删除；误删且没有可用备份时，V2 数据可能无法恢复。
降级后再次回到 V2，应该安装哪个版本？
如果继续使用此前的 V2 数据，可以直接安装 V2.0.2，且不要点击【重新迁移】。如果此前 V1 迁移失败或遗漏数据，可在完整备份当前 V2 后使用【设置】→【数据】→【重新迁移】；该操作会永久删除当前 V2 数据，再从 V1 重新导入。
## 参考资料
* [Cherry Studio V1 官方下载](https://cherryai.com.cn/download/v1)
* [Cherry Studio V2 官方下载](https://cherryai.com.cn/download)
* V2.0.2 发布页：[GitCode](https://gitcode.com/CherryHQ/cherry-studio/releases/v2.0.2) · [GitHub](https://github.com/CherryHQ/cherry-studio/releases/tag/v2.0.2)
* [问题反馈与功能建议](/question-contact/suggestions)
# 功能介绍
Cherry Studio 是一款桌面级 AI 客户端，集成了 **对话助手、智能体、绘画、翻译、知识库、笔记、文件管理、编码搭档** 等核心能力，并通过 [API 网关](/advanced-basic/developer-tools/api-gateway)、[频道](/advanced-basic/automation/channels)、[定时任务](/advanced-basic/automation/scheduled-heartbeat) 把 AI 能力延伸到自动化与跨平台场景。
下表是本节涉及的主要功能与对应入口：
| 功能 | 简述 | 入口 |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------ |
| [对话](/cherry-studio/preview/chat) | 创建 [对话助手](https://docs.cherryai.com.cn/cherry-studio/pages/KpokPiJoHRazyPziRFbM#助手库)，与不同模型对话，并调用知识库 | 【启动台】→【对话】 |
| [工作](/cherry-studio/preview/agent) | 工作即智能体，可自主执行任务 —— 读文件、跑命令、多步推理 | 【启动台】→【工作】 |
| [绘画](/cherry-studio/preview/drawing) | 接入文生图模型 | 【启动台】→【绘画】 |
| [翻译](/cherry-studio/preview/translation) | 双栏快速翻译 | 【启动台】→【翻译】 |
| [小程序](/cherry-studio/preview/app) | 客户端内运行 AI 厂商网页版 | 【启动台】→【小程序】 |
| [知识库](/cherry-studio/preview/knowledge-base) | 文档/网址/笔记向量化检索 | 【启动台】→【知识库】 |
| [文件](/cherry-studio/preview/files) | 集中查看对话、绘画、知识库等附件 | 【启动台】→【文件】 |
| [编码搭档](/cherry-studio/preview/code-cli) | 安装、配置并启动 AI 编程 CLI 工具 | 【启动台】→【编码搭档】 |
| [笔记](/cherry-studio/preview/notes) | 内置 Markdown 笔记本，随手记录、整理，可导出到知识库 | 【启动台】→【笔记】 |
| [快捷助手](/cherry-studio/preview/quick-assistant) | 全局快捷键唤起的迷你提问窗口 | 全局快捷键 |
| [划词助手](/cherry-studio/preview/selection-assistant) | 在任意应用划词后通过浮动工具栏调用 AI | 划词后浮动工具栏 |
更高阶能力请参考 [进阶教程](/advanced-basic/capability-map) 一节。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 启动台
启动台集中展示 Cherry Studio 的常用功能入口。点击顶部标签栏右侧的 **+**，即可打开新的启动台标签页；关闭最后一个标签页时，也会自动回到启动台。
## 默认应用
当前启动台包含 9 个内置应用：
| 应用 | 用途 |
| -------------------------------------------- | ----------------------- |
| [对话](/cherry-studio/preview/chat) | 与模型对话，管理助手与对话列表 |
| [工作](/cherry-studio/preview/agent) | 让智能体调用工具并完成多步骤任务 |
| [绘画](/cherry-studio/preview/drawing) | 使用图像模型生成和管理图片 |
| [翻译](/cherry-studio/preview/translation) | 翻译文本并对照查看原文和译文 |
| [小程序](/cherry-studio/preview/app) | 在 Cherry Studio 中使用网页应用 |
| [知识库](/cherry-studio/preview/knowledge-base) | 导入资料并进行检索和问答 |
| [文件](/cherry-studio/preview/files) | 查看和管理应用内使用的文件 |
| [编码搭档](/cherry-studio/preview/code-cli) | 安装、配置和启动 AI 编程 CLI 工具 |
| [笔记](/cherry-studio/preview/notes) | 创建和整理 Markdown 笔记 |
## 调整应用顺序
按住应用图标并拖到目标位置，即可调整内置应用的排列顺序。Cherry Studio 会自动保存新的顺序。
启动台和侧边栏分别保存自己的应用顺序。在启动台中排序不会改变侧边栏的排列。
## 固定到侧边栏
经常使用的应用可以固定到侧边栏：
1. 在启动台中右键点击应用。
2. 选择 **添加到侧边栏**。
3. 如需取消固定，再次右键点击并选择 **从侧边栏移除**。
> **提示：** **对话** 是侧边栏的必需入口，不能移除。其他应用即使没有固定到侧边栏，仍可从启动台打开。
## 管理小程序
在 [小程序](/cherry-studio/preview/app) 页面将网页应用添加到启动台后，它会显示在内置应用下方的“小程序”区域。
* 拖动小程序图标可以调整显示顺序。
* 右键点击小程序，可以将它添加到侧边栏或从启动台移除。
* 从启动台移除只会取消快捷入口，不会删除小程序本身。
***
### 获取帮助与提交反馈
如果在使用过程中遇到问题，或有功能改进建议，请通过 [反馈与建议](/question-contact/suggestions) 页面提供的官方渠道联系我们。
# 对话-助手
对话界面是 Cherry Studio 最常用的页面，但其结构包含 **两个层次**：助手 → 对话。理解这一结构有助于更高效地使用各类对话功能。
{% hint style="info" %}
如果还分不清助手、智能体、技能等概念，可以先看下方的 [助手库](#助手库) 小节与 [智能体](/cherry-studio/preview/agent) 页面。
{% endhint %}
## 助手与对话的关系
简单类比：
* **助手 = 一个角色**（如"产品文档助理"、"代码 reviewer"）
* **对话 = 与该角色的一段交流**（如周一讨论"重构方案"、周二讨论"bug 报告"）
也就是说：**一个助手下可创建多个对话**，所有对话共用该助手的人设与参数（提示词、模型、温度等），无需每次重新设定 AI 的角色与风格。
### 助手
助手为 AI 设定固定角色 —— 由系统提示词 + 模型参数预设组成。
* **系统默认助手**：通用助手，未设特殊提示词，可直接使用
* **更专项的助手**：在下方 [助手库](#助手库) 浏览现成预设，或自行创建
### 对话
每个助手下可创建多个对话（即多段独立聊天）。各对话之间相互独立，但共享所属助手的设置。
适用场景示例：
* 同一个"代码助手"下分别开"项目 A 重构"、"项目 B bug"两个对话，独立管理
* 同一个"翻译助手"下开多个对话，分别处理不同文章
每个助手下可展开多个对话（图中「市场营销」助手下展开了两个对话）
## 助手库
助手列表里的助手从哪来？除了系统默认助手，你可以从 **助手库** 添加，或自己创建。助手库是一个 **助手预设市场**，提供大量"角色 + 提示词 + 参数"模板，添加后就会出现在对话页的助手列表里。
{% hint style="warning" %}
**别和智能体搞混**：助手库产出的是上面说的 [对话助手](#助手)（一个角色预设）；[智能体](/cherry-studio/preview/agent)（入口【启动台】→【工作】）则是另一套能自主调用工具、读写文件、跨步骤完成任务的系统。两者是不同的东西，配置入口也不同：助手在对话页管理，智能体在【工作】里。
{% endhint %}
### 进入助手库
1. 在对话页左侧的助手列表顶部，点击 **展示方式** 图标（漏斗状），在弹出菜单中选择【管理助手】。
2. 在打开的「管理助手」页面右上角，点击【助手库】按钮，即可进入助手预设市场。
助手库 —— 按用途分类（带数量徽标）浏览助手卡片，顶部提供搜索框
### 在助手库中查找助手
* **分类筛选**：按 `全部` / `精选` 与多个用途分类（职业、商业、工具、语言、办公、通用、写作、编程、情感、教育、创意、学术、设计、艺术、娱乐、生活 等）筛选，分类名旁的数字为该类的助手数量
* **搜索**：顶部搜索框可在所有分类内按关键词查找
* **预览**：点击助手卡片可看到该助手的系统提示词、推荐模型、参数预设
### 添加到我的助手
* 点击助手卡片上的 **添加** 按钮，即可把该预设加入你的助手列表
* 之后在对话页助手列表中即可看到该助手
### 创建自己的助手
在「管理助手」页面右上角点击【新建助手】，会打开与 [编辑助手](#bian-ji-zhu-shou) 相同的对话框，可分标签页填写：
* **基础**：头像、名称、描述、该助手的默认模型、分组
* **模型**：温度、Top-P、最大 Token 数等模型参数（详见下方 [助手设置](#zhu-shou-she-zhi)）
* **提示词**：决定该助手的角色与行为；输入框右上角的闪电按钮即【AI 优化提示词】，可用 [全局默认助手模型](/pre-basic/settings/default-models) 把当前内容改写得更结构化
* **知识库**：关联已建好的 [知识库](/knowledge-base/knowledge-base)
* **MCP**：为该助手启用 MCP 工具
新建 / 编辑助手对话框，左侧为 基础 / 模型 / 提示词 / 知识库 / MCP 五个标签页
{% hint style="info" %}
**模型选择**：既可以在 **基础** 标签页为助手指定一个默认模型，也可以随时在对话页面顶部的模型下拉菜单中临时切换。未指定助手默认模型时，将使用 [全局默认对话模型](/pre-basic/settings/default-models#mo-ren-zhu-shou-mo-xing)。
{% endhint %}
### 导入与管理
「管理助手」页面右上角提供三个动作按钮：
* **新建助手**：打开 [编辑助手对话框](#bian-ji-zhu-shou) 从零创建一个助手
* **助手库**：进入上面介绍的助手预设市场
* **导入助手**：打开「从外部导入」对话框，导入他人分享的助手
「管理助手」页面本身用于集中管理已添加的助手，支持批量删除、批量导出。
【从外部导入】对话框提供三种一次性导入方式，导入完成后助手即出现在你的助手列表中：
* **文件上传**：拖入或选择一个 JSON 文件
* **剪贴板**：直接粘贴助手的 JSON 文本
* **URL 导入**：填入 JSON 链接（出于安全考虑，当前仅支持 GitHub Gist、raw\.githubusercontent.com 等来源）
从外部导入对话框 —— 文件上传 / 剪贴板 / URL 导入
### 何时使用助手库，何时使用智能体？
| 场景 | 推荐 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| 个性化"角色"快速对话（写作、翻译、技术问答等） | **助手库** |
| 让 AI 自主调用工具、读写文件、跨步骤完成任务 | [**智能体**](/cherry-studio/preview/agent) |
| 定时执行、跨平台消息推送 | **智能体 +** [**定时任务**](/advanced-basic/automation/scheduled-heartbeat) **+** [**频道**](/advanced-basic/automation/channels) |
## 对话框内按钮
输入框工具栏默认只放 4 个常用工具，其余功能都在【+】输入快捷面板里
输入框下方的工具栏 **默认只显示 4 个常用工具**，其余功能收在末尾的 **【+】输入快捷面板** 中。想改默认显示哪些工具，点【+】→【自定义工具栏】。
### 默认工具栏
| 名称 | 作用 |
| ------------- | --------------------------------------------------- |
| **新对话** | 在当前助手内创建一个新对话 |
| **网络搜索** | 把网页搜索结果作为上下文返回给模型，需先在 联网模式 中配置；部分模型也可改用「模型内置」搜索 |
| **知识库** | 把一个已建好的 [知识库](/knowledge-base/knowledge-base) 作为上下文 |
| **+（输入快捷面板）** | 打开下面这一组更多工具与操作 |
### 输入快捷面板（+）
点击 **+**，或直接在输入框里输入 `/`，都会打开这个面板。面板支持 ↑↓ 选择、Tab / 回车 确认、ESC 关闭。
| 名称 | 作用 |
| ---------- | ------------------------------------------------------------------------------ |
| **上传附件** | 上传图片或文档；图片需模型支持视觉能力，文档会被解析为上下文 |
| **生成图片** | 让当前对话模型生成图片；需先在【设置】→【默认模型】中配置画图模型。专门的生图请去 [绘画](/cherry-studio/preview/drawing) |
| **提示词管理** | 插入并管理预设提示词，详见 [输入工具栏与效率工具](/advanced-basic/workbench/composer-efficiency) |
| **MCP** | 查看并启用当前对话可用的 MCP 服务器 |
| **引用笔记** | 从 [笔记](/cherry-studio/preview/notes) 中选一篇作为附件引用 |
| **清除上下文** | **保留消息**，但让模型"忘掉"之前的对话（截断上下文） |
| **自定义工具栏** | 选择默认工具栏上显示哪些工具 |
已添加到输入框的图片会显示为附件标记。鼠标悬停可快速预览；点击附件，或用键盘聚焦后按 Enter / Space，可打开完整图片预览。
{% hint style="info" %}
**"清除上下文"不会删消息**：消息仍留在对话里，只是让模型从此刻起重新认识你，不再记得此前的内容。
{% endhint %}
### 输入框右侧
* **展开 / 收起**（输入框右上角）：放大输入框，便于输入长文
* **思考**（右下角下拉，显示为「默认」）：调整模型的推理强度，仅在所选模型支持推理时可调；不支持的模型会提示「当前模型不支持调整推理强度」
* **发送**：发送消息（默认 Enter，可在 [快捷键](/pre-basic/settings/key-shortcut) 中改）
### 通过键盘触发
输入框的提示里已经写明了两个快捷输入：
* **`/`**：打开输入快捷面板，选择工具或操作（与点击 **+** 等价）
* **`@`**：引用一个已有话题，把它的内容带进当前对话
{% hint style="info" %}
在【设置】→【外观】→【输入设置】中打开 **显示预估 Token 数** 后，输入框还会显示预估的 Token 消耗，供参考（不同模型分词方式不同，实际计费以模型提供商为准）。
{% endhint %}
## 对话设置
对话界面的 **消息显示** 与 **输入相关** 偏好现在统一放在 `设置 → 外观` 中，对所有助手的所有对话全局生效；**模型参数** 则按助手单独设置。
### 消息显示与输入设置
以下偏好都在 `设置 → 外观` 里调整，完整说明见 外观：
* **消息显示**：消息样式（气泡 / 简洁）、使用衬线字体、消息字体大小、思考内容自动折叠、显示消息大纲、代码显示行号 / 代码块可折叠 / 代码块可换行、代码风格、数学公式渲染等
* **输入相关**：发送快捷键、显示预估 Token 数、Markdown 渲染输入消息、删除消息前确认等
### 模型参数
温度、Top-P、最大 Token 数、流式输出、上下文管理、自定义参数等 **模型参数是按助手设置的**，位于 [编辑助手](#bian-ji-zhu-shou) 对话框的「模型」标签页，具体见下方 [助手设置](#zhu-shou-she-zhi)。
## 助手设置
在助手列表中 **右键点击** 需要设置的助手，在弹出菜单中选择【编辑助手】，即可打开助手编辑对话框。
### 编辑助手
{% hint style="info" %}
助手设置作用于该助手下的所有对话。
{% endhint %}
编辑对话框左侧分为五个标签页：
* **基础**：头像、名称、描述、该助手的默认模型、分组
* **模型**：温度、Top-P、最大 Token 数、流式输出、上下文管理、自定义参数等模型参数
* **提示词**：即 prompt，可以参照 [智能体](/cherry-studio/preview/agent) 页面的提示词写法来编辑内容
* **知识库**：关联已建好的 [知识库](/knowledge-base/knowledge-base)
* **MCP**：为该助手启用 MCP 服务器
编辑助手对话框（基础标签页）
#### 默认模型（基础标签页）
在「基础」标签页可为该助手固定一个默认模型；不设置时则跟随 [全局默认对话模型](/pre-basic/settings/default-models#mo-ren-zhu-shou-mo-xing)。
{% hint style="info" %}
助手的默认模型优先级高于全局默认对话模型。当不设置助手默认模型时，助手默认模型 = 全局默认对话模型。你也可以随时在对话页面顶部的模型下拉菜单中临时切换模型。
{% endhint %}
#### 模型参数（模型标签页）
以下参数都在「模型」标签页中调整。
#### **`温度 (Temperature)`** ：
温度参数控制模型生成文本的随机性和创造性程度（默认值为 0.7）。具体表现为：
* 低温度值(0-0.3)：
* 输出更确定、更专注
* 适合代码生成、数据分析等需要准确性的场景
* 倾向于选择最可能的词汇输出
* 中等温度值(0.4-0.7)：
* 平衡了创造性和连贯性
* 适合日常对话、一般性写作
* 推荐用于聊天机器人对话(0.5 左右)
* 高温度值(0.8-1.0)：
* 产生更具创造性和多样性的输出
* 适合创意写作、头脑风暴等场景
* 但可能降低文本的连贯性
#### **`Top P (核采样)`**：
默认值为 1，值越小，AI 生成的内容越单调，也越容易理解；值越大，AI 回复的词汇范围越大，越多样化。
核采样通过控制词汇选择的概率阈值来影响输出：
* 较小值(0.1-0.3)：
* 仅考虑最高概率的词汇
* 输出更保守、更可控
* 适合代码注释、技术文档等场景
* 中等值(0.4-0.6)：
* 平衡词汇多样性和准确性
* 适合一般对话和写作任务
* 较大值(0.7-1.0)：
* 考虑更广泛的词汇选择
* 产生更丰富多样的内容
* 适合创意写作等需要多样化表达的场景
{% hint style="info" %}
* 这两个参数可以独立使用或组合使用
* 根据具体任务类型选择合适的参数值
* 建议通过实验找到最适合特定应用场景的参数组合
* 以上内容仅供参考和了解概念，所给参数范围不一定适合所有模型，具体可参考模型相关文档给出的参数建议。
{% endhint %}
#### **`上下文管理`**
控制随请求一起发送给模型的历史上下文如何处理。开启后此助手使用自定义的上下文管理设置（如自动压缩较长历史、按阈值截断），关闭时跟随全局设置。上下文越长，模型记住的信息越多，但消耗的 token 也越多。
#### **`最大工具调用轮次`**
限制助手在一次回复中连续调用工具的轮数。新建助手默认使用 100 轮，可在 1–1000 之间设置；已有助手会保留原来的值，旧配置常见为 20 轮。
如果出现“达到工具调用轮次上限”一类提示，可适当提高此项，或把任务拆小后重试。轮数越高，工具链运行可能越久，也可能消耗更多 Token；普通对话无需主动调高。
#### **`开启消息长度限制 (MaxToken)`**
单次回答最大 [Token](https://docs.cherry-ai.com/question-contact/knowledge#shen-me-shi-tokens) 数，在大语言模型中，max token（最大令牌数）是一个关键参数，它直接影响模型生成回答的质量和长度。
> 如:在 CherryStudio 当中填写好 key 后测试模型是否连通时，只需要知道模型是否有正确返回消息而不需特定内容,这种情况下设置 MaxToken 为 1 即可。
多数模型的 MaxToken 上限为 32k Tokens，当然也有 64k，甚至更多的，具体需要到对应介绍页面查看。
具体设置多少取决于自己的需要，当然也可以参考以下建议。
{% hint style="success" %}
建议：
* 普通聊天：500-800
* 短文生成：800-2000
* 代码生成：2000-3600
* 长文生成：4000 及以上 (需要模型本身支持)
{% endhint %}
{% hint style="warning" %}
一般情况下模型生成的回答将被限制在 MaxToken 的范围内，当然也有可能会出现被截断（如写长代码时）或表达不完整等情况出现，特殊情况下也需要根据实际情况来灵活调整。
{% endhint %}
#### **`流式输出（Stream）`**
流式输出是一种数据处理方式，它允许数据以连续的流形式进行传输和处理，而不是一次性发送所有数据。这种方式使得数据可以在生成后立即被处理和输出，极大地提高了实时性和效率。
在 CherryStudio 客户端等类似环境下简单来说就是打字机效果。
关闭后(非流)：模型生成完信息后整段一次性输出（想象一下微信收到消息的感觉）；
打开时：逐字输出，可以理解为大模型每生成一个字就立马发送给你，直到全部发送完。
{% hint style="info" %}
如果某些特殊模型不支持流式输出需要将该开关关闭，比如 **刚开始** 只支持非流的 o1-mini 等。
{% endhint %}
#### **`自定义参数`**
在请求体（body）中加入额外请求参数，如 `presence_penalty` 等字段，一般人一般情况下用不到。
> 上述 top-p、maxtokens、stream 等参数就是这些参数之一。
填法：参数名称—参数类型（文本、数字等）—值，参考文档：[点击前往](https://openai.apifox.cn/doc-3222739)
{% hint style="info" %}
各个模型提供商都或多或少有自己独有的参数，需要到提供商的文档中寻找使用方法
{% endhint %}
{% hint style="info" %}
* 自定义参数优先级高于内置参数。即自定义参数如果与内置参数重复，则自定义参数会覆盖内置参数。
> 如：自定义参数中设置 `model` 为 `gpt-4o` 后，在对话中无论选择哪个模型都使用的是 `gpt-4o` 模型。
* 使用 参数名称:undefined 的设置可排除参数。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 工作-智能体
让 AI 自主执行任务的智能体
**工作**（也叫 **智能体 / Agent**）是 Cherry Studio 里一套能 **自主调用工具、读写文件、跨多步完成任务** 的系统——和"对话助手"（一个角色预设）不是一回事。入口在 **左侧导航栏的【工作】**（不是旧版教程里的顶部标签）。
{% hint style="success" %}
最省事的用法：先告诉 Agent 你想完成什么，让它自己检查还缺哪些模型 / 工具 / 知识库 / 频道；需要精确控制时再手动调。
{% endhint %}
【工作】界面：顶部依次选择智能体、模型与工作目录，在下方输入任务；左侧管理任务与工作目录
## 它能做什么
* **读写文件**：给它一个 **工作目录**，它就能在里面读、改、生成文件。
* **调用工具**：内置工具，加上你挂载的 [技能](/advanced-basic/extensions/skills) 与 [MCP](/advanced-basic/extensions/mcp) 外部工具。
* **多步推理 / 子任务**：拆解目标、派子智能体、跑后台命令。
* **接入自动化**：配合 [频道](/advanced-basic/automation/channels) 派驻到 IM 平台、用 [定时任务](/advanced-basic/automation/scheduled-heartbeat) 定时执行。
## 快速上手
1. 打开【工作】，选一个 Agent；没有就点【添加智能体】，按四步（基础信息 / 人格 / 技能 / 知识库）创建。内置的 **Cherry Assistant** 可直接用。
2. 需要处理本地文件时，选一个 **工作目录**；不涉及文件用默认工作区即可。
3. 用"要交付什么、可用哪些资料、怎样算完成"来描述任务。
4. 在右侧面板看 **状态 / 文件 / 子任务 / 消息流**；开了开发者模式还能看 **调用链**。
## 权限模式
Agent 执行文件 / 命令操作时，可选 **逐次确认 / 自动接受编辑 / 智能批准 / 仅规划 / 完全访问** 五种权限模式，从最谨慎到最放手。无人值守跑任务（如频道、定时任务）时才用更放手的模式。
***
## 想更深入？
完整用法见进阶教程：
* [Agent 工作区](/advanced-basic/agent-workspace) —— 从创建到交付的完整工作方式
* [创建 Agent 与模型分工](/advanced-basic/agent-workspace/create-agent)
* [工作目录、任务与文件](/advanced-basic/agent-workspace/workspaces-tasks-files)
* [内置工具、知识库、技能与 MCP](/advanced-basic/agent-workspace/tools-knowledge-skills-mcp)
* [权限、记忆与后台任务](/advanced-basic/agent-workspace/permissions-memory-background)
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 绘画
绘画页面是 Cherry Studio 内置的 **文生图工具**：通过文字描述生成图像，效果与 Midjourney / DALL·E 等网页服务类似。**主要优势在于直接复用 Cherry Studio 中已配置的服务商账号**，无需另行注册各家平台。
## 进入绘画
点击顶部标签栏右侧的 **+** 打开【启动台】，再点击【绘画】。
绘画页面：左侧是画板列表，中间是画布，底部输入区选择服务商与模型
页面主要由这几部分组成：
* **画板列表（左侧）**：纵向排列的画板缩略图，顶部 `+` 可新建画板、切换到新的一组
* **画布（中间）**：居中显示当前生成的图片
* **输入区（底部）**：提示词输入框，一侧提供 **服务商与模型选择** 入口；下方提示当前服务商有没有可用的图像模型，没有时会显示绿色 `去设置` 按钮直接跳到该服务商配置页
* **绘图 / 编辑**：没有单独的切换按钮，**由所选模型决定**——选文生图模型（如 `qwen-image`）就是绘图；选图像编辑模型（如 `qwen-image-edit`）则进入编辑，需先上传图片再描述改动
选择 **图像编辑模型**（如 `qwen-image-edit`）后，输入区会变为“上传图片 + 描述编辑”的模式：
选择图像编辑模型后 —— 需要先上传一张图片，再描述如何修改
## 当前支持的服务商
Cherry Studio 的绘画功能依赖各家服务商提供的 **图像模型**。在模型下拉里可以看到当前实际可选的全部条目，按服务商分组列出：
模型下拉：按服务商分组列出可用的图像模型，底部可“配置自定义模型”
按类型大致分为三类：
| 类型 | 服务商 | 说明 |
| ------- | --------------------------------------------- | ------------------------------------------ |
| 国内云服务 | [**硅基流动**](/pre-basic/providers/siliconcloud) | 国内访问最方便，价格便宜，模型选择多 |
| | [**PPIO 派欧云**](/pre-basic/providers/ppio) | 国内云算力服务 |
| | **智谱开放平台** | 国产模型 CogView |
| 聚合网关 | **AiHubMix** | 聚合多家厂商的网关 |
| | **DMXAPI** | 聚合多家厂商的网关 |
| | **TokenFlux** | 海外网关 |
| | **CherryIN** | Cherry 官方网关，统一计费 |
| | **唯一 AI（AiOnly）** | 第三方网关 |
| 自建 / 本地 | **New API** | 自建网关方案，添加后会出现在此列表 |
| | **OVMS** | OpenVINO Model Server，本地推理（仅在 OVMS 已运行时显示） |
{% hint style="info" %}
任何 **端点类型设为 `图像生成 (OpenAI)`** 的自定义服务商，都会动态出现在这里。后续会陆续接入更多。
{% endhint %}
## 开始画
1. 在输入区选择已配置的 **服务商与模型**；若提示"暂无可用的图片生成模型"，点击 `去设置` 在该服务商下添加一个端点类型为 **图像生成 (OpenAI)** 的模型
2. 选择一个 **文生图模型**（如 `qwen-image`），在输入框输入 **提示词**（中文/英文都可，越具体越好），例如：
```
一只戴着圆眼镜的橘猫坐在书堆上，复古油画风格，温暖的黄昏光线
```
3. 调整参数（尺寸、步数、随机种子等），不确定就用默认
4. 点击 **生成**，等几秒到几十秒（取决于模型）
5. 生成的图会出现在画布上，可下载、收藏，或一键再画一张
{% hint style="info" %}
不想每次都在输入区选模型？到【设置】→【默认模型】→【绘画模型】指定一个默认的 **图像生成模型**（说明为"图像生成使用的模型"），绘画时便会默认用它。
{% endhint %}
## 参数怎么填？
参数面板里部分字段右侧带 **ⓘ 信息图标**，鼠标悬停会显示说明（如硅基流动 / Aihubmix / PPIO 等服务商基本都带），但 **不是所有服务商** 都加了 Tooltip——比如智谱、NewAPI 的参数面板就没有提示。看不到说明时，按下面默认值直接试就行。
如果想深入了解：
* **尺寸**：影响细节量与生成时间。日常用 1024x1024 够了
* **步数（Steps）**：模型"打磨"次数。20-30 步通常够用，多了边际收益小
* **CFG / Guidance**：AI 对你提示词的"听话程度"。7-12 比较常用
* **种子（Seed）**：固定种子可让结果可复现；想看同一个提示词随机变化就留空
## 提示与技巧
* **用英文提示词通常效果更好**（绝大多数模型用英文素材训练为主）
* 越具体越好：风格、构图、光线、镜头都写进去
* 想要"参考某张图改"？看你选的服务商是否支持 **img2img**（图生图）
* 一次出 4 张省 4 倍时间：把"批次数"调到 4
{% hint style="info" %}
绘画功能会随版本扩展。最新支持的服务商以应用内下拉为准。
{% endhint %}
{% hint style="danger" %}
注意：Gemini 图片生成需要在对话界面使用，因为 Gemini 是多模态交互式的图片生成，也不支持参数调节。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 翻译
Cherry Studio 的翻译功能为您提供快速、准确的文本翻译服务，支持多种语言之间的互译。
### 界面概览
翻译页面：左输入、右输出，顶部切换语言与模型
顶部操作栏分左右两组。
**左侧（语言与翻译）：**
1. **源语言下拉**：默认 `自动检测`，自动检测命中后会在选项里显示具体语种
2. **方向切换**（⇆）：互换源 / 目标语言（源语言为【自动检测】时不可用）
3. **目标语言下拉**
4. **翻译按钮**：输入框为空或未选择模型时为灰色不可点
**右侧（模型与工具）：**
5. **模型选择**（模型头像）：切换用于翻译的模型
6. **翻译历史**（时钟图标）：打开历史面板，可搜索、按收藏筛选，点任意记录一键回填到输入 / 输出框
7. **设置**（滑块图标）：打开翻译设置面板
输入框（左）支持粘贴文本，也支持 **拖入或点击上传** 文件——文本文件（`.txt` / `.md`）直接读入，图片走 **OCR** 识别，文档（PDF / Word / PPT / Excel 等）直接抽取正文；结果框（右）鼠标移上去出现复制按钮。
{% hint style="info" %}
拖入图片会先做 OCR 识别文字再翻译；拖入 PDF / Word 等文档会直接抽取正文。图片与文本文件上限 5 MB，文档上限 20 MB。
{% endhint %}
### 使用步骤
1. **选择目标语言**
2. **输入或粘贴文本** 到左侧框 —— 拖入图片可直接 OCR 识别后翻译
3. 点击 **翻译** 按钮
4. 复制或继续编辑右侧结果
### 翻译设置
点击右上角 **滑块图标** 打开翻译设置面板：
翻译设置面板
* **Markdown 预览**：开启后翻译结果按 Markdown 渲染
* **翻译完成后自动复制**：结果生成即复制到剪贴板
* **滚动同步设置**：左右两栏滚动联动
* **自动检测方法**：自动 / 算法（franc 本地）/ LLM——LLM 检测更准但会消耗少量 token
* **双向翻译设置**：开启后只在指定的两种语种之间互译，顶部语言栏会合并为一个“源 ⇆ 目标”语言对；下方可选语种对
* **翻译提示词**：自定义翻译使用的系统提示词，改动后可一键恢复默认
* **自定义语言**：在内置语言之外添加、编辑或删除语言（填写语言名与语言代码，如 `zh-cn`）
### 常见问题解答 (FAQ)
* **Q: 翻译不准确怎么办？**
* A: AI 翻译虽然强大，但并非完美。对于专业领域或复杂语境的文本，建议进行人工校对。 您也可以尝试切换不同的模型。
* **Q: 支持哪些语言？**
* A: Cherry Studio 翻译功能支持多种主流语言，具体支持的语言列表请参考 Cherry Studio 的官方网站或应用内说明。
* **Q: 可以翻译整个文件 / 图片吗？**
* A: 可以。输入框支持直接 **拖入或点击上传** 图片与文档：图片会通过 OCR 识别后再翻译，PDF / Word / PPT / Excel 等文档会抽取正文后翻译。若文档特别长，也可以进入对话页面，把文档作为附件发给翻译助手处理。
* **Q: 翻译速度慢怎么办？**
* A: 翻译速度可能受网络连接、文本长度、服务器负载等因素影响。请确保您的网络连接稳定，并耐心等待。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 小程序
小程序页面以客户端原生窗口的方式打开各家 AI 厂商的网页版（如 ChatGPT、Claude、文心一言、Kimi 等），让你不离开 Cherry Studio 就能切换不同模型的 Web 体验。
### 进入小程序
{% stepper %}
{% step %}
### 打开启动台
顶部 Tab 栏点击 `+`，或直接打开【启动台】。
{% endstep %}
{% step %}
### 进入小程序
点击【小程序】应用图标。
{% endstep %}
{% step %}
### 选择服务
在小程序网格中选择需要打开的服务。
{% endstep %}
{% endstepper %}
小程序网格，内置数十家服务；点右上角 + 可添加任意网页
页面中部有 **搜索框**；右上角 `+` 用于添加自定义网页，`☰` 打开【小程序显示设置】。
### 设置
在【设置】→【小程序】中可以对小程序进行如下调整：
* **显示 / 隐藏小程序**：可以左右拖动小程序到两个区域，控制显隐
* **排序小程序**：上下拖动可以对小程序进行排序
* **小程序区域筛选**：根据你的选择，自动隐藏你无法访问的小程序
* **小程序缓存数量**：如果同时打开的小程序数量超出此数量，则有一部分小程序会进入不活跃状态
### 自定义与管理
Cherry Studio 的小程序支持以下操作：
* **添加到启动台**：把常用的小程序加入启动台，方便从 `+` 入口快速打开。可在【设置】→【小程序】中管理，或对小程序图标右键选择 **添加到启动台**
* **添加到侧边栏**：把常用的小程序固定到左侧边栏，一键直达；右键小程序图标即可选择 **添加到侧边栏** 或 **从侧边栏移除**
* **保活（Keep Alive）**：让小程序窗口在切走时不立即销毁，再次进入无需重新登录或重新加载
* **添加自定义网页**：点击页面右上角的 `+`，填写名称、URL、图标即可加入网格
* **删除 / 编辑**：对每个小程序图标右键即可
打开某个小程序后，其窗口自带一条工具栏：**后退**、**前进**、**刷新**、**在浏览器中打开**。你还可以切换页内链接是在默认窗口打开，还是在系统浏览器打开。
小程序窗口工具栏：左侧后退 / 前进 / 刷新，右侧在浏览器中打开、添加到启动台、页内链接打开方式
### 提示与技巧
* 小程序使用各服务的 **网页版**，登录态、Cookie、设置均保存在本地，与系统浏览器隔离
* 若某个小程序加载失败，可右键 → 刷新，或检查代理设置（参考 [常规设置](/pre-basic/settings/general)）
{% hint style="info" %}
当前小程序与对话面板暂未互通。若需让 AI 读取小程序中的内容，需要手动复制或截图。
{% endhint %}
如遇问题，请在 [反馈与建议](/question-contact/suggestions) 中提交反馈。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 知识库
知识库就像给 AI 配一本 **专属参考书**：你把自己的文档、笔记、网址塞进去，之后聊天时让 AI 翻这本书来回答你的问题。
知识库：左栏是已建知识库列表（顶部 + 新建知识库），右侧向选中的知识库添加文件 / 笔记 / 目录 / 链接数据源
## 用知识库能干什么？
举几个真实场景：
* **公司知识助手**：把产品手册、API 文档、内部规范全塞进去，员工问问题时 AI 自动答
* **个人资料管家**：把你历年的工作笔记、读书摘录、邮件存档放进去，问 AI"我去年在哪个 PPT 里提过那个分析框架"
* **学习陪练**：把课件、论文塞进去，让 AI 帮你按章节出题、解答疑惑
* **合同/法规速查**：把法条、合同模板放进去，问 AI 具体条款的应用
## 为什么用知识库，不直接把文件丢给 AI？
直接丢文件的限制：
* 每次提问都要重新上传，麻烦
* 单次对话有长度限制，长文档塞不下
* 跨对话不能复用
**知识库解决了上面所有问题**：上传一次，之后任何对话都可调用，且能从大量资料里"精准抓取相关段落"喂给 AI。
## 怎么用？
* 第一次用：看 [完整知识库教程](/knowledge-base/knowledge-base)
* 想加图片 / 扫描 PDF：先看 [文档预处理](/knowledge-base/document-preprocessing)，让 AI 能"读懂"图片里的文字
* 想了解嵌入模型怎么选：看 [嵌入模型参考](/knowledge-base/emb-models-info)
* 想离线用、不配云端嵌入：可以用内置的 [本地嵌入模型](/pre-basic/settings/local-models)，知识库无需联网即可建索引与检索
* 想了解数据存哪：看 [知识库数据](/knowledge-base/data)
## 与其他能力的组合
* **知识库 + 助手**：给某个助手"挂载"知识库，它就专精这个领域
* **知识库 +** [**智能体**](/cherry-studio/preview/agent)：让智能体在任务过程中自己查知识库
* **知识库 +** [**频道**](/advanced-basic/automation/channels)：把"会查公司文档"的智能体派到飞书群里值班
{% hint style="info" %}
推荐先阅读 [进阶能力地图](/advanced-basic/capability-map)，了解知识库与智能体、MCP、频道等功能如何协同。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 文件
文件页面是 Cherry Studio 的 **附件总仓库** —— 你在对话中拖进来的图片、PDF、文档，在绘画中生成的图，在知识库中导入的资料，都能在这里集中查看与管理。
可以理解成 Cherry Studio 内部的"我的电脑"。
## 进入文件页面
顶部 Tab 的 `+` →【启动台】→ 点击【文件】。
文件页面：左侧按类型分类，顶部排序与全选 / 多选
## 在这里可以做什么
* **按类型筛选**：左侧按类型分类 —— `文档`、`图片`、`文本`、`音频`、`视频`、`其他`、`所有文件`
* **排序**：顶部支持 `文件名` / `大小` / `类型` / `修改时间` 四种排序方式
* **批量操作**：右上 `全选` 复选框配合 `⋯` 菜单做批量删除
* **上传**：把文件直接拖入页面即可上传，或点击 `上传文件`
* **预览**：单击文件直接预览（图片、PDF 等支持的格式）
* **重命名**：右键 → 重命名
* **删除**：右键 → 删除，删除的文件会进入 **回收站**（详见下方说明）
* **打开所在位置**：右键 →【打开所在文件夹】（macOS = 访达，Windows = 资源管理器）
{% hint style="info" %}
若某个文件被标记为 **缺失**，说明它的本地原文件已被移动或删除；这类文件只能定位位置或从库中移除记录。
{% endhint %}
## 回收站
删除文件后，它不会立刻消失，而是先进入【回收站】。你可以在回收站中：
* **恢复**：把误删的文件放回原处
* **永久删除**：单独彻底清除某个文件
* **清空回收站**：一次性永久清除回收站中的全部文件
回收站：可恢复、永久删除，或清空全部
{% hint style="warning" %}
**永久删除无法撤销。** 删除文件也会同时移除它在所有相关消息中的引用，请确认后再操作。
{% endhint %}
## 文件存在哪？
Cherry Studio 把所有附件存在本地的应用数据目录中。具体路径：
* **macOS**：`~/Library/Application Support/CherryStudio`
* **Windows**：`%APPDATA%\CherryStudio`
* **Linux**：`~/.config/CherryStudio`
想换到别的盘？看 [修改存储位置](/pre-basic/settings/data-settings/storage)。
## 提示与技巧
* 长期不用的对话 / 知识库会越攒越多文件，定期到这里清一下能省不少磁盘
* 重要文件建议同时备份到云盘（WebDAV / S3 等），见 [数据设置](/pre-basic/settings/data-settings)
* 文件名乱码？通常是从外部拖入时编码问题，建议先重命名再用
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 编码搭档
【编码搭档】用于安装、配置和启动常见编程命令行工具。Cherry Studio 会识别自己的托管安装，也会检测系统登录环境中已经可用的 CLI；系统工具仍由原来的包管理器维护。
先确认工具已经安装且版本可用，再配置模型连接和项目目录。
## 页面能做什么
* 检查工具是否安装以及是否有可用更新；
* 安装或更新 Cherry Studio 托管的工具副本；
* 检测系统 PATH 中已有的工具；
* 为需要模型服务的 CLI 选择服务商和模型；
* 为使用自身账号登录的 CLI 保留原生登录方式；
* 选择工作目录和系统检测到的终端后启动。
页面当前包含 Claude Code、OpenAI Codex、Gemini CLI、OpenCode、Qwen Code、Kimi Code、Qoder CLI 和 GitHub Copilot CLI 等工具。实际可见项会随产品更新变化，以页面列表为准。
## 使用流程
{% stepper %}
{% step %}
### 1. 打开左侧导航【编码搭档】
选择需要的工具，先看状态是未安装、由 Cherry Studio 托管，还是来自系统。
{% endstep %}
{% step %}
### 2. 完成安装或登录
未安装时点击【安装】。由工具自身提供账号登录的 CLI，按照页面提示完成原生登录，不需要从 Cherry Studio 选择服务商。
{% endstep %}
{% step %}
### 3. 配置模型连接
需要 Cherry Studio 模型服务的工具，选择兼容的服务商和模型。页面会按 CLI 所需的接口类型筛选，不兼容的服务商不会列出。
{% endstep %}
{% step %}
### 4. 选择目录和终端
工作目录决定 CLI 启动位置。终端只能从系统检测到的列表中选择；自定义终端可执行文件路径不再提供。
{% endstep %}
{% step %}
### 5. 启动并验证
点击【启动】，在终端中运行一个只读检查。确认账号、模型和目录正确后再执行文件修改或命令。
{% endstep %}
{% endstepper %}
## Claude Code 的模型模式
配置 Claude Code 时，【模型】提供两种模式：
* 【通用】：所有请求使用同一个模型，配置简单；
* 【详细】：在【模型角色映射】中分别设置 Fable、Opus、Sonnet、Haiku 和 Subagent。表格里的【实际请求模型】就是每个角色最终使用的模型；需要时还可为对应角色开启【1M】上下文。
只有确实需要为后台子任务、压缩或标题等角色指定不同模型时，才使用【详细】。留空的角色会跟随主模型。修改后先用一个小任务确认每个角色都能正常请求。
## 使用场景：在项目目录启动编码工具
| 选择 | 建议起点 | 适用场景 | 注意事项 |
| ----- | ----------------------------- | ------------ | ---------------- |
| 安装来源 | 已有系统版本就先使用系统版本 | 团队已经统一管理 CLI | 更新和卸载仍由原包管理器负责 |
| 模型连接 | 先选一个已经在 Cherry Studio 验证可用的连接 | 需要模型服务的 CLI | 自带账号登录的工具按原生流程登录 |
| 工作目录 | 只选择当前项目目录 | 修改代码、运行检查 | 启动后先确认终端所在路径 |
| 第一次命令 | 只读查看项目状态 | 验证账号、模型和目录 | 确认无误后再允许写文件 |
### 完成标准
页面能识别安装来源；终端在正确目录打开；最小只读命令成功；工具显示的账号或模型与预期一致。
## 安装来源要分清
| 来源 | Cherry Studio 会做什么 | 你应该如何维护 |
| ---------------- | ------------------ | ------------------ |
| Cherry Studio 托管 | 安装、更新和卸载对应托管副本 | 在【编码搭档】或【环境依赖】中管理 |
| 系统 PATH | 检测并直接使用，不覆盖 | 用原包管理器更新或卸载 |
| 应用内置 | 直接使用，不提供系统级卸载 | 随 Cherry Studio 更新 |
{% hint style="warning" %}
卸载 Cherry Studio 托管副本后，如果系统中还有同名可执行文件，页面会自动回退到系统版本。版本或行为变化时，先确认当前使用的是哪一种来源。
{% endhint %}
为什么找不到已经安装的终端或 CLI？
Cherry Studio 从登录环境和标准位置检测工具。确认命令在登录终端中可运行，然后重启应用刷新环境。便携式或非标准路径目前需要从该终端手动启动。
# 笔记
笔记是 Cherry Studio 内置的 Markdown 编辑器，方便您在与 AI 对话之外整理灵感、保存阶段性产出，并借助 AI 与知识库能力进一步加工。
### 打开笔记
顶部标签栏点击【笔记】，或在【启动台】中点击【笔记】应用图标。
笔记界面：左侧是目录树与笔记列表，右侧是 Markdown 编辑器
### 创建第一篇笔记
1. 点击左上角第一个【新建笔记】图标
2. 在右侧编辑器中输入正文，支持 Markdown 语法与富文本快捷工具栏
3. 右键笔记列表中的笔记，为其命名
### 导入已有 Markdown 文件
* 直接将 `.md` 文件或包含 `.md` 文件的目录 **拖拽** 到笔记区域，即可导入为新笔记或新文件夹
* 也可点击左上角第二个【新建文件夹】图标先建好目录，再向其中拖拽
### 编辑器功能
笔记编辑器顶部工具栏提供常用富文本能力：
* **格式化**：粗体（B）、斜体（I）、下划线（U）、删除线
* **结构**：行内代码 / H1–H3 标题 / 无序列表 / 有序列表 / 代码块 / 引用 / 任务清单 / 公式
* **嵌入**：表格、超链接
新建笔记并写入正文后的编辑器
底部状态栏显示当前 **字符数**，左下角的 **A✓** 图标可开关拼写检查，右下角下拉切换 **实时预览**、**源码模式** 或 **阅读模式**。
### 目录管理
左侧侧栏顶部依次是：【新建笔记】/【新建文件夹】/【排序】/【收藏】/【搜索】。
* **排序**：6 个选项——文件名 `A→Z` / `Z→A`、更新时间从新到旧 / 从旧到新、创建时间从新到旧 / 从旧到新
* **收藏**：星标按钮切到"已收藏"视图
* **搜索**：放大镜按钮，搜索框中输入即可。**搜索同时匹配标题与正文**，命中正文的条目会在标题旁加 "内容" 或 "名称+内容" 标签提示来源
### 右键菜单（AI 联动 + 导出）
在左侧目录树 **右键** 任一笔记会弹出操作菜单——这是 AI 联动与多格式导出的入口：
右键单条笔记弹出的菜单
* **生成笔记名称** ✨：让 AI 根据正文自动生成一个标题（仅文件可用）
* **重命名** / **从外部打开**（在 Finder / 资源管理器中显示）
* **收藏笔记** / **取消收藏**
* **导出笔记到知识库**：发送到指定 [知识库](/knowledge-base/knowledge-base)
* **导出 ›** 二级菜单：Markdown / Word（.docx）/ Notion / 语雀 / Obsidian / Joplin / 思源，以及"复制为图片 / 导出为图片"——每一项的显示可在【设置】→【数据设置】→【导出菜单设置】中单独开关
* **删除**
> 文件夹的右键菜单更精简，只有：新建笔记 / 新建文件夹 / 重命名 / 从外部打开 / 删除。
### 右上角【⋯】菜单（视图与导出快捷入口）
笔记标题右上角的【⋯】是 **当前笔记** 的视图 / 导出快捷入口，不要和右键菜单混淆：
右上角【⋯】菜单
* **复制内容**：纯文本复制
* **导出为 Word**：快速生成 `.docx`（需要更多格式请走右键菜单的"导出 ›"）
* **导出为 PDF**：将当前笔记导出为 PDF 文件
* **打印**：调用系统打印当前笔记
* **缩减栏宽**：限制每行最大字数
* **显示目录大纲**：右侧显示当前笔记的标题树
* **字体设置 ›**：默认 / 衬线字体，三档字号（小 / 中 / 大）
* **更多设置**：打开笔记设置面板（数据 / 编辑器 / 显示三组设置）
### 工作目录与备份
笔记内容存储为本地文件。**工作目录** 在笔记设置面板的【数据设置】中查看与修改（从右上角【⋯】→【更多设置】打开）。
* 默认存放于 Cherry Studio 应用数据目录下
* 先【选择】自定义路径，再点【应用】切换（更改不会自动迁移已有文件，需手动复制）；点【重置为默认】可还原到默认目录
* 备份建议结合 [WebDAV](/pre-basic/settings/data-settings/webdav) / [S3 兼容存储](/pre-basic/settings/data-settings/s3-compatible)
### 编辑器与显示设置
从右上角【⋯】→【更多设置】打开笔记设置面板，除【数据设置】外还有两组：
**编辑器设置**
* **默认视图**：新笔记默认进入【编辑模式】还是【阅读模式】
* **默认编辑视图**：编辑模式下默认采用【实时预览】还是【源码模式】
**显示设置**
* **字体**：默认 / 衬线字体
* **字体大小**：10–30px 之间
* **缩减栏宽**：限制每行字数，让长行不至于横铺整屏
* **显示目录大纲**：在右侧显示当前笔记的标题树，便于文内导航
> 字体与字号既可在此显示设置面板调整，也能从右上角【⋯】→【字体设置】快速切换。
### 提示与技巧
* 笔记支持任务清单 `- [ ]` 写法，可用于日常待办
* 拖拽 `.md` 文件（或包含 `.md` 的目录）到目录树即可批量导入
* 跨设备恢复配置后若发现笔记目录为空，按提示路径手动复制文件即可
{% hint style="info" %}
若要让 AI **直接** 基于笔记内容回答问题，最方便的做法是把目标笔记 **导出到知识库**，然后在对话中开启该知识库。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 快捷助手
快捷助手是 Cherry Studio 提供的一个便捷工具，它允许您在任何应用程序中快速访问 AI 功能，从而实现即时提问、翻译、总结和解释等操作。
### 启用快捷助手
1. **打开设置：** 进入【设置】→【快捷助手】（在左侧菜单中）。
2. **启用开关：** 打开【启用快捷助手】。开启后页面会展开更多选项。
{% hint style="info" %}
**快捷助手 vs 划词助手**：两者是不同的功能。
* **快捷助手**：通过快捷键唤起一个迷你窗口主动提问，不依赖你当前选中的内容。
* **划词助手**：在任意应用内选中文字后，通过工具栏对所选文字做翻译/解释/改写。
* 配置入口分别在【设置】→【快捷助手】与【设置】→【划词助手】。
{% endhint %}
启用后的快捷助手设置
启用后可见的开关：
* **启用快捷助手**：主开关
* **点击托盘图标启动**：左键点击系统托盘 Cherry Studio 图标时直接唤起快捷助手（默认开启）
* **启动时读取剪贴板**：每次唤起快捷助手时自动把剪贴板内容作为输入
* **快捷助手模型**：【使用助手】跟随所选助手的模型；【默认模型】使用 [全局默认快速模型](/pre-basic/settings/default-models)
3. **设置快捷键（在另一个页面）：**
* 快捷键不在本页配置，需到【设置】→【快捷键】中调整。
* Windows 默认 Ctrl + E，macOS 默认 ⌘ + E。
* 可自定义快捷键以避免冲突或更符合个人习惯。
### 使用快捷助手
1. **唤起：** 在任何应用程序中，按下您设置的快捷键（或默认快捷键）即可打开快捷助手。
2. **交互：** 在快捷助手窗口中，您可以直接进行以下操作：
* **快速提问：** 向 AI 提问任何问题。
* **文本翻译：** 输入需要翻译的文本。
* **内容总结：** 输入长文本进行摘要。
* **解释说明：** 输入需要解释的概念或术语。
快捷助手界面示意图
3. **关闭：** 按下 ESC 键或点击快捷助手窗口外部的任意位置即可关闭。
{% hint style="info" %}
当【快捷助手模型】选【默认模型】时使用 [全局默认快速模型](/pre-basic/settings/default-models)；选【使用助手】后可以指定一个已有助手作为响应的模型。
{% endhint %}
### 提示与技巧
* **快捷键冲突：** 如果默认快捷键与其他应用程序冲突，请修改快捷键。
* **探索更多功能：** 除了文档中提到的功能，快捷助手可能还支持其他操作，例如代码生成、风格转换等。建议您在使用过程中不断探索。
* **反馈与改进：** 如果您在使用过程中遇到任何问题或有任何改进建议，请及时向 Cherry Studio 团队 [反馈](/question-contact/suggestions)。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 划词助手
划词助手（Selection Assistant）让你在 **任意应用中选中文字** 后，通过浮动工具栏调用 AI 做翻译、解释、优化、总结等操作，无需把内容粘贴回 Cherry Studio。
{% hint style="info" %}
**与** [**快捷助手**](/cherry-studio/preview/quick-assistant) **的区别**：
* **快捷助手**：用全局快捷键唤起一个 **主动输入** 窗口，你打字提问
* **划词助手**：选中文字后 **针对所选内容** 弹出工具栏，一键执行预设操作
{% endhint %}
### 平台支持
* ✅ **macOS**：完整支持，但首次启用需授予 **辅助功能（Accessibility）权限**
* ✅ **Windows**：完整支持，无需特殊权限
* ⚠️ **Linux**：仅在 **X11** 模式下完整支持；Wayland 模式下工具栏可能无法跟随选中文本定位。同时需要将当前用户加入 `input` 组（`sudo usermod -aG input $USER`）以获取按键监听权限
### 启用划词助手
打开【设置】→【划词助手】：
划词助手设置面板
1. 打开 **启用** 开关
2. **macOS** 用户首次启用会弹窗请求 **辅助功能权限**：
首次启用时的辅助功能权限提示
点击 **去设置** → 在弹出的【系统设置】→【隐私与安全性】→【辅助功能】中找到 Cherry Studio 并打开开关 → 回到 Cherry Studio 再次启用。
3. （可选）在【工具栏】→【取词方式】选择触发方式（不同平台可选项不同）：
* **划词**：选中文字后立即弹出工具栏（默认）
* **Ctrl 键**（仅 Windows）：选中文字后 **再长按 Ctrl 键** 才弹（避免误触）
* **快捷键**：选中文字后按快捷键再弹，快捷键在【设置】→【快捷键】中改
启用后的设置面板：取词方式 / 紧凑模式 / 跟随工具栏…
### 内置操作
划词助手提供 7 个内置操作，**默认启用 5 个**：翻译 / 解释 / 总结 / 搜索 / 复制。工具栏左侧的 **Cherry 图标不是操作按钮**——它只是工具栏的拖拽手柄，按住可移动整条工具栏。
| 操作 | 默认启用 | 用途 |
| ------ | ---- | ----------------------------------- |
| **翻译** | ✅ | 智能翻译：优先翻译为目标语言；若已是目标语言则翻译为备选语言 |
| **解释** | ✅ | 让 AI 解释这段内容 |
| **总结** | ✅ | 让 AI 用一段话总结所选内容 |
| **搜索** | ✅ | 用所选文字调用搜索引擎查询（默认 Google，可在每项右侧 ⋯ 改） |
| **复制** | ✅ | 复制选中文字 |
| **优化** | 待启用 | 让 AI 改写得更通顺 / 更专业，需在设置中拖入启用区 |
| **引用** | 待启用 | 把选中文字以引用形式发送到当前对话，需在设置中拖入启用区 |
设置面板的【功能】区：上方为已启用，下方暂存区拖到上方即启用
### 自定义操作
在【设置】→【划词助手】→【功能】中可：
* **编辑** 内置操作的提示词
* **添加** 自定义操作（命名 + 提示词 + 默认模型）
* **拖拽** 调整工具栏中操作的顺序
* 把不常用的操作拖到下方暂存区即可"停用"
### 工具栏 / 结果窗口外观
工具栏：
* **紧凑模式**：只显示图标，不显示文字，节省屏幕空间
结果窗口（【功能窗口】节）：
* **跟随工具栏**：窗口贴着工具栏弹（默认开），关闭则始终居中
* **记住大小**：本次手动调过的窗口尺寸，下次保留
* **自动关闭**：点窗口外即关
* **自动置顶**：始终悬浮在其他应用之上
* **透明度**：20%–100% 可调
### 搜索引擎
划词助手内置的【搜索】操作可选预设引擎（Google、Bing、DuckDuckGo 等）。配置入口在【设置】→【划词助手】→【功能】：找到 **搜索** 这条，点击行末右侧的齿轮图标弹出【设置搜索引擎】对话框，可在预设里挑或加自定义引擎，URL 中用 `{{queryString}}` 表示搜索词位置。
### 应用筛选（高级）
可在【设置】→【划词助手】→【高级】→【应用筛选】中设置 **黑名单 / 白名单**，让划词助手只在指定应用中生效（白名单）或不在指定应用中弹出（黑名单）。
* **macOS**：填入应用的 Bundle ID（如 `com.google.Chrome`、`com.apple.mail`）
* **Windows**：填入应用的可执行文件名（如 `chrome.exe`、`Cherry Studio.exe`）
### 使用的模型
划词助手默认使用 [全局默认对话模型](/pre-basic/settings/default-models)，也可针对每个操作单独指定模型。
### 提示与技巧
* macOS 上若工具栏不出现，检查【系统设置】→【隐私与安全性】→【辅助功能】中 Cherry Studio 是否打勾
* 频繁因误触选中文字而弹工具栏？切到 **Ctrl 键** 触发模式
* 工具栏图标过多挤屏？开启 **紧凑模式**
* 想做"翻译完直接朗读"等链式操作？把"翻译"结果复制后调用 [快捷助手](/cherry-studio/preview/quick-assistant) 继续处理
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 模型服务
Cherry Studio 内置 60+ 家 Provider（模型服务商）的连接模板，覆盖国内外大部分主流模型与本地推理框架。本节为每家 Provider 提供独立配置指南。
### Provider 类型
Cherry Studio 把 Provider 按协议分为以下几类，行为略有差异：
| 类型 | 兼容协议 | 典型代表 |
| ---------------- | ------------------------- | ----------------------------------------------- |
| **OpenAI 兼容** | `/v1/chat/completions` | OpenAI、DeepSeek、硅基流动、OpenRouter、绝大多数三方网关 |
| **Anthropic 兼容** | `/v1/messages` | Anthropic、CherryIN、部分网关。**Cherry Agent 需要此类型** |
| **Gemini** | Google AI Studio / Vertex | Google Gemini、Vertex AI |
| **Bedrock** | AWS Bedrock SDK | AWS Bedrock |
| **Azure OpenAI** | Azure OpenAI Service | Azure OpenAI |
| **本地推理** | 本地 HTTP 服务 | Ollama、LM Studio、GPUStack、OpenVINO Model Server |
| **特殊网关** | 厂商私有协议 | NewAPI、OneAPI、AiHubMix、DMXAPI 等 |
### 添加一个 Provider 的通用步骤
1. 打开 `设置 → 模型服务`
2. 在内置 Provider 列表中找到目标 Provider，点击进入详情页
3. 填写 **API 密钥**（必填），按需修改 **API 地址**（默认是 Provider 官方地址）
4. 点击 **获取模型列表**，按需添加你常用的对话/嵌入/视觉模型
5. （可选）点击 **检测**，用任一对话模型验证连接是否成功
### Provider 配置详解
#### 通用/网关类
* [CherryAI (免费)](/pre-basic/providers/cherryai)
* [CherryIN](/pre-basic/providers/cherryin-1) — 双端点（OpenAI + Anthropic），Cherry Agent 推荐
* [NewAPI](/pre-basic/providers/newapi) / [OneAPI](/pre-basic/providers/oneapi) — 自建/三方网关
#### 海外厂商
* [OpenAI](/pre-basic/providers/openai)
* [Google Gemini](/pre-basic/providers/google-gemini)
* [Vertex AI](/pre-basic/providers/vertex-ai)
* [Mistral](/pre-basic/providers/mistral)
* [Perplexity](/pre-basic/providers/perplexity)
* [GitHub Copilot](/pre-basic/providers/github-copilot)
* [MiniMax Coding Plan](/pre-basic/providers/minimax-coding-plan)
#### 国内厂商
* [阿里云百炼](/pre-basic/providers/a-li-yun-bai-lian)
* [智谱 ZhiPu](/pre-basic/providers/zhipu)
* [硅基流动](/pre-basic/providers/siliconcloud)
* [火山引擎（豆包）](/pre-basic/providers/doubao)
* [PPIO 派欧云](/pre-basic/providers/ppio)
* [ModelScope（魔搭）](/pre-basic/providers/modelscope)
#### 本地推理
* [Ollama](/pre-basic/providers/ollama)
#### 自定义服务商
* [自定义服务商](/pre-basic/providers/zi-ding-yi-fu-wu-shang) — 任意 OpenAI / Anthropic / Gemini 兼容端点
{% hint style="info" %}
**没找到你用的 Provider 怎么办？**
Cherry Studio 内置 60+ Provider 模板，但 **远多于本节文档已收录** 的数量。如果你用的是 Anthropic（Claude）、Azure OpenAI、DeepSeek 官方、Grok、Groq、LM Studio、OpenRouter、Mistral、Perplexity、Together 等，**它们都在 Provider 列表里**，直接添加密钥即可。本节文档将分批补齐这些 Provider 的专题页。
{% endhint %}
### API 密钥与 API 地址
详见 [模型服务设置](/pre-basic/providers/providers)（含 多 Key 轮询、`#` 结尾固定路径等高级用法）。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 全部 Provider 快速参考
Cherry Studio 内置 **60+ 家 Provider**，本页提供总览表，找到目标 Provider 后 **按指引填写密钥即可使用**。已有专题文档的 Provider 提供跳转链接，其余按通用步骤（[Provider 总览](/pre-basic/providers)）配置。
## 使用步骤
1. **查找目标 Provider**（可用 Ctrl/⌘+F 快速搜索）
2. 点击 **官网** 注册账号并获取 API Key
3. 在 Cherry Studio `设置 → 模型服务` 中找到对应 Provider，填写密钥后点击"获取模型列表"
4. 完成配置
## 一句话决策
| 你的需求 | 推荐方向 |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **新手快速上手**，避免复杂流程 | [CherryIN](/pre-basic/providers/cherryin-1) 或 [CherryAI](/pre-basic/providers/cherryai) |
| **国内访问最方便** | DeepSeek / Moonshot / 硅基流动 / 智谱 |
| **海外最强模型** | OpenAI / Anthropic / Gemini |
| **一个 key 通用 200 家** | [OpenRouter](/pre-basic/providers/openrouter) |
| **完全本地、隐私敏感** | [Ollama](/pre-basic/providers/ollama) / [LM Studio](/pre-basic/providers/lm-studio) |
| **企业合规** | [Azure OpenAI](/pre-basic/providers/azure-openai) / AWS Bedrock |
| **使用** [**智能体**](/cherry-studio/preview/agent) | [Anthropic](/pre-basic/providers/anthropic) / [CherryIN](/pre-basic/providers/cherryin-1)（要支持 Anthropic 协议） |
## 国内大厂自营模型
无需翻墙、有中文优势、价格相对便宜。
| Provider | 一句话特点 | 官网 | 专题文档 |
| ---------------------- | ----------------------------- | ----------------------------------------------------------------- | ------------------------------------------- |
| **DeepSeek** | 编程与推理性价比之王 | [deepseek.com](https://platform.deepseek.com/) | [→](/pre-basic/providers/deepseek) |
| **Moonshot AI (Kimi)** | 超长上下文（最长 200 万字） | [moonshot.cn](https://platform.moonshot.cn/) | [→](/pre-basic/providers/moonshot) |
| **ZhiPu (智谱)** | GLM 系列，多模态，兼容 Anthropic 可跑智能体 | [bigmodel.cn](https://open.bigmodel.cn/) | [→](/pre-basic/providers/zhipu) |
| **doubao (豆包/火山引擎)** | 字节出品，价格亲民 | [volcengine.com](https://www.volcengine.com/product/doubao) | [→](/pre-basic/providers/doubao) |
| **Baidu Cloud (文心一言)** | 百度 ERNIE 系列 | [cloud.baidu.com](https://cloud.baidu.com/) | — |
| **Bailian (阿里百炼)** | Qwen 系列、有海量模型 | [bailian.console.aliyun.com](https://bailian.console.aliyun.com/) | [→](/pre-basic/providers/a-li-yun-bai-lian) |
| **BAICHUAN AI** | 百川大模型 | [baichuan-ai.com](https://platform.baichuan-ai.com/) | — |
| **MiniMax** | 国内多模态（语音、视频） | [minimaxi.com](https://platform.minimaxi.com/) | [→](/pre-basic/providers/minimax) |
| **StepFun** | 阶跃星辰 | [stepfun.com](https://platform.stepfun.com/) | — |
| **LongCat** | 美团 LongCat 系列 | [longcat.chat](https://longcat.chat/) | — |
| **Xiaomi MiMo** | 小米大模型 | [mimo.mi.com](https://mimo.mi.com/) | — |
## 海外大厂自营模型
效果第一梯队，国内访问通常需要代理。
| Provider | 一句话特点 | 官网 | 专题文档 |
| ------------------- | ----------------- | --------------------------------------------------------- | --------------------------------------- |
| **OpenAI** | GPT 系列 | [openai.com](https://platform.openai.com/) | [→](/pre-basic/providers/openai) |
| **Anthropic** | Claude 系列，智能体首选 | [anthropic.com](https://console.anthropic.com/) | [→](/pre-basic/providers/anthropic) |
| **Gemini (Google)** | Google 大模型 | [aistudio.google.com](https://aistudio.google.com/) | [→](/pre-basic/providers/google-gemini) |
| **Azure OpenAI** | 微软托管的 OpenAI，企业合规 | [portal.azure.com](https://portal.azure.com/) | [→](/pre-basic/providers/azure-openai) |
| **VertexAI** | Google Cloud 托管 | [cloud.google.com](https://cloud.google.com/vertex-ai) | [→](/pre-basic/providers/vertex-ai) |
| **AWS Bedrock** | 亚马逊托管多家模型 | [aws.amazon.com/bedrock](https://aws.amazon.com/bedrock/) | — |
| **Mistral** | 欧洲开源模型代表 | [mistral.ai](https://console.mistral.ai/) | [→](/pre-basic/providers/mistral) |
| **Grok (xAI)** | 马斯克 xAI，自带联网 | [x.ai](https://console.x.ai/) | [→](/pre-basic/providers/grok) |
| **Perplexity** | 搜索增强对话 | [perplexity.ai](https://www.perplexity.ai/) | [→](/pre-basic/providers/perplexity) |
## 网关 / 聚合
一个 key 接入多家模型，账号集中管理。
| Provider | 一句话特点 | 官网 | 专题文档 |
| --------------------- | ------------------------------------- | --------------------------------------------- | ------------------------------------ |
| **CherryAI** | Cherry 官方免费体验 | — | [→](/pre-basic/providers/cherryai) |
| **CherryIN** | Cherry 官方付费网关，双端点（OpenAI + Anthropic） | [open.cherryin.cc](https://open.cherryin.cc/) | [→](/pre-basic/providers/cherryin-1) |
| **OpenRouter** | 海外最大聚合，200+ 模型 | [openrouter.ai](https://openrouter.ai/) | [→](/pre-basic/providers/openrouter) |
| **AiHubMix** | 海外聚合 | [aihubmix.com](https://aihubmix.com/) | — |
| **DMXAPI** | 国内聚合 | [dmxapi.cn](https://dmxapi.cn/) | — |
| **302.AI** | 国内聚合 | [302.ai](https://302.ai/) | — |
| **NewAPI** | 自建网关（开源） | [newapi.pro](https://docs.newapi.pro/) | [→](/pre-basic/providers/newapi) |
| **OneAPI** | 自建网关（开源） | — | [→](/pre-basic/providers/oneapi) |
| **PPIO 派欧云** | 国内云算力 + 模型 | [ppio.com](https://ppio.com/) | [→](/pre-basic/providers/ppio) |
| **BurnCloud** | 国内聚合 | [burncloud.com](https://ai.burncloud.com/) | — |
| **AIOnly** | 国内聚合 | [aiionly.com](https://www.aiionly.com/) | — |
| **ocoolAI** | 国内聚合 | [ocoolai.com](https://one.ocoolai.com/) | — |
| **Poe** | Quora 旗下 AI 集市 | [poe.com](https://poe.com/) | — |
| **Vercel AI Gateway** | Vercel 旗下网关 | [vercel.com/ai](https://vercel.com/ai) | — |
## 超低延迟 / 高吞吐推理服务
适合需要"速度感"的场景（IM 机器人、实时翻译等）。
| Provider | 一句话特点 | 官网 | 专题文档 |
| --------------- | ------------ | --------------------------------------- | ------------------------------ |
| **Groq** | LPU 硬件，毫秒级响应 | [groq.com](https://console.groq.com/) | [→](/pre-basic/providers/groq) |
| **Cerebras AI** | 自研芯片，超大上下文 | [cerebras.ai](https://cerebras.ai/) | — |
| **Together** | 开源模型集中托管 | [together.ai](https://www.together.ai/) | — |
| **Fireworks** | 开源模型推理优化 | [fireworks.ai](https://fireworks.ai/) | — |
## 国产云 + 算力服务
| Provider | 一句话特点 | 官网 | 专题文档 |
| ------------------- | ---------- | ----------------------------------------------- | -------------------------------------- |
| **Silicon (硅基流动)** | 国内最大开源模型托管 | [siliconflow.cn](https://cloud.siliconflow.cn/) | [→](/pre-basic/providers/siliconcloud) |
| **ModelScope (魔搭)** | 阿里旗下开源模型平台 | [modelscope.cn](https://modelscope.cn/) | [→](/pre-basic/providers/modelscope) |
| **AlayaNew** | 国内推理服务 | [alayanew.com](https://www.alayanew.com/) | — |
| **Qiniu (七牛)** | 七牛云 AI | [qiniu.com](https://www.qiniu.com/) | — |
| **LANYUN** | 国内推理 | [lanyun.net](https://maas.lanyun.net/) | — |
| **Xirang** | 天翼云息壤 | [ctyun.cn](https://www.ctyun.cn/) | — |
## 嵌入 / 重排专用
只用于做嵌入或重排，配合知识库 / 全局记忆使用。
| Provider | 一句话特点 | 官网 | 专题文档 |
| ------------ | ---------------- | ----------------------------------------- | ---- |
| **Jina** | 嵌入、重排、CLIP，免费额度大 | [jina.ai](https://jina.ai/) | — |
| **VoyageAI** | 嵌入 / 重排专家 | [voyageai.com](https://www.voyageai.com/) | — |
## 本地推理
完全离线，保护隐私。
| Provider | 一句话特点 | 官网 | 专题文档 |
| ------------------------- | ------------------------- | --------------------------------------- | ----------------------------------- |
| **Ollama** | 命令行本地推理，最流行 | [ollama.com](https://ollama.com/) | [→](/pre-basic/providers/ollama) |
| **LM Studio** | GUI 本地推理，Apple Silicon 友好 | [lmstudio.ai](https://lmstudio.ai/) | [→](/pre-basic/providers/lm-studio) |
| **GPUStack** | 企业级本地推理 | [gpustack.ai](https://gpustack.ai/) | — |
| **OpenVINO Model Server** | Intel 加速本地推理 | [openvino.ai](https://www.openvino.ai/) | — |
## 模型平台 / 其他
| Provider | 一句话特点 | 官网 | 专题文档 |
| ------------------ | ----------------- | ---------------------------------------------------------------------- | ---------------------------------------- |
| **Hugging Face** | 全球最大开源模型社区 | [huggingface.co](https://huggingface.co/) | — |
| **GitHub Copilot** | 微软 GitHub 编程助手 | [github.com/features/copilot](https://github.com/features/copilot) | [→](/pre-basic/providers/github-copilot) |
| **GitHub Models** | GitHub 模型市场（Beta） | [github.com/marketplace/models](https://github.com/marketplace/models) | — |
| **MiniMax Global** | MiniMax 海外版 | [minimax.io](https://platform.minimax.io/) | — |
| **SophNet** | 国内模型托管 | [sophnet.com](https://sophnet.com/) | — |
| **PH8** | 国内推理 | [ph8.co](https://ph8.co/) | — |
| **Z.ai** | 智谱国际版 | [z.ai](https://z.ai/) | — |
| **nvidia** | NVIDIA NIM 推理 | [nvidia.com](https://www.nvidia.com/ai/) | — |
## 自定义服务商
如果你用的服务不在上面列表里，但提供 **OpenAI 兼容 / Anthropic 兼容 / Gemini 兼容** 任一协议，都可以通过 [自定义服务商](/pre-basic/providers/zi-ding-yi-fu-wu-shang) 添加。
## 还是不知道选哪个？
直接走 [**CherryIN**](/pre-basic/providers/cherryin-1) 或 [**CherryAI**](/pre-basic/providers/cherryai) —— 最适合新手快速上手。需要进阶时再换。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 模型服务设置
本页介绍 `设置 → 模型服务` 里单个服务商配置页的各项功能。配置某一家服务商的完整流程，见 服务商配置。
{% hint style="info" %}
* 内置服务商通常只需填对应的 **API 密钥**。
* 不同服务商对密钥的叫法不同：密钥、Key、API Key、令牌，指的都是同一个东西。
{% endhint %}
### API 密钥
填入服务商的 API 密钥即可。Cherry Studio 支持 **一个服务商配置多个密钥、轮询使用**（按列表从前到后循环）。有两种管理方式：
* **快速添加**：多个密钥用 **英文逗号** 隔开直接填入，如 `sk-xxx1,sk-xxx2,sk-xxx3`。
* **API 密钥管理**：点 API 密钥输入框右侧的 **钥匙图标按钮**（悬停显示「API 密钥管理」）即可进入——每个密钥是一个独立条目，可分别 **编辑标签**、**启用 / 禁用**、**复制**、**删除**。
{% hint style="warning" %}
用逗号分隔多个密钥时，必须使用 **英文** 逗号。
{% endhint %}
### API 地址
内置服务商一般无需填 API 地址（用默认即可）。如需修改，请按服务商官方文档填写。
> 若服务商给的是 `https://xxx.com/v1/chat/completions` 这种完整地址，通常只填 **根地址** `https://xxx.com` 即可，Cherry Studio 会自动补上 `/v1/chat/completions`。
{% hint style="info" %}
如果服务商的请求路径不是常规的 `/v1/chat/completions`，可在 API 地址栏填 **完整地址并以 `#` 结尾**——以 `#` 结尾时不再自动拼接版本路径，只用你填的地址。
{% endhint %}
### 添加模型
点服务商配置页的「**获取模型列表**」按钮，会拉取该服务商支持的模型；在弹出的「模型管理」列表里点模型右侧的 `+` 把它加入你的模型列表。**只有加入列表的模型** 才会出现在各处的模型选择器里。
模型名称下方会显示服务商返回的 **实际 API 模型 ID**。日期版、供应商前缀版等名称相近的模型不会再被合并；添加或选择模型前，先核对这行 ID，避免选到同名的另一版本。
### 连通性检查
点「**检测**」按钮、选一个模型即可测试是否配置成功（配置多个密钥时，还可选择用哪个密钥检测）。若检测失败，请检查模型列表里是否有填错的或不受支持的模型。
### API 设置（高级）
部分服务商可在「**API 设置**」里开启特定能力，如：支持数组格式的 message content、Developer Message、`enable_thinking`（控制 Qwen3 等模型的思考）、`service_tier`（仅 OpenAI）等。一般无需改动。
{% hint style="danger" %}
配置好后，务必打开服务商右上角的 **启用开关**，否则该服务商仍未启用，其模型不会出现在模型选择列表里。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# CherryAI (免费)
**CherryAI** 是 Cherry Studio 官方内置的 **免费模型** 入口——无需自己去第三方平台注册、申请 key，打开就能用上一批免费额度的模型，适合刚上手、想先把功能跑通的用户。
### 在哪里用
打开 `设置 → 模型服务`，在内置列表里找到 **CherryAI** 即可。它已随软件预置，通常无需额外配置；点 **获取模型列表** 就能看到当前可用的免费模型。
### 可用的免费模型
{% hint style="warning" %}
**免费模型阵容是动态的。** 具体有哪些型号、各自的额度与限流，都由 Cherry 服务端实时下发、会不定期调整，**一切以你在软件内点 【获取模型列表】 看到的实际结果为准**。下面几篇只是对部分常见免费模型的说明，不代表当前完整清单。
{% endhint %}
* [DeepSeek V3.2](/pre-basic/providers/cherryai/free-deepseek)
* [智谱 GLM-4.6V](/pre-basic/providers/cherryai/free-glm46v)
* [智谱 GLM-4.5-Air](/pre-basic/providers/cherryai/free-glm45air)
* [Qwen3-8B](/pre-basic/providers/cherryai/free-qwen)
若需要更稳定、更强的模型，可选择 [CherryIN](/pre-basic/providers/cherryin-1) 或其他 [服务商](/pre-basic/providers)。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# DeepSeek V3.2
Cherry Studio 用户现在可以通过内置的 **CherryIN** 服务免费体验 **DeepSeek V3.2**——DeepSeek 于 2025 年 12 月 1 日发布的旗舰级稀疏注意力 MoE 模型，首次将"思考"原生集成到工具调用中，是进阶 Agent 与长上下文场景的理想选择。
***
## 什么是 DeepSeek V3.2？
DeepSeek V3.2 基于 V3.2-Exp 迭代而来，采用 Mixture-of-Experts（MoE）架构，并引入 **DeepSeek Sparse Attention（DSA）** 稀疏注意力机制，在保持超大规模总参数的同时显著降低长上下文推理成本。
* 架构：MoE + DeepSeek Sparse Attention（DSA）+ Multi-Head Latent Attention（MLA）
* 总参数量：685B
* 每 Token 激活参数量：约 37B
* 专家数：每层 256 个专家
* 开源许可：MIT
* 发布时间：2025 年 12 月 1 日（V3.2-Exp 于 2025 年 9 月 29 日发布）
V3.2 同时发布了面向 API 的 **DeepSeek-V3.2-Speciale** 版本，在复杂推理任务上取得 IMO、CMO、ICPC World Finals 与 IOI 2025 的金牌级表现。
***
## 延续扎实的训练与对齐流程
DeepSeek V3.2 沿用了 V3 系列成熟的训练流水线，并针对 Agent 场景做了关键扩展：
1. **大规模预训练**：在海量高质量多语言语料上完成基础训练，覆盖代码、数学与科学知识。
2. **稀疏注意力引入**：在 128K 序列长度下训练主模型与 lightning indexer，每个 query token 选择 2048 个 key-value token 参与注意力。
3. **大规模 Agent 数据合成**：覆盖 1,800+ 环境与 85,000+ 复杂指令的全新 Agent 训练数据合成方法。
4. **思考与工具调用融合**：V3.2 是 DeepSeek 首个将"思考"原生集成到工具调用中的模型，支持在"思考模式"与"非思考模式"下均可调用工具。
***
## 旗舰级核心能力
DeepSeek V3.2 主打"与 GPT-5 水平相当"的综合能力，并在 Agent 与复杂推理上大幅强化：
* ✅ **原生思考 + 工具调用**：首个将 thinking 集成进 tool-use 的 DeepSeek 模型
* ✅ **顶级推理能力**：V3.2-Speciale 在 IMO / CMO / ICPC World Finals / IOI 2025 上达到金牌水平
* ✅ **代码与开发任务**：继承 V3 系列强代码能力
* ✅ **长上下文稳定性**：DSA 带来的长文档与代码库级分析能力
* ✅ **结构化工具调用**：适合构建多步规划与执行的 Agent
***
## DeepSeek Sparse Attention：更长、更省
DSA 是 V3.2 的核心技术升级，通过 **lightning indexer + 细粒度 token 选择** 实现：
* 首次在大模型上实现细粒度稀疏注意力
* 将核心注意力复杂度从 O(L²) 降低
* 在长上下文训练与推理上显著提速，同时保持与稠密注意力几乎一致的输出质量
| 场景 | 推荐用法 | 示例 |
| ----------- | --------- | ---------------- |
| 短对话 / 简单问答 | 直接调用 | 日常问答、摘要 |
| 中等复杂任务 | 启用工具调用 | 数据分析、代码重构 |
| 复杂 Agent 任务 | 思考 + 工具调用 | 多步规划、代码库分析、长文档审阅 |
***
## 开放、可用、生态友好
* ⚡ DSA 带来的长上下文推理加速
* 💰 通过 CherryIN 在 Cherry Studio 中 **免费使用**
* 🖥️ 开源权重、MIT 许可，vLLM、SGLang 等主流推理框架 Day-0 支持
***
## 聚焦实用能力：代码与 Agent
DeepSeek V3.2 在实际开发工作流中表现尤为出色：
* 多语言代码生成与重构
* 代码仓库级上下文理解与补丁生成
* Agent 工具链：稳定调用外部工具、搜索、代码执行
* 数学与复杂推理：支持竞赛级题目
***
## 如何在 Cherry Studio 中使用？
1. 打开 Cherry Studio，进入 **设置 → 模型服务**。
2. 找到 **CherryIN** 服务商并开启。
3. 在模型列表中选择 **DeepSeek V3.2**。
4. 返回聊天界面，在顶部模型选择处切换为 **DeepSeek V3.2** 即可开始对话。
> 💡 提示：CherryIN 提供的免费模型额度由 Cherry Studio 官方承担，适合日常体验与评测；生产环境建议结合 DeepSeek 官方 API 使用。
***
📘 **立即体验 DeepSeek V3.2，开启旗舰级推理与 Agent 之旅！**
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 智谱 GLM-4.6V
Cherry Studio 用户现在可以通过内置的 **CherryIN** 服务免费体验 **智谱 GLM-4.6V**——由 Z.ai（智谱 AI）于 2025 年 12 月发布的视觉旗舰模型，MoE 架构、128K 原生多模态上下文、原生多模态工具调用，是图文理解与多模态 Agent 场景的首选。
***
## 什么是 GLM-4.6V？
GLM-4.6V 是 Z.ai GLM-V 系列的最新一代视觉语言模型，原生支持文本 + 图像统一建模，在 GLM-4.5V 的基础上进一步扩展上下文与工具调用能力。
* 架构：Mixture-of-Experts（MoE）
* 总参数量：106B
* 激活参数量：约 12B
* 上下文长度：128K tokens
* 开源许可：MIT
* 发布时间：2025 年 12 月 8–9 日
* 视觉编码器：支持多分辨率图像（最高 4K）
系列同时包含 **GLM-4.6V-Flash（9B）**，面向本地与低延迟场景，免费可商用。
***
## 延续 GLM-V 系列的多模态训练体系
GLM-4.6V 沿用了 GLM-4.1V-Thinking / GLM-4.5V 的技术路线，并在视觉与 Agent 方向做了进一步强化：
1. **原生多模态建模**：文本与图像联合训练，支持图文混合输入
2. **上下文扩展**：训练上下文扩展至 128K tokens，单次可处理约 150 页密集文档、200 页幻灯片或 1 小时视频
3. **原生多模态工具调用**：工具可以直接接收与返回图像，基于扩展的 MCP 协议以 URL 方式处理多模态产物
4. **强化学习增强**：沿用 GLM-V 系列的可扩展 RL 流程
***
## 原生多模态，面向真实场景
GLM-4.6V 的多模态能力覆盖日常与专业场景：
* ✅ **富文本内容理解**：长文档、多页文本与图文混排
* ✅ **视觉网页搜索**：结合视觉输入进行联网检索与理解
* ✅ **前端复刻**：从设计稿或 UI 截图生成前端代码
* ✅ **长上下文多模态文档分析**：整份 PDF / 幻灯片 / 视频级输入
* ✅ **图表与表格解析**：结构化信息抽取
***
## 原生多模态工具调用与 Agent 能力
GLM-4.6V 的核心升级之一，是 **"视觉感知 → 可执行动作"** 的闭环：工具调用原生支持图像作为输入与输出，让多模态 Agent 在真实业务中落地。
| 场景 | 推荐用法 | 示例 |
| ----------- | --------- | ----------------------- |
| 简单图文问答 | 直接对话 | "这张图里有什么？" |
| 中等复杂任务 | 启用工具调用 | 读取图表后检索数据 |
| 复杂多模态 Agent | 多工具 + MCP | 截图 → 理解 → 调用 API → 生成报告 |
***
## 高效 MoE，开放可用
* ⚡ MoE 稀疏激活：106B 总参数，仅激活约 12B
* 💰 通过 CherryIN 在 Cherry Studio 中 **免费使用**
* 🖥️ 权重、推理代码与 MCP 工具已在 GitHub 与 Hugging Face 开源，MIT 许可
***
## 聚焦实用能力：多模态助手
GLM-4.6V 在实际使用中适合以下场景：
* **文档助手**：长文档、扫描件、幻灯片整份阅读与摘要
* **数据分析**：识别并解读图表、仪表盘截图
* **前端与设计**：根据 UI 截图生成或修改前端代码
* **视觉搜索**：结合图像进行联网检索与信息整合
* **多模态 Agent**：结合浏览器、代码执行、检索等工具完成复杂任务
***
## 如何在 Cherry Studio 中使用？
1. 打开 Cherry Studio，进入 **设置 → 模型服务**。
2. 找到 **CherryIN** 服务商并开启。
3. 在模型列表中选择 **智谱 GLM-4.6V**。
4. 返回聊天界面，在顶部模型选择处切换为 **GLM-4.6V**，即可在对话中直接上传图片进行图文交互。
> 💡 提示：CherryIN 提供的免费模型额度由 Cherry Studio 官方承担，适合日常体验与评测；生产环境建议结合 Z.ai（智谱）官方 API 使用。
***
📘 **立即体验 智谱 GLM-4.6V，解锁原生多模态与视觉 Agent 能力！**
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 智谱 GLM-4.5-Air
为了让每一位开发者和用户都能轻松体验前沿大模型的能力，**智谱向免费为 Cherry Studio 的用户开放了 GLM-4.5-Air 模型**。作为专为智能体（Agent）应用打造的高效基础模型，GLM-4.5-Air 在性能与成本之间实现了出色平衡，是构建智能应用的理想选择。
***
**🚀 什么是 GLM-4.5-Air？**
GLM-4.5-Air 是智谱最新推出的高性能语言模型，采用先进的 **混合专家架构（Mixture-of-Experts, MoE）**，在保持卓越推理能力的同时，显著降低计算资源消耗。
* **总参数量：1060 亿**
* **激活参数量：120 亿**
通过精简设计，GLM-4.5-Air 实现了更高的推理效率，适合在资源受限环境下部署，同时仍能胜任复杂任务处理。
***
**📚 统一训练流程，夯实智能基础**
GLM-4.5-Air 与旗舰系列共享一致的训练流程，确保其具备扎实的通用能力基础：
1. **大规模预训练**：在高达 **15 万亿 token 的通用语料** 上完成训练，构建广泛的知识理解能力；
2. **专项领域优化**：在代码生成、逻辑推理、智能体交互等关键任务上进行强化训练；
3. **长上下文支持**：上下文长度扩展至 **128K tokens**，可处理长文档、复杂对话或大型代码项目；
4. **强化学习增强**：通过 RL 优化模型在推理规划、工具调用等方面的决策能力。
这一训练体系为 GLM-4.5-Air 赋予了出色的泛化能力和任务适应性。
***
**⚙️ 专为智能体优化的核心能力**
GLM-4.5-Air 针对智能体应用场景进行了深度适配，具备以下实用能力：
✅ **工具调用支持**：可通过标准化接口调用外部工具，实现任务自动化\
✅ **网页浏览与信息提取**：可配合浏览器插件完成动态内容理解与交互\
✅ **软件工程辅助**：支持需求解析、代码生成、缺陷识别与修复\
✅ **前端开发支持**：对 HTML、CSS、JavaScript 等前端技术有良好理解与生成能力
该模型可灵活集成至 **Claude Code、Roo Code** 等代码智能体框架，也可作为任意自定义 Agent 的核心引擎使用。
***
**💡 智能“思考模式”，灵活响应各类请求**
GLM-4.5-Air 支持 **混合推理模式**，用户可通过 `thinking.type` 参数控制是否启用深度思考：
* `enabled`：启用思考，适合需要分步推理或规划的复杂任务
* `disabled`：禁用思考，用于简单查询或即时响应
* 默认设置为 **动态思考模式**，模型自动判断是否需要深入分析
| 任务类型 | 示例 |
| ------------------ | ------------------------------------------------ |
| **简单任务**（建议关闭思考） | - 查询“智谱 AI 的成立时间”
- 翻译“I love you”为中文
|
| **中等任务**（建议启用思考） | - 比较飞机与高铁从北京到上海的优劣
- 解释木星为何有较多卫星
|
| **复杂任务**（强烈建议启用思考） | - 说明 MoE 模型中专家如何协作
- 基于市场信息分析是否应买入 ETF
|
***
**🌟 高效低成本，部署更轻松**
GLM-4.5-Air 在性能与成本之间实现了优秀平衡，特别适合实际业务部署：
* ⚡ **生成速度超 100 tokens/秒**，响应迅速，支持低延迟交互
* 💰 **API 成本极低**：输入仅 **0.8 元/百万 tokens**，输出 **2 元/百万 tokens**
* 🖥️ 激活参数少，算力需求低，易于在本地或云端高并发运行
真正实现“高性能、低门槛”的 AI 服务体验。
***
**🧠 聚焦实用能力：智能代码生成**
GLM-4.5-Air 在代码生成方面表现稳定，支持：
* 覆盖 **Python、JavaScript、Java** 等主流语言
* 根据自然语言指令生成 **结构清晰、可维护性强** 的代码
* 减少模板化输出，贴近真实开发场景需求
适用于快速原型构建、自动化补全、Bug 修复等高频开发任务。
***
现在就免费体验 **GLM-4.5-Air**，开启你的智能体开发之旅！\
无论你是想打造自动化助手、编程伴侣，还是探索下一代 AI 应用，GLM-4.5-Air 都将是你高效可靠的 AI 引擎。
📘 立即接入，释放创造力！
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Qwen3-8B
**知名 MaaS 服务平台 “硅基流动”为大家免费提供 Qwen3-8B 模型的调用服务**。作为通义千问 Qwen3 系列中的高性价比成员，Qwen3-8B 以小巧体积实现强大能力，是智能应用与高效开发的理想选择。
***
**🚀 什么是 Qwen3-8B？**
Qwen3-8B 是阿里巴巴于 2025 年 4 月发布的通义千问第三代大模型系列中的 **80 亿参数密集模型**，采用 **Apache 2.0 开源协议**，可自由用于商业与研究场景。
* **总参数量：80 亿**
* **架构类型：Dense（纯稠密结构）**
* **上下文长度：128K tokens**
* **支持多语言：覆盖 119 种语言和方言**
尽管体积小巧，Qwen3-8B 在推理、代码、数学和 Agent 能力方面表现稳定，性能媲美前代更大的模型，在实际应用中展现出极高的实用性。
***
**📚 强大训练基础，小模型也有大智慧**
Qwen3-8B 基于 **约 36 万亿 token 的高质量多语言数据** 完成预训练，涵盖网页文本、技术文档、代码库与专业领域合成数据，知识覆盖面广。
其后训练阶段引入了 **四阶段强化流程**，特别优化了以下能力：
✅ 自然语言理解与生成\
✅ 数学推理与逻辑分析\
✅ 多语言翻译与表达\
✅ 工具调用与任务规划
得益于训练体系的全面升级，**Qwen3-8B 的实际表现接近甚至超越 Qwen2.5-14B**，实现显著的参数效率跃迁。\\
***
**💡 混合推理模式：思考 or 快速响应？**
Qwen3-8B 支持 **“思考模式”与“非思考模式”** 的灵活切换，用户可根据任务复杂度自主选择响应方式。
通过以下方式控制模式：
* **API 参数设置**：`enable_thinking=True/False`
* **提示词指令**：在输入中添加 `/think` 或 `/no_think`
| 模式 | 适用场景 | 示例 |
| --------- | -------------- | ----------------------------- |
| **思考模式** | 复杂推理、数学题、规划类任务 | - 求解几何问题
- 编写完整项目架构
|
| **非思考模式** | 快速问答、翻译、摘要 | - 查询天气
- 中英文互译
|
该设计让用户在 **响应速度与推理深度之间自由权衡**，提升使用体验。
***
**⚙️ 原生支持 Agent 能力，赋能智能应用**
Qwen3-8B 具备出色的 **Agent 化能力**，可轻松集成到各类自动化系统中：
🔹 **函数调用（Function Calling）**：支持结构化工具调用\
🔹 **MCP 协议兼容**：原生支持模型上下文协议，便于扩展外部能力\
🔹 **多工具协同**：可接入搜索、计算器、代码执行等插件
推荐结合 **Qwen-Agent 框架** 使用，快速构建具备记忆、规划与执行能力的智能助手。
***
**🌐 广泛语言支持，面向全球应用**
Qwen3-8B 支持包括中文、英文、阿拉伯语、西班牙语、日语、韩语、印尼语等在内的 **119 种语言和方言**，适用于国际化产品开发、跨语言客服、多语种内容生成等场景。
对中文理解尤为出色，支持简体、繁体及粤语表达，适用于港澳台及海外华人市场。
***
**🧠 实用能力强，场景覆盖广**
Qwen3-8B 在多个高频应用场景中表现优异：
✅ **代码生成**：支持 Python、JavaScript、Java 等主流语言，能根据需求生成可运行代码\
✅ **数学推理**：在 GSM8K 等基准中表现稳定，适合教育类应用\
✅ **内容创作**：撰写邮件、报告、文案，结构清晰、语言自然\
✅ **智能助手**：可构建个人知识库问答、日程管理、信息提取等轻量级 AI 助手
***
现在就通过 **硅基流动** 免费体验 Qwen3-8B，开启你的轻量 AI 应用之旅！\\
📘 立即使用，让 AI 触手可及！
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# CherryIN
1. 点击 CherryIN 服务商的 "点击这里获取密钥"
2. 在 CherryIN 的控制台中创建密钥，注意创建密钥时，根据令牌分组不同，模型倍率不同，即折扣不同。
3. 点击密钥后方的按钮，复制密钥到剪贴板
4. 在 Cherry Studio 中填入密钥（就是第 1 步那个服务商页面里的 API 密钥输入框）
5. 点击管理按钮，并添加模型
6. 在 Cherry Studio 中选择对应模型，即可对话
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# OpenAI
## 获取 APIKey
* 在官方 [API Key 页面](https://platform.openai.com/api-keys) 点击`+ Create new secret key`
* 将生成的 key 复制，并打开 CherryStudio 的 [模型服务设置](/pre-basic/providers/providers)
* 找到服务商 OpenAI，填入刚刚获取到的 key
* 点击最下方管理或者添加，加入支持的模型并打开右上角服务商开关就可以使用了。
{% hint style="info" %}
* 中国除台湾之外其他地区无法直接使用 OpenAI 服务，需自行解决代理问题；
* 需要有余额。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Anthropic
Anthropic 的 Claude 是当前最适合作为 [Cherry Agent](/cherry-studio/preview/agent) 后端的模型之一，因为 Agent 需要 Anthropic 协议端点。
## 获取 API Key
* 前往 [Anthropic Console](https://console.anthropic.com/) 注册账号
* 进入 `Settings → API Keys` → `Create Key`，复制生成的 `sk-ant-...` 密钥
## 在 Cherry Studio 配置
* 打开 `设置 → 模型服务`，找到 **Anthropic** Provider 进入详情页
* 在 **API 密钥** 中填入 `sk-ant-...`
* **API 地址** 默认 `https://api.anthropic.com`，无需修改
* 点击 **获取模型列表**，添加 `claude-opus-4`、`claude-sonnet-4`、`claude-haiku-4` 等模型
## 推荐用法
| 模型 | 适合场景 |
| ----------------- | ----------------------- |
| `claude-opus-4` | 最强推理 / 编程 / 复杂 Agent 任务 |
| `claude-sonnet-4` | 通用对话与日常 Agent，性价比首选 |
| `claude-haiku-4` | 高吞吐场景、低成本快速回复 |
## Agent 场景配置
把该 Provider 在 [Cherry Agent](/cherry-studio/preview/agent) 配置时选为默认模型来源，即可直接获得 Anthropic 协议 Agent 能力。
{% hint style="info" %}
* 中国大陆无法直接访问 Anthropic API，需自备代理（参考 [常规设置 → 代理模式](/pre-basic/settings/general)）
* 订阅了 Claude Code 的用户也可用同一 key + endpoint 接入 Cherry Studio
* Claude 模型按 token 计费，长上下文请关注用量
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Azure OpenAI
Azure OpenAI 是微软在 Azure 上托管的 OpenAI 模型服务，适合需要企业合规、数据驻留承诺、或微软生态的团队。
## 前置准备
* 已开通 Azure 订阅
* 已在 Azure Portal 中申请并通过 Azure OpenAI Service 访问审批
* 已创建至少一个 **资源（Resource）** 与 **部署（Deployment）**
## 获取 API Key
* Azure Portal → 你的 Azure OpenAI 资源 → `Keys and Endpoint`
* 复制 `KEY 1` 或 `KEY 2`，记下 `Endpoint`（形如 `https://.openai.azure.com/`）
## 在 Cherry Studio 配置
* 打开 `设置 → 模型服务`，找到 **Azure OpenAI** Provider 进入详情页
* **API 密钥**：填入复制的 KEY
* **API 地址**：填入资源的 Endpoint（无需带末尾路径）
* **API Version**：在专属字段填入你的部署的 API 版本（例如 `2024-08-01-preview`）
* 点击 **获取模型列表**，或手动添加你已在 Azure 上部署的模型名（即 Deployment Name，而非 OpenAI 原始模型 ID）
{% hint style="warning" %}
**Deployment Name vs Model ID**：Azure 用的是你给部署起的名字（如 `gpt-4o-prod`），不是 `gpt-4o` 这种原始 ID。填错会 404。
{% endhint %}
## 推荐用法
* **gpt-4o / gpt-4o-mini**：通用对话、Agent
* **gpt-4 turbo**：长上下文
* **text-embedding-3-**\*：嵌入模型，可用于知识库
## 常见问题
* **401 Unauthorized**：检查 Key 是否正确、Endpoint 末尾是否多余斜杠
* **404 Not Found**：检查 Deployment Name 是否与 Azure 上一致、API Version 是否填了
* **429 Throttled**：检查 Azure 配额（Quota & Limits 页）
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Google Gemini
## 获取 APIKey
* 获取 Gemini 的 api key 前，你需要有一个 Google Cloud 项目（如果你已有，此过程可跳过）
* 进入 [Google Cloud](https://console.cloud.google.com/projectcreate) 创建项目，填写项目名称并点击创建项目
* 在官方 [API Key 页面](https://aistudio.google.com/app/apikey?hl=zh-cn) 点击 `密钥 创建API密钥`
* 将生成的 key 复制，并打开 CherryStudio 的 [模型服务设置](/pre-basic/providers/providers)
* 找到服务商 Gemini，填入刚刚获取到的 key
* 点击最下方管理或者添加，加入支持的模型并打开右上角服务商开关就可以使用了。
{% hint style="info" %}
* 中国除台湾之外其他地区无法直接使用 Google Gemini 服务，需自行解决代理问题；
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Vertex AI
暂时不支持Claude模型
## 教程概述
### 1. 获取 API Key
* 获取 Gemini 的 API Key 前，你需要有一个 Google Cloud 项目（如果你已有，此过程可跳过）
* 进入 [Google Cloud](https://console.cloud.google.com/projectcreate) 创建项目，填写项目名称并点击创建项目
* 进入 [Vertex AI 控制台](https://console.cloud.google.com/vertex-ai)
* 在创建的项目中开通 [Vertex AI API](https://console.cloud.google.com/apis/library/aiplatform.googleapis.com?inv=1\&invt=Ab0iBA)
## 2. 设置 API 访问权限
* 打开 [服务账号](https://console.cloud.google.com/iam-admin/serviceaccounts) 权限界面，创建服务账号
* 在服务账号管理页面找到刚刚创建的服务账号，点击 `密钥` 并创建一个新的 JSON 格式密钥
* 创建成功后，密钥文件将会以 JSON 文件的格式自动保存到你的电脑上，请 **妥善保存**
## 3. 在 Cherry Studio 中配置 Vertex AI
* 选择 Vertex AI 服务商
* 将 JSON 文件的对应字段填入
点击添加 [模型](https://console.cloud.google.com/vertex-ai/model-garden)，就可以愉快地开始使用了！
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# DeepSeek
DeepSeek 是国内主流大模型厂商之一，以 V3 / R1 系列在编程与推理任务上有口皆碑，且价格亲民。
## 获取 API Key
* 前往 [DeepSeek Platform](https://platform.deepseek.com/) 注册账号
* `API Keys` → `创建 API Key`，复制 `sk-...` 密钥
* 充值任意金额（最低 ¥1 即可开通）
## 在 Cherry Studio 配置
* 打开 `设置 → 模型服务`，找到 **deepseek** Provider 进入详情页
* **API 密钥** 填入 `sk-...`
* **API 地址** 默认 `https://api.deepseek.com`，无需修改
* 点击 **获取模型列表**
## 推荐用法
| 模型 | 适合场景 |
| ------------------- | ---------------------------------- |
| `deepseek-chat` | 通用对话，性价比极高 |
| `deepseek-reasoner` | 数学、代码、复杂推理。注意输出会带 `` 思考块 |
## 原生联网
DeepSeek 中支持联网能力的模型可以直接使用服务商原生网络搜索。选择模型时查看名称旁是否有 🌐 图标；具体支持范围可能随服务商更新，不建议只按模型名称判断。
在对话中打开 🌐 后，如果【设置】→【网络搜索】里的【优先使用已配置的搜索服务】保持开启，Cherry Studio 会优先使用已配置的搜索服务；关闭该选项后，才会优先使用模型原生联网。详见 联网模式。
## 与全局记忆的搭配
DeepSeek 自家没有嵌入模型。如果你要用知识库：
* 嵌入模型推荐用其他 Provider 的（如 [硅基流动](/pre-basic/providers/siliconcloud) 的 `bge-m3` 或 [OpenAI](/pre-basic/providers/openai) 的 `text-embedding-3-small`）
* 对话模型仍可用 DeepSeek
{% hint style="info" %}
* DeepSeek 价格按 token 计费，缓存命中可大幅降价（参考其官方文档）
* `deepseek-reasoner` 的思考内容默认会渲染在对话中，可在 [对话设置](/cherry-studio/preview/chat#dui-hua-she-zhi) 中切换"思考内容自动折叠"
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 智谱 ZhiPu
智谱 AI 的 **GLM** 系列（含多模态 GLM-4V），国内直连、中文表现好。智谱在 Cherry Studio 中走 **Anthropic 兼容端点**，因此除普通对话外，也可用于 **Cherry Agent**。
## 获取 API Key
* 打开智谱开放平台的 [API Keys 页面](https://open.bigmodel.cn/apikey/platform)（需先注册/登录）
* 新建并复制一个 API Key
## 在 Cherry Studio 中配置
1. 打开 Cherry Studio 的 [模型服务设置](/pre-basic/providers/providers)，在内置列表中找到 **ZhiPu（智谱）**
2. 填入刚获取的 API Key
3. 点击 **获取模型列表**，添加你需要的 GLM 模型，打开右上角服务商开关即可使用
{% hint style="info" %}
智谱模型自带 **联网搜索** 能力，具体以模型是否支持为准。更多平台文档见 [智谱官方文档](https://docs.bigmodel.cn/)。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Grok
Grok 是 xAI 推出的大模型，以"语气更随意 + 接入 X (Twitter) 实时数据"著称。
## 获取 API Key
* 前往 [xAI Console](https://console.x.ai/) 注册账号
* `API Keys` → `Create API Key`，复制 `xai-...` 密钥
## 在 Cherry Studio 配置
* 打开 `设置 → 模型服务`，找到 **Grok** Provider 进入详情页
* **API 密钥** 填入 `xai-...`
* **API 地址** 默认 `https://api.x.ai`，无需修改
* 点击 **获取模型列表**，添加 `grok-4`、`grok-4-fast` 等模型
## 推荐用法
| 模型 | 适合场景 |
| ------------- | ----------- |
| `grok-4` | 综合最强，复杂任务首选 |
| `grok-4-fast` | 高吞吐、低延迟场景 |
| `grok-3-mini` | 低成本日常对话 |
## 联网搜索
部分 Grok 模型自带联网能力，模型名后会显示小地球图标。可直接在对话框开启"联网"使用，详见 [联网模式](/pre-basic/settings/websearch)。
{% hint style="info" %}
* Grok 需海外网络访问，国内用户请配代理
* xAI 提供免费额度（按月刷新），日常体验足够
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Mistral
Mistral AI 是欧洲开源大模型的代表，提供 Mistral / Codestral 等系列，兼顾效果与开放性。
## 获取 API Key
* 打开 Mistral 控制台的 [API Keys 页面](https://console.mistral.ai/api-keys/)（需先注册/登录）
* 新建并复制一个 API Key
## 在 Cherry Studio 中配置
1. 打开 Cherry Studio 的 [模型服务设置](/pre-basic/providers/providers)，在内置列表中找到 **Mistral**
2. 填入刚获取的 API Key
3. 点击 **获取模型列表**，添加你需要的模型，打开右上角服务商开关即可使用
{% hint style="info" %}
国内访问 Mistral 通常需要自行解决网络代理问题。更多信息见 [Mistral 官方文档](https://docs.mistral.ai)。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Perplexity
Perplexity 的 **Sonar** 系列主打 **搜索增强对话**——回答会结合实时联网检索，适合需要引用最新信息的场景。
## 获取 API Key
* 打开 Perplexity 的 [API 设置页](https://www.perplexity.ai/settings/api)（需先注册/登录）
* 生成并复制一个 API Key
## 在 Cherry Studio 中配置
1. 打开 Cherry Studio 的 [模型服务设置](/pre-basic/providers/providers)，在内置列表中找到 **Perplexity**
2. 填入刚获取的 API Key
3. 点击 **获取模型列表**，添加 Sonar 等模型，打开右上角服务商开关即可使用
{% hint style="info" %}
Perplexity 模型自带联网检索能力，无需额外配置联网模式。国内访问通常需要自行解决网络代理问题。更多信息见 [Perplexity 官方文档](https://docs.perplexity.ai/home)。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Groq
Groq（注意：不是 xAI 的 Grok）是一个以 **LPU 硬件加速、超低延迟** 见长的推理服务，主要托管 Llama / Mixtral / Whisper 等开源模型，输出速度通常是普通云推理的几倍。
## 获取 API Key
* 前往 [GroqCloud](https://console.groq.com/) 注册账号
* `API Keys` → `Create API Key`，复制 `gsk_...` 密钥
## 在 Cherry Studio 配置
* 打开 `设置 → 模型服务`，找到 **Groq** Provider 进入详情页
* **API 密钥** 填入 `gsk_...`
* **API 地址** 默认 `https://api.groq.com/openai/v1`，无需修改
* 点击 **获取模型列表**
## 推荐用法
| 模型 | 适合场景 |
| ------------------------- | ---------- |
| `llama-3.3-70b-versatile` | 通用对话，速度极快 |
| `llama-3.1-8b-instant` | 简单任务，毫秒级响应 |
| `mixtral-8x7b-32768` | 长上下文 |
| `whisper-large-v3` | 语音转文字 |
## 适用场景
* **实时聊天机器人**：Groq 的"几乎瞬时响应"很适合 IM 接入（搭配 [频道](/advanced-basic/automation/channels)）
* **大量并发**：每秒 token 数显著高于普通云推理
* **不在乎模型最新**：Groq 主要托管 Llama 系等开源模型，没有 GPT-5 / Claude-4 这种闭源模型
## 区分 Grok vs Groq
| | [Grok](/pre-basic/providers/grok) | Groq |
| -- | --------------------------------- | --------------- |
| 公司 | xAI（马斯克） | Groq Inc. |
| 主打 | 自研大模型 + 联网 | LPU 硬件 + 开源模型推理 |
| 模型 | `grok-4` 等自研 | `llama-3.x` 等开源 |
{% hint style="warning" %}
Grok（xAI）和 Groq 经常被混淆。在 Cherry Studio Provider 列表中是两个独立条目，请注意区分。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# OpenRouter
OpenRouter 是一个 **统一网关**，用一把 key 接入 200+ 家厂商的对话模型（GPT、Claude、Gemini、Llama、DeepSeek 等），按 token 转计费，适合多模型对比 / 没法一一注册各家账号的用户。
## 获取 API Key
* 前往 [OpenRouter](https://openrouter.ai/) 注册账号
* `Settings → Keys` → `Create Key`，复制 `sk-or-...` 密钥
* 充值任意金额（最低 $1）
## 在 Cherry Studio 配置
* 打开 `设置 → 模型服务`，找到 **OpenRouter** Provider 进入详情页
* **API 密钥** 填入 `sk-or-...`
* **API 地址** 默认 `https://openrouter.ai/api`，无需修改
* 点击 **获取模型列表**，OpenRouter 会返回数百个可用模型
## 推荐用法
OpenRouter 的模型 ID 形如 `/`：
| 模型 ID 示例 | 实际是谁 |
| ----------------------------------- | ------------------------- |
| `openai/gpt-4o` | OpenAI GPT-4o |
| `anthropic/claude-sonnet-4` | Anthropic Claude Sonnet 4 |
| `google/gemini-2.0-flash` | Google Gemini Flash |
| `meta-llama/llama-3.3-70b-instruct` | Meta Llama 3.3 70B |
| `deepseek/deepseek-chat` | DeepSeek V3 |
| `x-ai/grok-4` | xAI Grok |
## 适用场景
* **多模型 A/B 对比**：在同一 Cherry Studio Provider 下随意切模型，无需切 Provider
* **避免一一注册**：一个 key 一个发票就能用 200+ 模型
* **冷门模型**：很多小厂商只在 OpenRouter 上提供（如 Cohere、Reka 等）
## 原生联网与网址读取
OpenRouter 的对话模型可使用原生网络搜索和 URL 内容读取。选择模型时查看名称旁的 🌐 图标，并在对话输入栏打开 🌐。
如果【设置】→【网络搜索】中的【优先使用已配置的搜索服务】保持开启，Cherry Studio 会优先使用外部搜索服务；关闭该选项后，才会优先使用 OpenRouter 的模型原生能力。服务商可能对联网请求单独计费，实际费用以 OpenRouter 账单为准。
## 与 Anthropic 协议的关系
OpenRouter 默认走 OpenAI 协议格式封装所有上游模型。这意味着：
* ✅ 普通对话、知识库、快捷助手都可用
* ⚠️ [Cherry Agent](/cherry-studio/preview/agent) **建议直接用** Anthropic / CherryIN，不要走 OpenRouter（Agent 需要 Anthropic 原生协议）
{% hint style="info" %}
* OpenRouter 在原厂价格基础上有少量加价（通常 5-10%），换来"一个账号通用"
* 部分模型可走 "free" 版本（免费有限速），筛选时注意带 `(free)` 后缀的条目
* 详细价格表见 [OpenRouter Models](https://openrouter.ai/models)
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Moonshot AI (Kimi)
Moonshot AI 是国内知名大模型团队，主打产品是 **Kimi**，以 **超长上下文**（最长可达 200 万字）见长，适合塞大段文档 / 代码让 AI 帮你处理。
## 获取 API Key
* 前往 [Moonshot 开放平台](https://platform.moonshot.cn/) 注册账号
* 进入 `API Key 管理` 创建 `sk-...` 密钥
* 充值任意金额开通（最低很少）
## 在 Cherry Studio 配置
* 打开 `设置 → 模型服务`，找到 **Moonshot AI** Provider 进入详情页
* 填入 `sk-...` 密钥
* API 地址默认 `https://api.moonshot.cn`
* 点击 **获取模型列表**
## 推荐用法
| 模型 | 适合场景 |
| -------------------- | ------------------- |
| `moonshot-v1-8k` | 短上下文，便宜快速 |
| `moonshot-v1-32k` | 中等上下文，日常足够 |
| `moonshot-v1-128k` | 长上下文，文档分析、代码 review |
| `kimi-k2-* / k2.5-*` | 最新旗舰，推理能力更强 |
## 适合的场景
* **超长 PDF / 文档分析**：Moonshot 长上下文优势最明显
* **大段代码 review**：可以一次塞进完整文件不切分
* **整本电子书摘要**：长上下文模型省去手动切片麻烦
{% hint style="info" %}
* Moonshot 的"上下文缓存"功能可显著降低重复对话的 token 消耗，参考其官方文档
* Kimi 在网页端有自己的对话界面，但通过 Cherry Studio 接入 API 可以用上 Cherry Studio 的助手、知识库、MCP 工具等扩展能力
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# MiniMax
MiniMax 是国内大模型厂商之一，特点是有比较出色的 **多模态能力**（文本、语音、图像、视频生成都有）。
## 获取 API Key
* 前往 [MiniMax 开放平台](https://platform.minimaxi.com/) 注册账号
* 完成实名认证后，进入 `账户管理 → 接口密钥` 创建 API Key
## 在 Cherry Studio 配置
* 打开 `设置 → 模型服务`，找到 **MiniMax** Provider 进入详情页
* 填入 API 密钥
* API 地址保持默认即可
* 点击 **获取模型列表**
## 推荐用法
| 模型 | 适合场景 |
| ----------------------------------- | ----- |
| `abab6.5s-chat` / `MiniMax-Text-01` | 日常对话 |
| `abab6.5-chat` | 高质量长文 |
{% hint style="info" %}
* MiniMax 国内访问方便，新用户有一定免费额度
* 海外用户请走 **MiniMax Global**（Cherry Studio Provider 列表中是另一个独立条目）
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# NewAPI
Cherry Studio 已内置 New API 服务商。一个 New API 地址可以同时连接 OpenAI Chat、OpenAI Responses、Anthropic Messages 和 Gemini 协议，不需要为每种协议分别添加服务商。
## 配置步骤
1. 在 New API 管理后台创建并复制令牌；
2. 打开 Cherry Studio【设置】→【模型服务】→【New API】；
3. 填写【API 密钥】；
4. 在【API 地址】填写 New API 的根地址，例如 `https://api.example.com`；
5. 获取或手动添加模型，完成【检测】后打开右上角启用开关。
Cherry Studio 会按所选协议自动使用对应版本路径，例如 `/v1` 或 `/v1beta`。通常只需填写一次根地址，不要把 `/chat/completions` 等完整接口路径粘贴进去。
{% hint style="warning" %}
如果曾使用测试版，并在其他协议地址中保留了 `localhost:3000` 等旧值，请进入 New API 设置，把非默认协议的旧地址清空一次，再重新检测。否则部分模型可能仍请求旧地址。
{% endhint %}
中转站使用无版本路径怎么办？
只有当中转站明确要求使用不带 `/v1` 或 `/v1beta` 的路径时，才在对应 API 地址末尾加 `#`。`#` 表示不再自动拼接版本路径；普通 New API 部署不要使用。
{% hint style="info" %}
地址必须保留正确的 `http://` 或 `https://`。使用 IP 和端口时，可填写形如 `http://127.0.0.1:3000` 的根地址。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# OneAPI
* 登录并进入令牌页面
* 创建新令牌（也可以直接使用 default 令牌↑）
* 复制令牌
* 打开 CherryStudio 的服务商设置点击服务商列表最下方的 `添加`
* 输入备注名称，提供商选 OpenAI，点击确定
* 填入刚刚复制的 key
* 回到获取 API Key 的页面，在对应浏览器地址栏复制根地址，例：
只需要复制https://xxx.xxx.com即可，“/”及其之后的内容不需要
{% hint style="info" %}
* 当地址为 IP+端口时填[http://IP:端口即可，如：http://127.0.0.1:3000](https://docs.cherryai.com.cn/pre-basic/providers/http:/IP:端口即可，如：http:/127.0.0.1:3000)
* 严格区分 `http` 和 `https`，如果没有开启 SSL 就不要填 https
{% endhint %}
* 添加模型（点击管理自动获取或手动输入）打开右上角开关即可使用。
{% hint style="success" %}
OneAPI 其他主题可能界面有所不同，但添加方法跟上述操作流程一致。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Ollama
Ollama 是一款优秀的开源工具，让您可以在本地轻松运行和管理各种大型语言模型（LLMs）。Cherry Studio 现已支持 Ollama 集成，让您可以在熟悉的界面中，直接与本地部署的 LLM 进行交互，无需依赖云端服务！
## 什么是 Ollama？
Ollama 是一个简化大型语言模型（LLM）部署和使用的工具。它具有以下特点：
* **本地运行：** 模型完全在您的本地计算机上运行，无需联网，保护您的隐私和数据安全。
* **简单易用：** 通过简单的命令行指令，即可下载、运行和管理各种 LLM。
* **模型丰富：** 支持 Llama 2、Deepseek、Mistral、Gemma 等多种流行的开源模型。
* **跨平台：** 支持 macOS、Windows 和 Linux 系统。
* **开放 API**：支持与 OpenAI 兼容的接口，可以和其他工具集成。
## 为什么要在 Cherry Studio 中使用 Ollama？
* **无需云服务：** 不再受限于云端 API 的配额和费用，尽情体验本地 LLM 的强大功能。
* **数据隐私：** 您的所有对话数据都保留在本地，无需担心隐私泄露。
* **离线可用：** 即使在没有网络连接的情况下，也能继续与 LLM 进行交互。
* **定制化：** 可以根据您的需求，选择和配置最适合您的 LLM。
## 在 Cherry Studio 中配置 Ollama
### **1. 安装和运行 Ollama**
首先，您需要在您的计算机上安装并运行 Ollama。请按照以下步骤操作：
* **下载 Ollama：** 访问 Ollama 官网（），根据您的操作系统下载对应的安装包。\
在 Linux 下，可直接运行命令安装 ollama：
```sh
curl -fsSL https://ollama.com/install.sh | sh
```
* **安装 Ollama：** 按照安装程序的指引完成安装。
* **下载模型：** 打开终端（或命令提示符），使用 `ollama run` 命令下载您想要使用的模型。例如，要下载 Llama 2 模型，可以运行：
```sh
ollama run llama3.2
```
Ollama 会自动下载并运行该模型。
* **保持 Ollama 运行：** 在您使用 Cherry Studio 与 Ollama 模型交互期间，请确保 Ollama 保持运行状态。
### **2. 在 Cherry Studio 中添加 Ollama 服务商**
接下来，在 Cherry Studio 中添加 Ollama 作为自定义 AI 服务商：
* **打开设置：** 在 Cherry Studio 界面左侧导航栏中，点击“设置”（齿轮图标）。
* **进入模型服务：** 在设置页面中，选择“模型服务”选项卡。
* **添加提供商：** 点击列表中的 Ollama。
### **3. 配置 Ollama 服务商**
在服务商列表中找到刚刚添加的 Ollama，并进行详细配置：
1. **启用状态：**
* 确保 Ollama 服务商最右侧的开关已打开，表示已启用。
2. **API 密钥：**
* Ollama 默认 **不需要** API 密钥。您可以将此字段留空，或者填写任意内容。
3. **API 地址：**
* 填写 Ollama 提供的本地 API 地址。通常情况下，地址为：
```
http://localhost:11434/
```
如果修改了端口，请自行更改。
4. **保持活跃时间：** 此选项是设置会话的保持时间，单位是分钟。如果在设定时间内没有新的对话，Cherry Studio 会自动断开与 Ollama 的连接，释放资源。
5. **模型管理：**
* 点击“+ 添加”按钮，手动添加您在 Ollama 中已经下载的模型名称。
* 比如您已经通过 `ollama run llama3.2` 下载了 `llama3.2` 模型, 那么此处可以填入 `llama3.2`
* 点击“管理”按钮，可以对已添加的模型进行编辑或删除。
## 开始使用
完成以上配置后，您就可以在 Cherry Studio 的聊天界面中，选择 Ollama 服务商和您已下载的模型，开始与本地 LLM 进行对话了！
## 技巧与提示
* **首次运行模型：** 第一次运行某个模型时，Ollama 需要下载模型文件，可能需要较长时间，请耐心等待。
* **查看可用模型：** 在终端中运行 `ollama list` 命令，可以查看您已下载的 Ollama 模型列表。
* **硬件要求：** 运行大型语言模型需要一定的计算资源（CPU、内存、GPU），请确保您的计算机配置满足模型的要求。
* **Ollama 文档**: 可以点击配置页面中的 `查看Ollama文档和模型` 链接快速跳转至 Ollama 官网文档。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# LM Studio
LM Studio 是一款流行的 **本地大模型 GUI**，支持下载、量化并在本机推理各种开源模型。Cherry Studio 可作为前端连接到 LM Studio 的本地服务，在保留本地隐私的同时获得更好的对话体验。
## 前置准备
1. 从 [LM Studio 官网](https://lmstudio.ai/) 下载并安装客户端
2. 在 LM Studio 中下载至少一个模型（推荐先试 Llama 3.x 8B 或 Qwen 系列）
3. 打开 LM Studio 顶部 **Server** Tab，点击 **Start Server**（默认端口 `1234`）
## 在 Cherry Studio 配置
* 打开 `设置 → 模型服务`，找到 **LM Studio** Provider 进入详情页
* **API 地址** 默认 `http://localhost:1234`，如改过 LM Studio 端口请同步修改
* **API 密钥** 可留空（本地推理无需鉴权），或在 LM Studio 中开启鉴权后填入
* 点击 **获取模型列表**，Cherry Studio 会自动拉取 LM Studio 已加载的模型
{% hint style="info" %}
**模型列表为空？** LM Studio 只暴露 **已 `Load` 到内存** 的模型，没 Load 的不会出现在列表里。回到 LM Studio 先 Load 模型再来"获取模型列表"。
{% endhint %}
## 推荐用法
| 场景 | 建议 |
| -------------------- | ----------------------------------- |
| 隐私敏感对话 | 选小模型（8B 以下）本机跑，完全离线 |
| Apple Silicon（M 系芯片） | LM Studio 用 MLX 后端，效率显著高于 llama.cpp |
| 嵌入模型 | LM Studio 也可加载嵌入模型，用于知识库 |
## 与 Ollama 的区别
| | LM Studio | [Ollama](/pre-basic/providers/ollama) |
| ---- | ------------- | ------------------------------------- |
| 形态 | 图形界面 + Server | 命令行 / 后台服务 |
| 模型管理 | GUI 浏览/下载 | `ollama pull` |
| API | OpenAI 兼容 | OpenAI 兼容 |
| 适合 | 偏好图形交互的用户 | 偏好命令行 / Docker 部署 |
两者都可接入 Cherry Studio，按个人偏好选择即可。
## 常见问题
* **Cherry Studio 连不上**：确认 LM Studio 中 Server 是否已 Start（绿点状态）
* **响应巨慢**：模型过大 / 显存不足，换更小模型或更大量化（如 Q4 → Q3）
* **乱码 / 输出截断**：上下文长度超过模型限制，在 LM Studio 中调高 `n_ctx`
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# GitHub Copilot
使用 GitHub Copilot 需要先拥有一个 GitHub 账号，并订阅 GitHub Copilot 服务，free 版本的订阅也可以，但 free 版本不支持最新的 Claude 3.7 模型，具体请参考 [GitHub Copilot 官网](https://github.com/features/copilot)。
## 获取 Device Code
点击「登录 GitHub」，获取 Device Code 并复制。
获取 Device Code
## 在浏览器中填写 Device Code 并授权
成功获取 Device Code 后，点击链接打开浏览器，在浏览器中登录 GitHub 账号，输入 Device Code 并授权。
GitHub 授权
授权成功后，返回 Cherry Studio，点击「连接 GitHub」，成功后会显示 GitHub 用户名和头像。
GitHub 连接成功
## 点击「管理」获取模型列表
点击下方的「管理」按钮，会自动联网获取当前支持的模型列表。
获取模型列表
## 常见问题
### 获取 Device Code 失败，请重试
获取 Device Code 失败
目前使用 Axios 构建请求，Axios 不支持 socks 代理，请使用系统代理或 HTTP 代理，或者直接不在 CherryStudio 中设置代理，使用全局代理。首先请确保您的网络连接正常，以避免获取 Device Code 失败的情况。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# MiniMax Coding Plan
**Coding Plan** 是 MiniMax 推出的高性价比编程订阅服务（如 Starter/Plus 套餐）。通过在 Cherry Studio 中配置该套餐，你可以以极低的固定成本（最低 ¥29/月）使用 `MiniMax-M2.1` 模型。
{% hint style="success" %}
**核心优势**
* **适用人群**：拥有 MiniMax Coding Plan 订阅（Starter / Plus / Max）的用户。
* **计费模式**：按时段刷新额度（如每 5 小时 40 次 Prompt），而非按 Token 计费，无需担心消耗过快。
{% endhint %}
### 1. 准备工作
在开始之前，请确保你已经购买了套餐并获取了密钥：
1. 登录 [**MiniMax 开放平台**](https://platform.minimaxi.com/)。
2. 进入 [**Coding Plan** 页面](https://platform.minimaxi.com/subscribe/coding-plan?code=FYWiC6CtHy\&source=link)，确保套餐已生效。
3. 在 **Coding Plan** 中复制你的专属 `API Key`（以 `sk-` 开头）。
### 2. 配置步骤
#### 第一步：定位服务商
进入 Cherry Studio，点击侧边栏的 **设置** > **模型服务**，在列表中找到 **MiniMax**。
{% hint style="info" %}
如果列表较长，可以在顶部的搜索框输入 `mini` 快速定位。
{% endhint %}
#### 第二步：填写配置
**不需要** 修改复杂的 API 地址，使用默认配置即可，请参考以下说明填写：
| 参数项 | 填写说明 |
|---|
| API Key | 粘贴你的 Coding Plan 专属密钥
(注意：必须是购买套餐后生成的 Key，不要有多余空格) |
| API 地址 | 保持默认 https://api.minimaxi.com/v1 |
| 开关 | 点击右上角开关，确保为 绿色 (ON) |
#### 第三步：添加指定模型 (关键)
Coding Plan 套餐仅支持特定的模型，选错模型将无法使用或产生额外费用。
1. 点击配置页底部的 **管理 (Manage)** 按钮。
2. 在列表中找到并添加 **`MiniMax M2.1`**。
{% hint style="warning" %}
**请务必选择正确模型！**
* ✅ **推荐**：`MiniMax M2.1` (Coding Plan 指定主力模型)。
{% endhint %}
#### 第四步：保存并验证
1. 点击 API 密钥输入框旁边的 **检测 (Check)** 按钮。
2. 如果显示绿色 **Success**，说明你的 Coding Plan 套餐已成功连接！
### 3. 用量与限制说明
Coding Plan 与普通 API 的计费模式完全不同，请务必理解以下机制：
{% hint style="info" %}
**额度刷新机制** Coding Plan 的额度是 **周期性刷新** 的。例如 Starter 套餐：**每 5 小时** 提供 **40 次** 对话额度。
* **如果不回复了**：说明你当前 5 小时的额度已耗尽。
* **解决办法**：休息几个小时，等待额度自动恢复即可，无需额外付费。
{% endhint %}
### 4. 常见问题排查
{% hint style="danger" %}
**遇到 `429 Too Many Requests` 报错？**
这不是软件故障，而是触发了 **Coding Plan 的频控限制**。
* 这意味着你当前时段的“发消息次数”已用完。
* 请耐心等待下一个 5 小时周期刷新。
{% endhint %}
{% hint style="warning" %}
**遇到 `401 Unauthorized` 报错？**
* 检查 API Key 是否有多余空格。
* 登录 MiniMax 官网确认你的 Coding Plan 订阅是否已过期。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# ModelScope（魔搭）
## 什么是 ModelScope？
> ModelScope 是新一代开源模型即服务（MaaS）共享平台，致力于为泛 AI 开发者提供 **灵活、易用、低成本** 的一站式模型服务解决方案，让模型应用更简单！
>
> 通过 **API-Inference 服务化能力**，平台将开源模型标准化为可调用的 API 接口，开发者可轻量、快速地集成模型能力至各类 AI 应用，支持工具调用、原型开发等创新场景。
### 核心优势
* ✅ **免费额度**：每日提供 **2000 次免费 API 调用额度**（[计费规则](#计费与额度规则)）
* ✅ **丰富模型库**：覆盖 NLP、CV、语音、多模态等 1000+ 开源模型
* ✅ **即开即用**：无需部署，通过 RESTful API 快速调用
***
## Cherry Studio 接入流程
### 步骤 1：获取 ModelScope API 令牌
1. **登录平台**
* 访问 [ModelScope 官网](https://modelscope.cn) → 点击右上角 **登录** → 选择认证方式 
2. **创建访问令牌**
* 进入 [**账户设置 → 访问令牌**](https://modelscope.cn/my/myaccesstoken)
* 点击 **`新建令牌`** → 填写描述 → **复制生成的令牌**（*页面示例见下图*） 
> 🔑 **重要提示**：令牌泄露将影响账号安全！
### 步骤 2：配置 Cherry Studio
* 打开 **Cherry Studio** → **设置 → 模型服务 → ModelScope**
* 在 `API 密钥` 栏粘贴复制的令牌 
* 点击 **`保存`** 完成授权
### 步骤 3：调用模型 API
1. **查找支持 API 的模型**
* 访问 [ModelScope 模型库](https://modelscope.cn/models)
* 筛选条件：**勾选 `API-Inference`**（或认准模型卡片上的 `API` 图标） 
> API-Inference 覆盖的模型范围，主要根据模型在魔搭社区中的关注程度（参考了点赞，下载等数据）来判断。因此，在能力更强，关注度更高的下一代开源模型发布之后，支持的模型清单也会持续迭代。
2. **获取模型 ID**
* 进入目标模型详情页 → 复制 **Model ID**（格式如 `damo/nlp_structbert_sentiment-classification_chinese-base`） 
3. **填入 Cherry Studio**
* 在模型服务配置页的 `模型 ID` 栏输入 ID → 选择任务类型 → 完成配置 
***
## 计费与额度规则
### 重要说明
* 🎫 **免费额度**：每位用户 **每日 2000 次 API 调用**（\*以官网最新规则为准）
* 🔁 **额度重置**：每日 UTC+8 00:00 自动重置，**不支持跨日累计或升级**
* 💡 **超额处理**：
* 达到当日上限后 API 将返回 `429 错误`
* 解决方案：切换备用账号 / 使用其他平台 / 优化调用频率
### 查看剩余额度
* 登录 ModelScope → 点击右上角 **`用户名`** → **`API 使用情况`** 
> ⚠️ 注意：推理 API-Inference 每天 2000 次的免费调用额度。更多调用需求可考虑使用阿里云百炼等云上服务。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# PPIO 派欧云
## Cherry Studio 接入 PPIO LLM API
### [](https://ppinfra.com/docs/third-party/cherry-studio-use#%E6%95%99%E7%A8%8B%E6%A6%82%E8%BF%B0) 教程概述
Cherry Studio 是一款多模型桌面客户端，目前支持：Windows 、Linux 、MacOS 系电脑安装包。它聚合主流 LLM 模型，提供多场景辅助。用户可通过智能会话管理、开源定制、多主题界面来提升工作效率。
Cherry Studio 现已与 **PPIO 高性能 API 通道** 深度适配——通过企业级算力保障，实现 **DeepSeek-R1/V3 高速响应** 与 **99.9% 服务可用性**，带给您快速流畅的体验。
下方教程包含完整接入方案（含密钥配置），3 分钟开启「Cherry Studio 智能调度 + PPIO 高性能 API」的进阶模式。
### [](https://ppinfra.com/docs/third-party/cherry-studio-use#1-%E8%BF%9B%E5%85%A5-cherrystudio%EF%BC%8C%E6%B7%BB%E5%8A%A0-%E2%80%9Cppio%E2%80%9D-%E4%BD%9C%E4%B8%BA%E6%A8%A1%E5%9E%8B%E6%8F%90%E4%BE%9B%E5%95%86) 1. 进入 CherryStudio，添加 “PPIO” 作为模型提供商
首先前往官网下载 Cherry Studio：[ ](https://cherryai.com.cn/download) （如果进不去可以打开下面的夸克网盘链接下载自己需要的版本：）
（1）先点击左下角设置，自定义提供商名称为：`PPIO`，点击“确定”
（2）前往 [派欧算力云 API 密钥管理 ](https://ppinfra.com/user/register?invited_by=JYT9GD\&utm_source=github_cherry-studio)，点击【用户头像】—【API 密钥管理】进入控制台
点击 【+ 创建】按钮来创建新的 API 密钥。自定义一个密钥名称，**生成的密钥仅在生成时呈现，务必复制并保存到文档中，以免影响后续使用**
（3）在 CherryStudio 填入密钥 点击设置，选择【PPIO 派欧云】，输入官网生成的 API 密钥，最后点击【检查】
（4）选择模型：deepseek/deepseek-r1/community 为例，如需更换其他模型，可直接更换。
DeepSeek R1 和 V3 community 版本仅供大家尝鲜，也是全参数满血版模型，稳定性和效果无差异，如需大量调用则须 **充值并切换到非 community 版本**。
### [](https://ppinfra.com/docs/third-party/cherry-studio-use#2-%E6%A8%A1%E5%9E%8B%E4%BD%BF%E7%94%A8%E9%85%8D%E7%BD%AE) 2. 模型使用配置
（1）点击【检查】显示连接成功后即可正常使用
（2）最后点击【@】选择 PPIO 供应商下刚刚添加的 DeepSeek R1 模型，即可成功开始聊天\~
【部分素材来源：[ 陈恩 ](https://www.kdocs.cn/l/ctGiF5K6PQoO)】
### [](https://ppinfra.com/docs/third-party/cherry-studio-use#3-ppio%C3%97cherry-studio-%E8%A7%86%E9%A2%91%E4%BD%BF%E7%94%A8%E6%95%99%E7%A8%8B) 3. PPIO×Cherry Studio 视频使用教程
若您更倾向直观学习，我们在 B 站准备了视频教程。通过手把手教学，助您快速掌握「PPIO API+Cherry Studio」的配置方法，点击下方链接直达视频，开启流畅开发体验 → [《 【还在为 DeepSeek 疯狂转圈抓狂？】派欧云+DeepSeek 满血版 =？不再拥堵，即刻起飞》](https://www.bilibili.com/video/BV1BZNmeTEwg/?buvid=XX82F37818653072D274A6BB8A4FE7938A30C\&from_spmid=search.search-result.0.0\&is_story_h5=false\&mid=3CpKQv%2Bjnb8k6iTGlUl1eH8FTQ%2FSZMtL1rElX6M3iMo%3D\&plat_id=116\&share_from=ugc\&share_medium=android\&share_plat=android\&share_session_id=b892268f-5751-4f6e-9690-50b37855d346\&share_source=WEIXIN\&share_source=weixin\&share_tag=s_i\&spmid=united.player-video-detail.0.0\×tamp=1739160448\&unique_k=eKDZuRP\&up_id=3546757841554023\&vd_source=50fea165795ccc47455a165f5bcaeed2)
【视频素材来源：sola】
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 阿里云百炼
1. 登录 [阿里云百炼](https://bailian.console.aliyun.com/?tab=model#/api-key)，没有阿里云账号的话需要注册。
2. 点击右上角的 `创建我的 API-KEY` 按钮。
阿里云百炼创建 API 密钥
3. 在弹出的窗口中选择默认业务空间（或者你也可以自定义），如果你想要的话可以填入描述。
阿里云百炼创建 API 密钥弹窗
4. 点击右下角的 `确定` 按钮。
5. 随后，你应该能看到列表中新增了一行，点击右侧的 `查看` 按钮。
阿里云百炼查看 API 密钥
6. 点击 `复制` 按钮。
阿里云百炼复制 API 密钥
7. 转到 Cherry Studio，在 `设置` → `模型服务` → `阿里云百炼` 中找到 `API 密钥` ，将复制的 API 密钥粘贴到这里。
阿里云百炼填入 API 密钥
8. 可以按照 [模型服务](/pre-basic/providers/providers) 中的介绍调整相关设置，然后就能使用了。
## 原生联网与网址读取
阿里云百炼中支持联网能力的模型可以使用原生网络搜索，部分 Qwen 模型还支持 URL 内容读取。选择模型时以名称旁的 🌐 图标为准，具体能力可能随百炼模型更新。
在对话中打开 🌐 后，如果【设置】→【网络搜索】里的【优先使用已配置的搜索服务】保持开启，Cherry Studio 会优先使用已配置的搜索服务；关闭该选项后，才会优先使用模型原生能力。详见 联网模式。
{% hint style="info" %}
如果发现模型列表中没有阿里云百炼的模型，请确认已经按照 [模型服务](/pre-basic/providers/providers) 中的介绍添加模型，并开启了这个提供商。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 硅基流动
## 1. 配置 SiliconCloud 的模型服务
#### [](https://docs.siliconflow.cn/usercases/use-siliconcloud-in-cherry-studio#2-1) 1.2 点击左下角的设置，在模型服务中选择【硅基流动】
#### [](https://docs.siliconflow.cn/usercases/use-siliconcloud-in-cherry-studio#2-2-siliconcloud-api) 1.2 点击链接获取 SiliconCloud API 密钥
1. 登录 [SiliconCloud](https://cloud.siliconflow.cn/)（若未注册首次登录会自动注册账号）
2. 访问 [API 密钥](https://cloud.siliconflow.cn/account/ak) 新建或复制已有密钥
#### [](https://docs.siliconflow.cn/usercases/use-siliconcloud-in-cherry-studio#2-3) 1.3 点击管理添加模型
## [](https://docs.siliconflow.cn/usercases/use-siliconcloud-in-cherry-studio#3) 2. 模型服务使用
1. 点击左侧菜单栏的“对话”按钮
2. 在输入框内输入文字即可开始聊天
3. 可以选择顶部菜单中的模型名字切换模型
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 火山引擎
* 登录 [火山引擎](https://console.volcengine.com/)
* 直接点击 [这里直达](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D)
### 获取 API Key
* 点击侧栏下方的 [API Key 管理](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey)
* 创建 API Key
* 创建成功后，点击创建好的 API Key 后的小眼睛打开并复制
* 将复制的 API Key 填入到 CherryStudio 当中后，打开服务商开关。
### 开通并添加模型
* 在方舟控制台侧栏最下方的 [开通管理](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement?LLM=%7B%7D\&OpenTokenDrawer=false) 开通需要使用的模型，这里可以按需开通豆包系列和 DeepSeek 等模型。
* 在 [模型列表文档](https://www.volcengine.com/docs/82379/1330310#%E6%96%87%E6%9C%AC%E7%94%9F%E6%88%90) 里，找到所需模型对应的 模型 ID。
* 打开 Cherry Studio 的 [模型服务](/pre-basic/providers/providers) 设置找到火山引擎
* 点击添加，将之前获得的 模型 ID 复制至 模型 ID 文本对话框即可
* 按照此流程依次添加模型
### API 地址
API 地址有两种写法
* 第一种为客户端默认的：`https://ark.cn-beijing.volces.com/api/v3/`
* 第二种写法为：`https://ark.cn-beijing.volces.com/api/v3/chat/completions#`
{% hint style="info" %}
两种写法没什么区别，保持默认即可，无需修改。
关于 `/` 和 `#` 结尾的区别参考文档服务商设置的 API 地址部分，[点击前往](/pre-basic/providers/providers#api-di-zhi)
{% endhint %}
官方文档 cURL 示例
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 自定义服务商
Cherry Studio 不仅集成了主流的 AI 模型服务，还赋予了您强大的自定义能力。通过 **自定义 AI 服务商** 功能，您可以轻松接入任何您需要的 AI 模型。
## 为什么需要自定义 AI 服务商？
* **灵活性：** 不再受限于预置的服务商列表，自由选择最适合您需求的 AI 模型。
* **多样性：** 尝试各种不同平台的 AI 模型，发掘它们的独特优势。
* **可控性：** 直接管理您的 API 密钥和访问地址，确保安全和隐私。
* **定制化：** 接入私有化部署的模型，满足特定业务场景的需求。
## 如何添加自定义 AI 服务商？
只需简单几步，即可在 Cherry Studio 中添加您的自定义 AI 服务商：
1. **打开设置：** 在 Cherry Studio 界面左侧导航栏中，点击“设置”（齿轮图标）。
2. **进入模型服务：** 在设置页面中，选择“模型服务”选项卡。
3. **添加提供商：** 在“模型服务”页面中，您会看到已有的服务商列表。点击列表下方的“+ 添加”按钮，打开“添加提供商”弹窗。
4. **填写信息：** 在弹窗中，您需要填写以下信息：
* **提供商名称：** 为您的自定义服务商起一个易于识别的名称（例如：MyCustomOpenAI）。
* **提供商类型：** 从下拉列表中选择您的服务商类型。目前支持：
* OpenAI
* Gemini
* Anthropic
* Azure OpenAI
5. **保存配置：** 填写完毕后，点击“添加”按钮保存您的配置。
## 配置自定义 AI 服务商
添加完成后，您需要在列表中找到您刚刚添加的服务商，并进行详细配置：
1. **启用状态** 自定义服务商列表最右侧有一个启用开关，打开代表启用该自定义服务。
2. **API 密钥：**
* 填写您的 AI 服务商提供的 API 密钥（API Key）。
* 点击右侧的“检查”按钮，可以验证密钥的有效性。
3. **API 地址：**
* 填写 AI 服务的 API 访问地址（Base URL）。
* 请务必参考您的 AI 服务商提供的官方文档，获取正确的 API 地址。
4. **模型管理：**
* 点击“+ 添加”按钮，手动添加此提供商下您想要使用的模型 ID。例如 `gpt-3.5-turbo`、`gemini-pro` 等。
* 如果您不确定具体的模型名称，请参考您的 AI 服务商提供的官方文档。
* 点击"管理"按钮，可以对已经添加的模型进行编辑或者删除。
## 开始使用
完成以上配置后，您就可以在 Cherry Studio 的聊天界面中，选择您自定义的 AI 服务商和模型，开始与 AI 进行对话了！
## 使用 vLLM 作为自定义 AI 服务商
vLLM 是一个类似 Ollama 的快速且易于使用的 LLM 推理库。以下是如何将 vLLM 集成到 Cherry Studio 中的步骤：
1. **安装 vLLM：** 按照 vLLM 官方文档（）安装 vLLM。
```sh
pip install vllm # 如果你使用 pip
uv pip install vllm # 如果你使用 uv
```
2. **启动 vLLM 服务：** 使用 vLLM 提供的 OpenAI 兼容接口启动服务。主要有两种方式，分别如下：
* 使用 `vllm.entrypoints.openai.api_server` 启动
```sh
python -m vllm.entrypoints.openai.api_server --model gpt2
```
* 使用 `uvicorn` 启动
```sh
vllm --model gpt2 --served-model-name gpt2
```
确保服务成功启动，并监听在默认端口 `8000` 上。 当然， 您也可以通过参数 `--port` 指定 vLLM 服务的端口号。
3. **在 Cherry Studio 中添加 vLLM 服务商：**
* 按照前面描述的步骤，在 Cherry Studio 中添加一个新的自定义 AI 服务商。
* **提供商名称：** `vLLM`
* **提供商类型：** 选择 `OpenAI`。
4. **配置 vLLM 服务商：**
* **API 密钥：** 因为 vLLM 不需要 API 密钥，可以将此字段留空，或者填写任意内容。
* **API 地址：** 填写 vLLM 服务的 API 地址。默认情况下，地址为： `http://localhost:8000/`（如果使用了不同的端口，请相应地修改）。
* **模型管理：** 添加您在 vLLM 中加载的模型名称。 在上面运行 `python -m vllm.entrypoints.openai.api_server --model gpt2` 的例子中, 应该在此处填入 `gpt2`
5. **开始对话：** 现在，您可以在 Cherry Studio 中选择 vLLM 服务商和 `gpt2` 模型，开始与 vLLM 驱动的 LLM 进行对话了！
## 提示与技巧
* **仔细阅读文档：** 在添加自定义服务商之前，请务必仔细阅读您所使用的 AI 服务商的官方文档，了解 API 密钥、访问地址、模型名称等关键信息。
* **检查 API 密钥：** 使用“检查”按钮可以快速验证 API 密钥的有效性，避免因密钥错误导致无法使用。
* **关注 API 地址：** 不同的 AI 服务商和模型，API 地址可能有所不同，请务必填写正确的地址。
* **模型按需添加:** 请只添加您实际上会用到的模型, 避免添加过多无用模型.
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 软件设置
Cherry Studio 的设置面板覆盖 **模型配置、工具能力、界面偏好、效率工具与系统行为** 等所有选项。设置左侧按 **模型 / 工具 / 偏好 / 效率 / 系统** 五大块分组，本节按同样的分组给出地图，方便你按需跳转。
### 模型
| 设置项 | 文档 | 内容 |
| ------ | ----------------------------------------------------- | ------------------------------ |
| 模型服务 | [模型服务](/pre-basic/providers) | Provider 添加、密钥、API 地址、多 Key 轮询 |
| 默认模型 | [默认模型设置](/pre-basic/settings/default-models) | 全局默认对话 / 命名 / 翻译等模型 |
| 本地模型 | [本地模型](/pre-basic/settings/local-models) | 内置、离线运行的嵌入模型与 OCR 模型 |
| API 网关 | [API 网关](/advanced-basic/developer-tools/api-gateway) | 对外暴露本地 OpenAI 兼容 API |
### 工具
| 设置项 | 文档 | 内容 |
| ---- | ------------------------------------------- | ---------------------------- |
| MCP | [MCP 与外部工具](/advanced-basic/extensions/mcp) | Model Context Protocol 工具接入 |
| 技能 | [技能与能力库](/advanced-basic/extensions/skills) | 为助手或 Agent 加装专项能力 |
| 网络搜索 | [联网模式](/pre-basic/settings/websearch) | 免费联网、Tavily、火山引擎、SearXNG 等 |
| 文档处理 | [文档处理](/pre-basic/settings/doc-process) | PDF / 复杂版式文档的结构化解析（MinerU 等） |
| OCR | [OCR](/pre-basic/settings/ocr) | 图片 / 扫描件的文字识别引擎 |
### 偏好
| 设置项 | 文档 | 内容 |
| ---- | ----------------------------------------- | -------------------- |
| 外观 | [外观](/pre-basic/settings/display) | 主题、主题色、缩放、语言、话题布局 |
| 通知 | [通知](/pre-basic/settings/notification) | 助手消息、备份、知识库完成提醒 |
| 数据 | [数据设置](/pre-basic/settings/data-settings) | WebDAV / S3 备份与第三方集成 |
| 用量统计 | [用量统计](/pre-basic/settings/usage) | 成本、Token、请求与每日活动统计 |
### 效率
| 设置项 | 文档 | 内容 |
| ---- | ------------------------------------------------------ | ----------------------- |
| 频道 | [频道](/advanced-basic/automation/channels) | Agent 接入飞书 / Telegram 等 |
| 定时任务 | [定时任务](/advanced-basic/automation/scheduled-heartbeat) | Agent 按 Cron 定时运行 |
| 快捷键 | [快捷键设置](/pre-basic/settings/key-shortcut) | 全部快捷键的修改与启停 |
| 快捷助手 | [快捷助手](/cherry-studio/preview/quick-assistant) | 全局悬浮的迷你对话窗 |
| 划词助手 | [划词助手](/cherry-studio/preview/selection-assistant) | 选中文字即时翻译 / 解释 / 改写 |
### 系统
| 设置项 | 文档 | 内容 |
| ---- | -------------------------------------------- | ------------------------ |
| 系统 | [系统](/pre-basic/settings/general) | 启动、托盘、代理、硬件加速、开发者模式 |
| 环境依赖 | [环境依赖](/pre-basic/settings/env-dependencies) | uv / bun 等运行时与二进制工具的安装管理 |
| 关于我们 | — | 版本信息、检查更新、许可协议与社区链接 |
{% hint style="info" %}
设置改动会 **实时生效**，无需重启。涉及 Provider / 模型 / 默认模型这类核心项时，建议先在 `设置 → 数据` 中做一次备份。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 默认模型设置
Cherry Studio 在很多场景下都需要"挑一个模型用一下"（比如帮你给对话起名字、优化提示词、做翻译、生成图片），不可能每次都问你"用哪个模型"。**默认模型设置** 就是告诉 Cherry Studio：**当我没明说时，用哪个模型**。
> 注意：这些是"幕后小工"用的模型，**和你聊天用的模型可以不一样**。聊天主模型是在每个助手里单独设的。
默认模型（① 为区块标题）：下方 默认助手 / 快速 / 翻译 / 绘画 四个默认模型，各自选一个
## 4 个默认模型分别管什么？
### 默认助手模型
* **谁用**：助手没有指定自己的模型时，自动使用此处的模型
* **怎么选**：选一个你常用、稳定、价格合理的对话模型
### 快速模型
* **谁用**：**对话命名**、**搜索关键字提炼** 等轻量、不需要顶级智能的内部任务
* **怎么选**：用 **便宜快速** 的模型即可，建议选轻量模型、不建议选思考模型
### 翻译模型
* **谁用**：对话框内的消息翻译、翻译页；[划词助手](/cherry-studio/preview/selection-assistant) 中的翻译操作
* **怎么选**：普通对话模型都行；如果中英互译多，DeepSeek 或 Claude 系列效果较好
### 绘画模型
* **谁用**：图像生成（绘画）默认使用的模型
* **怎么选**：选一个你已配置的图像生成模型（如 qwen-image 系列）
## 一句话推荐
如果不想细究，照下面填即可：
| 字段 | 推荐 |
| ------ | -------------------------------------- |
| 默认助手模型 | 你最常用的对话模型 |
| 快速模型 | 便宜快速的轻量模型 |
| 翻译模型 | 任何能遵循指令的对话模型都行（也可选专用翻译模型，如 qwen-mt 系列） |
| 绘画模型 | 你已配置的图像生成模型 |
不确定时全部保持默认，用一段时间发现哪个不够用再回来调整即可。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 本地模型
本地模型是 Cherry Studio 内置、**下载后即可离线运行** 的小模型：不走任何服务商 API，也不需要填 API Key。它们体积小、跑在你自己的电脑上，专门用来兜底一些"不值得为它单独配一个云端模型"的基础能力。
打开 `设置 → 本地模型` 即可管理：
本地模型：① 两个内置本地模型——本地嵌入模型 + 本地 OCR 模型（图中均为「已就绪」，可点右侧删除移除）
目前内置两类本地模型：
| 本地模型 | 底层 | 大小 | 用途 |
| ------------- | -------------------- | -------- | --------------------------------------------------------- |
| **本地嵌入模型** | Qwen3 Embedding 0.6B | 约 614 MB | 把文本转成向量，用于 [知识库](/knowledge-base/knowledge-base) 检索、召回等场景 |
| **本地 OCR 模型** | PaddleOCR PP-OCRv6 | 约 140 MB | 离线识别图片 / 扫描件里的文字，供 [OCR](/pre-basic/settings/ocr) 功能调用 |
### 下载与状态
* 模型名称旁会显示状态徽章：未下载的卡片 **底部** 有一条整宽「**下载**」按钮，点击开始下载；下载完成后徽章变为 **已就绪**。
* 已就绪的模型可点击右侧的 **删除** 图标移除，释放磁盘空间；需要时可再次下载。（若嵌入模型仍被知识库使用，删除会被拒绝、权重保留。）
* 少数平台 / 架构不支持本地推理时，面板会显示「**当前平台不支持本地模型**」，此时不提供下载。
下载时如果一个镜像不可用，Cherry Studio 会自动尝试其他下载源。下载完成后，本地嵌入模型的推理过程在本机运行，不需要联网。
{% hint style="warning" %}
如果页面提示【模型文件不完整，请重新下载修复。】，说明本地缓存缺少必要文件。删除或重新下载该模型即可修复；不要手动拼接模型文件。
{% endhint %}
{% hint style="info" %}
本地模型是 **可选项**。如果你已经在 [模型服务](/pre-basic/providers/providers) 里配置了云端嵌入模型，或用系统自带 OCR 就够用，可以不下载它们。
{% endhint %}
### 什么时候用本地模型
* **没有云端嵌入模型 / 不想为知识库单独付费**：下载本地嵌入模型，知识库就能在完全离线的情况下建索引与检索。
* **需要离线 OCR**：在没有网络、或不希望图片上传到第三方的场景，下载本地 OCR 模型，配合 [OCR 设置](/pre-basic/settings/ocr) 选择「本地 PaddleOCR」即可。
* **隐私优先**：所有计算都在本机完成，内容不会离开你的电脑。
{% hint style="warning" %}
本地模型是"够用就好"的轻量方案。若对检索精度或识别准确率要求很高，云端的 [嵌入模型](/knowledge-base/emb-models-info)、更强的 OCR 服务通常效果更好。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 联网模式
如何在 Cherry Studio 使用联网模式
{% hint style="info" %}
联网模式让 AI 在回答前先去搜索最新内容，适合以下场景：
* **时效性信息**：今日 / 本周 / 刚刚发生的新闻、价格、汇率等
* **实时数据**：天气、股价、商品库存等动态数值
* **新兴知识**：刚出现的工具、概念、技术
{% endhint %}
## 如何开启联网
在对话输入框的工具栏中点击 🌐 **小地球** 图标，即可对当前对话开启联网。
对话输入栏的地球图标：点击即对当前对话开启联网（提示会显示当前搜索服务商）
**开箱即用**：Cherry Studio 默认已内置 **Exa MCP** 作为搜索服务商，**无需配置任何 API 密钥**（走公开的 MCP 端点 `mcp.exa.ai`），默认的 URL 获取服务商是 **Jina**。所以装好后点 🌐 就能直接联网搜索。
## 走配置的服务，还是模型自带
联网走哪条路，由「优先使用已配置的搜索服务」开关决定，它 **默认开启**：
* **开启（默认）**：点 🌐 会走你在 `设置 → 网络搜索` 里配置的服务——初始就是免密钥的 Exa MCP。
* **关闭**：如果模型自身 **原生带搜索**（模型名旁有小地球图标 🌐），则交由模型自己的联网处理。
是否支持原生联网，请以模型名称旁的 🌐 图标为准，不要依赖固定模型清单。当前常见情况包括：
* **DeepSeek**：支持该能力的模型可使用原生网络搜索；
* **OpenRouter**：对话模型可使用原生网络搜索和 URL 内容读取；
* **阿里云百炼**：支持该能力的模型可使用原生网络搜索，部分 Qwen 模型还支持 URL 内容读取；
* Google Gemini、智谱 AI、xAI Grok 等服务商的部分模型也支持原生联网。
模型能力会随服务商调整。选择模型时认准 🌐 图标；没有图标时，使用已配置的搜索服务更稳妥。
{% hint style="info" %}
还有少数模型即使没显示小地球图标，也能联网（取决于服务商配置）。例如 [火山引擎接入联网](/pre-basic/settings/websearch/volcengine) 中介绍的一类情况。
{% endhint %}
## 在设置里配置服务
打开 `设置 → 网络搜索`，配置分成两个部分，每个部分用一个下拉框选择服务商，**选中的即作为该能力的默认**：
| 分区 | 作用 |
| ------------- | --------------------- |
| **搜索服务商** | 根据你的问题检索网页，返回结果摘要 |
| **URL 获取服务商** | 从指定网址抓取网页正文，补全搜索结果的内容 |
网络搜索设置：搜索服务商 / URL 获取服务商 两个分区，与底部「优先使用已配置的搜索服务」开关
### 内置服务商
内置以下服务，类型分 **API** 与 **MCP** 两种：
| 服务 | 类型 | 能力 | 说明 |
| ------------- | --- | ----------- | -------------------------------- |
| **Exa MCP** | MCP | 搜索 | **默认**，免密钥即用 |
| **Tavily** | API | 搜索 | 专为 LLM 优化的搜索引擎 |
| **Bocha（博查）** | API | 搜索 | 面向 AI 场景的中文搜索 API，实时网页 + 结构化结果 |
| **Exa** | API | 搜索 | 为 AI 应用设计的神经搜索，擅长语义检索 |
| **Zhipu（智谱）** | API | 搜索 | 智谱 GLM Web Search，联网搜索与实时信息 |
| **Querit** | API | 搜索 | 面向 AI 应用的网页检索服务 |
| **SearXNG** | API | 搜索 | 可自托管的免费元搜索引擎 |
| **Firecrawl** | API | 搜索 | 网页抓取与搜索，可将结果转 Markdown |
| **Jina** | API | 搜索 · URL 获取 | Jina Reader；也是 **默认的 URL 获取服务商** |
| **Fetch** | API | URL 获取 | 内置 URL 获取，从指定网址抓正文 |
> 除默认的 **Exa MCP**（免密钥）外，多数 API 服务商需填各自的 API 密钥；**SearXNG** 填自部署地址，**Fetch** 为内置、无需配置。
### 高级设置
* **搜索结果个数**：单次返回多少条（默认 5，最多 100）。未开启压缩时数量过大会消耗更多 Token。
* **搜索结果压缩**：把返回内容压缩后再喂给模型，节省 Token。默认即为「截断」，截断长度默认 2000 字符；也可改为「不压缩」，或调整截断长度。
* **搜索结果黑名单**：屏蔽不想出现的网站，详见 [网络搜索黑名单配置](/pre-basic/settings/websearch/blacklist)。
高级设置：搜索结果个数、压缩方法（不压缩 / 截断）、黑名单
## 相关配置
默认的 Exa MCP 免密钥即可用；想换用其他服务或深入配置，见下面几篇：
* [免费联网模式](/pre-basic/settings/websearch/free-search) —— 不花钱也能用上搜索能力
* [Tavily 联网登录注册教程](/pre-basic/settings/websearch/tavily) —— 换用 Tavily 时，如何注册并获取密钥
* [SearXNG 本地部署与配置](/pre-basic/settings/websearch/searxng) —— 自托管、完全本地化
* [网络搜索黑名单配置](/pre-basic/settings/websearch/blacklist) —— 屏蔽不想要的网站
## 工作机制
无论走哪种方式，对话流程都是：
1. 你问“今天上海天气怎么样？”
2. Cherry Studio 把问题先发给搜索服务
3. 搜索服务返回相关网页摘要
4. Cherry Studio 把这些摘要拼到提示词里发给 AI 模型
5. AI 基于实时数据回答你
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 免费联网模式
想不花钱就让 AI 联网？Cherry Studio 有两种 **免费** 方案，都不需要付费 API：
## 方案一：默认的 Exa MCP（开箱即用、免密钥）
Cherry Studio **默认** 就把搜索服务商设成 **Exa MCP**——走公开端点、**无需任何 API 密钥**。装好后，在对话输入框点 🌐 **小地球** 图标对当前对话开启联网即可，无需额外配置。
详见 [联网模式](/pre-basic/settings/websearch)。
## 方案二：SearXNG（自托管、完全免费）
如果你愿意自己部署，**SearXNG** 是开源的元搜索引擎，可完全本地 / 自建服务器运行、不限调用次数，隐私也更可控。
部署与接入步骤见 [SearXNG 本地部署与配置](/pre-basic/settings/websearch/searxng)。
{% hint style="info" %}
想要更强的检索效果、或用 Tavily 这类 **需要密钥** 的服务？那属于在 [联网模式](/pre-basic/settings/websearch) 里另配搜索服务商，不在"免费"范围内。
{% endhint %}
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 网络搜索黑名单配置
不想让某些网站出现在联网搜索的结果里？在 `设置 → 网络搜索` 的 **黑名单** 里逐条添加要屏蔽的网站即可。规则写法参考 [ublacklist](https://github.com/iorate/ublacklist)。
## 手动配置
在黑名单输入框里 **按行** 添加规则，支持两种写法：
* **匹配模式**（[match pattern](https://developer.mozilla.org/zh-CN/docs/mozilla/add-ons/webextensions/match_patterns)）：如 `*://*.example.com/*`
* **正则表达式**：如 `/example\.(net|org)/`
添加后，命中规则的网站就不会再出现在联网搜索的结果里。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 火山引擎接入联网
cherry studio使用「火山引擎」接入deepseekR1联网功能，喂饭教程。
### 1、登陆/注册 「火山引擎」 账号
访问官网：
火山引擎官网
### 2、创建 「可以联网的」 「我的应用」
2.1、 登陆火山引擎，进入「火山方舟」页面，传送门：
2.2、 **依次点击：****「我的应用」 - 「创建应用」 - 「零代码」 - 「单聊」**
### 3、填写信息并发布应用
**应用名称**：按照要求随便起个名字即可。（带**\*必填**，其他可以不写）
**关键是：联网插件要点开（需要先开通）**
#### 3.1、 开通联网插件功能（注意费用和免费次数）
点击立即购买，一步步执行到显示下面的界面，说明开通成功了。
注意状态，至此开通成功
然后返回刚才的「填写应用信息」界面，继续操作。
#### 3.2、联网搜索「高级配置」说明
根据实际情况选择，个人建议：
* 如果想要精准控制输入输出，可以用「**自定义调用**」联网；
* 如果嫌麻烦可以不修改，使用「**自动调用**」- 默认值；
* 如果不差钱，对信息时效性要求很高，可以「**强制开启**」。
#### 3.3、发布应用
点击右上角「发布」按钮，应用创建成功。
### 4、获取 API Key
依次点击：**「API 调用指南」-「选择 API Key 并复制」-「查看并选择」**
把 API key 先复制下来，然后我们去 cherry studio 粘贴。 （操作详情，见下面界面）
注意：如果没有 API key，就在弹窗右上角 - 「**创建 API Key**」，然后复制 API key 就行了。
### 5、在 cherry studio 中使用 API Key 实现联网访问 deepseek-R1
#### 5.1、打开 cherry studio - 「设置」- 「随便写名称」-「类型为： openAI」
#### 5.2、配置 url 和 key
注意，找不到地址，或者不是北京的节点，可以在这个地方找到具体的地址，注意不要忘记“/”：
#### 5.3、添加模型名字
注意，是复制下面那个小字为模型名字，否则会报错。
### 6、 效果预览
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# Tavily 联网登录注册教程
如何注册tavily？
### 一、tavily 官网
{% hint style="info" %}
有的同学访问可能比较慢，如果有代理，可以使用代理。
{% endhint %}
### 二、tavily 注册详细步骤
访问上述官网，或者从 cherry studio - 设置 - 网络搜索 - 点击「获取密钥」，会直接跳转到 tavily 登录注册页面。
{% hint style="warning" %}
如果是第一次使用，要先注册一个（Sign up）账号，才能登录（Log in）使用。默认跳转的是登录页面哦。
{% endhint %}
1. 点击注册账号，进入下面的界面，输入自己的常用邮箱，或者使用谷歌、github 账号，然后下一步输入密码，常规操作。
注册账号
2. 🚨🚨🚨**【****关键步骤****】 注册成功后，会有一个****动态验证码****的步骤，需要扫描二维码，生成一次性 Code 才能继续使用。**
很多同学卡在这一步，人麻了....莫慌
{% hint style="danger" %}
很简单，此时你有 2 个办法。
1. 下载一个验证身份的 APP，微软出的—— Authenticator 【略微繁琐】
2. 使用微信小程序：腾讯身份验证器 。【简单，有手就行，建议】
{% endhint %}
3. 打开微信小程序，搜索：腾讯身份验证器
微信小程序-搜索-点击打开
点击后，扫描刚才 tavily 页面的二维码
你会得到一串数字
复制到 tavily 页面
会提示你复制 code 到安全的地方，听劝照做，虽然不咋会用上
### 三、注册成功
上面的步骤做完，就会进入下面的界面，说明你注册成功了，复制 key 到 cherry studio 就可以开始愉快的使用了。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# SearXNG 本地部署与配置
CherryStudio 支持通过 SearXNG 进行网络搜索，SearXNG 是一个可本地部署也可在服务器上部署的开源项目，所以与其他需要 API 提供商的配置方式略有不同。
**SearXNG 项目链接**：[SearXNG](https://github.com/searxng/searxng)
## SearXNG 的优势
* 开源免费，无需 API
* 隐私性相对较高
* 可高度定制化
## 本地部署
### 一、Docker 直接部署
由于 SearXNG 不需要复杂的环境配置，可以不用 docker compose，只需要简单提供一个空闲端口即可部署，所以最快捷的方式可以使用 Docker 直接拉取镜像进行部署。
#### 1. 下载安装并配置 [docker](https://www.docker.com/)
安装后选择一个镜像存储路径：
#### 2. 搜索并拉取 SearXNG 镜像
搜索栏输入 **searxng** ：
拉取镜像：
#### 3. 运行镜像
拉取成功后来到 **images** 页面：
选择拉取的镜像点击运行：
打开设置项进行配置：
以 `8085` 端口为例：
运行成功后点击链接即可打开 SearXNG 的前端界面：
出现这个页面说明部署成功：
## 服务器部署
鉴于 Windows 下安装 Docker 是一件较为麻烦的事情，用户可以将 SearXNG 部署在服务器上，也可借此共享给其他人使用。但是很遗憾，SearXNG 自身暂不支持鉴权，导致他人可以通过技术手段扫描到并滥用你部署的实例。
为此，Cherry Studio 目前已支持配置 [HTTP 基本认证（RFC7617）](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Guides/Authentication)，如果用户欲将自己部署的 SearXNG 暴露在公网环境下，请 **务必** 通过 Nginx 等反向代理软件配置 HTTP 基本认证。下面提供简要教程，需要你有基本的 Linux 运维知识。
### 部署 SearXNG
类似地，仍然使用 Docker 部署。假设你已经按照 [官方教程](https://docs.docker.com/engine/install) 在服务器上安装好了最新版 Docker CE，以下提供一条龙命令，适用于 Debian 系统下全新安装：
```bash
sudo apt update
sudo apt install git -y
# 拉取官方仓库
cd /opt
git clone https://github.com/searxng/searxng-docker.git
cd /opt/searxng-docker
# 如果你的服务器带宽很小, 可以设置为 false
export IMAGE_PROXY=true
# 修改配置文件
cat < /opt/searxng-docker/searxng/settings.yml
# see https://docs.searxng.org/admin/settings/settings.html#settings-use-default-settings
use_default_settings: true
server:
# base_url is defined in the SEARXNG_BASE_URL environment variable, see .env and docker-compose.yml
secret_key: $(openssl rand -hex 32)
limiter: false # can be disabled for a private instance
image_proxy: $IMAGE_PROXY
ui:
static_use_hash: true
redis:
url: redis://redis:6379/0
search:
formats:
- html
- json
EOF
```
如果你需要修改本地监听端口、复用本地已有的 nginx，可以编辑 `docker-compose.yaml` 文件，参考如下：
```yaml
version: "3.7"
services:
# 如果不需要 Caddy 而复用本地已经有的 Nginx, 就把下面的去掉. 我们默认不需要 Caddy.
caddy:
container_name: caddy
image: docker.io/library/caddy:2-alpine
network_mode: host
restart: unless-stopped
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy-data:/data:rw
- caddy-config:/config:rw
environment:
- SEARXNG_HOSTNAME=${SEARXNG_HOSTNAME:-http://localhost}
- SEARXNG_TLS=${LETSENCRYPT_EMAIL:-internal}
cap_drop:
- ALL
cap_add:
- NET_BIND_SERVICE
logging:
driver: "json-file"
options:
max-size: "1m"
max-file: "1"
# 如果不需要 Caddy 而复用本地已经有的 Nginx, 就把上面的去掉. 我们默认不需要 Caddy.
redis:
container_name: redis
image: docker.io/valkey/valkey:8-alpine
command: valkey-server --save 30 1 --loglevel warning
restart: unless-stopped
networks:
- searxng
volumes:
- valkey-data2:/data
cap_drop:
- ALL
cap_add:
- SETGID
- SETUID
- DAC_OVERRIDE
logging:
driver: "json-file"
options:
max-size: "1m"
max-file: "1"
searxng:
container_name: searxng
image: docker.io/searxng/searxng:latest
restart: unless-stopped
networks:
- searxng
# 默认映射到宿主机 8080 端口, 假如你想监听 8000 就改成 "127.0.0.1:8000:8080"
ports:
- "127.0.0.1:8080:8080"
volumes:
- ./searxng:/etc/searxng:rw
environment:
- SEARXNG_BASE_URL=https://${SEARXNG_HOSTNAME:-localhost}/
- UWSGI_WORKERS=${SEARXNG_UWSGI_WORKERS:-4}
- UWSGI_THREADS=${SEARXNG_UWSGI_THREADS:-4}
cap_drop:
- ALL
cap_add:
- CHOWN
- SETGID
- SETUID
logging:
driver: "json-file"
options:
max-size: "1m"
max-file: "1"
networks:
searxng:
volumes:
# 如果不需要 Caddy 而复用本地已经有的 Nginx, 就把下面的去掉
caddy-data:
caddy-config:
# 如果不需要 Caddy 而复用本地已经有的 Nginx, 就把上面的去掉
valkey-data2:
```
执行 `docker compose up -d` 启动。执行 `docker compose logs -f searxng` 可以看到日志。
### 部署 Nginx 反向代理和 HTTP 基本认证
如果你使用了一些服务器面板程序，例如宝塔面板或 1Panel，请参阅其文档添加网站并配置 nginx 反向代理，随后找到修改 nginx 配置文件的地方，\
参考下面的示例进行修改：
```conf
server
{
listen 443 ssl;
# 这行是你的主机名
server_name search.example.com;
# index index.html;
# root /data/www/default;
# 如果配置了 SSL 应该有这两行
ssl_certificate /path/to/your/cert/fullchain.pem;
ssl_certificate_key /path/to/your/cert/privkey.pem;
# HSTS
# add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload";
# 默认情况下通过面板配置反向代理, 默认的 location 块就是这样
location / {
# 只需要在 location 块添加下面两行, 其他保留原状就行.
# 此处示例假设你的配置文件保存在 /etc/nginx/conf.d/ 目录下.
# 如果是宝塔应该是保存在 /www 之类的目录下, 需要注意.
auth_basic "Please enter your username and password";
auth_basic_user_file /etc/nginx/conf.d/search.htpasswd;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_redirect off;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_protocol_addr;
proxy_pass http://127.0.0.1:8000;
client_max_body_size 0;
}
# access_log ...;
# error_log ...;
}
```
假设 Nginx 配置文件保存于 `/etc/nginx/conf.d` 下，我们将将密码文件保存在同目录下。
执行命令（自行将 `example_name`、`example_password` 替换为你将要设定的用户名和密码）：
```bash
echo "example_name:$(openssl passwd -5 'example_password')" > /etc/nginx/conf.d/search.htpasswd
```
重启 Nginx（重载配置也可以）。
这时可以打开一下网页，已经会提示你输入用户名和密码，请输入前面设定的用户名和密码查看能否成功进入 SearXNG 搜索页面，藉此检查配置是否正确。
## Cherry Studio 相关配置
SearXNG 本地或在服务器部署成功后，接下来是 CherryStudio 的相关配置。
来到网络搜索设置页面，选择 Searxng ：
直接输入本地部署的链接发现验证失败，此时不用担心：
因为直接部署后默认并没有配置 json 返回类型，所以无法获取数据，需要修改配置文件。
回到 Docker，来到 Files 标签页找到镜像中找到带标签的文件夹：
展开后继续往下翻，会发现另一个带标签的文件夹：
继续展开，找到 **settings.yml** 配置文件：
点击打开文件编辑器：
找到 78 行，可以看到类型只有一个 html
添加 json 类型后保存，重新运行镜像
重新回到 Cherry Studio 进行验证，验证成功：
地址既可以填写本地： : 端口号\
也可以填写 docker 地址： : 端口号
如果用户遵循前面的示例在服务器上部署并正确配置了反向代理，已经开启了 json 返回类型。输入地址后进行验证，由于已给反向代理配置了 HTTP 基本认证，此时验证则应返回 401 错误码：
在客户端配置 HTTP 基本认证，输入刚才设置的用户名与密码：
进行验证，应当验证成功。
### 其他配置
此时 SearXNG 已具备默认联网搜索能力，如需定制搜索引擎需要自行进行配置
需要注意的是此处首选项并不能影响大模型调用时的配置
如需配置需要大模型调用的搜索引擎，需在配置文件中设置：
配置语言参考：
若内容太长直接修改不方便，可将其复制到本地 IDE 中，修改后粘贴到配置文件中即可。
## 验证失败常见原因
### 返回格式未添加 json 格式
在配置文件中将返回格式加上 json：
### 未正确配置搜索引擎
Cherry Studio 会默认选取 categories 同时包含 web general 的引擎进行搜索，默认情况下会选中 google 等引擎，由于大陆无法直接访问 google 等网站导致失败。增加以下配置使得 searxng 强制使用 baidu 引擎，即可解决问题：
```
use_default_settings:
engines:
keep_only:
- baidu
engines:
- name: baidu
engine: baidu
categories:
- web
- general
disabled: false
```
### 访问速率过快
searxng 的 limiter 配置阻碍了 API 访问，请尝试将其在设置中设为 false：
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 文档处理
简单说：**这是 Cherry Studio 把"PDF / 复杂版式文档"读成规整文本的中央配置。**
带表格、多栏、扫描页的 PDF（学术论文、合同、研报等）直接丢给模型往往会读得乱七八糟。文档处理会先用专门的解析引擎把它们转成结构清晰的文本，再交给对话或 [知识库](/knowledge-base/knowledge-base) 使用。
{% hint style="info" %}
**文档处理 vs OCR**：两者是分开的两页设置。
* **文档处理**（本页）：管 **PDF / 复杂版式文档** 的结构化解析。
* [**OCR**](/pre-basic/settings/ocr)：管 **图片 / 扫描件** 里的文字识别。
普通纯文本 PDF、`.md`/`.txt`/`.docx` 里的文字段落两者都不需要，直接读即可。
{% endhint %}
### 配置入口
打开 【设置】→【文档处理】，右上角的下拉里选择解析引擎，**选中的引擎即作为默认**。
文档处理设置：① 右上角下拉选择解析引擎（默认 MinerU）；下方填入所选引擎的 API 密钥与 API 地址
### 内置解析引擎
文档处理内置 5 个引擎，默认 **MinerU**：
| 引擎 | 说明 | 接入方式 |
| --------------- | ------------------------------- | ----------------------------------------------------------------------------- |
| **MinerU**（默认） | OpenDataLab 开源的高质量 PDF 提取工具 | API 密钥（[mineru.net/apiManage](https://mineru.net/apiManage)） |
| **PaddleOCR** | 百度飞桨 OCR 识别系统 | 填 API 密钥（[飞桨星河社区](https://aistudio.baidu.com/paddleocr/)）；如自部署则把 API 地址指向你的服务 |
| **Doc2x** | 高级文件还原引擎 | API 密钥（[open.noedgeai.com](https://open.noedgeai.com/apiKeys)） |
| **Mistral** | 文件解析与理解服务 | API 密钥（[mistral.ai](https://mistral.ai/api-keys)） |
| **Open MinerU** | 可自部署的 MinerU 服务，适合希望自行控制处理链路的团队 | 自部署后填 API 地址（按需填 API 密钥） |
### 配置 MinerU（默认方案）
{% stepper %}
{% step %}
### 填入 API 密钥
在【API 密钥】字段填入 MinerU 申请到的 key（点右侧「获取密钥」跳转申请页面，多个密钥可用逗号分隔）。
{% endstep %}
{% step %}
### 确认 API 地址
【API 地址】保持默认即可。
{% endstep %}
{% step %}
### 在知识库 / 对话中直接使用
导入复杂 PDF 时会自动走此处的解析设置，切换到知识库或对话时无需额外配置。
{% endstep %}
{% endstepper %}
{% hint style="info" %}
**换用其他引擎**：在下拉里选中它，填入该引擎的【API 密钥】/【API 地址】即可，选中即成为默认。其中 **PaddleOCR** 和 **Open MinerU** 支持自部署——部署后把【API 地址】填成你自己的服务地址。
{% endhint %}
### 与知识库的关系
* 文档处理仅负责"复杂文档 → 规整文本"这一步；
* 转换后的文本继续走 [嵌入模型](/knowledge-base/emb-models-info) 向量化、入库；
* 详细的"在知识库中启用"流程见 [知识库文档预处理](/knowledge-base/document-preprocessing)。
### 提示与技巧
* MinerU 对带表格 / 多栏排版的 PDF 效果显著更好，遇到学术论文等首选；
* 需要识别的是 **图片里的文字**（截图、扫描件）而非 PDF 结构，请改用 [OCR](/pre-basic/settings/ocr)。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# OCR
OCR（Optical Character Recognition，光学字符识别）负责把 **图片里的文字变成可复制、可被 AI 读取的文本**。下面这些事都依赖它：
* 把一张截图 / 扫描件拖进对话框，想让 AI 读懂里面的文字
* 把图片格式的发票、资料放进 [知识库](/knowledge-base/knowledge-base)，希望以后能搜到
* [智能体](/cherry-studio/preview/agent) 打开本地某张图片进行分析
OCR 是一页独立的设置。你在 【设置】→【OCR】 里配一次识别引擎，所有用到图片识字的地方都会用同一套配置。
OCR 设置：① 右上角下拉选择识别引擎（图示为 Mistral），下方填入所选引擎的 API 密钥与 API 地址
### 选择识别引擎
面板右上角的下拉框用于切换 OCR 引擎，**选中的引擎即作为默认**。内置引擎：
| 引擎 | 接入 / 运行方式 | 适合谁 |
| ----------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| **System OCR** | 离线、免配置 | 借用系统自带识别（macOS Live Text / Windows OCR），开箱即用、速度最快 |
| **PaddleOCR** | 填 API 密钥（[飞桨星河社区](https://aistudio.baidu.com/paddleocr/)）；如自部署则把 API 地址指向你的服务。可选解析模型 | 不想占本地资源、又想要 Paddle 的识别效果 |
| **本地 PaddleOCR** | 离线，需先在【设置】→【本地模型】下载本地 OCR 模型（约 140MB） | 中文识别效果好且完全在本机运行，隐私优先 |
| **Tesseract OCR** | 离线、已内置 | 经典开源 OCR，支持多语言，可作为兜底 |
| **Mistral** | Mistral API 密钥 | 借助多模态大模型识别，复杂版式 / 手写体等更智能 |
| **Intel OV OCR** | 本地运行（Intel OpenVINO，NPU 加速） | **仅在 Windows + Intel 酷睿 Ultra（带 NPU）、且已部署 OV 模型时才出现**，其余设备看不到此项 |
{% hint style="success" %}
不确定选哪个？先用 **System OCR**——绝大多数截图、清晰扫描件都能直接搞定，且无需任何配置。识别效果不理想时再换 本地 PaddleOCR 或 Mistral。
{% endhint %}
选中 System OCR 时，面板会显示 检测到 macOS Live Text / Windows OCR 引擎可用（系统不支持时，该项不会出现在下拉里）。
{% hint style="warning" %}
* 选择「本地 PaddleOCR」前，请先在【设置】→【本地模型】下载「本地 OCR 模型」，否则无法调用。
* **Tesseract**（及 Windows 上的 System OCR）可在面板的「语言」下拉里勾选要识别的语种。
{% endhint %}
### 与文档处理的区别
很多人会把 OCR 和 [文档处理](/pre-basic/settings/doc-process) 搞混，一句话区分：
* **OCR**：管 **图片 / 扫描件** 里的文字识别（图 → 字）。
* **文档处理**：管 **PDF / 复杂版式文档** 的结构化解析（带表格、多栏的 PDF → 规整文本）。
两者相互独立、各配各的。纯文本 PDF、`.md`/`.txt`/`.docx` 里的文字段落两者都不经过，直接读即可。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 外观
外观设置集中了 **界面长什么样、消息怎么显示、代码与公式怎么渲染** 这一整套偏好。打开 `设置 → 外观`，从上到下依次是主题、显示与语言、字体、输入、消息、公式、代码块等分区。
> 不满足于这里的选项？还可以走 [自定义 CSS](/pre-basic/settings/display/custom-css) 深度定制。
### 主题与主题颜色
主题、主题颜色与显示语言
* **主题**：在 **浅色 / 深色 / 系统** 之间切换（"系统"跟随操作系统的深浅色）。
* **主题颜色**：选择界面主色调，提供多个预设色，也可在右侧输入十六进制色值（如 `#00B96B`）自定义。
### 显示与语言
| 设置项 | 说明 |
| ---------- | ---------------------------------------- |
| **语言** | 界面显示语言，支持简体中文、繁体中文、英语、日语、德语、法语等多种语言 |
| **缩放** | 整体界面缩放比例，屏幕大 / 小或觉得字小时可调 |
| **右键菜单样式** | 在 Cherry 自绘菜单与系统 **原生** 右键菜单之间切换 |
| **透明窗口** | 开启窗口半透明毛玻璃效果（**仅 macOS 提供**；部分显卡下可能影响性能） |
### 字体设置
* **全局字体**：界面整体字体，默认使用系统字体，可换成你喜欢的字体。
* **代码字体**：代码块使用的等宽字体。
字体推荐见 [字体推荐](/pre-basic/settings/display/font)。
### 输入设置
字体、输入与消息显示设置
| 设置项 | 说明 |
| ------------------- | ------------------------------------ |
| **发送快捷键** | 设置发送消息的按键（如 `Enter`、`Shift+Enter` 等） |
| **拼写检查** | 输入英文时在拼写错误下显示红色波浪线；主要用中文可关闭以免误报 |
| **显示预估 Token 数** | 在输入框显示输入内容预估消耗的 Token（仅供参考，非实际计费） |
| **Markdown 渲染输入消息** | 关闭后你发送的消息不做 Markdown 渲染，只渲染模型回复 |
| **删除消息前确认** | 删除消息时先弹确认，防止误删 |
### 消息设置
控制 AI 回复在对话区如何呈现：
| 设置项 | 说明 |
| ------------ | ------------------------- |
| **宽布局模式** | 让消息内容占满更宽的区域 |
| **使用衬线字体** | 正文切换为衬线字体，长文阅读更舒适 |
| **思考内容自动折叠** | 支持推理的模型在思考完成后自动折叠思考过程 |
| **显示消息大纲** | 为较长回复生成可跳转的大纲 |
| **消息样式** | 在 **气泡** 与 **简洁** 两种样式间切换 |
| **多模型回答样式** | 多模型对比时的排布，如 **横向排列** |
| **对话导航按钮** | 长对话中的快速定位方式，如 **对话锚点** |
| **消息字体大小** | 拖动滑块调整对话区字体大小 |
### 数学公式
* **启用 `$...$`**：开启后识别行内数学公式（用 `$` 包裹的内容）并渲染为公式。
### 代码块设置
数学公式与代码块设置
| 设置项 | 说明 |
| ---------- | ------------------------ |
| **代码风格** | 代码高亮配色方案（默认 `auto` 跟随主题） |
| **花式代码块** | 更精致的代码块外观 |
| **代码编辑器** | 用可编辑的代码编辑器样式显示代码 |
| **代码显示行号** | 代码块左侧显示行号 |
| **代码块可折叠** | 较长代码自动折叠 |
| **代码块可换行** | 单行过长时自动换行，避免横向滚动 |
> 打开 **代码编辑器** 后，还会多出 **高亮当前行 / 折叠控件 / 自动补全 / 快捷键** 四个子开关，进一步控制编辑器行为。
### 代码执行
* **代码执行**：允许在对话中直接运行模型生成的代码片段。
* **启用预览工具**：为 mermaid 等代码块渲染后的图表产物提供即时预览。
{% hint style="warning" %}
代码执行会在你的电脑上运行模型生成的代码。仅在你理解并信任相关内容时开启。
{% endhint %}
### 自定义 CSS
面板底部的编辑器可直接写入自定义 CSS，对界面做更细致的个性化调整。写法与示例见 [自定义 CSS](/pre-basic/settings/display/custom-css)；想恢复默认见 [清除 CSS 设置](/pre-basic/settings/display/clear-css)。
***
### 获取帮助与提交反馈
如果您在配置或使用过程中遇到任何疑问、Bug 或有功能改进建议，请参考 [反馈与建议](/question-contact/suggestions) 中提供的官方渠道。
# 自定义 CSS
通过自定义 CSS，你可以在不改动源代码的情况下调整软件外观，让界面更符合自己的喜好，例如换字体、改主题色、调整消息气泡背景等。
### 在哪里设置
打开 **【设置】→【外观】**，在页面底部找到 **「自定义 CSS」** 代码框，把样式写进去即可实时生效。留空则不加载任何自定义样式。
【设置】→【外观】页面底部的「自定义 CSS」代码框
你写入的 CSS 会被原样注入到每个窗口的 `` 中，对应一个 `