Cherry Studio 安装与配置完全指南：10 分钟装好并跑通第一次对话

Cherry Studio 安装与配置完全指南10 分钟装好并跑通第一次对话【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioCherry Studio 是一款支持多个 LLM 提供商的桌面客户端一个界面里就能接 OpenAI、Gemini、Anthropic、Claude也能连本地 Ollama 模型。跟着本文操作你可以把它装到 Windows / macOS / Linux 上完成第一个 API Key 配置并发出第一条对话全程约 10 分钟想从源码构建的版本也有最小步骤。 先选路径再动手Cherry Studio 是开箱即用的桌面应用普通用户不需要装任何开发环境。先按下表挑一行你的系统推荐路径一句话操作Windows官方安装包最稳从项目发布页下载.exe双击安装macOS.dmg拖拽挂载后把应用拖进ApplicationsLinuxAppImage下载后加执行权限直接运行开发者任意系统源码构建见下方「源码构建」小节以下以 Windows 安装包为例走一遍其余系统操作类似到项目发布页Releases下载最新版 Windows 安装包。双击.exe按向导点到底即可默认选项就能用。确认桌面出现 Cherry Studio 快捷方式说明装好了。macOS下载.dmg→ 挂载 → 拖入Applications→ 首次打开若提示无法验证开发者在系统设置 → 隐私与安全性里点仍要打开。Linux下载 AppImage 后执行一次chmod x CherryStudio-*.AppImage之后双击或命令行运行均可。 跑通第一步5 分钟最小可运行装好先别关终端接下来做三件事做完 Cherry Studio 就算真正活了。第 1 步打开主窗口做什么确认应用能正常启动。怎么做双击桌面快捷方式。成功标志出现主窗口左侧是助手和话题列表中间是聊天输入区。第 2 步接入第一个模型做什么让应用有一个能调用的模型。怎么做点左下角「设置」→「助手/服务商管理」二选一云端服务选一家 OpenAI 兼容的服务如 SiliconFlow填入你的 API Key 和 Base URL挑一个模型本地模型先在本机跑起 Ollamaollama serve然后在设置里选 Ollama 提供商无需 Key。成功标志所选提供商出现在模型选择列表里可以点开选模型。第 3 步发出第一条对话做什么验证消息链路真的通了。怎么做新建话题输入你好介绍一下你自己回车。成功标志回复逐字流式返回结束后对话保留在话题列表里随时可以续聊。开发者版源码构建的最小命令如果你要改代码而不是用应用最小路径如下为什么分这几步Node 版本被.node-version锁死为 24.11.1pnpm 版本由package.json的packageManager字段决定corepack 会自动装对git clone https://gitcode.com/CherryHQ/cherry-studio cd cherry-studio nvm install # 自动读到 24.11.1 corepack enable # 自动启用 pnpm 11.8.0 pnpm install cp .env.example .env pnpm dev看到 Electron 窗口弹出、且终端没有红色报错源码版就跑起来了。开发数据默认带Dev后缀的独立目录不会污染正式安装版的数据。Cherry Studio 是典型 Electron 双进程结构渲染进程负责界面、主进程负责 AI 调用与落库看懂这张图再改代码不容易迷路编辑器建议用 VS Code 系扩展清单在 .vscode/extensions.json装好 i18n Ally 插件后界面文案会实时显示翻译预览⚙️ 关键配置逐项拆解配置就这几个真正影响跑通的只有前两项其余基本不用动配置项作用默认值要不要改API Key云端模型服务的鉴权空必改用云端时Base URL模型服务端点随提供商而定换中转/私有部署时必改注意带/v1模型Model该提供商下默认调用的模型提供商推荐可选本地模型地址Ollama 等服务地址http://localhost:11434Ollama 没换端口就不用改主题浅色 / 深色 / 跟随系统跟随系统看喜好CS_DEV_USER_DATA_SUFFIX区分多个开发实例的数据目录Dev只在你并行跑多个pnpm dev时改源码构建的.env模板在 .env.example里面API_KEY、BASE_URL、MODEL三项只影响内置 Cherry 助手的开箱效果不填也能跑日志级别用CSLOGGER_MAIN_LEVEL/CSLOGGER_RENDERER_LEVEL控制。更多目录结构见 docs/references/architecture-overview.md。 进阶让工具更顺手Cherry Studio 自带浅色/深色主题macOS 上还额外支持透明窗口在「设置 → 外观」里打开即可。想要更彻底的换肤应用支持导入自定义主题 CSS从项目 README 里列出的社区主题中选一份样式文件在外观设置中导入保存后即时生效无需重启。顺便看一眼消息在内部是怎么走的输入 → 消息服务 → 服务商调用 → AI Core → 流式返回渲染层消息块最终写入本地数据库 卡点排查症状可能原因解法云端模型发消息无响应或报错API Key 过期或 Base URL 少了/v1重新核对 Key 与端点用 curl 直接打一次端点验证本地模型列表为空Ollama 没启动终端执行ollama list未启动则ollama serveWindows 克隆或安装依赖报符号链接错误未开启符号链接支持打开系统开发者模式再执行git config --global core.symlinks true后重新克隆详见 docs/guides/development.mdpnpm install报版本不满足Node 不是 24.11.1.npmrc开了engine-strictnvm install切到锁定版本再装多个开发实例互相覆盖数据用了同一个数据目录启动时加CS_DEV_USER_DATA_SUFFIXMyName pnpm dev区分更完整的构建与调试命令pnpm build:win/build:mac/build:linux、pnpm debug等在 docs/guides/development.md文档索引见 docs/。遇到复现的稳定问题欢迎到项目 Issue 区反馈。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考