Cherry Studio Integration

Add QCode.cc as a custom provider in Cherry Studio: the Settings-to-Model-Services path, what URL each of the four provider types needs, and why the Agent feature wants an Anthropic-type endpoint

Need an API key? Sign up →·Endpoints & base URLs →

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

At a glance¶

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 by the vendor — see the download page). No Cherry Studio account and no model-vendor accounts are needed.
• A QCode.cc cr_ key (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-sol) or Chinese model (glm-5.3, kimi-k3, deepseek-v4.1-flash, qwen3.8-max, …) — current list at qcode.cc/models.

The remaining types¶

• OpenAI Responses: same host https://api.qcode.cc/openai; note the QCode Responses endpoint serves GPT models only — no Claude, no Chinese models (matrix: Endpoints and API paths).
• Gemini (QCode does not offer Gemini for now; this entry only describes Cherry's type): 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; every request is visible at probe.qcode.cc.

Known limitations¶

• Claude cannot use the OpenAI type: the QCode OpenAI endpoint 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 — 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.

Provider types and QCode addresses¶

As of 2026-10-15, according to the "provider types" section of the Cherry Studio documentation: the OpenAI-compatible type uses /v1/chat/completions, the Anthropic-compatible type uses /v1/messages, and Cherry Agent requires the Anthropic type; a custom provider can connect any OpenAI / Anthropic / Gemini compatible endpoint. Mapped to QCode:

In mainland China replace api.qcode.cc with asia.qcode.cc.

Key settings explained¶

Common errors and how to troubleshoot¶

If you still cannot tell, enter your key at probe.qcode.cc to see whether requests reach QCode, then continue with Troubleshooting.

FAQ¶

Do I need a Cherry Studio account?¶

No. It is a purely local-configuration client: enter the QCode address and key and you are ready.

Why create two providers for one key?¶

Because Claude only works through the Anthropic interface while GPT and Chinese models use the OpenAI interface, and a Cherry Studio provider can have only one type. Both providers use the same cr_ key; only address and type differ.

How do I set up the in-app Agent feature?¶

Per the official documentation Cherry Agent needs a provider of Anthropic type: choose Anthropic, set the API address to https://api.qcode.cc/api, and add Claude models.

When do I need a # at the end of the API address?¶

Only when a service requires a fixed full path and you do not want Cherry Studio to append one by type. For normal QCode use, enter just the root address from the mapping table above; no # is needed.

Can I use Gemini through Cherry Studio?¶

QCode does not currently offer Gemini models. Please use Claude, GPT or Chinese models instead.

Related docs¶

• Endpoints and API paths
• Tool Compatibility Overview
• Chinese Models
• Subscriptions vs API Keys vs QCode Keys
• Troubleshooting
• LobeChat Setup — another desktop/cloud client; the address belongs in the Proxy URL field under App Settings → AI Providers

Enterprise →