Roo Code в VS Code: надёжная настройка OpenAI-совместимой модели и проверка tool calling

Агент в редакторе полезен не тем, что умеет продолжать строку, а тем, что может читать рабочие файлы, планировать изменение и вызывать инструменты в контролируемом цикле. Для такой работы важны три вещи: совместимость протокола, корректный идентификатор модели и воспроизводимая проверка после настройки. Ниже — практический маршрут для Roo Code в VS Code с API Ace Data Cloud. Он рассчитан на разработчиков, работающих с несколькими моделями и желающих отделить проверку транспорта от проверки агентских действий.

Что именно настраивается

Roo Code поддерживает провайдера OpenAI Compatible. В этом режиме расширение отправляет запросы в формате OpenAI Chat Completions и ожидает, что выбранная модель умеет нативный вызов функций. Это существенная деталь: успешный текстовый диалог ещё не доказывает, что агент способен вызывать инструменты. Модель и сервер должны корректно передавать структуру вызова, аргументы и результат инструмента, в том числе при потоковой выдаче.

У Ace Data Cloud базовая точка для OpenAI-совместимого сценария — https://api.acedata.cloud/v1. Платформа объединяет доступ к нескольким семействам моделей за одним endpoint; текущий каталог следует получать программно, а не переносить в конфигурацию устаревшее имя из старого примера. Сведения об аккаунте и приложениях находятся в консоли приложений, а актуальные руководства — в документации. Общая русскоязычная страница платформы доступна по адресу platform.acedata.cloud/ru.

Подготовка токена и модели

Сначала создайте или выберите приложение для разработки в консоли и выпустите токен с необходимой областью доступа. Не помещайте ключ в репозиторий, настройки рабочей области или скриншоты. Для локальной диагностики удобно хранить его в переменной окружения текущего терминала. Следующая команда получает доступный в данный момент каталог моделей:

export ACE_API_TOKEN="ваш_токен"

curl -sS https://api.acedata.cloud/v1/models \
  -H "Authorization: Bearer $ACE_API_TOKEN" \
  -H "Content-Type: application/json"

В ответе найдите точный id модели, поддерживающей нативные tools. Не подменяйте его названием клиентского приложения: Roo Code — это клиент, а идентификатор модели выбирается отдельно. При выборе сопоставьте реальные возможности модели с задачей: контекст, максимальный вывод, работу с изображениями и компьютерными действиями. Не включайте возможности лишь потому, что они видны в интерфейсе расширения.

Настройка Roo Code в VS Code

Откройте настройки расширения Roo Code и создайте профиль провайдера. Затем укажите следующие значения:

• API Provider: OpenAI Compatible;
• Base URL: https://api.acedata.cloud/v1;
• API Key: токен приложения для разработки;
• Model ID: точный идентификатор из каталога моделей.

Сохраните профиль и полностью перезагрузите окно VS Code. Перезапуск важен: расширение может держать прежние параметры и активные соединения в памяти. Если в вашем профиле есть поле для максимального числа выходных токенов, задавайте его с запасом для кода и промежуточных действий. Для задач с файлами также проверьте размер доступного контекста, а для мультимодальных задач — явное наличие нужной способности у выбранной модели.

Проверка транспорта до запуска агента

Проверку стоит разделить на независимые шаги. Сначала выполните простой запрос без инструментов. Он обнаруживает проблемы с токеном, URL, заголовками, названием модели и форматом полезной нагрузки. Команда ниже отправляет короткую инструкцию; замените MODEL_ID реальным значением из каталога.

curl -sS https://api.acedata.cloud/v1/chat/completions \
  -H "Authorization: Bearer $ACE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {"role": "user", "content": "Ответь строго: OK"}
    ],
    "temperature": 0
  }'

Ожидаемый смысловой результат — OK. После этого выполните ту же проверку внутри Roo Code. Если внешний запрос проходит, а расширение нет, сравнивайте Base URL, секрет и точный Model ID, а также смотрите журнал расширения. Такой порядок заметно сокращает область поиска: сеть и учётные данные уже исключены.

Python-проверка и обработка ошибок

В CI или локальном bootstrap-скрипте можно проверять конфигурацию на Python. Пример использует только стандартную библиотеку, поэтому его можно запустить без дополнительной установки пакетов. Он завершится ненулевым кодом при ошибке HTTP и выведет краткий текст ответа для диагностики.

import json
import os
from urllib.error import HTTPError
from urllib.request import Request, urlopen

url = "https://api.acedata.cloud/v1/chat/completions"
payload = {
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Ответь строго: OK"}],
    "temperature": 0,
}
request = Request(
    url,
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['ACE_API_TOKEN']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request, timeout=30) as response:
        print(json.load(response)["choices"][0]["message"]["content"])
except HTTPError as error:
    print(error.code, error.read().decode("utf-8"), flush=True)
    raise

Для production-окружения добавьте ограничение повторов с экспоненциальной паузой только для временных ошибок, метрики задержки и уникальный идентификатор запроса в собственные логи. Не логируйте токен и полный пользовательский контекст: в диагностике обычно достаточно кода ответа, длительности, имени модели и безопасного request ID.

Тест нативного вызова инструментов

Теперь переходите к агентскому сценарию. В Roo Code попросите: «Ответь только OK», а затем поручите прочитать небольшой тестовый файл в рабочем каталоге и сообщить его первую строку. Наблюдайте, появился ли вызов инструмента и вернулся ли результат. Если обычный диалог успешен, но агентское действие не выполняется, наиболее вероятная причина — выбранная модель не поддерживает нативные tools либо несовместимая реализация не передаёт аргументы и результаты в ожидаемом формате.

Не исправляйте это повышением температуры, бесконечными повторами или произвольным изменением системных инструкций. Сначала выберите другую модель из актуального каталога, которая заявляет нужную возможность. Затем повторите короткий файловый тест. Лишь после успешного минимального сценария включайте более сложные действия: редактирование нескольких файлов, терминальные команды, изображения или компьютерные операции.

Эксплуатационный чек-лист

• Проверяйте каталог моделей перед обновлением профиля и фиксируйте выбранный Model ID в защищённой конфигурации.
• Держите отдельные токены для локальной разработки, CI и командных интеграций; ограничивайте их область и срок действия по политике команды.
• Начинайте с теста «OK», затем проверяйте чтение одного файла и только потом разрешайте изменения в проекте.
• Ведите журнал кодов ответа и задержек, но исключайте секреты и содержимое приватных файлов.
• Пересматривайте лимиты контекста и вывода при смене модели: эти параметры влияют на качество агентской работы и расход Credits.

Такая последовательность превращает подключение редакторного агента из разовой ручной настройки в проверяемую инженерную процедуру. Единый endpoint упрощает инфраструктуру, а явная проверка совместимости tools помогает обнаружить проблему до того, как агент начнёт менять файлы в рабочем проекте.

Как закрепить настройку в команде

Хорошая практика — описать минимальную проверку в файле onboarding проекта. Укажите переменную с секретом, команду получения каталога, один запрос чата и сценарий чтения безопасного демонстрационного файла. Тогда новый участник команды не копирует неявные параметры из чужого редактора, а проходит одинаковый набор шагов. В CI можно выполнять только сетевой smoke-test: он подтверждает действительность токена и доступность модели, но не раскрывает исходный код. Для агентских задач полезно заранее определить границы: какие каталоги разрешены для чтения, какие команды допустимы и когда изменение файла требует просмотра diff человеком.

Отдельно договоритесь, как обновлять профиль. Изменение модели, лимита вывода или политики доступа оформляйте короткой записью в журнале команды: дата, причина, идентификатор модели, результат теста и ответственное лицо. Это помогает объяснять различия в поведении агента и быстрее возвращать известную рабочую конфигурацию. При инциденте сначала воспроизведите минимальный запрос вне редактора, затем сравните параметры профиля, и только после этого анализируйте конкретную задачу агента. Такой порядок сохраняет диагностику короткой и проверяемой.