Cherry Studio Guide (2026): Download, Add a Custom API Provider and Fix Common Errors

This guide covers v2.1.6, the current release as of October 15, 2026. The URL rules described below come from reading Cherry Studio's own source code at that release, because that's where most "it doesn't connect" problems start.

What Cherry Studio is (and what it isn't)

Cherry Studio is a client, not a model provider. It gives you a polished chat interface with assistants, multi-model conversations, a knowledge base, MCP tools, translation and image generation, and you bring the models. You can connect several providers at once and switch per conversation.

• License: AGPL-3.0 for the free Community Edition. A paid Enterprise Edition adds private deployment and admin controls.
• Free models: the built-in CherryAI provider serves a rotating set of free models. Cherry's docs say the list changes, so fetch it in the app to see what's current.
• Mobile: Cherry Studio Mobile (iOS and Android) is a separate app.
• Your data stays local: chats, settings and keys live in the app's data folder on your machine. Requests go straight to whichever provider you choose.

V1 or V2?

Cherry Studio 2.0 changed the data format and reorganized several features. If you're on 1.x, don't just install over it:

1. Update V1 to 1.9.13 and start it once.
2. Turn off "lite backup" and make a full backup, then fully quit the app and copy the whole data folder somewhere safe.
3. Install V2.0.2 or later. It migrates V1 data directly.

Migration is one-way: new V2 data never syncs back to V1, and V1 and V2 backups can't be restored into each other. After upgrading, recheck your providers and default models. Anthropic OAuth logins don't migrate, so re-enter an API key, and new providers start switched off. Don't click Re-migrate in Settings → Data unless the first migration failed, because it deletes your current V2 data.

Download and install

The Windows installer fetches the Microsoft Visual C++ runtime if it's missing. On macOS, if Gatekeeper blocks the first launch, confirm the file came from an official source and allow it under System Settings → Privacy & Security. For an AppImage, run chmod +x on the file first.

Add a provider

Built-in providers

Cherry Studio ships with presets for OpenAI, Anthropic, Google Gemini, DeepSeek, Mistral, Groq, OpenRouter, Ollama, LM Studio and many more. Open Settings → Model Provider, pick one, paste your API key, switch the provider on (top-right toggle), and click Get model list.

A custom provider (any compatible API)

For a service that isn't in the list, such as a company gateway, a self-hosted model or an API aggregator:

1. Settings → Model Provider → + Add Provider opens Add Custom Provider.
2. Provider Name: anything you'll recognize.
3. API Key: the key from that service.
4. Endpoint settings: Cherry Studio 2 lets one provider expose several API formats. OpenAI and Anthropic fields are shown by default. More options adds OpenAI Responses, Gemini, and image generation/editing URLs. Fill in only the formats the service supports. Under each field, Cherry Studio shows the request path it will actually call. Check it before saving.
5. Click Add, then switch the provider on. New providers start disabled.
6. Models: click Get model list to pull models from the service's /v1/models, or click + and type a Model ID exactly as the service names it. For each model you can set an Endpoint type (OpenAI, OpenAI-Response, Anthropic, Gemini), which decides which of your configured formats it uses.
7. Go to Settings → Default Model and pick a model from this provider, or pick it from the model menu in a chat.

The Check button sends real requests to the selected models, which may cost a little. It's still the fastest way to confirm the key and URL work.

Get the API URL right

This is where most connection problems come from. In v2.1.6 (and 1.9.x), Cherry Studio builds the final URL like this:

The rules:

• No version in the URL? Cherry Studio appends /v1, or /v1beta for Gemini.
• Already has a version (/v1, /v2, /v1beta…)? It leaves the URL alone.
• Ends with #? It uses your URL as-is. The app's own tip says the same: "Add # at the end to disable the automatically appended API version." Use this for services whose path has no version segment and must not get /v1 added.
• Never paste the full endpoint (…/chat/completions). Cherry Studio adds that part itself.

Older tutorials say a trailing / stops Cherry Studio from adding /v1. That isn't true in current versions: the slash is stripped and /v1 is added anyway.

Example: an API gateway

With api.foo, the gateway that publishes these docs, one custom provider can cover GPT, Claude and Gemini models:

Then give Claude models the Anthropic endpoint type, Gemini models Gemini, and the rest OpenAI. Claude then talks to Anthropic's native Messages API instead of going through an OpenAI-format translation, which keeps Claude-specific features such as extended thinking. We checked the resulting paths against api.foo with a test key: /v1/chat/completions, /v1/messages and /v1/models all reach the gateway, and a mistyped double path returns a clear 404 (see below).

Knowledge base in one paragraph

Knowledge Base in the left sidebar lets you add files, notes, folders or web pages, then attach the knowledge base to a chat or agent. In v2 you don't need an embedding model to start: without one, Cherry Studio uses keyword (BM25) retrieval, and adding an embedding model switches it to hybrid keyword-plus-semantic search. Use recall test to check that the right passages come back before relying on answers.

Fix common problems

The key is saved, but chats fail

Work through the checklist from Cherry Studio's own FAQ: the provider is switched on, the API URL is right (check the request-path preview), and Settings → Default Model points to a model this provider actually serves. Behind a corporate proxy, also check Cherry Studio's network proxy settings.

401 / invalid token / invalid API key

The service rejected the key. Re-copy it, watching for spaces, and make sure it belongs to this service and not another provider. Some gateways return their own wording. api.foo, for example, says 无效的令牌 ("invalid token").

404 with a doubled path

{"error":{"message":"Invalid URL (POST /v1/chat/completions/chat/completions)","type":"invalid_request_error"}}

You pasted a full endpoint into the URL field. Cut it back to the base (https://api.example.com or …/v1).

The model I want isn't in the list

Click Get model list again, or add it manually with + and the exact Model ID. Different screens filter by capability. Agents, image generation and embeddings each show only suitable models, so a chat model won't appear in the embedding picker.

"Check" passes but a specific model fails

Check only tests the models you selected. Confirm the failing model's Endpoint type matches what the service supports for it. A Claude model set to Gemini, for example, will fail.

Related

• Install Claude Code
• Claude API pricing
• OpenAI API pricing