Cherry Studio · 跨平台开源桌面 AI 工作站 · 安装配置与源码构建全指南

项目仓库： https://github.com/CherryHQ/cherry-studio

开源协议：GNU AGPL-3.0（社区版，商用须遵守 AGPL-3.0 条款，另有商业授权可选） · 技术栈：Electron + TypeScript · 运行形态：桌面客户端（Windows / macOS / Linux），配套 iOS / Android 移动端为独立仓库 · 服务端端口：无（本地桌面应用，不自带常驻服务端口） · 仓库分支：main（本文命令与版本信息以官方仓库最新说明为准）

1 项目简介

Cherry Studio 是一款运行在 Windows、macOS 和 Linux 上的开源 AI 工作站：在同一个桌面应用里完成多模型对话、Agent 任务编排、本地知识库搭建、图片生成、网页工具调用与日常效率操作。用户可以在一处集中配置 OpenAI、Anthropic、Gemini 等云端服务商，也可以接入本机通过 Ollama、LM Studio 运行的本地模型，并在同一会话中切换或对比多个模型的回答。

项目由 CherryHQ 社区团队维护，提供社区版与企业版两条产品线：社区版以 AGPL-3.0 协议开源；企业版面向团队与组织提供集中模型管理、共享知识库、员工访问控制与私有化部署选项。

非官方声明：Cherry Studio 是独立的开源第三方客户端，与 OpenAI、Anthropic、Google、DeepSeek、月之暗面等模型厂商不存在隶属、授权、赞助或技术支持关系；应用内出现的厂商名称仅用于标识兼容的模型服务商。模型能力、计费与数据政策由对应服务商各自规定，使用前请阅读其服务条款。

1.1 核心信息一览

1.2 适用场景

• 希望在一个桌面客户端里集中管理多家云端模型与本地模型，随时切换、并排对比不同模型的回答，而不是在多个网页和工具之间来回跳转。
• 需要为不同任务建立专属助手（Agent）：各自携带系统指令、工作区、模型与工具权限，完成文件处理、命令执行、浏览器与电脑自动化等多步骤任务。
• 把本地文件、文件夹与网页资料整理成知识库，在对话与 Agent 工作流中检索引用；支持 PDF、Office 文档、图片与文本的处理及 OCR 选项。
• 需要图片生成与编辑、文本与文档翻译、网页搜索、跨会话与知识库内容检索，以及通过 Mini Apps 打开网页工具、通过 API Gateway 把配置好的模型开放给其他应用调用。
• 重视本地数据留存：会话历史与知识库保存在本机设备上，支持本地备份与 WebDAV 备份选项。

1.3 能力边界（官方口径）

• 模型与工具的可用性取决于所选服务商、操作系统与配置；部分功能需要 API 凭据、已下载的模型、额外依赖或系统权限，具体以官方用户文档为准。
• 云端模型的回答质量、上下文长度、计费与限流由服务商决定；本地模型的能力上限由本机推理工具与模型权重决定，Cherry Studio 只负责客户端接入与编排。
• 社区版不包含企业版的集中模型管理、共享知识库、员工访问控制与私有化部署能力；团队级需求需另行咨询企业版。
• 官方 README 未公布统一的服务器端部署形态；本文不虚构 Docker 镜像、服务端端口或后台管理界面。

2 功能特性

以下功能条目均来自官方 README 的功能分组，具体入口名称以当前版本应用内界面为准。

2.1 Agent 与自动化

• 自定义 Agent：可为 Agent 单独配置指令、工作区、模型与工具权限。
• 文件与工具调用：Agent 可操作文件、执行命令，并使用浏览器与电脑自动化工具。
• Skills 与 MCP 扩展：通过 Skills 与 MCP（Model Context Protocol）服务器扩展能力边界。
• 定时任务与消息渠道：支持定时运行任务，并可通过 Channels 把 Agent 接入消息平台。

2.2 模型与会话

• 云端服务商：接入 OpenAI、Anthropic、Gemini 等主流云端服务商，也可添加自定义兼容接口的服务。
• 本地模型：通过 Ollama 与 LM Studio 使用本机运行的模型。
• 助手与会话对比：可自定义助手，并在同一会话中对比多个模型的回答。
• 富文本渲染与导出：回答支持 Markdown、代码高亮、数学公式、Mermaid 图表渲染，并可导出会话记录。

2.3 知识与文档

• 本地知识库：从文件、文件夹与网页资料建立知识库，供对话与 Agent 工作流检索使用。
• 多格式处理：处理 PDF、Office 文档、图片与文本，提供 OCR 与文档处理选项。
• 笔记与文件库：在 Markdown 笔记中整理思路，集中管理附件与生成文件。

2.4 创意与日常工具

• 图片创作：通过受支持的图片模型生成并编辑图片。
• 翻译：翻译文本与文档，并提供来自其他应用的快捷翻译。
• 搜索：网页搜索、网页阅读，以及跨会话与知识库内容检索。
• Mini Apps 与 API Gateway：通过 Mini Apps 打开网页工具；通过 API Gateway 把已配置的模型连接给其他应用使用。

2.5 语音与工作区

• 语音输入与朗读：支持语音识别输入消息，并可朗读模型回答，语音选项包含本地模型。
• 多窗口工作：支持标签页与独立窗口、窗口置顶、Quick Assistant 与文本选择工具。
• 主题与布局：提供亮色 / 暗色主题、布局调整与自定义 CSS。
• 数据留存与备份：会话历史与知识库保存在本机，支持本地备份与 WebDAV 备份选项。

3 官方界面预览

3.1 Agent 工作区

开头封面即为 Agent 工作区截图：左侧为内置与自定义 Agent 列表，右侧可选择 Agent、模型与工作区；示例中 “Slide Designer” Agent 调用文件与工具，分步生成并校验了一份演示文稿，生成的 .pptx 文件可在会话中直接打开。

3.2 会话与图表渲染

会话界面中，模型回答以 Markdown 排版呈现，代码块高亮，Mermaid 图表直接渲染为可视化图形；左侧助手列表可按任务角色切换。

3.3 模型服务商配置

设置页的模型服务商面板：左侧列出已接入的服务商与本地模型入口，右侧填写 API Key、API Host，可一键同步模型列表并逐个启用；左侧边栏同时包含 MCP、Skills、Prompts、网页搜索、文档处理、OCR 等工具配置项。

3.4 本地知识库

知识库界面：左侧为多个知识库分组，右侧展示当前知识库的数据来源（文件夹、Markdown、Word、PDF、Excel、PPT 等）与 Ready 状态，支持添加数据来源与召回测试。

4 官方跳转链接汇总

下表列出项目相关的官方入口，均可直接点击访问。

5 前置要求与服务器配置

5.1 软件前提

• 操作系统：Windows、macOS 或 Linux，安装包按系统与处理器架构（x64 / arm64）在官方下载页选择；具体受支持的系统版本以下载页与安装包说明为准。
• 网络连接：接入云端模型需要能够访问对应服务商接口的网络环境；接入本地模型则需要本机已运行对应的推理工具。
• 云端模型 API Key：使用 OpenAI、Anthropic、Gemini、DeepSeek、Moonshot、SiliconFlow 等云端服务时，需自行在对应服务商控制台申请 API Key；客户端不附带任何密钥。
• 本地推理工具（可选）：使用本地模型时，需另行安装并运行 Ollama 或 LM Studio，并按其各自文档下载模型权重。
• 源码构建（仅开发者）：Node.js（版本由仓库 .node-version 锁定，当前为 24.18.1）、pnpm（版本由 package.json 的 packageManager 字段锁定，经 corepack 自动启用），详见第 7 节。

5.2 硬件与系统建议

官方 README 未公布统一的最低硬件配置表；普通云端对话场景以官方下载页标注的系统要求为准。接入本地模型时，内存、显卡显存与磁盘空间要求由所选本地模型与推理工具决定，需对照 Ollama / LM Studio 及模型权重页面的说明预留资源。

5.3 端口与网络说明

安全提示：API Key 只填写在客户端本地设置中，不要提交到公开仓库、截图或分享文档；本地模型服务默认只应对本机回环地址开放，不要随意把推理端口暴露到公网。

6 方式一：官方安装包下载安装（推荐普通用户）

Cherry Studio 是桌面客户端，官方推荐路径是从下载页获取对应系统的安装包，不存在官方 Docker 一键部署方式。

6.1 下载与安装

1. 打开官方下载页 https://cherryai.com/download。
2. 按操作系统与处理器架构选择安装包：Windows（x64 / arm64）、macOS（Apple Silicon arm64 / Intel x64）、Linux（x64 / arm64）。
3. 下载完成后按系统常规方式安装：Windows 运行安装程序；macOS 拖入应用程序文件夹或按系统提示打开；Linux 按下载包格式（AppImage / deb 等）执行对应安装。
4. 安装过程中如遇到权限提示、安全隔离提示或安装失败，查阅官方文档的 “Download and Installation” 章节处理。

6.2 首次配置模型服务商（官方快速上手流程）

按官方 Quick Start 文档，首次使用按以下步骤完成配置：

1. 打开应用，进入 Settings → Model Provider（设置 → 模型服务商）。
2. 选择或添加服务商；尚无 API Key 时，可参考官方文档的 Model Provider Quick Reference，按地区、模型能力与隐私需求选择服务商。
3. 在服务商设置中填写 API Key，点击 Sync models（同步模型），勾选要使用的聊天模型，并启用该服务商开关。
4. 返回 Chat（对话），新建或打开一个助手，选中刚添加的模型，即可发送第一条消息。

6.3 接入本地模型（Ollama / LM Studio）

1. 先按各自官方文档安装并启动 Ollama 或 LM Studio，下载需要的模型权重，确认本地推理服务已在本机运行。
2. 在 Cherry Studio 设置的本地模型入口中选择 Ollama 或 LM Studio，填写本地推理工具提供的接口地址（端口以工具自身配置为准）。
3. 同步模型列表后，在助手或会话中选择本地模型即可对话。
4. 若本地模型列表为空，先排查推理工具是否已启动、接口地址与端口是否正确、模型是否已下载完成。

7 方式二：源码本地运行与打包构建（开发者）

面向参与开发、二次构建或需要自定义版本的用户。开发环境要求与命令均来自官方 docs/contrib/development.md 与仓库配置文件。

7.1 环境准备

• Node.js：所需版本由仓库 .node-version 锁定（当前为 24.18.1），建议使用 nvm、fnm 等版本管理器自动安装：

nvm install

• pnpm：版本锁定在 package.json 的 packageManager 字段，启用 corepack 后自动使用正确版本：

corepack enable

• Windows 开发者注意：项目使用符号链接同步 AGENTS.md、skills 等文件，Windows 上克隆前需先开启符号链接支持：
  1. 开启开发者模式（设置 → 更新和安全 → 开发者），或通过 secpol.msc 授予 SeCreateSymbolicLinkPrivilege 权限；
  2. 配置 Git：

git config --global core.symlinks true

3. 开启后再克隆（或重新克隆）仓库。

7.2 克隆仓库并安装依赖

# 1. 克隆仓库
git clone https://github.com/CherryHQ/cherry-studio.git
cd cherry-studio

# 2. 安装依赖
pnpm install

# 3. 复制开发环境变量模板
cp .env.example .env

7.3 开发模式启动

pnpm dev

• 默认情况下，开发实例会在 Electron 默认 userData 目录后追加 Dev 后缀，使本地开发数据与打包应用数据相互隔离。
• 如需完全隔离的开发配置目录，在 .env 中设置绝对路径：

CS_DEV_PROFILE_ROOT=/absolute/path/to/cherry-profile

设置后，Cherry 主目录与 BootConfig、Electron userData、应用日志都会落在该根目录下；该路径不能是相对路径或文件系统根目录，打包构建会忽略此项。

• 如需轻量隔离多个开发实例，可为每个实例设置唯一的 userData 后缀：

CS_DEV_USER_DATA_SUFFIX=DevQuito pnpm dev
CS_DEV_USER_DATA_SUFFIX=DevParis pnpm dev

后缀必须是单个路径组件，不能包含路径分隔符、盘符冒号、* ? " < > |、控制字符或结尾点号；留空时回退为 Dev。

7.4 调试、测试与打包构建

# 调试模式启动，随后在浏览器地址栏输入 chrome://inspect 进行调试
pnpm debug

# 按平台打包构建（架构细分命令见 package.json 与开发文档）
pnpm build:win    # Windows
pnpm build:mac    # macOS
pnpm build:linux  # Linux

# 测试
pnpm test:main src/main/path/to/example.test.ts
pnpm test:renderer src/renderer/path/to/example.test.ts
pnpm test

# 校验与代码规范
pnpm check --plan
pnpm check
pnpm check:all
pnpm lint
pnpm lint:fix
pnpm format
pnpm typecheck

注意：主进程测试会为 Node 重建 SQLite，而 pnpm dev 为 Electron 重建 SQLite，不要在同一工作目录下并发运行两者的原生二进制；架构专属打包命令与 better-sqlite3 预编译流程见仓库 docs/contrib/linux-packaging.md。

8 配置项说明

8.1 开发环境变量（.env）

仓库提供 .env.example 模板，开发时复制为本地 .env。下表字段来自官方模板，默认值仅用于开发环境，不构成生产凭据。

8.2 应用内配置项

以下配置在客户端设置界面中完成，分组名称以当前版本界面为准：

9 常用运维命令

桌面安装包版本通过应用内检查更新；以下命令面向源码开发与构建场景。

# 开发模式启动
pnpm dev

# 调试模式启动
pnpm debug

# 平台打包构建
pnpm build:win
pnpm build:mac
pnpm build:linux

# 运行测试
pnpm test
pnpm test:main <主进程测试文件路径>
pnpm test:renderer <渲染进程测试文件路径>

# 代码校验、检查与格式化
pnpm check
pnpm check:all
pnpm lint
pnpm lint:fix
pnpm format
pnpm typecheck

数据备份与迁移：

• 会话历史、知识库与应用配置默认保存在本机用户数据目录；升级或重装前，先在应用 Data 分组中执行本地备份。
• 支持配置 WebDAV 备份；使用 WebDAV 前请确认备份服务器的访问控制与传输加密，避免资料外泄。
• 开发实例的数据隔离目录由 CS_DEV_PROFILE_ROOT 或 CS_DEV_USER_DATA_SUFFIX 控制（见 7.3 节）。

10 常见故障排查

以下条目结合官方文档目录与源码开发说明整理；遇到未覆盖的问题时，先查阅官方文档 Troubleshooting 章节与 Issues 列表。

10.1 云端模型连接失败

• 依次检查：API Key 是否填写正确、服务商是否已启用开关、模型是否已勾选启用、API Host 是否与服务商文档一致、本机网络能否访问该接口。
• 需要代理的网络环境，检查系统代理或应用网络设置；接口超时或 401 / 403 时优先对照服务商控制台的密钥状态、额度与限流说明。
• 新增服务商后记得点击 Sync models 同步模型列表，再回到会话选择模型。

10.2 本地模型不显示或无法对话

• 确认 Ollama / LM Studio 已启动且模型权重已下载完成；接口地址与端口填写到本地模型配置中，端口以推理工具自身设置为准。
• 本地服务默认只监听本机回环地址；如需局域网访问，按推理工具官方文档配置监听地址与防火墙，不要直接把端口暴露到公网。
• 模型上下文长度、工具调用能力受本地模型本身限制；不支持视觉或工具调用的模型，对应功能不可用属于模型侧限制。

10.3 Windows 源码构建报符号链接错误

• 先确认开发者模式已开启或已授予符号链接权限，git config --global core.symlinks true 已配置，再重新克隆仓库。
• 仍失败时检查仓库所在磁盘格式与权限，必要时在独立用户目录下重新克隆构建。

10.4 依赖安装与版本问题

• Node 版本不符合 .node-version 时，先用 nvm 等版本管理器切换到锁定版本再 pnpm install。
• pnpm 版本由 corepack 自动锁定；如 corepack 未启用，先执行 corepack enable，不要混用其他包管理器安装依赖。
• 安装失败可清理 node_modules 与锁文件缓存后重试；构建内存不足时检查 NODE_OPTIONS=--max-old-space-size 设置。

10.5 社区主题不生效或样式错乱

• 社区主题与应用版本存在适配关系：官方说明中提到，为 v1 编写的主题需要适配 v2 界面才能使用；安装前先查看主题仓库标注的支持版本。
• 主题资源见 README 的 Theme 分组（主题画廊与第三方主题仓库），问题反馈到对应主题仓库。

10.6 日志与调试定位

• 开发环境日志级别由 CSLOGGER_MAIN_LEVEL、CSLOGGER_RENDERER_LEVEL 控制，需要排查问题时可将级别调低输出更详细日志。
• 调试模式下使用 chrome://inspect 连接渲染进程；官方文档另含 Trace 与开发者模式章节，供定位 Agent 与工具调用链路。

10.7 文档处理、OCR 与语音功能异常

• 文档解析与 OCR 效果取决于所选文档格式、系统组件与已安装依赖；官方文档 Knowledge Base Troubleshooting 与 MCP Troubleshooting 章节列有高频问题处理方式。
• 语音识别与朗读部分选项支持本地模型；对应本地组件未安装或模型未下载时，该选项不可用，属于配置前提不满足。

11 风险与合规说明

• 开源协议义务：社区版以 GNU AGPL-3.0 协议发布。修改、分发或通过网络向用户提供基于本项目的修改版本时，须遵守 AGPL-3.0 的开源义务；如需豁免 AGPL 条款的商业授权，请联系官方商务渠道办理。
• 第三方服务商条款：云端模型、搜索、图片生成等能力由对应服务商提供，其计费、数据留存、内容政策与使用限制以服务商条款为准；API Key 属于个人敏感凭据，仅限本人在受控环境中使用。
• 数据隐私：会话历史、知识库与笔记默认保存在本机；使用云端模型时，发送内容会按服务商规则传输与处理，请勿把未脱敏的隐私、商业机密或个人证件信息粘贴进对话。开启 WebDAV 备份前，确认备份渠道的加密与访问权限。
• 模型生成内容责任：模型生成的文案、代码、图片与图表可能存在错误或版权瑕疵，重要内容须人工复核；图片与代码生成内容的版权归属按对应模型与服务条款执行。
• 企业版与社区版边界：集中模型管理、共享知识库、员工权限与私有化部署属于企业版能力；在未取得企业授权前，不要把社区版文档中的企业功能描述当作可直接获得的能力。
• 非官方立场：本文为基于官方 README、官方文档站与开发指南整理的部署使用指南，项目名称与厂商名称归各自权利人所有；如遇官方文档更新，以仓库与文档站最新说明为准。