通用 OpenAI 相容用戶端
將支援自訂 OpenAI 相容供應端的圖形或命令列用戶端連到 AIXHUB，驗證路由，並安全復原原本設定。
當圖形或命令列用戶端支援自訂供應端或 OpenAI 相容 API，卻沒有專用 AIXHUB 教學時，請使用本指南。AIXHUB API 金鑰不是 OpenAI 官方登入憑證；務必使用用戶端的自訂 Provider、自訂 API 或 OpenAI 相容設定流程。
前置條件
- 為這個用戶端建立一組專用 AIXHUB API 金鑰。金鑰只放在用戶端的秘密欄位或文件指定的秘密儲存區，不要顯示在終端機。
- 從模型路由複製完整相容模型 ID。本指南需要模型時一律使用
panel-model-id。 - 確認用戶端支援自訂 Base URL。只有官方帳號登入功能並不足夠。
- 確認用戶端需要 OpenAI 相容 API，並檢查是否提供 OpenAI Responses 模式。
- 變更前先備份目前用戶端設定，或記錄供應端、URL、模型、API 模式與憑證儲存方式的精確原值。
若工具無法設定自訂供應端與 Base URL，請停止操作。不要把 AIXHUB 金鑰貼進 OpenAI、Google、Anthropic 或其他供應商的官方登入表單。
操作步驟
選擇自訂供應端流程
圖形介面通常可在「設定 → 供應端 → 新增自訂供應端」或「OpenAI 相容」找到入口。命令列工具則使用其文件指定的自訂供應端設定檔或引數。不同用戶端的名稱可能不同，但流程必須提供自訂 URL 與 API 金鑰欄位。
不要選擇官方帳號登入流程。若用戶端強制開啟瀏覽器登入，而且沒有自訂 API 欄位，就無法套用這份通用設定。
填寫核心欄位
使用以下值：
| 欄位 | 值 |
|---|---|
| Provider 名稱 | AIXHUB |
| API 或供應端類型 | OpenAI-compatible |
| API 金鑰 | 在秘密欄位輸入專用 AIXHUB 金鑰 |
| Base URL | 通常是 https://api.aixhub.org/v1 |
| 模型 | panel-model-id |
| API 模式（若有） | 只有用戶端與所選模型支援時，才優先選用 OpenAI Responses |
請複製模型 ID，不要憑記憶輸入。螢幕擷取畫面、命令輸出或支援記錄都不可出現金鑰。
依欄位語意選擇 URL
正確 URL 取決於欄位標示：
| 用戶端欄位語意 | 值 |
|---|---|
| Base URL 或 API Base | https://api.aixhub.org/v1 |
Host 或 Origin，而且用戶端會自動附加 /v1 | https://api.aixhub.org |
| Full endpoint，明確用於所選 Responses 請求 | https://api.aixhub.org/v1/responses |
多數用戶端要求 Base URL，因此先使用 https://api.aixhub.org/v1。只有用戶端文件明確表示會自動附加 /v1 時，才使用根網址。只有欄位明確要求完整端點時，才填入 Full endpoint。
不可產生 /v1/v1。也不要把 https://api.aixhub.org/v1/responses 填入 Base URL 欄位，否則用戶端可能再次附加請求路徑。
儲存、完整重啟並選擇路由
儲存自訂供應端後，完整關閉並重新開啟圖形或命令列用戶端，讓它重新載入金鑰、URL、模型與模式。確認作用中的供應端是 AIXHUB，作用中的模型是 panel-model-id。若用戶端分別設定聊天、代理與預設模型，請檢查測試工作階段實際使用的項目。
啟用工具或執行大型工作前，先送出小型請求：
不要使用工具，也不要變更任何資料。只回覆 OK。收到回應後，開啟 AIXHUB 用量，將請求時間與 panel-model-id 和本次測試比對，並確認記錄狀態為成功。只有用量實際顯示請求協定或 API 模式時，才與用戶端所選項目核對。若用量沒有該欄位，請以用戶端選擇的 API 模式及成功經過 AIXHUB 的請求作為設定依據；不要聲稱用量一定會顯示協定欄位。只有用戶端回應，並不能證明請求確實經過 AIXHUB。
備份與復原
編輯前記錄供應端、Base URL 或端點、模型、API 模式及憑證儲存方式的精確原值。若用戶端可以匯出設定，請保護匯出檔案，因為其中可能含有秘密值。
若要復原，請完整關閉用戶端，再逐項還原記錄的原值。原本存在的供應端物件或設定檔必須還原，不可直接刪除。只有記錄能確認某個 AIXHUB 專用項目原本不存在時，才能移除。若原始狀態未知，請停止並取得可信的副本，不要自行猜測。
安全檢查
- 為這個用戶端使用專用 AIXHUB 金鑰，才能獨立輪替或撤銷。
- 把金鑰保留在秘密欄位、作業系統鑰匙圈，或用戶端文件指定的秘密管理方式。
- 不可提交金鑰、把金鑰貼進提示內容、使用 echo 命令顯示金鑰，或放進螢幕擷取畫面與支援記錄。
- 檢查匯入的設定檔與專案層級設定，因為它們可以取代供應端、URL 或模型。
- 若金鑰外洩，請立即輪替，再只更新這個用戶端受保護的憑證。
驗證結果
用戶端應對範圍明確的請求回傳以下精確輸出：
OK在 AIXHUB 用量中，確認同一時間出現使用 panel-model-id 且狀態成功的請求。只有用量實際顯示協定或 API 模式時才核對該欄位；若沒有顯示，請以用戶端所選模式及相符的成功請求為準，不要把不存在的欄位歸因於用量。完整重啟後，也要確認作用中的供應端仍顯示 AIXHUB。
常見問題
找不到自訂供應端
升級用戶端，並查看目前文件是否支援自訂 API、自訂供應端或 OpenAI 相容介面。若只有官方帳號登入功能，不要輸入 AIXHUB 金鑰。請改用專用指南，或選擇支援自訂 Base URL 的其他用戶端。
401 或驗證失敗
確認秘密欄位使用目前有效的專用 AIXHUB 金鑰，而且已啟用自訂 AIXHUB 供應端。不要以 AIXHUB 控制台密碼代替金鑰，也不要用官方 OpenAI 登入掩蓋缺少自訂憑證的問題。以不顯示金鑰的方式重新輸入，再完整重啟用戶端。
404、找不到端點或 API 版本重複
檢查欄位語意。Base URL 或 API Base 通常使用 https://api.aixhub.org/v1；只有用戶端會附加版本時，Host 或 Origin 才使用 https://api.aixhub.org；Responses 的 Full endpoint 使用 https://api.aixhub.org/v1/responses。移除 /v1/v1 等重複路徑，也不要把完整端點放進 Base URL 欄位。
model not found
從模型路由重新複製完整模型 ID。除非面板顯示不同的完整 ID，否則維持 panel-model-id 不變。也要確認所選模型支援用戶端選擇的 API 模式。
請求成功但用量沒有相符記錄
用戶端可能使用了其他供應端、官方帳號、備援路由或工作階段模型。重啟後重新檢查作用中的供應端、模型與協定。若用戶端允許，請在小型驗證請求中停用自動備援，再重做測試並比對用量時間。
若收到 403、429、502 或 503，請繼續參考錯誤代碼。
下一步
- 程式碼接入前，請建立另一組只供該程式碼使用的專用 AIXHUB 金鑰，不要重複使用這個用戶端的金鑰；接著再閱讀 API 驗證。
- Claude Code 使用專用 Anthropic 相容環境變數流程。
- Codex CLI 使用 Responses 供應端與獨立憑證檔案。
- OpenCode 使用
opencode.json供應端格式。 - OpenClaw 使用模型供應端與本機代理流程。
一般參考資料
最後核對：2026-07-14