# Cherry Studio Integration

> **Last verified**: 2026-09-18 · 📄 Per official docs (Cherry Studio v2.0.14, released 2026-09-09)

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ (Anthropic type) · GPT ✅ (OpenAI type) · Chinese models ✅ (OpenAI type) · Gemini ✅ (Gemini type, path-join not live-tested) |
| Protocol & Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai` · Gemini: `https://api.qcode.cc/gemini` (root URLs only — see below) |
| Where to configure | In-app: Settings → Model Services → "+ Add a provider" |
| Official docs | [Provider configuration](https://docs.cherryai.com.cn/) |

Cherry Studio is one of the most popular open-source desktop AI clients among Chinese-speaking users (Windows / macOS / Linux): chat, translation, knowledge bases and MCP in one window. **No account system, purely local configuration** — point it at any OpenAI / Anthropic compatible endpoint and go.

## Prerequisites

- Cherry Studio installed (the download page ships Global and CN builds, x64 / ARM64; minimum OS versions are not stated upstream — see the [download page](https://www.cherryai.com.cn/)). No Cherry Studio account and no model-vendor accounts are needed.
- A QCode.cc `cr_` key ([dashboard](https://qcode.cc/dashboard)).
- From mainland China, swap `api.qcode.cc` for `asia.qcode.cc` in everything below — identical capabilities.

## Setup

Open **Settings → Model Services**, click "**+ Add a provider**" below the list, and work in the "Add custom provider" dialog. The official rule: **the "API Host" field takes the root URL only — no `/v1`, no paths** — Cherry Studio appends the rest based on the type you picked (e.g. OpenAI type appends `/v1/chat/completions`); to disable the appending entirely, end the URL with `#`.

### Route A: Claude models (Anthropic type, recommended)

1. Pick type **Anthropic**.
2. API host: `https://api.qcode.cc/api`.
3. API key: your `cr_` key.
4. Add the model IDs you want (e.g. `claude-sonnet-5`) in the endpoint/model settings, or fetch the model list.
5. The official docs state the **Cherry Agent feature requires an Anthropic-protocol-capable endpoint** — if you want in-app agents, this is the route.

### Route B: GPT and Chinese models (OpenAI type)

1. Pick type **OpenAI**.
2. API host: `https://api.qcode.cc/openai` (Cherry builds `/openai/v1/chat/completions` from it).
3. API key: the same `cr_` key.
4. Model IDs: any GPT (e.g. `gpt-5.6`) or Chinese model (`glm-5.3`, `kimi-k3`, `deepseek-v4.1-flash`, `qwen3.8-max`, …) — current list at [qcode.cc/models](https://qcode.cc/models).

### The remaining types

- **OpenAI Responses**: same host `https://api.qcode.cc/openai`; note the QCode Responses leg serves **GPT models only** — no Claude, no Chinese models (matrix: [Endpoints and API paths](/docs/getting-started/endpoints-and-api-paths)).
- **Gemini**: API host `https://api.qcode.cc/gemini`; we have not verified the exact path Cherry appends for this type — on a 404, adjust using the root-URL + trailing `#` technique.

## Verify it works

Send one message to the new model in any chat tab, or use the in-app "fetch model list" (it hits `<api host>/models`). If nothing comes back: first check the type matches the model family (Claude needs the Anthropic type), then check you did not hand-write `/v1/...` into the host (it would double to `/v1/v1`). Still stuck? Follow the [troubleshooting guide](/docs/reference/troubleshooting); every request is visible at [probe.qcode.cc](https://probe.qcode.cc).

## Known limitations

- **Claude cannot use the OpenAI type**: the QCode OpenAI leg rejects Claude models outright (`model_not_available_on_endpoint`); use the Anthropic type.
- Do **not** paste full paths like `/v1/chat/completions` into the API host — appending is the default; the trailing `#` is the escape hatch.
- Cherry's own bilingual docs label the settings page both "Model Services" and "Model Provider" depending on version; the "fetch model list" button may read "sync models" in your build.
- Image generation / editing have their own Base URL fields; QCode's image model (`gpt-image-2`) is documented in [gpt-image-2 image generation and editing](/docs/usage/image-2) — Cherry-side behavior not verified here.
- The official docs domain recently moved (docs.cherry-ai.com now 301s to docs.cherryai.com.cn); old bookmarks will redirect.

## Related docs

- [Endpoints and API paths](/docs/getting-started/endpoints-and-api-paths)
- [Tool Compatibility Overview](/docs/ide/tool-compatibility)
- [Chinese Models](/docs/usage/cn-models)
- [Subscriptions vs API Keys vs QCode Keys](/docs/reference/subscription-vs-api-key)
- [Troubleshooting](/docs/reference/troubleshooting)