canonical_url: https://yycode.net/docs/en/cherry-studio-quickstart
lang: en
updated_at: 2026-07-04T13:33:48.616Z
source_html: https://yycode.net/docs/en/cherry-studio-quickstart

# Dragon Code x Cherry Studio Quick Start Guide

## Applicable Scenario

This document solves one thing only: connect Cherry Studio to the Dragon Code gateway and complete one usability check.

---

## One-sentence Quick Start

You only need to fill in these 3 items:

- **Base URL**: `https://dragoncode.codes`
- **API Key**: the key you obtained from Dragon Code
- **Model ID**: for example `claude-opus-4-6`

Not sure what to fill in? Follow the steps below one by one.

---

## 1. Preparation

Before you begin, make sure:

- Cherry Studio is installed
- You have registered a [Dragon Code](https://dragoncode.codes) account
- You have obtained an API Key (in the form `sk-xxxx`)

### Create an API Key

Log in to the Dragon Code console. In the left sidebar, go to **API Keys** -> click **Create Key**.

- **Name**: anything is fine, such as `dragoncode`
- **Group**: choose according to the tool you want to use
  - Use **Codex** (OpenAI tool) -> choose the `codex` group
  - Use **Claude Code** (Anthropic tool) -> choose the corresponding Claude group
- Other fields can remain at their defaults
- Click Create

![Create key](https://r2.bozhouai.com/dragoncode-cherry-studio/page2_img1.png)

After creation, click the copy button in the list to get the full API Key.

![Copy API Key](https://r2.bozhouai.com/dragoncode-cherry-studio/page3_img1.png)

### How to Confirm the API Key Is Correct

- You can see this Key in the Dragon Code backend
- After copying, it is a complete string with no spaces or truncation

### Common Sticking Points

- No API Key -> cannot use the service
- One character missing when copied -> returns `401`
- Base URL written incorrectly -> returns `404` / `400`

---

## 2. Open Cherry Studio Settings

1. Open Cherry Studio
2. Click **Settings** in the bottom-left / top-right corner

![Cherry Studio settings entry](https://r2.bozhouai.com/dragoncode-cherry-studio/page4_img1.png)

---

## 3. Add the Dragon Code Provider

1. Click **+ Add** in model services

   ![Add provider entry](https://r2.bozhouai.com/dragoncode-cherry-studio/page5_img1.png)

   The provider name can be anything, for example `dragoncode`.

   ![Enter provider name](https://r2.bozhouai.com/dragoncode-cherry-studio/page5_img2.png)

2. Select provider type

   Cherry Studio supports both **OpenAI** and **Anthropic** provider types. Choose according to the model family you want to use.

   ![Select provider type](https://r2.bozhouai.com/dragoncode-cherry-studio/page6_img1.png)

3. Fill in the API Key and API address (the screenshot below uses OpenAI as an example)

   - **API Key**: the API Key you created in Dragon Code
   - **API Address**: `https://dragoncode.codes`

   ![Fill in API key and address](https://r2.bozhouai.com/dragoncode-cherry-studio/page7_img1.png)

   > **Note**: The API Key must match the group. The OpenAI type can only use a Key created under the `codex` group, and the Anthropic type can only use a Key created under a Claude group.

4. Add models (OpenAI and Anthropic types require their respectively supported model IDs)

---

## Supported Models

### OpenAI-compatible Models

| Model name |
|---|
| `gpt-5.4` |
| `gpt-5.2` |
| `gpt-5.3-codex` |

### Anthropic-compatible Models

| Model name |
|---|
| `claude-opus-4-6` |
| `claude-sonnet-4-6` |

> The model ID must be **exactly the same** as the one supported by Dragon Code. Case and hyphens must match.

### Add a Model

![Add model](https://r2.bozhouai.com/dragoncode-cherry-studio/page8_img1.png)

After adding it, click **Check**. When it reports success, proceed to the next step.

![Check model](https://r2.bozhouai.com/dragoncode-cherry-studio/page9_img1.png)

---

## 4. Start Chatting (Verify Access)

1. Create a new chat
2. Select the model you just added

   ![Select model](https://r2.bozhouai.com/dragoncode-cherry-studio/page10_img1.png)

3. Enter: `你好`

### Success Indicator

If the model replies normally, the connection is successful.

![Successful chat](https://r2.bozhouai.com/dragoncode-cherry-studio/page11_img1.png)

If there is no reply or an error appears, refer to the troubleshooting table below.

---

## 5. Error Troubleshooting

Match the error you see with the corresponding item below.

### 503 Service temporarily unavailable

- **Meaning**: The current model route is unavailable or too congested
- **Solution**: Retry, or switch to another model (recommended)

### 502 Bad gateway

- **Meaning**: Dragon Code failed to connect to upstream Claude / GPT
- **Solution**: Wait 1-2 minutes and try again, or switch models

### AI_RetryError

- **Meaning**: Automatic retry failed after 3 attempts (usually a 502 / 503 underneath)
- **Solution**: Same as above: switch models or retry later

### 401 / 403

- **Meaning**: API Key is wrong or does not match the group
- **Solution**: Copy the Key again and confirm that the provider type matches the Key group

### 400

- **Meaning**: Model ID or URL is wrong
- **Solution**: Check
  - Whether the API address is `https://dragoncode.codes`
  - Whether the model ID is in the [Supported Models](#supported-models) list

### Keeps Spinning / Stuck

- **Meaning**: Network, streaming connection, or model exception
- **Solution**: Start a new chat, restart Cherry Studio, or switch model/group

---

## 6. One-minute Self-check

90% of issues are in this table.

| Item | Correct value |
|---|---|
| Base URL | `https://dragoncode.codes` |
| API Key | `sk-xxxx` (complete, no spaces) |
| Model ID | Must be in the supported list |
| Group and type | OpenAI <-> `codex` group; Anthropic <-> Claude group |