Как я подключал YandexGPT к AI-агентам (OpenCode, Pi, Hermes и Claude Code)

Я уже исследовал возможности интеграции разных моделей в инструменты разработки. Недавно решил плотно посмотреть на Yandex AI Studio и понять, как легко их модели залетают в популярные клиенты.

Главное открытие — у Яндекса отличная поддержка стандарта OpenAI «из коробки» (эндпоинт https://ai.api.cloud.yandex.net/v1). Оказывается, всё настраивается в разы проще, чем то, с чем я столкнулся при подключении GigaChat к OpenCode ^[1]. Там из-за разницы протоколов потребовались серьёзные танцы с бубном и написание собственного слоя совместимости. А здесь — никаких кастомных прокси или адаптеров для большинства тулзов. Достаточно прокинуть baseURL, API-ключ и передать ваш Folder ID в заголовке OpenAI-Project. Сами модели при этом лучше указывать полным URI (например, gpt://<folder_ID>/yandexgpt-5.1). Ниже я собрал рабочие конфиги, которые отладил в ходе ресерча.

Настройка для OpenCode

В ~/.config/opencode/opencode.json используем адаптер @ai-sdk/openai-compatible.

{
  "provider": {
    "yandex": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Yandex",
      "options": {
        "baseURL": "https://ai.api.cloud.yandex.net/v1",
        "apiKey": "<API_key>",
        "headers": {
          "OpenAI-Project": "<folder_ID>"
        }
      },
      "models": {
        "yandexgpt-5.1": {
          "id": "gpt://<folder_ID>/yandexgpt-5.1",
          "name": "YandexGPT Pro 5.1"
        }
      }
    }
  }
}

Настройка для Pi

Для Pi добавляем провайдера в ~/.pi/agent/models.json с типом openai-completions и отключаем фичи, которые Yandex пока не переваривает.

{
  "providers": {
    "yandex": {
      "baseUrl": "https://ai.api.cloud.yandex.net/v1",
      "api": "openai-completions",
      "apiKey": "<API_key>",
      "authHeader": true,
      "headers": {
        "OpenAI-Project": "<folder_ID>"
      },
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "gpt://<folder_ID>/yandexgpt-5.1",
          "name": "YandexGPT Pro 5.1"
        }
      ]
    }
  }
}

Настройка для Hermes

Hermes тоже умеет в custom провайдеры. Главное — прокинуть заголовок проекта.

model:
  default: "gpt://<folder_ID>/yandexgpt-5.1"
  provider: custom
  base_url: "https://ai.api.cloud.yandex.net/v1"
  api_key: "<API_key>"
headers:
  OpenAI-Project: "<folder_ID>"

С Claude Code история получилась немного другой. Настроить его «в лоб», как Pi или OpenCode, нельзя. Дело в том, что Claude Code общается через Anthropic Messages API, а Yandex отдает OpenAI-совместимый интерфейс. Так что для него обязательно понадобится поднимать gateway-переводчик. Всё остальное завелось буквально с пол-оборота. Единственный нюанс — чтобы запросы пошли и модели начали отвечать, не забудьте включить биллинг в консоли облака. Но по сравнению с написанием собственных адаптеров с нуля, это вообще не проблема.