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

Last verified: 2026-09-18 · 📄 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 upstream — 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) 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 leg serves GPT models only — no Claude, no Chinese models (matrix: 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; every request is visible at 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 — 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
• Tool Compatibility Overview
• Chinese Models
• Subscriptions vs API Keys vs QCode Keys
• Troubleshooting