Эта страница переведена с английской документации. Команды, идентификаторы и примеры не изменены. Среда выполнения 7.24.4 · SDK 2.6.7. Английский оригинал

Пользовательские провайдеры и шлюзы

Статус: действует Область: текущее состояние Последняя проверка: 2026-09-06 Владелец: среда выполнения ax-code

AX Code обращается к моделям через стандартные протоколы провайдеров. Любую конечную точку с API, совместимым с OpenAI (/v1/chat/completions) или совместимым с Anthropic (/v1/messages), можно добавить как пользовательского провайдера, указав на неё baseURL. Менять код и ждать встроенного пресета не нужно.

Сюда входят самостоятельно размещённые агрегаторы и ретранслирующие шлюзы, такие как LiteLLM, one-api, new-api и Vercel AI Gateway, а также частные корпоративные прокси и любая другая совместимая служба. AX Code обращается с ними одинаково: он говорит на протоколе обмена, а URL и ключ задаёте вы.

Примечание об ответственности. Шлюз стоит между AX Code и вышестоящей моделью, поэтому через него проходят ваши промпты, код и учётные данные. Если вы направляете AX Code на сторонний ретранслятор или ретранслятор с общим пулом учётных записей, вы сами отвечаете за доверие к этому оператору и за соблюдение условий обслуживания каждого вышестоящего провайдера, куда он маршрутизирует. Встроенные пресеты шлюзов, например OpenRouter, используют тот же стандартный путь протокола. Настройка пользовательского шлюза не означает одобрения какого-либо оператора ретрансляции.

Интерактивная настройка

Используйте /connect → Облачный провайдер API → Пользовательский провайдер API для совместимого шлюза или /connect → AX Trust → Подключить AX Trust для шлюза AX Trust. Введите базовый URL (для AX Trust включая /v1) и клиентский ключ API. Редактор обнаруживает идентификаторы моделей и метаданные и хранит учётные данные в зашифрованном хранилище аутентификации. Он также может принять явные идентификаторы моделей, если обнаружение недоступно. Повторное подключение сохранённого URL сохраняет идентификатор провайдера и ключ, если токен оставлен пустым. Подключения AX Trust сохраняют свою категорию после правок и обновления моделей. На этих подключениях AX Code отправляет X-AX-Prompt-Cache-Key с идентификатором сеанса, чтобы шлюз мог удерживать сеанс на одной подходящей учётной записи. Задайте provider.<id>.options.axTrust равным false, чтобы это отключить. Этот заголовок не пересылается выше по цепочке и не является телом prompt_cache_key.

Подключённые провайдеры AX Trust в фоне обновляют списки моделей при запуске. AX Code вызывает GET /models настроенной конечной точки с существующими учётными данными и обновляет имена моделей, пределы контекста и вывода, рассуждение, вызов инструментов, поддержку температуры и поддержку изображений. Модели, способные принимать изображения, показывают маркер зрения в /models, включая псевдонимы шлюза, когда AX Trust объявляет их поддержку изображений. TUI обновляется, когда обнаружение завершается. Для точных собственных идентификаторов моделей DeepSeek недостающие метаданные заполняются из вложенного каталога models.dev. Явные флаги возможностей и пределы шлюза имеют приоритет. Неизвестные псевдонимы не наследуют возможности по сходству имён.

Успешное обновление заменяет список среды выполнения и убирает модели, которые шлюз больше не объявляет, и по-прежнему применяет настроенные списки разрешения и блокировки. Тайм-ауты, ошибки, пустые или недействительные ответы сохраняют сохранённый список и записывают неудачу обнаружения. Запуск не ждёт сети. Это обновление не переписывает конфигурацию провайдера и учётные данные. Сохранённая конфигурация остаётся запасным вариантом при запуске. Обычные пользовательские провайдеры API сохраняют ручное обновление.

Как разрешается провайдер

Для каждого запроса AX Code нужны от записи провайдера три вещи:

npm — адаптер AI SDK, который говорит на протоколе обмена. Используйте @ai-sdk/openai-compatible для конечных точек в стиле OpenAI и @ai-sdk/anthropic для конечных точек в стиле Anthropic. Вложены и устанавливаемы только адаптеры @ai-sdk/*.
options.baseURL — URL шлюза. Откатывается к полю провайдера api, затем к собственному api.url модели. Поддерживает подстановку ${ENV_VAR}.
Учётные данные — разрешаются по порядку из options.apiKey, затем из сохранённого хранилища аутентификации, затем из переменных провайдера env.

Ручная настройка также требует явной карты models. Интерактивный редактор заполняет эту карту из конечной точки или из идентификаторов моделей, которые вы задаёте.

Выделенные частные облака GPU — полноправные провайдеры в /connect → Частное облако GPU. Вставьте URL, совместимый с OpenAI, и токен (alibaba-pai, runpod, huggingface-endpoints, sagemaker, volcengine-ark, modelarts, tencent-ti или custom-private-gpu). AX Code вызывает GET …/models и автоматически использует идентификаторы развёрнутых моделей.

Каталоги размещённых 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.
Каждый ключ под models — локальный идентификатор выбора. Задайте id записи равным точному идентификатору модели, которого ждёт шлюз, если он отличается от этого ключа. Иначе ключ используется для вручную объявленных моделей без существующего сопоставления каталога.
Предпочитайте ${ENV_VAR} буквальному ключу, чтобы секрет не попал в зафиксированную конфигурацию.

Псевдонимы моделей шлюза после смены конечной точки

Смена options.baseURL не переводит вручную настроенные идентификаторы моделей. Например, конечная точка AX Trust может объявлять deepseek-flash, тогда как существующий локальный выбор — ax-trust/deepseek-v4-flash. Сохраните локальный ключ и задайте provider.ax-trust.models.deepseek-v4-flash.id равным deepseek-flash. Тогда AX Code отправляет идентификатор шлюза в запросах API.

См. пример настройки DeepSeek Flash в AX Trust. Влейте нужные поля провайдера в существующую конфигурацию, сохранив другие модели и их настройки возможностей. Пример использует {env:AX_TRUST_API_KEY}. Задайте эту переменную окружения до запуска AX Code или сохраните уже настроенные учётные данные. После правки перезапустите AX Code.

При диагностике 403 model is not allowed сравните идентификатор модели в запросе с аутентифицированным ответом GET /models конечной точки. Один успешный запрос списка моделей не устанавливает право запускать модель. Если точный идентификатор всё ещё не проходит, проверьте права ключа и модели на шлюзе.

Шлюз, совместимый с Anthropic

Ретрансляторы, которые открывают /v1/messages (форма API Claude), используют адаптер 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-..."

Запись конфигурации всё же рекомендуется, если шлюз должен появляться как собственный выбираемый провайдер с отобранным списком моделей.

Поля модели

Записи моделей повторно используют схему реестра. Для пользовательской конечной точки полезны такие поля:

Поле	Смысл
`name`	Подпись в выборе модели
`tool_call`	Поддерживает ли модель вызов инструментов и функций (нужно для инструментов)
`reasoning`	Выдаёт ли модель расширенное рассуждение
`attachment`	Принимает ли модель вложения изображений и файлов
`limit`	Пределы токенов `{ context, output }` для бюджетирования
`modalities`	Необязательные массивы `{ input, output }` (`text`, `image`, `pdf` и так далее)

Задайте флаги возможностей так, чтобы они совпадали с тем, что вышестоящая модель действительно поддерживает. AX Code по ним пропускает вызовы инструментов, вложения и бюджетирование контекста.

Проверка

После сохранения конфигурации:

ax-code models перечисляет каждую модель, которую открывает ваш провайдер.
/connect внутри TUI показывает провайдера и позволяет пройти аутентификацию, если вы использовали ключ env, а не options.apiKey.

Если модели нет, подтвердите идентификатор провайдера, ключ модели и то, что шлюз доступен по baseURL.

Устранение неполадок

Ошибки аутентификации — подтвердите порядок разрешения учётных данных: побеждает options.apiKey, иначе используется ключ env или хранилища аутентификации.
Застрявшие потоки — шлюзы иногда буферизуют SSE. Настройте options.chunkTimeout (на фрагмент) и options.timeout (на весь запрос) у провайдера.
Отклонённые вызовы инструментов — задайте "tool_call": true у модели и подтвердите, что вышестоящая модель за шлюзом действительно поддерживает инструменты.