> ## 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

> How to connect the Cherry Studio desktop client to RuAPI

[Cherry Studio](https://cherry-ai.com) is an open-source cross-platform desktop AI client. It can hold configs for several LLM providers at once, supports a local knowledge base and agents, and connects to RuAPI through the **OpenAI-compatible** protocol.

## Prerequisites

<Steps>
  <Step title="RuAPI account + API key">
    Console → **Tokens** → create a `sk-...` key.
  </Step>
</Steps>

## Install Cherry Studio

Download from [cherry-ai.com](https://cherry-ai.com) or [GitHub Releases](https://github.com/CherryHQ/cherry-studio/releases/latest):

<Tabs>
  <Tab title="Windows">
    Download `Cherry-Studio-Setup-x.y.z.exe` and run the installer.
  </Tab>

  <Tab title="macOS">
    Download `Cherry-Studio-x.y.z-arm64.dmg` (Apple Silicon) or `Cherry-Studio-x.y.z-x64.dmg` (Intel) and drag to **Applications**.
  </Tab>

  <Tab title="Linux">
    Download `Cherry-Studio-x.y.z.AppImage`:

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

## Add RuAPI as a provider

<Steps>
  <Step title="Open Settings → Model Services">
    Once Cherry Studio is running, click the ⚙️ icon at the bottom-left → **Settings** → **Model Services** in the left panel.
  </Step>

  <Step title="Click 'Add'">
    Find the **+ Add** button at the bottom of the provider list.
  </Step>

  <Step title="Basic info">
    | Field             | Value      |
    | ----------------- | ---------- |
    | **Provider name** | `RuAPI`    |
    | **Provider type** | **OpenAI** |

    Click **OK**.
  </Step>

  <Step title="API key and base URL">
    In the RuAPI provider detail panel:

    | Field        | Value                  |
    | ------------ | ---------------------- |
    | **API key**  | `sk-your-key`          |
    | **API host** | `https://www.ruapi.ai` |

    <Note>
      Cherry Studio appends `/v1/chat/completions` automatically, so `https://www.ruapi.ai` is enough. `https://www.ruapi.ai/v1` usually works too (Cherry Studio dedupes).
    </Note>

    Toggle **Enable** on.
  </Step>

  <Step title="Add models">
    Below the same panel, click **+ Add Model** and enter model IDs:

    * `gpt-5.4`
    * `gpt-5.4-mini`
    * `claude-sonnet-5`
    * `claude-opus-4-8`
    * `claude-haiku-4-5-20251001`
    * `deepseek-v4-pro`
    * `gemini-2.5-pro`

    Full list at the [pricing page](https://www.ruapi.ai/pricing).

    <Tip>
      Click **Fetch Model List** and Cherry Studio will pull the full catalog via `/v1/models` and add them all.
    </Tip>
  </Step>
</Steps>

## First call

Back on the main screen, **New chat** in the top-left, click the model name in the top-right and pick **RuAPI → your model** (or any model you added). Send:

```
Introduce yourself in one English sentence.
```

A normal reply plus a matching RuAPI Console → **Logs** entry = success.

## Default model choices

**Settings → Default Models**:

* **Default assistant model**: everyday chat. Recommend `gpt-5.4` or Claude Sonnet.
* **Topic naming model**: auto-titles conversations. Recommend a cheap small model like Claude Haiku.
* **Translation model**: `gpt-5.4-mini` or Claude Haiku work well.

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 / authentication failed">
    * The API key must be a **RuAPI** token (`sk-...`), not an OpenAI key.
    * Watch for trailing whitespace.
    * Check the key in RuAPI Console → **Tokens**.
  </Accordion>

  <Accordion title="Model not found / 404">
    * Model ID typo. Hand-entered names must match RuAPI exactly — use **Fetch Model List** to autoload them.
    * Don't append `/chat/completions` to the API host — `https://www.ruapi.ai` is enough.
  </Accordion>

  <Accordion title="Streaming is choppy / slow">
    Streaming (SSE) is enabled by default on both sides. If it stutters:

    * Check network stability.
    * Try disabling streaming in settings to compare.
  </Accordion>

  <Accordion title="Function calling / tools don't work">
    Cherry Studio's MCP relies on model-level function calling. `gpt-5.4` and Claude Sonnet support it for compatible models — check the capability badges on the [pricing page](https://www.ruapi.ai/pricing).
  </Accordion>

  <Accordion title="Image input fails (vision)">
    Make sure the selected model supports vision. On RuAPI, vision-capable models include `gpt-5.4`, Claude Sonnet, Claude Opus, and Gemini Pro. Check the capability badges on the [pricing page](https://www.ruapi.ai/pricing).
  </Accordion>

  <Accordion title="Run RuAPI alongside other providers">
    Cherry Studio supports any number of providers. Add each one the same way. The model dropdown in the top-right of each chat switches between them.
  </Accordion>
</AccordionGroup>

## Advanced

* **Local knowledge base**: Cherry Studio's built-in RAG works with any embedding model — use `text-embedding-3-small` or `text-embedding-3-large` from RuAPI.
* **Agents**: Cherry Studio's agent system runs client-side and calls your configured provider. Claude Sonnet or `gpt-5.4` are solid agent backbones.
* **Multiple keys**: if one key isn't enough, create several with separate limits in the RuAPI Console and bind them to different Cherry Studio profiles.