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

# Dragon Code × Cherry Studio 快速開始指南

## 適用場景

這篇指南只解決一件事：把 Cherry Studio 接到 Dragon Code 中轉站，並完成一次可用性驗證。

---

## 一句話快速開始

只需要填這 3 項就能用：

- **Base URL**：`https://dragoncode.codes`
- **API Key**：你在 Dragon Code 取得的 key
- **模型 ID**：例如 `claude-opus-4-6`

不會填？按下面的步驟一步一步來。

---

## 1. 準備工作

在開始前，請確認：

- 已安裝 Cherry Studio
- 已註冊 [Dragon Code](https://dragoncode.codes) 帳號
- 已取得 API Key（形如 `sk-xxxx`）

### 建立 API 金鑰

登入 Dragon Code 控制台，左側欄進入 **API 金鑰** → 點選 **建立金鑰**。

- **名稱**：可以隨便填，比如 `dragoncode`
- **分組**：根據你要使用的工具選擇
  - 使用 **Codex**（OpenAI 工具）→ 選 `codex` 分組
  - 使用 **Claude Code**（Anthropic 工具）→ 選 Claude 對應分組
- 其他欄位可保持預設
- 點選建立

![建立金鑰](https://r2.bozhouai.com/dragoncode-cherry-studio/page2_img1.png)

建立完成後，在清單中點選複製按鈕拿到完整的 API Key。

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

### 如何確認 API Key 正確

- 能在 Dragon Code 後台看到該 Key
- 複製後是完整的一串字元，沒有空格或截斷

### 常見卡點

- 沒有 API Key → 無法使用
- 複製少一位 → 會報 `401`
- Base URL 寫錯 → 會報 `404` / `400`

---

## 2. 打開 Cherry Studio 設置

1. 打開 Cherry Studio
2. 點選左下角/右上角 **設置**

![Cherry Studio 設置入口](https://r2.bozhouai.com/dragoncode-cherry-studio/page4_img1.png)

---

## 3. 新增 Dragon Code 提供商

1. 在模型服務中點選 **+ 新增**

   ![新增提供商入口](https://r2.bozhouai.com/dragoncode-cherry-studio/page5_img1.png)

   提供商名稱可以隨便填，例如 `dragoncode`。

   ![填寫提供商名稱](https://r2.bozhouai.com/dragoncode-cherry-studio/page5_img2.png)

2. 選擇提供商類型

   Cherry Studio 支援 **OpenAI** 和 **Anthropic** 兩種類型，按你要用的模型系列選擇。

   ![選擇提供商類型](https://r2.bozhouai.com/dragoncode-cherry-studio/page6_img1.png)

3. 填寫 API 金鑰和 API 地址（下圖以 OpenAI 為例）

   - **API 金鑰**：你在 Dragon Code 建立的 API Key
   - **API 地址**：`https://dragoncode.codes`

   ![填寫 API 金鑰和地址](https://r2.bozhouai.com/dragoncode-cherry-studio/page7_img1.png)

   > **注意**：API Key 要和分組匹配 —— OpenAI 類型只能選 `codex` 分組建立的 Key，Anthropic 類型只能選 Claude 分組建立的 Key。

4. 新增模型（OpenAI 和 Anthropic 類型要填各自支援的模型 ID）

---

## 支援的模型

### OpenAI 相容模型

| 模型名 |
|---|
| `gpt-5.4` |
| `gpt-5.2` |
| `gpt-5.3-codex` |

### Anthropic 相容模型

| 模型名 |
|---|
| `claude-opus-4-6` |
| `claude-sonnet-4-6` |

> 模型 ID 必須和 Dragon Code 支援的**完全一致**，大小寫、連字元都不能差。

### 新增模型

![新增模型](https://r2.bozhouai.com/dragoncode-cherry-studio/page8_img1.png)

新增完成後點選 **檢測**，提示成功即可進入下一步。

![檢測模型](https://r2.bozhouai.com/dragoncode-cherry-studio/page9_img1.png)

---

## 4. 開始聊天（驗證接入）

1. 新建對話
2. 選擇剛剛新增的模型

   ![選擇模型](https://r2.bozhouai.com/dragoncode-cherry-studio/page10_img1.png)

3. 輸入：`你好`

### 成功表現

模型正常回覆內容即表示接入成功。

![成功對話](https://r2.bozhouai.com/dragoncode-cherry-studio/page11_img1.png)

如果沒有回覆或報錯，參考下面的排查表。

---

## 5. 報錯排查

看到什麼報錯，就對照下面這一條。

### 503 Service temporarily unavailable

- **含義**：目前模型通道不可用或太擁堵
- **解決**：重試；或切換到其他模型（推薦）

### 502 Bad gateway

- **含義**：Dragon Code 連接上游 Claude / GPT 失敗
- **解決**：等 1~2 分鐘再試；或切換模型

### AI_RetryError

- **含義**：已自動重試 3 次仍失敗（本質通常是 502 / 503）
- **解決**：同上，切換模型或稍後重試

### 401 / 403

- **含義**：API Key 錯誤或分組不匹配
- **解決**：重新複製 Key；確認提供商類型與 Key 分組一致

### 400

- **含義**：模型 ID 或 URL 寫錯
- **解決**：檢查
  - API 地址是否為 `https://dragoncode.codes`
  - 模型 ID 是否在[支援的模型](#支持的模型)清單中

### 一直轉圈 / 卡住

- **含義**：網路、流式連接或模型異常
- **解決**：新開對話；重啟 Cherry Studio；切換模型或分組

---

## 6. 一分鐘自檢

90% 的問題都出在這張表裡。

| 專案 | 正確寫法 |
|---|---|
| Base URL | `https://dragoncode.codes` |
| API Key | `sk-xxxx`（完整、無空格） |
| 模型 ID | 必須在支援清單中 |
| 分組與類型 | OpenAI ? `codex` 分組；Anthropic ? Claude 分組 |