Cherry Studio 串接 AIXHUB

本指南會在 Cherry Studio 新增 AIXHUB 自訂 OpenAI 供應端，並把內建供應端檢查、第一筆真實聊天與 AIXHUB 用量驗證分開處理。

完成目標

完成本指南後，你會得到以下結果：

1. 安裝符合平台與處理器架構的官方 Cherry Studio 版本。
2. 記錄或備份原始供應端狀態，且不洩露已儲存金鑰。
3. 新增已啟用的 AIXHUB 供應端，並加入一個精確 panel-model-id 模型。
4. 使用預期模型執行供應端 檢查。
5. 完成一筆回傳 OK 的不呼叫工具聊天，並與 AIXHUB 用量核對。
6. 保留欄位層級復原方式，不覆寫後來的聊天、助手與設定。

支援平台

Cherry Studio 發布以下套件：

• Windows： x64 與 ARM64。
• macOS： Intel 與 Apple Silicon。
• Linux： x86_64 與 ARM64 AppImage。

請選擇符合作業系統與處理器的套件。套件名稱、版本及直接下載網址可能變動，因此請使用官方下載頁或 GitHub releases，不要複製舊的直接連結。

安裝或開啟應用程式

請從官方下載頁或 GitHub releases取得 Cherry Studio，不要依賴第三方教學寫死的版本號。

安裝或開啟符合架構的套件。若應用程式顯示目前版本，可把它記入設定紀錄，但不要依賴特定「關於」選單標示。只有確認套件來自官方管道後，才完成作業系統信任或安裝提示。

設定值

API 位址是 Base URL。目前 Cherry Studio 會在 API Host 沒有版本時自動附加 /v1；若已填入 https://api.aixhub.org/v1，則會保持不變，再由用戶端附加 /chat/completions。因此，https://api.aixhub.org 也能正規化成含版本的基底網址。本指南建議明確填入 https://api.aixhub.org/v1，方便直接與 AIXHUB Base URL 對照。此欄位絕不可填入完整 /v1/chat/completions 或 /v1/responses 端點。若錯誤中出現 /v1/v1，請檢查實際啟用欄位與版本組合，再恢復為明確建議值，並和目前 Cherry Studio 供應端文件核對。

設定 AIXHUB

備份並記錄原始狀態

1. 開啟左側欄的設定齒輪，再進入資料設定。
2. 若已安裝版本提供本機或雲端備份，請在編輯供應端前建立一次受控備份。只使用你信任且獲准使用的儲存位置與同步帳號。
3. 把備份視為憑證檔案：完整資料備份包含供應端設定與 API 金鑰。不可分享、附加到支援案件，或上傳到不受信任的儲存空間。
4. 記錄 AIXHUB 供應端是否原本存在，並記錄非秘密欄位、模型清單、啟用狀態及金鑰是否屬於其他設定。精確秘密值只保留在受保護備份，不可寫進一般紀錄。

若無法備份，請建立受保護的欄位層級紀錄。供應端原始狀態或歸屬未知時，請停止操作，不要假設可以覆寫或在之後刪除。

新增自訂供應端

1. 選擇設定齒輪，再開啟模型服務。
2. 在供應端清單下方選擇 + 新增。
3. 供應端名稱輸入 AIXHUB，供應端類型選擇 OpenAI，再完成新增。
4. 在供應端清單找到新的 AIXHUB。

若 AIXHUB 原本已存在，請和受保護紀錄比較，並明確判斷是否確實要取代欄位。不要建立名稱略有差異的重複供應端。

輸入金鑰與 API 位址

1. 為 Cherry Studio 建立或選擇一組專用 AIXHUB API 金鑰。
2. 輸入供應端 API Key 欄位，不要在其他位置顯示。
3. API 位址必須剛好是 https://api.aixhub.org/v1。

不要把金鑰貼進提示內容、供應端名稱、模型欄位或官方帳號登入流程。

加入模型並啟用供應端

1. 在模型區域選擇 + 新增，並輸入從模型路由取得的精確 panel-model-id。
2. 模型管理視窗顯示清單時，仍要按 panel-model-id 右側的 + 控制項。只在視窗看到模型並不足夠；按下右側 + 才會真正加入供應端。
3. 回到供應端，確認已加入模型清單出現 panel-model-id。
4. 開啟供應端右側或右上方的啟用開關。

模型未真正加入或供應端未啟用時，聊天介面可能仍看不到供應端或模型。

執行供應端檢查

按 API Key 欄位右側的 檢查。預設會使用供應端已加入模型清單中最後一個對話模型。執行前，確認 panel-model-id 是最後一個預期對話模型；必要時移除尾端誤加的模型。

檢查成功代表 Cherry Studio 能以該模型送出供應端請求，但不能證明後續聊天一定使用 AIXHUB；仍須分別驗證第一筆聊天與用量記錄。檢查 會送出真實請求，可能產生少量用量。

首次使用

建立新聊天或助手，明確為該對話選擇 AIXHUB 供應端與 panel-model-id，不要依賴舊助手預設值或備援路由。

第一次請求不要啟用網路存取、MCP、知識庫、工具或自動備援。送出：

Do not use tools or change any data. Reply with OK only.

收到回應前，不要啟用任何額外功能。

驗證

供應端檢查應成功，新聊天應回傳：

OK

接著開啟 AIXHUB 用量，核對聊天請求時間、panel-model-id 與成功狀態。只有用量實際顯示協定或 API 模式時才核對，不要假設一定看得到該欄位。重新開啟聊天後，也要確認仍顯示 AIXHUB 與 panel-model-id。

疑難排解

找不到供應端或模型

確認供應端啟用開關已開啟。重新開啟模型管理，確認曾按 panel-model-id 右側的 +；只在可用清單看到模型並不代表已加入。回到聊天後再次選擇供應端與模型。

檢查失敗或使用錯誤模型

檢查 會使用已加入模型清單中最後一個對話模型。請讓 panel-model-id 成為最後一個預期對話模型，或移除尾端錯誤項目，再重試。檢查失敗本身不能證明 API 金鑰或 Base URL 一定錯誤。

401 或驗證失敗

確認 API Key 欄位是目前有效的專用 AIXHUB 金鑰，而且正在檢查已啟用的 AIXHUB 供應端。不要使用 AIXHUB 控制台密碼或官方 OpenAI 憑證。重新輸入金鑰時，不可顯示在螢幕擷取畫面或記錄中。

404、API 版本重複或端點錯誤

使用明確建議的 API 位址 https://api.aixhub.org/v1。目前 Cherry Studio 也能接受 https://api.aixhub.org 並自行附加 /v1，所以根網址本身不一定是 404 的原因。請從 Base URL 欄位移除 /v1/chat/completions 或 /v1/responses 等完整端點字尾。若出現 /v1/v1，請檢查實際啟用的供應端欄位及匯入設定，再還原為明確建議的 Base URL。

model not found

從模型路由重新複製完整模型 ID，移除錯誤模型項目，再透過右側 + 加入 panel-model-id。確認所選路由支援 Cherry Studio 使用的 OpenAI 相容請求。

聊天成功但用量沒有相符記錄

對話可能使用其他供應端、助手預設值或備援路由。開啟該聊天的模型選擇器，明確選擇 AIXHUB 與 panel-model-id；若可設定，請在本次測試停用備援，再重試。請比對時間、模型與狀態，不要只看畫面回應就判定路由。

Proxy 或網路失敗

檢查 Cherry Studio 作用中的網路或 Proxy 設定，以及作業系統連線。維持 HTTPS 憑證驗證，不要關閉。變更供應端欄位前，先區分本機連線失敗與 AIXHUB HTTP 錯誤。

若收到 403、429、502 或 503，請繼續參考錯誤代碼。

升級與復原

升級前先透過資料設定建立新的受控備份，並記錄供應端欄位、模型清單、啟用狀態與備份位置。只透過官方下載頁或 GitHub releases 升級，再重做供應端檢查、不呼叫工具聊天與用量驗證。

若 AIXHUB 原本不存在，只有確認後來的聊天、助手、預設值、備援或其他設定都不依賴，而且欄位仍符合本指南新增內容時，才能刪除新供應端。若 AIXHUB 原本已存在，請還原精確原始欄位、模型清單、啟用狀態與金鑰歸屬，不可刪除。

只有在受控期間，而且確認不會覆寫後來必須保留的聊天、助手、供應端變更或其他設定時，才能還原完整資料備份。否則請執行欄位層級復原，並保留後來新增的不相關狀態。歸屬或原始狀態未知時，請停止，不要猜測。

還原後不再需要專用金鑰時，請撤銷或輪替。若金鑰仍在其他位置使用，變更前先確認歸屬。

安全注意事項

• 為 Cherry Studio 使用專用 AIXHUB 金鑰，才能獨立輪替。
• 每一份完整資料備份都包含供應端 API 金鑰，必須視為敏感憑證檔案。
• 限制本機裝置、備份位置及儲存 Cherry Studio 資料的同步帳號存取權。
• 不可把金鑰貼進提示內容、提交，或放入螢幕擷取畫面、匯出記錄、診斷與支援訊息。
• 金鑰外洩後立即輪替，再更新受保護的供應端欄位並重新驗證聊天。
• 檢查 按鈕會送出真實請求，可能產生少量用量；沒有需要時不要重複點擊。

官方資料

• 自訂供應端
• 供應端設定
• 資料設定
• 下載 Cherry Studio

最後核對：2026-07-14