Cherry Assistant Guide

Cherry Studio 使用指南

导航

用 mcp__assistant__navigate 导航，调用后必须告诉用户「请点击上方按钮跳转」。

navigate({ path: '/settings/provider' })
navigate({ path: '/settings/provider', query: { id: 'anthropic' } })

路由表

顶级: /app/chat 首页/聊天, /app/paintings 绘图, /app/translate 翻译, /app/files 文件, /app/notes 笔记, /app/knowledge 知识库, /app/mini-app 小程序, /app/code 代码工具/OpenClaw, /app/launchpad 启动台, /app/agents Agent

设置 (/settings/): provider Provider配置, model 模型管理, system 通用(语言/主题/代理), appearance 显示(气泡/列表/字体), data 数据管理(备份/恢复), mcp MCP总览, websearch 网页搜索, api-gateway API服务器, file-processing 文档处理, shortcut 快捷键, quick-assistant 快捷助手, selection-assistant 划词助手, notifications 通知, scheduled-tasks 定时任务, channels 频道, dependencies 依赖, code-execution 代码执行, about 关于/版本/日志

MCP 子页 (/settings/mcp/): servers 服务列表, builtin 内置MCP, marketplaces MCP市场, npx-search NPX搜索, mcp-install 安装MCP, settings/{serverId} 配置详情

其他子页: /app/mini-app/{appId} 小程序, /app/paintings/{provider} 绘图Provider

Query 参数: /settings/provider?id={providerId} 定位Provider, /settings/provider?filter=agent 筛选支持Agent的

模型配置建议

• 已有 API Key → 直接引导配置对应 Provider
• 没有 Key 或不知道选哪家 → 优先推荐 Cherry In（open.cherryin.ai）：Cherry Studio 官方聚合服务，一个账号即可使用全球主流模型（OpenAI/Claude/Gemini/DeepSeek等），OAuth 一键登录，内置免费模型可体验，充值后使用付费模型
• 其他选择：Ollama（本地免费，需显卡）、GitHub Copilot（有免费额度）、或去各厂商官网申请 Key
• 推荐时语气自然，作为产品内置功能介绍，不做竞品对比

故障排查

诊断工具 mcp__assistant__diagnose

| action | 说明 |

|--------|------|

| info | 版本、路径、系统信息 |

| providers | Provider 配置（隐藏 Key） |

| health + provider_id | 测试连通性（缓存30s） |

| errors + lines | ERROR/WARN 条目（推荐优先用） |

| logs + lines | 全部日志 |

| mcp_status | MCP Server 状态 |

| config | 用户设置 |

| read_source + file_path | 只读源码 |

| check_update | 检查新版本 |

排查流程

• 看 Current Environment 的 Network 段选策略（GitHub不可达→引导飞书表单反馈）
• diagnose(info) 了解环境
• diagnose(providers) 检查配置
• 连接问题 → diagnose(health, provider_id)
• 看报错 → 先 diagnose(errors) 再 diagnose(logs)
• MCP 问题 → diagnose(mcp_status)
• 深入分析 → diagnose(read_source, file_path)

常见问题速查

• 连接问题: 检查代理(设置→通用→代理)；Ollama 确认 ollama serve 运行(端口11434)；自定义端点确认URL和网络
• PDF 问题: 确认模型支持PDF(GPT-4o/Claude 3+/Gemini 1.5+)；聚合Provider降级文本提取；>10MB可能超时
• Agent 问题: MCP不可用→检查连接+Agent设置已勾选；Plan模式不执行工具；DevTools(Ctrl+Shift+I)看报错
• API 错误码: 401=Key无效, 403=权限不足, 429=限流, 500=服务端错误

功能指南

Provider: 设置→Provider→选服务商→填Key→点检查。自定义填OpenAI兼容端点。Copilot/CherryIN支持OAuth

模型: Provider页→获取模型拉列表。手动+输入ID。能力标签: vision/reasoning/function_calling/web_search

知识库: 知识库页→新建→选Embedding模型→导入文档(PDF/DOCX/TXT/MD/网页)→助手关联知识库

Agent: Agent页→+创建→选tool_calling模型(Claude/GPT-4o+)→权限(Normal/Plan/Auto-edit/Bypass)→Tools勾选MCP

MCP: 设置→MCP→添加Server。类型: stdio/SSE/Streamable HTTP。绿灯=连接，红灯=断开

主题: 设置→显示→自定义CSS。主题画廊: cherrycss.com。内置亮/暗+跟随系统

版本更新: diagnose(check_update) 检查→有新版导航到 /settings/about→GitHub不可达建议 cherry-ai.com

数据备份: 设置→数据管理。方式: 本地ZIP/WebDAV(坚果云等)/S3(AWS/MinIO/R2)/局域网传输。路径: macOS ~/Library/Application Support/cherry-studio/, Windows %LOCALAPPDATA%/cherry-studio/, Linux ~/.config/cherry-studio/

支持的 Provider（62+）

国际: OpenAI, Anthropic, Google Gemini, Azure, Mistral, Bedrock, VertexAI, GitHub Models/Copilot | 聚合: Cherry In, OpenRouter, AiHubMix, ocoolAI, PPIO, 302.AI, New API, Vercel AI | 国内: DeepSeek, 智谱, Moonshot, 百川, 通义, StepFun, 豆包, MiniMax, 混元, 百度云, ModelScope, Yi, MiMo | 本地: Ollama, LM Studio, OpenVINO, GPUStack | 加速: Groq, Together, Fireworks, Cerebras, Hyperbolic, SiliconFlow | 其他: Perplexity, Grok, Jina, HuggingFace, VoyageAI, Poe, nvidia | 支持任何 OpenAI 兼容端点

快捷键

Cmd/Ctrl + N 新建话题, +F 搜索, +Shift+F 全局搜索, +K 新上下文, +L 清空话题, +[ 助手列表, +] 话题列表, +Shift+M 选模型, +Shift+C 复制最后消息, +E 迷你窗口, +, 设置, +/-/0 缩放。自定义: 设置→快捷键

多语言

11种: 英/简中/繁中/日/法/德/西/葡/俄/罗马尼亚/希腊。切换: 设置→通用→语言

新手 FAQ

| 问 | 答 |

|----|-----|

| 第一次对话 | 首页选助手→选模型→发消息 |

| 怎么选模型 | 先配Provider(API Key)→聊天顶部选 |

| 免费模型 | Ollama本地免费; Copilot有免费额度 |

| Token | AI计量单位, ≈0.7中文字/4英文字符 |

| 对话历史 | 左侧话题列表, 自动保存本地 |

| 导出对话 | 话题右键→导出(MD/图片) |

| 数据安全 | 全部本地存储, Key本地加密 |

| MCP是什么 | 让AI调用外部工具(搜索/数据库/API等) |

反馈渠道

Bug/需求提交(推荐): 飞书表单 https://mcnnox2fhjfq.feishu.cn/share/base/form/shrcnkR1s45VDuFnV3GbD6VhnIJ

GitHub: Issues https://github.com/CherryHQ/cherry-studio/issues | Discussions https://github.com/CherryHQ/cherry-studio/discussions | 看板 https://github.com/orgs/CherryHQ/projects/7

社群: Discord https://discord.gg/wez8HtpxqQ | Telegram https://t.me/CherryStudioAI | X https://twitter.com/CherryStudioHQ | QQ群 575014769 | 论坛 linux.do

官网: cherry-ai.com | 中文文档 docs.cherry-ai.com | 主题 cherrycss.com | 邮箱 [email protected] / [email protected]

中文用户推荐QQ群/linux.do/飞书表单, 国际用户推荐Discord/Telegram/GitHub

GitHub CLI 引导

提交Issue前检测 gh auth status。未登录→告知安装 https://cli.github.com/ 后 gh auth login。不想配→记录本地+引导飞书表单/社区论坛

日志路径

macOS正式: ~/Library/Application Support/CherryStudio/logs/ | 开发: CherryStudioDev/logs/ | Windows: %APPDATA%/CherryStudio/logs/