Настройка OpenAI-совместимого провайдера в OpenCode: Маршрутизация моделей для кодирования через Flatkey

Настройка OpenCode OpenAI-совместимого провайдера полезна, когда вы хотите, чтобы OpenCode обращался к маршруту модели, который ведет себя как OpenAI Chat Completions API, в то время как ваша команда сохраняет владение ключами, маршрутизацию моделей и анализ использования в одном шлюзе.

Важно то, что в OpenCode есть документированный путь для пользовательских провайдеров. В документации по провайдерам OpenCode, проверенной 8 июля 2026 года, последовательность действий такова: добавьте учетные данные с помощью /connect, выберите Other для провайдера, которого еще нет в списке, дайте этому провайдеру запоминающийся ID, настройте провайдера в opencode.json, а затем выполните /models, чтобы выбрать одну из настроенных моделей.

Flatkey подходит под эту схему в качестве шлюза, стоящего за провайдером. Вы оставляете OpenCode в качестве агента для кодирования, указываете провайдеру базовый URL OpenAI-совместимого API Flatkey и проверяете, что трафик моделей OpenCode появляется в журналах использования или запросов Flatkey, прежде чем сделать его маршрутом по умолчанию.

Краткий ответ по настройке OpenAI-совместимого провайдера в OpenCode

Используйте эту схему настройки, когда конечная точка модели совместима с Chat Completions.

Это руководство по настройке OpenAI-совместимого провайдера в OpenCode использует шаблоны. Проверьте точные псевдонимы моделей и семейство конечных точек в вашем аккаунте Flatkey, прежде чем маршрутизировать рабочие задачи агента для кодирования.

Что требуется для OpenCode

OpenCode имеет два отдельных элемента состояния для пользовательского провайдера.

Конфигурация OpenCode может быть в формате JSON или JSONC. Вы можете разместить ее глобально по пути ~/.config/opencode/opencode.json или в корне проекта как opencode.json. Конфигурация проекта имеет более высокий стандартный приоритет, поэтому используйте файл проекта, если вы хотите протестировать Flatkey в одном репозитории, не изменяя каждое рабочее пространство OpenCode.

Шаг 1: Создайте ключ Flatkey для OpenCode

Создайте ключ Flatkey для этой рабочей нагрузки и запишите три значения вне системы контроля версий.

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_MODEL=your-current-flatkey-model-alias

Держите корневой API отдельно от пути конечной точки. В конфигурации провайдера OpenCode следует использовать https://router.flatkey.ai/v1 в качестве options.baseURL; прямые дымовые тесты HTTP добавляют /chat/completions.

Перед подключением OpenCode выполните прямой тест с тем же ключом Flatkey и псевдонимом модели.

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      { "role": "user", "content": "Ответьте в точности: flatkey route ok" }
    ]
  }'

Если этот прямой запрос не удался, исправьте ключ Flatkey, псевдоним модели, семейство конечных точек или маршрут учетной записи, прежде чем отлаживать OpenCode. OpenAI-совместимый провайдер OpenCode не может компенсировать псевдоним модели, который учетная запись шлюза не может вызвать.

Шаг 2: Добавьте учетные данные Flatkey в OpenCode

OpenCode хранит учетные данные провайдера через /connect. В TUI OpenCode:

/connect

Выберите Other, введите ID провайдера, например flatkey, затем вставьте API-ключ Flatkey. Не вставляйте базовый URL в поле для учетных данных. Ключ подтверждает личность; базовый URL должен находиться в opencode.json.

Используйте простой идентификатор провайдера. flatkey лучше, чем flatkey-prod-openai-compatible-gateway-v2, потому что вы будете вводить его в идентификаторах моделей и заметках по откату.

Шаг 3: Добавьте конфигурацию провайдера OpenCode

Создайте или обновите opencode.json в корне проекта, который вы хотите протестировать.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "your-current-flatkey-model-alias": {
          "name": "Flatkey primary model"
        }
      }
    }
  },
  "model": "flatkey/your-current-flatkey-model-alias"
}

Это самая минимальная конфигурация для OpenAI-совместимого провайдера в OpenCode. Она предоставляет OpenCode провайдера с именем flatkey, указывает OpenCode использовать пакет AI SDK, совместимый с OpenAI, и отображает один псевдоним модели в средстве выбора моделей.

Если вы хотите, чтобы OpenCode использовал меньший маршрут для легковесных задач, добавьте small_model только после того, как основной маршрут заработает.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "flatkey": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Flatkey",
      "options": {
        "baseURL": "https://router.flatkey.ai/v1"
      },
      "models": {
        "primary-flatkey-model-alias": {
          "name": "Flatkey primary"
        },
        "lighter-flatkey-model-alias": {
          "name": "Flatkey lightweight"
        }
      }
    }
  },
  "model": "flatkey/primary-flatkey-model-alias",
  "small_model": "flatkey/lighter-flatkey-model-alias"
}

Используйте псевдонимы моделей, которые ваш ключ Flatkey действительно может вызывать. Если ваша учетная запись предоставляет аутентифицированный маршрут /v1/models, сравните настроенные идентификаторы моделей с этим ответом. В противном случае скопируйте псевдонимы из текущей панели управления Flatkey или каталога моделей и проверьте их с помощью реального запроса.

Шаг 4: Выберите и протестируйте модель в OpenCode

После сохранения конфигурации откройте средство выбора моделей.

/models

Выберите модель провайдера Flatkey. Затем выполните небольшой запрос в OpenCode:

Reply with exactly: opencode flatkey route ok

Пока не переносите весь рабочий процесс кодирования. Сначала сохраните компактный пакет верификации.

Это превращает миграцию OpenAI-совместимого провайдера в OpenCode в небольшое операционное изменение вместо слепой замены провайдера.

Шаг 5: Разделяйте Chat Completions и Responses

В документации OpenCode по пользовательским провайдерам указано разграничение пакетов: используйте @ai-sdk/openai-compatible для OpenAI-совместимых провайдеров, которые используют /v1/chat/completions; если провайдер или модель используют /v1/responses, используйте @ai-sdk/openai.

Это означает, что первый маршрут Flatkey должен быть моделью в стиле Chat Completions, если у вас нет актуальных доказательств того, что выбранная вами модель и клиентский путь используют другое семейство конечных точек.

Используйте эту таблицу принятия решений перед добавлением новых моделей.

Для большинства настроек начинайте с одного маршрута Chat Completions. Добавляйте потоковую передачу, вызовы инструментов и вторичные псевдонимы моделей после того, как первый дымовой тест OpenAI-совместимого провайдера в OpenCode станет виден в Flatkey.

Шаг 6: Добавьте средства управления для команды после того, как маршрут заработает

Как только OpenCode сможет вызывать Flatkey, сделайте маршрут наблюдаемым.

Именно здесь Flatkey становится чем-то большим, чем просто базовый URL. Рабочий OpenAI-совместимый провайдер для OpenCode также должен предоставлять командам платформы, финансов и эксплуатации место для анализа использования моделей и изменения маршрута, не требуя от каждого разработчика управления отдельными учетными записями провайдеров.

Для более широкого планирования миграции используйте это руководство вместе с руководством по миграции OpenAI-совместимого API от Flatkey. Если вы сравниваете смежные инструменты для кодирования, ознакомьтесь с руководством по настройке OpenAI-совместимого провайдера для Continue.dev и руководством по настройке OpenAI-совместимого API для Roo Code.

Устранение неполадок с OpenAI-совместимым провайдером для OpenCode

Если первый запрос не удался, пока не меняйте промпты, агентов, разрешения или код репозитория. Ограничьте область отладки OpenAI-совместимого провайдера для OpenCode до минимума: учетные данные, ID провайдера, базовый URL, пакет, псевдоним модели и один простой запрос в чат.

Итоговый чек-лист

Прежде чем использовать Flatkey в качестве маршрута по умолчанию для OpenCode, убедитесь в следующем:

1. В /connect есть учетные данные Flatkey с тем же ID провайдера, который используется в opencode.json.
2. provider.flatkey.npm имеет значение @ai-sdk/openai-compatible для маршрута Chat Completions.
3. provider.flatkey.options.baseURL имеет значение https://router.flatkey.ai/v1.
4. model указывает на настроенное значение flatkey/<model-alias>.
5. В /models отображается настроенная модель Flatkey.
6. Однострочный промпт в OpenCode успешно возвращает ответ.
7. В журналах использования или запросов Flatkey отображается тестовый запрос от OpenCode.
8. Предыдущий маршрут провайдера/модели задокументирован для возможности отката.

Настройка OpenAI-совместимого провайдера для OpenCode считается завершенной, когда провайдер настроен, доступен для выбора, проверен в журналах Flatkey и его изменения обратимы. Когда вы будете готовы маршрутизировать трафик моделей для кодирования через один ключ, получите ключ Flatkey и начните с одного низкорискового промпта в OpenCode.