本頁譯自英文文件。指令、識別名稱與範例保持原樣。執行環境 7.24.4 · SDK 2.6.7。 英文原文

自訂與閘道供應商

狀態：現行 範圍：現行狀態 上次審閱：2026-09-06 負責人：ax-code 執行環境

AX Code 透過標準的供應商協定與模型對話。任何會說 OpenAI 相容（/v1/chat/completions）或 Anthropic 相容（/v1/messages）API 的端點，都可以把 baseURL 指向它，加為自訂供應商。不必改程式碼，也不必等待內建預設組。

這涵蓋自行架設的彙整器與轉送閘道，例如 LiteLLM、one-api、new-api 與 Vercel AI Gateway，也包含公司內部的私有代理，以及其他相容服務。AX Code 一律以相同方式對待它們：它說的是線路協定，URL 與金鑰由你提供。

責任說明。 閘道位於 AX Code 與上游模型之間，因此你的提示、程式碼與憑證都會經過它。當你把 AX Code 指向第三方，或指向把多個帳號集中轉送的服務時，你必須自行負責信任該操作者會處理你的資料，並遵守它所路由到的每一個上游供應商的服務條款。OpenRouter 這類內建閘道預設組走的是同一條標準協定路徑；自訂閘道設定並不表示背書任何轉送操作者。

互動式設定

相容的閘道請用 /connect，再到 API Cloud Provider、Custom API provider；AX Trust 閘道則用 /connect，再到 AX Trust、Connect AX Trust。輸入它的基底 URL（AX Trust 要包含 /v1）與用戶端 API 金鑰。編輯器會探索模型 ID 與中繼資料，並把憑證存進加密的驗證儲存。若探索不可用，也可以接受明確的模型 ID。重新連接已儲存的 URL 時，若權杖留白，會保留它的供應商 ID 與金鑰。AX Trust 連線在編輯與模型重新整理之後，仍保持原來的類別。AX Code 會在那些連線上，連同工作階段 ID 送出 X-AX-Prompt-Cache-Key，讓閘道可以把工作階段留在一個合格帳號上；若要停用，把 provider.<id>.options.axTrust 設為 false。這個標頭不會轉送到上游，也不是本文裡的 prompt_cache_key。

已連線的 AX Trust 供應商會在啟動時於背景重新整理模型清單。AX Code 會用既有憑證呼叫已設定端點的 GET /models，並更新模型名稱、上下文與輸出上限、推理、工具呼叫、temperature 支援與影像支援。具備影像能力的模型會在 /models 顯示視覺標記；當 AX Trust 宣告閘道別名支援影像時，那些別名也包含在內。探索完成時，TUI 會更新。對於精確的第一方 DeepSeek 模型 ID，缺少的中繼資料會從隨附的 models.dev 目錄補上。明確的閘道能力旗標與上限優先；未知別名不會因為名稱相似而繼承能力。

成功的重新整理會取代執行環境清單，移除閘道不再宣告的模型，並且仍然套用已設定的允許清單與封鎖清單。逾時、錯誤、空白或無效的回應會保留已儲存的清單，並記錄一次探索失敗。啟動不會等待網路。這次重新整理不會改寫供應商設定或憑證；已儲存的設定仍是啟動時的後援。一般的自訂 API 供應商仍維持手動重新整理。

供應商如何解析

每次請求，AX Code 都需要從供應商項目取得三樣東西：

• npm：說線路協定的 AI SDK 配接器。OpenAI 風格的端點用 @ai-sdk/openai-compatible，Anthropic 風格的端點用 @ai-sdk/anthropic。只有 @ai-sdk/* 配接器是隨附或可安裝的。
• options.baseURL：閘道 URL。先退回供應商的 api 欄位，再退回模型自己的 api.url。支援 ${ENV_VAR} 替換。
• 憑證：依序從 options.apiKey 解析，然後是已保存的驗證存放區，最後是供應商的 env 變數。

手動設定還需要明確的 models 對應。互動式編輯器會從端點，或從你提供的模型 ID，填入這個對應。

專用的私有 GPU 雲端是 /connect 底下的一等供應商，路徑是 Private GPU cloud。貼上 OpenAI 相容的 URL 與權杖（alibaba-pai、runpod、huggingface-endpoints、sagemaker、volcengine-ark、modelarts、tencent-ti 或 custom-private-gpu）；AX Code 會呼叫 GET …/models，並自動使用已部署的模型 ID。

託管的 GPU 目錄（nebius、fireworks-ai、togetherai、baseten、nvidia、deepinfra）使用 API 金鑰與隨附的模型快照，模式與 OpenCode 相同。

OpenAI 相容閘道

大多數彙整器（LiteLLM、one-api、new-api，以及免費或自行架設的閘道）都會公開 OpenAI 相容的表面。把下面這段加到你的 ax-code.json（全域在 ~/.config/ax-code/ax-code.json，專案則在儲存庫根目錄）：

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-gateway": {
      "name": "My Gateway",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o (via gateway)",
          "tool_call": true,
          "reasoning": false,
          "attachment": true,
          "limit": { "context": 128000, "output": 16384 },
        },
      },
    },
  },
}

• 鍵 "my-gateway" 是你在 /connect 與 ax-code models 中選擇的供應商 id。
• models 底下的每個鍵都是本機選擇 ID。當它與閘道預期的不同時，請把該項目的 id 設成閘道預期的精確模型 ID；否則，對於沒有既有目錄對應、且手動宣告的模型，就使用該鍵。
• 請優先使用 ${ENV_VAR}，不要用字面金鑰，這樣祕密就不會進到已提交的設定。

變更端點之後的閘道模型別名

變更 options.baseURL 並不會轉換手動設定的模型 ID。例如，AX Trust 端點可能宣告 deepseek-flash，而既有的本機選擇是 ax-trust/deepseek-v4-flash。請保留本機鍵，並把 provider.ax-trust.models.deepseek-v4-flash.id 設為 deepseek-flash。之後 AX Code 會在 API 請求中送出閘道 ID。

請見 AX Trust 的 DeepSeek Flash 設定範例。把相關的供應商欄位合併進你既有的設定，並保留其他模型與其能力設定。範例使用 {env:AX_TRUST_API_KEY}；請在啟動 AX Code 之前設定該環境變數，或沿用你既有的憑證設定。編輯之後請重新啟動 AX Code。

診斷 403 model is not allowed 時，請把請求的模型 ID 與端點已驗證的 GET /models 回應互相比較。只成功取得模型清單，並不能建立執行該模型的權限。若精確 ID 仍然失敗，請檢查閘道的金鑰與模型權限。

Anthropic 相容閘道

公開 /v1/messages（Claude API 的形式）的轉送，使用 Anthropic 配接器：

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-claude-gateway": {
      "name": "My Claude Gateway",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://gateway.example.com",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet (via gateway)",
          "tool_call": true,
          "reasoning": true,
          "attachment": true,
          "limit": { "context": 200000, "output": 64000 },
        },
      },
    },
  },
}

有些 Anthropic 形式的轉送也會直接遵守 Claude 的環境變數。若要在不編輯設定的情況下快速做一次無介面執行，可以設定：

export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-..."

若你希望閘道以自己的可選供應商出現，並帶有整理過的模型清單，仍然建議建立設定項目。

模型欄位

模型項目沿用登錄結構描述；對自訂端點來說，有用的欄位是：

請把能力旗標設成與上游模型實際支援的一致；AX Code 用它們來把關工具呼叫、附件與上下文預算。

驗證

儲存設定之後：

• ax-code models 會列出供應商公開的每一個模型。
• TUI 裡的 /connect 會顯示供應商；若你用的是 env 金鑰而不是 options.apiKey，也可以在那裡進行驗證。

若缺少某個模型，請確認供應商 id、模型鍵，以及閘道在 baseURL 可以連上。

疑難排解

• 驗證錯誤：確認憑證的解析順序。options.apiKey 優先，否則使用 env 或驗證存放區的金鑰。
• 串流停住：閘道有時會緩衝 SSE。請在供應商上調整 options.chunkTimeout（每個片段）與 options.timeout（整次請求）。
• 工具呼叫被拒：請在模型上設定 "tool_call": true，並確認閘道後面的上游模型確實支援工具。