Cherry Studio 怎么接小鱼API：地址、密钥、模型三步填完就能用

一、先填三条配置，Cherry Studio 就能对话

Cherry Studio 连小鱼API，真正要填的只有三个值：API 地址 https://xyuapi.top/v1、API 密钥（平台后台生成的 sk- 开头令牌）、模型名（照平台列表手动输入，一字不差）。三样填完点「检查」，通过后回到助手对话框，右上角选中模型就能开聊。

步骤一：设置 → 模型服务 → 添加提供方

点左下角齿轮进「设置」，左侧一栏选「模型服务」，页面底部有「添加提供方」。名称随手写，比如 小鱼API；类型选「OpenAI 兼容」（部分版本显示为「自定义」，选它也对）。类型决定了客户端往地址后面拼什么路径，选错会在检查连通性时报 404。

步骤二：API 地址填 `https://xyuapi.top/v1`

粘贴 https://xyuapi.top/v1，结尾带 /v1，结尾不要斜杠。Cherry Studio 会自己在后面补 /chat/completions，所以地址只要写到 /v1 这一层。写成 https://xyuapi.top/v1/v1 会拿到 404，因为实际请求变成了 /v1/v1/chat/completions。

步骤三：API 密钥填 `sk-` 令牌，切到「模型」分栏手动加模型

密钥框里粘 sk- 开头的令牌，注意别把空格或换行一起复制进去。令牌在平台后台生成，同一个令牌可以给多台设备、多个客户端同时用。填完先别关设置页，切到同一页面的「模型」分栏，把要用的模型名逐个加进去。

备用地址 `https://xyuai.cc/v1` 什么时候用

主地址是 https://xyuapi.top/v1。如果某条线路握手慢或者偶发超时，把地址换成 https://xyuai.cc/v1 再点一次检查，密钥和模型名都不用改。备用线路额外带 /v1beta/ 路径，那是给 Gemini 原生格式用的，走 OpenAI 兼容格式的 Cherry Studio 不需要碰它。

二、下载安装与配置备份

安装包怎么选

到 Cherry Studio 的发布页面下载对应系统的包：Windows 选 .exe，macOS 按芯片选 Intel 或 Apple Silicon 版，Linux 用 .AppImage。装完直接打开就能用，提供方配置全部存在本地，不依赖云端账户。

数据目录与配置备份

配置、话题记录、知识库索引都放在本地数据目录里，Windows 一般在 C:\Users\你的用户名\AppData\Roaming\CherryStudio。换机器前把整个目录复制走，或者用设置里的导出功能存一份配置。重装客户端之前先备份，能省掉重新手敲模型名的功夫。

三、添加提供方与地址写法的坑

多个提供方并存怎么摆

Cherry Studio 允许同时存在多个提供方，互不干扰：一个填 https://xyuapi.top/v1 跑主力模型，另一个填备用地址做兜底，还可以再留一个本地模型服务。每个提供方的密钥和模型清单各自独立，助手里的模型下拉框会把它们汇总到一起，靠名称前缀区分来源。

地址结尾要不要带 `/v1`

要带。https://xyuapi.top 这种写法看着干净，但客户端拼出来的路径会缺一段，请求直接 404。带上 /v1 之后，拼出来是 /v1/chat/completions，正好对上接口的真实路径。这是新装客户端时出现频率很高的一类问题。

地址结尾的斜杠

建议不带斜杠。有的客户端拼接逻辑是先补斜杠再加路径，地址写成 https://xyuapi.top/v1/，最终请求就是 https://xyuapi.top/v1//chat/completions，多出来一条斜杠，部分网关会直接返回 404 或者 400。写 https://xyuapi.top/v1，一行到底。

地址末尾加 `#` 是什么意思

Cherry Studio 支持在地址末尾加 #，含义是「按原样使用这个地址」，客户端不再自动追加任何路径。只有当你确实需要一个精确到端点的地址时才加它。普通用法不要加，加了之后客户端不补 /chat/completions，反而连不通。

代理设置要选「不使用代理」

设置里有网络代理相关的开关。如果客户端跟着系统代理走，请求可能根本出不去，表现为点「检查」一直转圈然后超时。把代理调成「不使用代理」或者直连，再点一次检查。只有在你确认本机代理链路能通到接口域名时，才保留代理。

四、模型名必须一字不差

模型要手动点「添加」才会出现在下拉框

这一步最容易被漏掉。新建提供方之后，「模型」分栏是空的，客户端不会自动拉取模型列表，必须在那一栏点「添加」，把模型名一个一个敲进去。加完它会出现在下面的列表里，还能单独设置显示名，比如把 claude-opus-4-5-thinking 显示成「Opus 干硬活」。没加过的模型，助手对话框的下拉框里根本找不到。

模型分组与命名备注

模型多了以后建议分组：日常组放 deepseek-v3.2-thinking 和 grok-4.1，重活组放 claude-opus-4-5-thinking，读图组放 gemini-2.5-pro。模型列表支持拖动排序和分组展示，显示名可以写中文方便记，但真正发出去的模型名必须还是平台列表里那串英文。

按次计费价格表

下面五行是平台当前的按次价格。模型名要原样复制，大小写和连字符都不能改，手输入时多一个字符就会报错。

模型名	价格
`gemini-2.5-pro`	0.031 元/次
`deepseek-v3.2-thinking`	0.049 元/次
`grok-4.1`	0.05 元/次
`claude-sonnet-4-5-thinking`	0.09 元/次
`claude-opus-4-5-thinking`	0.12 元/次

别自己加 `-latest` 之类的后缀

有人习惯在模型名后面补 -latest、-preview，或者把连字符写成下划线，结果直接 400 加 model not found。平台的模型名是固定字符串，照上表复制粘贴就行。粘完顺手检查一遍有没有带上尾部空格。

五、连通性测试、超时与报错对照

点「检查」按钮看什么

提供方页面右上角有「检查」按钮，它发一个体量很小的测试请求。连通成功会显示绿色的提示；失败会在弹窗里带 HTTP 状态码和一段英文报错。看状态码就能定位问题，比反复改地址高效得多。

超时时间调到 300 秒以上

带 thinking 的模型思考时间长，二十几秒到一分钟都算正常。客户端默认超时往往只有 60 秒甚至更短，长回答会被中途掐断，界面上显示成连接中断或者空回复。在提供方设置里把超时改到 300 秒以上，比如 600 秒，回答就不会再被腰斩。

报错对照表

报错	原因与处理
401	密钥不对：复制时带了空格、令牌被停用、或者填到了另一个提供方下面
403	令牌没有该模型的调用权限，或者请求命中了限制规则
404	地址写错：多写了 `/v1/v1`、漏了 `/v1`，或者结尾多了一条斜杠
429	请求太密，短时间内的调用频率超过限制，放慢节奏或降低并发
model not found	模型名拼错、加了多余后缀，或者压根没在「模型」里添加过

用命令行先验一遍

分不清是客户端的问题还是配置的问题，就先用 curl 打一次接口。命令行能通，说明问题出在客户端的某个填写项上。

curl https://xyuapi.top/v1/chat/completions -H "Authorization: Bearer sk-你的令牌" -H "Content-Type: application/json" -d '{"model":"deepseek-v3.2-thinking","messages":[{"role":"user","content":"你好"}]}'

请求体长什么样

接口格式是 OpenAI 兼容，参数名和 OpenAI 那边一致，客户端里能跑通的配置，换成脚本调用照样跑通。

{
  "model": "deepseek-v3.2-thinking",
  "messages": [
    {"role": "system", "content": "你是运维助手"},
    {"role": "user", "content": "说一下 404 和 401 的区别"}
  ],
  "temperature": 0.6,
  "max_tokens": 2048
}

六、助手、话题、知识库、划词助手

助手（Assistant）预设

助手是一套预设提示词加默认模型的组合。建议按用途建：一个「代码助手」挂 claude-sonnet-4-5-thinking，一个「长文助手」挂 grok-4.1，一个「读图助手」挂 gemini-2.5-pro。提示词在助手里写死，新建对话就不用每次重复交代背景。

默认助手与默认模型

设置里可以指定打开客户端后默认停在哪个助手、默认使用哪个模型。把日常用得多的那组设为默认，省掉每次切换的动作。默认模型建议挑按次价格低的那几个，免得随手一问就花掉一次贵模型的调用。

话题（Topic）管理

话题是同一个助手下面的多条独立对话，每个话题有自己的上下文，互相不串味。写代码开一个话题，写文案另开一个；长对话变慢或者模型开始跑偏时，新建话题比继续追问有效。话题支持改名和搜索，重要的及时改名，别一排都叫「新话题」。

知识库配置要点

知识库是把本地文档切片、做向量化，提问时再把相关片段塞给模型。上传前先把文档转成纯文本，扫描版要先做文字识别，否则切片出来全是空白。切片按段落来，一份文档切完能检索到具体章节就够，切得太碎检索时会丢上下文。

划词快捷助手

划词助手是选中一段文字后弹出的小窗口，在设置里绑定快捷键并指定一个专用助手。做翻译和润色时很顺手：选中英文，按快捷键，直接出中文。给它单独挂一个便宜的模型，日常划词就没有成本压力。

翻译场景怎么配

翻译要的是稳定和快，模型建议用 grok-4.1 或者 deepseek-v3.2-thinking，温度调到 0.2 到 0.3，提示词里写清「只输出译文，不要解释」。整篇文档翻译走助手窗口，选中段落翻译走划词助手，两种用法分开配置，别共用一个助手。

MCP 工具接入

Cherry Studio 支持 MCP，可以把文件操作、网页抓取这类工具挂给模型用。配置写在客户端的 MCP 设置里，一个服务一份配置，加完再到助手里勾选允许使用的工具。装完先在对话里让它读一个本地文件，确认工具真的被调用起来了，再去跑复杂任务。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:/work"]
    }
  }
}

七、参数、模型分工与成本估算

温度、上下文数、最大输出

温度控制随机性：写文案放到 0.8 到 1.0，写代码和翻译压到 0.2 到 0.4。上下文数决定带多少轮历史，带得越多越慢也越费，日常 10 轮够用。最大输出要设够，思考过程和正文都算在里面，设成 2048 时 thinking 模型容易只说一半就断。

便宜模型跑日常，贵模型干硬活

按次价格的差距有三倍多，用法上分清就能省下来。日常问答、摘要、翻译、划词交给 deepseek-v3.2-thinking 和 grok-4.1；架构设计、复杂重构、长链路推理再切到 claude-opus-4-5-thinking。同一个话题里临时切一次贵模型，问完再切回来，配置完全不受影响。

每千次调用大概多少钱

按上面的按次价格，一千次调用的花费可以直接算出来：

模型	单次	1000 次
`gemini-2.5-pro`	0.031 元	31 元
`deepseek-v3.2-thinking`	0.049 元	49 元
`grok-4.1`	0.05 元	50 元
`claude-sonnet-4-5-thinking`	0.09 元	90 元
`claude-opus-4-5-thinking`	0.12 元	120 元

把日常任务压在两个便宜模型上，一个月几千次调用的开销可以控制在一百元出头。充值在平台后台做，令牌额度实时可查，用掉多少心里有数。