> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cherry Studio

> 如何把 Cherry Studio 桌面客户端对接 RuAPI

[Cherry Studio](https://cherry-ai.com) 是一个开源跨平台 AI 桌面客户端，支持同时配置多家 LLM 服务商、本地知识库、Agent 等功能。RuAPI 通过 **OpenAI 兼容** 协议接入。

## 前置条件

<Steps>
  <Step title="RuAPI 账号 + API key">
    控制台 → **令牌** 创建一把 `sk-...`。
  </Step>
</Steps>

## 安装 Cherry Studio

到 [cherry-ai.com](https://cherry-ai.com) 或 [GitHub Releases](https://github.com/CherryHQ/cherry-studio/releases/latest) 下载：

<Tabs>
  <Tab title="Windows">
    下载 `Cherry-Studio-Setup-x.y.z.exe` → 双击安装。
  </Tab>

  <Tab title="macOS">
    下载 `Cherry-Studio-x.y.z-arm64.dmg`（Apple Silicon）或 `Cherry-Studio-x.y.z-x64.dmg`（Intel）→ 拖到 **应用程序**。
  </Tab>

  <Tab title="Linux">
    下载 `Cherry-Studio-x.y.z.AppImage`：

    ```bash theme={null}
    chmod +x Cherry-Studio-*.AppImage
    ./Cherry-Studio-*.AppImage
    ```
  </Tab>
</Tabs>

## 添加 RuAPI 服务商

<Steps>
  <Step title="打开『设置 → 模型服务』">
    Cherry Studio 启动后，左下角点 ⚙️ 齿轮图标 → 进入 **设置** → 左侧选 **模型服务**。
  </Step>

  <Step title="点『添加』按钮">
    在 "模型服务" 列表底部点 **+ 添加** 按钮。
  </Step>

  <Step title="填基础信息">
    | 字段        | 填什么        |
    | --------- | ---------- |
    | **提供商名称** | `RuAPI`    |
    | **提供商类型** | **OpenAI** |

    点 **确定**。
  </Step>

  <Step title="填 API key 和地址">
    在 RuAPI 这条记录的详情面板里：

    | 字段         | 填什么                    |
    | ---------- | ---------------------- |
    | **API 密钥** | `sk-你的KEY`             |
    | **API 地址** | `https://www.ruapi.ai` |

    <Note>
      Cherry Studio 会自动给地址后面拼 `/v1/chat/completions`，所以填 `https://www.ruapi.ai` 即可。如果填了 `https://www.ruapi.ai/v1`，Cherry Studio 一般也兼容（会自动去重）。
    </Note>

    打开 **启用** 开关。
  </Step>

  <Step title="添加模型">
    在同一面板下方点 **+ 添加模型**，输入模型 ID，常用系列：

    * GPT 系列
    * Claude 系列（Sonnet / Opus / Haiku）
    * DeepSeek 系列
    * Gemini 系列

    具体可用名以价格页面为准，完整列表在 [价格页面](https://www.ruapi.ai/pricing)。

    <Tip>
      也可以点 **获取模型列表** 按钮，Cherry Studio 会调用 RuAPI 的 `/v1/models` 拉一份完整列表，自动填进来。
    </Tip>
  </Step>
</Steps>

## 第一次验证

回到主界面，左上角 **新建对话**，右上角点模型名 → 选 **RuAPI → 你刚添加的任意模型**，发送：

```
用一句中文介绍你自己
```

正常拿到回复 + RuAPI 控制台 → **日志** 有对应调用 = 成功。

## 设置默认模型

**设置 → 默认模型**：

* **默认助手模型**：日常聊天用的，建议用 GPT 或 Claude Sonnet 系列。
* **话题命名模型**：自动给对话起标题用的，建议用 Claude Haiku 这种便宜的小模型。
* **翻译模型**：建议用便宜的小模型（如 GPT mini 或 Claude Haiku）。

## 常见问题

<AccordionGroup>
  <Accordion title="提示 401 / 鉴权失败">
    * API 密钥填的应该是 **RuAPI** 令牌（`sk-...`），不是 OpenAI 官方 key。
    * 复制时小心末尾空格。
    * 控制台 → **令牌** 看 key 状态。
  </Accordion>

  <Accordion title="提示模型不存在 / 404">
    * 模型 ID 拼写。Cherry Studio 里手动填的模型名必须和 RuAPI 上的完全一致，建议用 **获取模型列表** 按钮自动拉。
    * API 地址末尾 **不要** 加 `/chat/completions`，只填到 `https://www.ruapi.ai` 即可。
  </Accordion>

  <Accordion title="流式输出卡顿 / 不流畅">
    Cherry Studio 默认开启流式（SSE），RuAPI 默认也支持。如果遇到卡顿：

    * 检查网络稳定性。
    * 设置里关掉 "流式输出" 试试，对比一下。
  </Accordion>

  <Accordion title="函数调用 / 工具调用不生效">
    Cherry Studio 的 MCP 功能依赖模型支持 function calling。主流 GPT、Claude 系列在兼容的模型上支持这一能力——以[价格页](https://www.ruapi.ai/pricing)上的能力标签为准，再按 Cherry Studio 内置的 MCP 设置走即可。
  </Accordion>

  <Accordion title="多模态（图片）输入失败">
    确认选的模型支持视觉。RuAPI 上支持视觉的常用系列：GPT、Claude（Sonnet / Opus）、Gemini。具体看 [价格页面](https://www.ruapi.ai/pricing) 模型卡片上的能力标签。
  </Accordion>

  <Accordion title="想同时挂 RuAPI + 其他服务商">
    Cherry Studio 支持任意多个服务商并存。重复上面的添加流程即可。聊天时右上角切换模型自动切服务商。
  </Accordion>
</AccordionGroup>

## 进阶

* **本地知识库**：Cherry Studio 内置 RAG，把文档拖进来就能问答，embedding 模型可以也用 RuAPI 上的 `text-embedding-3-small`、`text-embedding-3-large` 等。
* **Agent / 智能体**：Cherry Studio 的 Agent 功能完全在客户端跑，调用模型走配好的服务商。建议给 Agent 配 Claude Sonnet 或 GPT 系列。
* **多账户**：如果一把 key 不够分，可以在 RuAPI 控制台多建几把 key 各自限额，给不同的 Cherry Studio profile 用。