Cherry Studio With Claude / GPT: Step-by-Step Setup and Error Guide (2026)
Add one custom provider in Cherry Studio and call Claude / GPT / Gemini with CNY top-up. Step-by-step config, one-click model fetch, and a failure checklist.
1. What Cherry Studio is
Setting this straight avoids disappointment: Cherry Studio provides no models; it is a shell — a desktop chat client handling the interface, sessions and prompt management, while model capability comes from an API you connect. So 'how do I use Claude in Cherry Studio' really means 'where do I get an API that reaches Claude, and how do I enter it'. Its strengths: conversations stored on your own machine, a pleasant interface, several providers side by side with instant switching. Its role is chat, not coding — daily writing, Q&A, organizing material. For code completion or API calls inside a project, use a coding tool or the SDK; do not expect it to replace those.
2. Get a working API (the route from China)
The API must meet two conditions: OpenAI-compatible (Cherry Studio integrates on that standard) and fundable from China. The official route usually sticks at card binding — an overseas card that passes risk controls, and Chinese-issued cards are often declined. The easier path is a compatible relay with CNY top-up: with cocodot, sign up, small Alipay top-up (no free allowance; balance must exceed 0 to call), accept the terms in the AI API console and create a key — minutes to obtain the two things you need: the endpoint and the key. Start tiny, prove the whole pipeline, then add — far safer than a large first top-up.
3. Step-by-step (just two fields)
Open Cherry Studio, go to Settings → Model Providers, add a provider of the OpenAI-compatible type, and fill two fields: ① API address: `https://cocodot.co/api/ai/v1` — the trailing `/v1` is mandatory; omitting it is the most frequent failure; ② API key: the key from your console. Save. A common misconception: some enter the full `/chat/completions` path — do not; the client appends the specific path after `/v1`, so supply only the `/v1` level. After saving, do not chat yet — fetch the model list first.
4. Do not type models; let it fetch them
This step saves effort and errors. Once the provider is configured, the panel usually has a 'Fetch models' / 'Get model list' button; click it and the client requests the server's standard model-list endpoint and pulls in every available model for you to tick. Two advantages over typing IDs: no typos (codes are short, meaningless strings that are easy to mistype), and you only see currently listed models, never retired ones. To preview the catalog, the list endpoint is public and needs no key — check it in a browser or terminal: ```bash curl https://cocodot.co/api/ai/v1/models ``` If fetching fails, it is usually the address or key — recheck those two fields.
5. When it will not connect, check in this order
Do not guess; check four items in order. ① Does the address end in `/v1`? — this alone fixes most 'cannot connect' and 404 cases; ② is the key right? — 401 / authentication failure almost always means the key; re-copy from the console and watch for stray spaces; ③ is the balance 0? — no free allowance, so a zero balance fails outright regardless of config; ④ is the model code right? — on 'model does not exist', refetch the list per the previous section instead of using a typed code. Slow responses or timeouts are a separate case: models are slower than ordinary web requests, especially on long answers; extend the client timeout if there is a setting.
6. One balance, switch models at will
Once connected, a very practical habit: several models under one provider, switched mid-conversation. They share one interface, one key and one balance, so you need not open accounts at each vendor. A typical rhythm: a comfortable mid-tier model for daily Q&A and writing, a flagship when a question needs careful reasoning or long documents, and a cheap small model for formatting, translation and classification. Switching model by task is the most direct saving — much spend comes from using the priciest model for every question. Switching costs nothing; make it a habit.
7. A few usage reminders
① Local conversation storage is a strength but means you migrate it yourself when changing machines — export important sessions. ② The key equals your balance; never post a settings screenshot with the key in a group or forum — redact first. ③ Separate keys for separate uses, so revoking one does not affect the others. ④ Prove the pipeline small before adding funds: after the first successful call, confirm normal billing in the console. ⑤ For API calls in code or coding assistance, do not route through a chat client — use the OpenAI SDK with `base_url` and `api_key`; same address, same key.
Fields and what to check first when it fails
| Field | Value | Symptom if wrong |
|---|---|---|
| Provider type | The OpenAI-compatible type | Wrong type → request format mismatch |
| API address | https://cocodot.co/api/ai/v1 | Missing /v1 → cannot connect / 404 |
| API key | The key created in the console | Wrong → 401 authentication failure |
| Model list | Click 'Fetch models' to pull automatically | Hand-typed codes get misspelled or retired |
| Balance | Small Alipay top-up first | Balance 0 → calls fail outright (no free allowance) |