Cherry Studio

Cherry Studio 是支援 Windows、macOS 和 Linux 的多模型桌面用戶端。透過新增自訂 OpenAI 服務供應商，可以讓 Cherry Studio 使用 AGTCloud 的 Chat Completions 相容入口。

本教學只介紹一般聊天串接。檔案、圖片、工具呼叫、推理、知識庫、Agent、MCP 和其他進階能力取決於 Cherry Studio 版本及目標模型的實際支援範圍。

準備工作

開始前，請確認你已經：

準備好受支援的 Windows、macOS 或 Linux 裝置；
註冊並登入 AGTCloud；
在 API Keys 頁面建立 AGTCloud API Key；
從模型廣場複製目前 API Key 可見且支援 Chat Completions 的模型 ID。

下載並安裝 Cherry Studio

從 Cherry Studio 官方下載頁取得安裝套件。下載頁和安裝套件名稱可能隨版本更新，請根據作業系統與處理器架構選擇目前版本。

常見的 Intel 或 AMD 電腦選擇 Windows x64 一般安裝版；
Windows ARM 裝置選擇 ARM64 安裝套件；
下載完成後執行安裝程式，並按照介面提示完成安裝。

不確定裝置架構時，可以在 設定 → 系統 → 系統資訊 中檢視“系統類型”。

安裝完成後啟動 Cherry Studio。如果首次啟動出現初始化、資料目錄或更新提示，請按目前版本介面完成設定。

新增 AGTCloud 服務供應商

開啟模型服務設定

開啟 Cherry Studio，進入 Settings → Model Provider。中文介面中的名稱可能顯示為“設定 → 模型服務”。

新增自訂服務供應商

點選服務供應商清單中的 Add 或“新增”，新建一個自訂服務供應商。Provider Name 填寫 AGTCloud，Provider Type 選擇 OpenAI。

填寫連線資訊

Cherry Studio 欄位	填寫內容
`Provider Name`	`AGTCloud`
`Provider Type`	`OpenAI`
`Chat Endpoint / Protocol`（如有）	`OpenAI Chat Completions`
`API Key`	`your-api-key`
`API Host`	`https://api.agtcloud.cn/v1/`
`Custom Headers`	預設留空

將 your-api-key 替換為在 API Keys 頁面建立的 AGTCloud API Key。若目前版本提供聊天協議選擇，請使用 OpenAI Chat Completions。

啟用服務供應商

儲存設定後，開啟服務供應商右上角的啟用開關。服務供應商未啟用時，已經新增的模型也不會出現在聊天頁面的模型清單中。

API Host 需要以 / 結尾

請填寫 https://api.agtcloud.cn/v1/。不要填寫完整的 /v1/chat/completions 請求地址，否則 Cherry Studio 再次串接路徑時可能產生重複 Endpoint。

取得並新增模型

開啟模型管理

在 AGTCloud 服務供應商設定頁點選 Manage。Cherry Studio 會嘗試根據目前 API Host 和 API Key 取得可見模型。

將模型加入清單

在傳回的模型清單中找到支援 Chat Completions 的模型，點選右側的 +。只有加入服務供應商模型清單的模型，才會出現在聊天頁面的模型選擇器中。

無法載入時手動新增

如果模型清單沒有正常載入，請先檢查 API Host、API Key 和服務供應商啟用狀態。也可以從模型廣場複製模型 ID，然後使用 Cherry Studio 目前版本提供的手動新增入口填寫 MODEL_ID。

檢查連線

點選 API Key 輸入欄位附近的連通性檢查按鈕。Cherry Studio 通常會使用已新增清單中的最後一個聊天模型進行檢查；如果檢查失敗，請先確認清單中至少存在一個目前 API Key 可以呼叫的聊天模型。

模型設定以實際能力為準

不需要一次新增所有模型。模型的上下文長度、檔案輸入、圖片理解、工具呼叫和推理能力，以目前模型和協議入口的實際支援範圍為準。

請用三句話介紹你自己。

檢查結果

如果用戶端能夠正常接收回覆，說明 API Host、API Key 和模型的基本連線已經建立。本步會產生正常的 API 用量。

常見問題

現象	優先檢查	處理方式
AGTCloud 模型未顯示	服務供應商開關和模型新增狀態	啟用服務供應商，並確認目標模型已經加入服務供應商模型清單
`Manage` 傳回空清單	API Host、API Key、目前帳戶模型範圍	重新填寫 API Host 和 API Key，或從模型廣場複製 `MODEL_ID` 後手動新增
連通性檢查失敗	已新增模型、模型協議和 Key 權限	確保清單中最後一個聊天模型可由目前 Key 透過 Chat Completions 呼叫
傳回 `401`	API Key 內容和權杖狀態	重新複製有效 API Key，並確認填寫內容沒有多餘空格
傳回 `403`	權杖權限、模型權限和帳戶狀態	在控制台檢查 API Key 狀態及目前帳戶的模型可用範圍
傳回 `404`	API Host、重複路徑和模型 ID	使用 `https://api.agtcloud.cn/v1/`，不要填寫完整 Endpoint，並重新核對模型 ID
請求路徑重複	API Host 填寫了完整請求地址	恢復為以 `/` 結尾的 `https://api.agtcloud.cn/v1/`，再重新檢查連線
進階功能呼叫失敗	模型真實能力、協議支援和用戶端版本	先關閉檔案、工具、知識庫或推理等進階功能，再使用一般文字完成驗證
回覆中斷或緩慢	網路代理、上下文長度和模型狀態	使用較短的新話題重試，並檢查本機網路與目前模型執行狀態

遇到無法定位的問題時，請記錄請求時間、模型 ID、HTTP 狀態和去識別化錯誤資訊，然後檢視錯誤與疑難排解。不要提交完整 API Key。

安全建議

不要把 API Key 放入截圖、聊天匯出、記錄或共享設定；
不要在首次驗證中提交密碼、客戶資料、私有檔案或其他敏感內容；
多人共用裝置時，使用完畢後刪除 Cherry Studio 中儲存的憑證；
匯出或分享 Cherry Studio 設定前，先確認其中不包含 API Key。