Плагин GigaChat для OpenCode

English

Плагин подключает GigaChat / GigaCode к OpenCode. Он преобразует запросы и ответы между форматами OpenAI и GigaChat API v1.

Плагин поддерживает текст, вызовы инструментов, потоковые ответы и загрузку изображений. Он получает OAuth-токен и проверяет TLS-сертификаты при запросах к Сберу.

Установка и сборка

Для установки нужен OpenCode и готовый файл gigachat-plugin.js. Файл содержит код плагина и его зависимости. Сборка и npm install не нужны.

Установка плагина

1. Закройте OpenCode.

2. Скачайте gigachat-plugin.js из релиза v1.0.2.

3. Откройте терминал в папке со скачанным файлом.

4. Создайте папку плагинов:

   mkdir -p "$HOME/.config/opencode/plugins"

5. Скопируйте файл:

   cp gigachat-plugin.js "$HOME/.config/opencode/plugins/gigachat-plugin.js"

Установленный плагин находится в ~/.config/opencode/plugins/gigachat-plugin.js. OpenCode загружает его при запуске. Архивы Source code, которые показывает GitHub, нужны только для разработки.

Если в массиве plugin есть прежняя копия GigaChat-плагина, удалите её запись. Сохраните записи остальных плагинов.

Настройка конфигурации

1. Откройте ~/.config/opencode/opencode.json. Если файла нет, создайте его.
2. Добавьте провайдера GigaChat (Sberbank) в раздел provider.

Минимальный конфиг:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "GigaChat (Sberbank)": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.gigachat.local/v1",
        "verifySSL": true
      },
      "models": {
        "GigaChat": {
          "name": "GigaChat",
          "limit": { "context": 32000, "output": 4096 },
          "modalities": { "input": ["text"], "output": ["text"] }
        }
      }
    }
  }
}

Если в файле уже есть настройки, сохраните их. Добавьте только запись провайдера.

https://api.gigachat.local/v1 служит виртуальным адресом. Плагин отправляет запросы с этого адреса в https://api.giga.chat/v1.

Полный список моделей и параметры провайдера: конфигурация. Корпоративный адрес можно задать в options.baseURL.

Вход

1. Запустите команду:

   opencode providers login --provider "GigaChat (Sberbank)"

2. Выберите scope своего аккаунта:

   Scope	Тип аккаунта
   GIGACHAT_API_PERS	Физическое лицо
   GIGACHAT_API_B2B	Бизнес
   GIGACHAT_API_CORP	Корпоративный API

3. Вставьте ключ авторизации GigaChat в поле API key.

Используйте ключ Base64 из кабинета Sber Developers. Временный access_token для входа не подходит. OpenCode сохранит ключ и scope в своём хранилище авторизации.

Если у вас отдельно Client ID и Client Secret, выполните npm run encode-creds в клонированном репозитории. Команда создаст строку Base64(Client_ID:Client_Secret).

Плагин проверяет OAuth при первом запросе к модели. Альтернатива входу: переменные GIGACHAT_CREDENTIALS и GIGACHAT_SCOPE.

Запуск и проверка

1. Откройте терминал в папке своего проекта.

2. Запустите OpenCode:

   opencode --model "GigaChat (Sberbank)/GigaChat"

3. Отправьте запрос: «Ответь одним словом: работает».

4. Проверьте инструмент запросом: «Покажи файлы текущего проекта».

Для вывода журнала добавьте --print-logs к команде запуска. Если запрос завершился ошибкой, откройте руководство по ошибкам.

Обновление

1. Закройте OpenCode.
2. Скачайте gigachat-plugin.js из последнего релиза.
3. Замените файл ~/.config/opencode/plugins/gigachat-plugin.js скачанным файлом.
4. Запустите OpenCode.

Ключ и конфиг хранятся отдельно от файла плагина. Если вы установили ZIP из v1.0.1, после замены JS-файла папка ~/.config/opencode/plugins/gigachat-plugin/ больше не нужна. Её можно удалить. Остальные плагины сохраняйте.

Разработка

Исходники в src/ разделены на модули. Готовый файл генерируется без минификации и содержит пути исходных модулей. Для сборки из исходников нужен Node.js 18 или новее.

Сборка из исходников

1. Клонируйте репозиторий:

   git clone https://github.com/Overman775/opencode-gigachat-plugin.git

2. Откройте папку репозитория:

   cd opencode-gigachat-plugin

3. Установите зависимости:

   npm ci

4. Соберите плагин:

   npm run build:release

5. Проверьте код и готовый файл:

   npm test
   npm run test:release

Результат	Назначение
dist/gigachat-plugin.js	Готовый файл для установки
dist/index.js	Входной файл для разработки; требует остальные модули dist/ и npm-зависимости

Сборка и обновление заменяют изменения в готовых файлах.

Возможности и ограничения

• Плагин использует один аккаунт. Ключ можно сохранить через OpenCode, в конфиге или в переменных окружения.
• Если до истечения OAuth-токена осталось меньше 5 минут, следующий запрос обновляет токен. Срок возвращает сервер; обычно токен действует 30 минут.
• Одновременные запросы используют один запрос обновления токена.
• Плагин преобразует tools в functions и передаёт один вызов функции из сообщения.
• Плагин загружает изображения Base64 через /files, затем передаёт их идентификаторы в attachments.
• Плагин преобразует параметры reasoning_effort и thinking в системные инструкции. Подробнее: параметры рассуждений.
• При размере отдельной текстовой части сообщения больше 400 КБ плагин выводит предупреждение. Он не уменьшает эту часть автоматически.

Идентификаторы моделей: GigaChat, GigaChat-2, GigaChat-2-Lite, GigaChat-Plus, GigaChat-Pro, GigaChat-2-Pro, GigaChat-Max, GigaChat-2-Max. Плагин заменяет GigaChat-2-Lite на GigaChat-2.

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

Сертификаты

Проверка TLS включена по умолчанию. Плагин читает CA-бандл по заданному пути. Если файла нет, он использует встроенные сертификаты Минцифры.

Если нужен другой бандл, задайте путь в options.caBundle или GIGACHAT_CA_BUNDLE_FILE. Для корпоративного прокси включите его CA-сертификат в бандл вместе с сертификатами Минцифры.

Бандл Минцифры можно подготовить командами:

mkdir -p "$HOME/.config/opencode/certs"
curl --fail --show-error --location -o "$HOME/.config/opencode/certs/root.crt" https://gu-st.ru/content/lending/russian_trusted_root_ca_pem.crt
curl --fail --show-error --location -o "$HOME/.config/opencode/certs/sub.crt" https://gu-st.ru/content/lending/russian_trusted_sub_ca_pem.crt
cat "$HOME/.config/opencode/certs/root.crt" "$HOME/.config/opencode/certs/sub.crt" > "$HOME/.config/opencode/certs/russian_trusted_root_ca.pem"
rm "$HOME/.config/opencode/certs/root.crt" "$HOME/.config/opencode/certs/sub.crt"

Этот путь используется по умолчанию. verifySSL: false отключает проверку TLS. Используйте это значение только для временной диагностики, затем верните true.

Если verifySSL не задан в конфиге, проверку можно временно отключить через GIGACHAT_VERIFY_SSL=false.

Переменные окружения

Настройки провайдера и ключ из хранилища OpenCode имеют приоритет над переменными окружения.

Переменная	Значение по умолчанию	Назначение
GIGACHAT_CREDENTIALS	Нет	Ключ Base64(Client_ID:Client_Secret)
GIGACHAT_SCOPE	GIGACHAT_API_PERS	Scope ключа из переменной окружения
GIGACHAT_CA_BUNDLE_FILE	~/.config/opencode/certs/russian_trusted_root_ca.pem	Путь к CA-бандлу
GIGACHAT_VERIFY_SSL	true	Проверка TLS; false только для диагностики

Документация

• Конфигурация: параметры провайдера, модели и способы входа.
• Параметры рассуждений: варианты модели и поля ответа.
• Ошибки: причины и действия для проверки.
• Архитектура: модули, запросы, инструменты и сборка.
• API: адреса, заголовки и примеры сообщений.
• Статья автора: опыт подключения GigaChat к OpenCode.

Лицензия и статус проекта

Лицензия: MIT.

Проект создан как исследовательский прототип. Дальнейшая поддержка и развитие не планируются. Для связи по исправлениям используйте Telegram из профиля автора.

При работе над преобразованием запросов и вызовами функций автор использовал решения из ai-forever/gigachat. Проект независим от Сбербанка и команды GigaChat. «GigaChat», «GigaCode» и «Сбер» зарегистрированы как товарные знаки ПАО Сбербанк.