自訂供應商可讓 PandaNpc 使用您所控制的 API 帳戶、私人閘道或本機模型端點。這通常稱為 BYOK：自備金鑰。當您需要內建目錄以外的模型、供應商端計費、內部代理伺服器、Ollama、LM Studio 或自架的 OpenAI 相容服務時，此功能相當實用。
就支援的直接聊天而言，PandaNpc 會將請求傳送到您設定的端點，而非取代內建模型。您的上游供應商仍會控制定價、資料保留、速率限制、模型可用性與可接受使用政策。
先決條件與安全邊界
新增供應商之前，請先備妥下列資訊：
- 供應商的 API Key 或本機驗證權杖。
- API Base URL，OpenAI 相容服務通常以
/v1結尾。 - API 接受的確切模型識別碼。
- 如果您打算覆寫預設值，請備妥文件中記載的上下文視窗與最大輸出限制。
請使用具備最低必要權限的專用金鑰，並在供應商支援的情況下設定消費上限。切勿將金鑰放入文件、聊天提示、螢幕截圖、瀏覽器主控台輸出或 Git 儲存庫中。
在網頁瀏覽器中，直接請求會受到 CORS 限制。供應商必須允許來自 https://pandanpc.com 的請求。像是 http://localhost:11434/v1 的 Base URL 指的是執行瀏覽器的電腦，而非自動指向遠端 PandaPaw 機器。桌面應用程式可能更適合本機端點，因為它不像瀏覽器那樣受到 CORS 限制。
第 1 步：開啟模型設定
登入 PandaNpc 並開啟 模型設定。供應商與模型是分開的記錄：供應商儲存連線與驗證詳細資料，而每個模型則儲存傳送到該連線的識別碼與限制。
如果官方供應商已存在，請設定或複製它，而不是自行發明不同的協定。若要新增 OpenAI 相容閘道，請選取 新增供應商。
第 2 步：新增供應商
填寫供應商表單：
| 欄位 | 要輸入的內容 | 範例或指引 |
|---|---|---|
| 顯示名稱 | 您可見的標籤 | Company AI Gateway |
| 供應商 ID | 穩定的內部識別碼 | company-openai |
| API Key | 作為 bearer token 使用的密鑰 | 供應商核發的值 |
| Base URL | API 根路徑，不含 /chat/completions |
https://gateway.example.com/v1 |
| 協定 | 上游 API 格式 | 選擇 openai 以使用 OpenAI 相容的聊天完成 |
| 密鑰 | 選用的第二個密鑰 | 除非供應商要求，否則留空 |
| 組織 | 選用的組織識別碼 | 僅在供應商要求時填寫 |
| 專案 | 選用的專案識別碼 | 僅在供應商要求時填寫 |
| 支援內容陣列 | 訊息內容是否可使用結構化陣列 | 若供應商接受現代多模態訊息內容，請保持啟用 |
PandaNpc 會移除 Base URL 尾端的斜線，並在直接 OpenAI 相容聊天請求中附加 /chat/completions。因此請輸入：
https://api.example.com/v1而非：
https://api.example.com/v1/chat/completions新增模型之前，請先儲存供應商。編輯現有供應商時，空的 API Key 或密鑰欄位代表「保留已設定的值」；它不會將已儲存的密鑰顯示回表單中。
第 3 步：新增模型
在供應商下方選擇 新增模型，並填寫下列欄位：
| 欄位 | 意義 | 範例 |
|---|---|---|
| 顯示名稱 | 人類可讀的選擇器標籤 | My Coding Model |
| 模型值 | 上游確切的模型 ID | model-name-from-provider |
| 模型類型 | PandaNpc 的能力／類別對應 | 從表單中選擇目前的值 |
| 供應商 | 上方建立的供應商記錄 | Company AI Gateway |
| 上下文視窗 | 支援的總 token 數 | 使用供應商文件中的整數限制 |
| 最大 Token 數 | 最大產出 token 數 | 使用不大於供應商限制的正值 |
顯示名稱 可以變更，且不會影響 API 呼叫。模型值 無法從行銷名稱猜測；請從供應商的 API 文件或模型清單端點複製。
若不確定，請將上下文視窗與最大 Token 數留空。保守的預設值比宣告大於伺服器支援的上下文視窗更安全。這些欄位對 PandaCode 尤其重要，因為它們會影響壓縮與輸出預算。
常見端點範例
以下模式說明 URL 的形狀；可用性與模型 ID 取決於您的安裝或供應商帳戶：
| 服務類型 | 典型 Base URL | 備註 |
|---|---|---|
| OpenAI 相容雲端 API | https://provider.example.com/v1 |
必須支援串流 Chat Completions 與 bearer 驗證 |
| 檢視電腦上的 Ollama | http://localhost:11434/v1 |
啟動 Ollama 的 OpenAI 相容端點；瀏覽器使用可能需要 CORS 設定 |
| 檢視電腦上的 LM Studio | http://localhost:1234/v1 |
啟動本機伺服器並選取已載入的模型 ID |
| 私人網路閘道 | https://ai.internal.example/v1 |
PandaNpc 用戶端必須能夠解析並連線到該主機 |
請勿假設每個宣稱「OpenAI 相容」的服務都會實作串流、工具呼叫、影像、推理欄位或相同的錯誤回應。請測試您的工作流程所需的確切功能。
驗證供應商與模型
在依賴此設定之前，請先使用低成本、非敏感的提示：
- 在新的對話中選取新模型。
- 傳送
Reply with exactly: provider connected。 - 確認回應會串流，且供應商儀表板記錄了該請求。
- 傳送簡短的後續訊息以驗證對話歷史。
- 如果您需要工具、影像或長上下文，請分別測試每一項功能。
若是本機端點，請先在 PandaNpc 之外驗證。OpenAI 相容的模型清單通常可透過以下方式取得：
curl http://localhost:11434/v1/models僅使用回應來確認可連線性與模型 ID。請勿將正式環境的 API Key 直接放入 shell 歷史記錄中。
將自訂模型用於 PandaCode
PandaCode 可以在您選擇的模型後端（包括 DeepSeek、Qwen、OpenAI 相容閘道或內部服務）上提供 Claude Code 風格的編碼工作流程。設定供應商與模型之後，請為相關的 PandaCode 連線或任務選取該模型。
模型必須支援編碼引擎所需的互動模式。可用於純聊天的供應商，仍可能無法處理工具呼叫、長時間串流或結構化內容。請參閱 PandaNpc 支援的 AI 模型 以了解聊天模型與本機編碼引擎之間的差異，並參閱 PandaPaw 安裝與指令 以了解遠端引擎設定。
疑難排解
`401` 或 `403` 驗證錯誤
建立新的供應商金鑰，確認其已啟用，然後重新輸入。請檢查上游服務是否要求組織、專案或不同的驗證方法。從編輯畫面複製的遮罩金鑰並非原始密鑰。
`404` 端點或模型找不到
從設定的 Base URL 移除 /chat/completions，因為 PandaNpc 會自動附加。確認在需要時包含 /v1，且模型值與上游模型 ID 完全相符。供應商可能會對錯誤的 URL 與不存在的模型傳回相同的 404。
瀏覽器回報網路或 CORS 錯誤
僅開啟瀏覽器開發者主控台來識別被封鎖的來源；請勿在其中貼上密鑰。設定供應商以允許 https://pandanpc.com、使用其 HTTPS 端點，或使用 PandaNpc 桌面應用程式。混合內容規則會封鎖 HTTPS 頁面呼叫某些純 HTTP 端點。
無法連線到本機 Ollama 或 LM Studio
請確認伺服器正在與發出請求的用戶端同一台電腦上執行，並監聽設定的介面與連接埠。如果模型伺服器執行在另一台電腦上，localhost 是錯誤的；請使用可連線的私人主機名稱或 IP，並在公開前保護該服務。
回應開始後停止或沒有內容
確認 API 支援串流 Chat Completions，並發出標準的 data: 事件。降低最大 Token 數、測試純文字訊息，並且僅在供應商文件指出它只接受字串內容時，才停用結構化內容陣列。
長時間工作階段在接近上下文限制時失敗
將設定的上下文視窗降低至供應商實際支援的限制，並為輸出、系統指令與工具結果保留空間。變更模型設定後，請開始新的工作階段，以便一致套用新的限制。
如需帳戶層級的配額與資料流詳細資料，請閱讀 PandaNpc 帳戶、方案與 API 成本 與 隱私權政策。