外觀
Cherry Studio
Cherry Studio 是一款支援多家供應商的桌面 AI 客戶端，內建「OpenAI 相容」類型的供應商設定，因此可以直接接入瓜瓜AI。
版本差異
Cherry Studio 由第三方維護，選單名稱與畫面配置可能隨版本變動。以下步驟以「新增 OpenAI 相容供應商」的通用流程說明；若你的版本畫面不同，請以實際介面為準，或參考 通用 OpenAI 相容客戶端。
前置準備
| 項目 | 值 |
|---|---|
| API 位址（Base URL） | https://api.guagua5487.xyz/v1 |
| API 金鑰 | 你的瓜瓜AI API Key（YOUR_API_KEY 為佔位，請勿照抄） |
| 模型代號 | 瓜瓜AI 提供的模型代號，見 支援模型 |
待補充
瓜瓜AI 的 API Key 申請方式尚未確認，請以官方公告為準。
設定步驟
1. 開啟模型服務設定
進入應用程式的設定（Settings）→ 模型服務 / 模型提供者（Model Providers）。
2. 新增供應商
點擊新增 / 添加（Add），供應商類型選擇 OpenAI（或標示為「OpenAI 相容」的選項）。
為什麼選 OpenAI 類型
瓜瓜AI 提供 OpenAI 相容介面，因此使用 OpenAI 類型的設定項即可；不需要選擇 OpenAI 官方專屬的其他類型。
3. 填入連線資訊
| 欄位 | 填入內容 |
|---|---|
| API 金鑰 / API Key | 你的瓜瓜AI API Key |
| API 位址 / Base URL | https://api.guagua5487.xyz/v1 |
| 供應商名稱 | 可自訂，例如「瓜瓜AI」 |
設定名稱可任意填寫，真正影響連線的只有 API 位址與金鑰。
不要貼上真實金鑰
截圖或提問時請遮蔽金鑰。本文件所有範例皆為佔位字串，不含任何真實憑證。
4. 加入模型
在該供應商下新增模型（Add Model），填入瓜瓜AI 的模型代號。
| 欄位 | 填入內容 |
|---|---|
| 模型 ID / Model ID | 瓜瓜AI 的模型代號（例如 MODEL_ID） |
| 顯示名稱 | 可自訂 |
若客戶端提供「取得模型清單 / Fetch models」按鈕，可先嘗試自動抓取；抓不到時通常代表模型列表端點未開放或設定有誤，請手動輸入，詳見 模型選擇。
5. 測試
在對話視窗選擇剛加入的模型，送出一句簡短訊息：
text
你好，請用一句話自我介紹。能正常收到回覆即代表設定成功。
欄位對照表
不同版本或不同客戶端的欄位名稱可能不一樣，對照如下：
| 你可能看到的欄位名稱 | 應填入 |
|---|---|
| API 位址 / API Host / Base URL / 接口地址 | https://api.guagua5487.xyz/v1 |
| API 金鑰 / API Key / 密鑰 / Token | 你的瓜瓜AI API Key |
| 模型 ID / Model / 模型名稱 | 瓜瓜AI 的模型代號 |
| 供應商類型 / Provider Type | OpenAI（相容） |
疑難排解
| 症狀 | 可能原因 | 處理 |
|---|---|---|
| 401 Unauthorized | 金鑰貼錯、多了空白、或含 Bearer 前綴 | 只填金鑰本身，見 401 |
| 404 Not Found | Base URL 少了 /v1 或多了 /chat/completions | 只填到 /v1，見 Base URL |
| 400 Bad Request | 模型代號錯誤或請求內容異常 | 見 400 |
| 403 Forbidden | 金鑰有效但無該模型權限 | 見 403 |
| 429 Too Many Requests | 請求過於頻繁 | 見 429 |
| 一直轉圈或逾時 | 網路、防火牆或 Proxy 問題 | 先用 curl 驗證連線 |
| 回覆一次全部出現 | 客戶端或代理未啟用串流 | 屬正常現象，不影響功能 |
| 模型清單抓不到 | 模型列表端點未開放 | 手動輸入模型代號 |
安全提醒
- 金鑰只存在你自己的裝置上；共用電腦請留意本機儲存位置。
- 不要把含金鑰的設定檔同步到公開雲端或提交到版本控制。
- 若懷疑金鑰外洩，請立即更換。