通用 OpenAI 相容客戶端

除了 Cherry Studio 之外，任何允許自訂 OpenAI Base URL 的客戶端、IDE 外掛或框架，都可以用同樣的方式接入瓜瓜AI。

本頁提供通用設定原則，不綁定特定軟體。

通用設定四要素

設定項	值
供應商類型 / Provider	OpenAI（或「OpenAI 相容 / Compatible」）
Base URL / API 位址	`https://api.guagua5487.xyz/v1`
API Key	你的瓜瓜AI API Key
模型 / Model ID	瓜瓜AI 的模型代號

只要該工具能改這四項，通常就能接入。

欄位名稱對照表

不同工具的欄位命名差異很大，請依下表對照：

你可能看到的欄位	對應設定	備註
`API Base` / `Base URL` / `API Host` / `接口地址` / `端點`	Base URL	只填到 `/v1`，不要加 `/chat/completions`
`API Key` / `API Token` / `密鑰` / `Secret`	你的金鑰	只填金鑰本身，不要加 `Bearer`
`Model` / `Model ID` / `模型名稱` / `deployment`	模型代號	依支援模型
`Provider` / `供應商類型`	OpenAI 相容	不要選 OpenAI 官方專屬類型
`Organization`	留空	瓜瓜AI 未確認支援此欄位
`API Version`	留空或預設	屬 Azure 專屬欄位，通常不適用
`Streaming` / `串流`	可開啟	見串流輸出

兩個最常見的設定錯誤

Base URL 少了 /v1 → 通常回 404。
Base URL 多寫了 /chat/completions → 路徑重複，回 404。

詳見 Base URL。

常見工具類型

類型	說明	設定重點
桌面聊天客戶端	支援自訂供應商的桌面應用	新增 OpenAI 類型供應商，填入 Base URL 與金鑰
瀏覽器擴充／網頁應用	允許自填 API 端點者	注意金鑰會存在瀏覽器端，風險較高
編輯器／IDE 外掛	支援 OpenAI 相容端點者	填 Base URL、金鑰與模型代號
工作流程／自動化平台	具備 OpenAI 節點且可改 Base URL 者	於節點設定中覆寫端點
自架聊天介面	開源、可設定 `OPENAI_API_BASE` 等環境變數者	以環境變數注入，勿寫入映像檔

待補充

經實測確認可用的工具清單尚待官方補充。 上表僅按工具類型說明設定方式；相容性仍須以你的版本與實際測試結果為準。

驗證流程

設定完成後，請依序驗證，這樣出錯時最容易定位問題：

先用 curl 確認服務可連線（排除網路與金鑰問題）：

bash

curl https://api.guagua5487.xyz/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model":"MODEL_ID","messages":[{"role":"user","content":"ping"}]}'

再於客戶端送出一句短訊息（排除客戶端設定問題）。
最後才測試進階功能（串流、系統提示、工具呼叫等）。

常見問題

症狀	可能原因	處理
客戶端顯示「無法連線」	網路、Proxy、DNS 或 Base URL 錯誤	先用 `curl` 測試
404	Base URL 缺 `/v1` 或路徑重複	見 Base URL
401	金鑰錯誤或格式不對	見 401
403	無模型權限	見 403
400	客戶端送了不支援的參數	見 400
429	請求過於頻繁	見 429
串流不逐字顯示	客戶端或代理緩衝	見串流輸出
模型下拉選單是空的	未開放模型列表端點	手動輸入模型代號

安全提醒

風險	建議
金鑰存在瀏覽器或前端	改用有後端代理的客戶端，或限制金鑰用途
共用裝置	登出時清除設定；避免勾選「記住金鑰」
設定檔備份／同步	排除含金鑰的檔案，勿同步到公開位置
第三方外掛	只使用可信任來源的工具
金鑰外洩	立即更換金鑰並檢查用量

通用 OpenAI 相容客戶端 ​

通用設定四要素 ​

欄位名稱對照表 ​

常見工具類型 ​

驗證流程 ​

常見問題 ​

安全提醒 ​

相關頁面 ​