Roo Code

Roo Code — расширение для VS Code, Cursor и VSCodium, которое работает как агент по разработке: читает файлы проекта, пишет и правит код, запускает команды в терминале и сам продолжает задачу после ошибки. Он не «дописывает строку по Tab» — он выполняет многошаговые задачи целиком, и каждый шаг стоит токенов, поэтому модель под ним стоит выбирать осознанно. С SpeShu.AI расширение работает через OpenAI-совместимый режим: меняются только базовый адрес и ключ, код агента и его набор инструментов остаются прежними.

Подключение сводится к двум значениям: https://speshu.ai/api/v1 как базовый адрес и ваш API-ключ. Эндпоинт /api/v1/chat/completions совместим с OpenAI Chat Completions, поэтому Roo Code обращается к нему обычным OpenAI-запросом — менять настройки расширения сверх адреса и ключа не нужно. Ключ создаётся на speshu.ai/profile, подробности — в разделе Аутентификация.

Установка

Установите расширение

Откройте панель Extensions в редакторе (Ctrl+Shift+X на Windows и Linux, Cmd+Shift+X на macOS), найдите Roo Code и нажмите Install. Расширение ставится в VS Code, Cursor и VSCodium одинаково — это один и тот же пакет.

Откройте панель Roo Code

Значок расширения появится в боковой панели. Откройте его и нажмите на иконку шестерёнки — это настройки API-конфигурации.

Ключ и идентификатор модели

Ключ не зашивайте ни в настройки расширения, ни в репозиторий: Roo Code хранит конфигурацию в состоянии редактора, и файл с ключом нередко попадает в бэкапы и на общие машины. Получите ключ и сохраните его в менеджере секретов или переменной окружения.

export SPESHU_API_KEY="sk-ваш-ключ"
curl -s https://speshu.ai/api/v1/balance \
  -H "Authorization: Bearer $SPESHU_API_KEY"

Пустой объект {} — корректный ответ: ключ рабочий, записей в кошельке пока нет. Ответ 401 invalid_api_key означает, что ключ недействителен, отозван или истёк. Идентификатор текстовой модели возьмите из каталога и положите в переменную окружения:

cURL

export TEXT_MODEL=$(curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data[0].id')
echo "$TEXT_MODEL"

Идентификатор текстовой модели нельзя зашивать в настройки: состав каталога меняется, модели уходят и переименовываются, и зашитый идентификатор начинает падать с 404 model_not_found без предупреждения. Формат ответа и параметры выбора — в разделе Модели и цены.

Для агентной работы по коду смотрите в каталоге на context_length и cost_completion: Roo Code отправляет выбранные файлы целиком, и длинный контекст на дорогой модели съедает баланс быстрее, чем сама задача. Провайдер модели виден в поле owned_by.

Настройка подключения

В Roo Code настройка провайдера живёт в панели расширения, за иконкой шестерёнки. Дальше ориентируйтесь на эти шаги — точные подписи полей немного расходятся между версиями расширения.

Откройте список провайдеров

В настройках API найдите выпадающий список API Provider и выберите вариант OpenAI Compatible. Это OpenAI-совместимый режим: он единственный позволяет задать свой базовый адрес и пользоваться каталогом моделей SpeShu.AI.

Задайте базовый адрес

В поле Base URL (в части версий он называется OpenAI Base URL) впишите https://speshu.ai/api/v1 — без завершающего слэша.

Вставьте ключ

В поле API Key вставьте значение sk-.... Roo Code отправляет его заголовком Authorization: Bearer — это то, что ожидает /api/v1/chat/completions.

Укажите модель

В поле Model ID вставьте значение $TEXT_MODEL из шага выше. Roo Code сам запрашивает список моделей у OpenAI-совместимого провайдера, поэтому поле заполнится автоматически; если не заполнилось, впишите идентификатор вручную — тем же значением, что вернул GET /api/v1/models.

Зафиксируйте режим конфигурации

В настройках есть переключатель Global settings и Settings (Current session). В режиме сессии настройки живут только до перезапуска редактора и не попадают в общие настройки — для рабочей интеграции выбирайте глобальный режим.

Адрес должен заканчиваться ровно на /v1. Варианты https://speshu.ai/api и https://speshu.ai/api/v1/ дают 404 при верных ключе и модели — Roo Code склеивает базовый адрес с /chat/completions и получает несуществующий путь.

Конфигурация файлом

Если настройку нужно раздать на несколько машин или положить в IaC, Roo Code умеет экспортировать её в JSON: в настройках нажмите Export Settings — расширение спросит имя файла и запишет всю конфигурацию, включая ключ.

Экспортированный файл содержит API-ключ открытым текстом. Не коммитьте его и не кладите в общий доступ: добавьте в .gitignore или удалите сразу после импорта. Лучше раздавать конфигурацию без ключа и подставлять его при первом запуске.

Форма файла зависит от версии расширения: Roo Code развивается, и имена полей внутри менялись. Надёжный способ узнать имена — сделать Export Settings у себя и посмотреть блок API-конфигурации. По смыслу он выглядит так:

{
  "apiConfiguration": {
    "apiProvider": "openai-compatible",
    "openAiBaseUrl": "https://speshu.ai/api/v1",
    "openAiApiKey": "sk-ваш-ключ",
    "openAiModelId": "<идентификатор из GET /api/v1/models>"
  }
}

Готовый файл импортируется обратно через Import Settings. Точный путь к файлам состояния, если нужно посмотреть их вручную, — globalStorage расширения в каталоге пользовательских данных редактора: ~/.config/Code/User/globalStorage/ на Linux, ~/Library/Application Support/Code/User/globalStorage/ на macOS, %APPDATA%\Code\User\globalStorage\ на Windows. У Cursor каталог называется иначе, но уровень вложенности тот же.

Первый запрос и проверка

Прежде чем запускать агента, убедитесь, что адрес, ключ и модель работают вместе — обычным запросом к API вне редактора:

cURL

curl -s https://speshu.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$TEXT_MODEL\",
    \"messages\": [{\"role\": \"user\", \"content\": \"Ответь одним словом: работает?\"}]
  }" | jq -r '.choices[0].message.content, .usage.cost.total_cost'

Если команда ответила текстом и числом списания — адрес и ключ верны, а вопрос остался только к настройкам расширения. usage.cost.total_cost — сумма, списанная с кошелька в рублях; её имеет смысл записать до начала работы агента, чтобы потом сверить расход. Подробности — в разделе Тарификация и оплата.

Проверьте в Roo Code

Откройте чат в панели расширения и отправьте короткий вопрос: «Ответь одним словом: работает?». Ответ означает, что подключение собрано верно.

Проверьте инструмент, а не только текст

Попросите расширение прочитать один файл из открытого проекта: «Прочитай README.md и назови его первый заголовок». Если текст пришёл, а файл не открылся — модель не отдаёт вызовы инструментов, и это отдельная проблема от адреса и ключа.

Сделайте первый платный шаг осознанно

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

Что работает

Потоковую передачу включать не нужно. Roo Code всегда запрашивает ответ потоком и показывает токены по мере поступления — менять настройки для этого не требуется. Разбор формата кадров, маркера [DONE] и кадра со списанием — на странице Потоковая передача. Инструменты агента. Roo Code сам собирает свой набор инструментов и отправляет его в поле tools запроса, а вызовы читает в choices[0].message.tool_calls — тот же протокол, что и в обычном чате. Схема и разбор аргументов — в гайде Вызов функций. Требование к модели одно: она должна уметь вызывать инструменты. Модель без такой способности ответит текстом, и задача встанет. MCP-серверы. Инструменты из подключённых MCP-серверов попадают в тот же набор, что и встроенные. Настройка серверов — в гайде MCP. Изображения. Если в контекст задачи попала картинка, Roo Code передаёт её как блок image_url. Модель без зрения отвергнет такой запрос целиком с 400 invalid_request — картинка не будет молча проигнорирована. Требования к ссылке, base64 и загрузке через хранилище разобраны в гайде Медиаввод.

Генерация изображений, видео и музыки в Roo Code не встроена. Это отдельный асинхронный API: запрос создаёт задачу, оплата идёт при создании, результат приходит по опросу. Идентификаторы медиа-моделей стабильны — например, nano-banana-2; их каталог открыт без ключа. Формат запроса — в разделе Создать задачу.

Про контекст

Roo Code сам собирает контекст из открытых файлов и истории диалога, и размер запроса часто оказывается главным ограничением, а не качество модели. Каталог сообщает окно каждой модели в поле context_length:

cURL

curl -s https://speshu.ai/api/v1/models \
  -H "Authorization: Bearer $SPESHU_API_KEY" \
  | jq -r '.data[] | "\(.id) — \(.context_length)"'

Если вход не помещается вместе с зарезервированным выходом, приходит 422 content_too_large с числами в тексте ошибки. Лечится это не повтором: сокращайте задачу, сужайте набор файлов или берите модель с окном побольше.

Типичные проблемы

404 на первом же запросе, хотя ключ и модель верны

Проверьте базовый адрес: он должен быть ровно https://speshu.ai/api/v1 — без завершающего слэша и без потерянного /v1. Обе частые ошибки дают 404 при полностью рабочем ключе.

401 invalid_api_key

В поле ключа остались кавычки или перенос строки, либо ключ отозван в профиле. Проверьте его напрямую запросом баланса — он ничего не стоит. Разбор — в разделе Аутентификация.

404 model_not_found

Идентификатор в поле Model ID устарел или скопирован с ошибкой. Возьмите его заново из GET /api/v1/models и подставьте как есть — без префикса и без обрезки.

Модель отвечает текстом, но не вызывает инструменты и задача не двигается

Модель не поддерживает вызов функций. Roo Code отправляет свой набор инструментов, но если модель их не принимает, она просто продолжает рассуждать текстом. Возьмите из каталога модель с поддержкой инструментов.

Агент зависает на большой задаче и получает 504 gateway_timeout

Потолок одного запроса — 300 секунд, и он достигается на длинном контексте с большим резервируемым выходом. Сократите объём задачи, разбейте её на шаги или возьмите модель с большим окном и меньшей ценой выходных токенов.

402 insufficient_quota

На балансе нет положительной суммы. Проверка баланса делается до обращения к модели, деньги за отказ не списываются. Пополнение — на speshu.ai/profile.

Всё остальное

Полная таблица кодов, три формата ошибок и цикл повторов — на странице Ошибки, таймауты и квоты — в разделе Лимиты.

Что дальше

Модели и цены

Как выбрать модель под объём контекста агента

Вызов функций

Как устроен вызов инструмента и разбор аргументов

Запрос чату

Поля запроса и формат ответа

Ошибки

Полная таблица кодов

Начало работы

Возможности моделей

Генерация медиа

Фреймворки

Базы данных

Агенты и редакторы

No-code и автоматизация

Установка

Ключ и идентификатор модели

Настройка подключения

Конфигурация файлом

Первый запрос и проверка

Что работает

Про контекст

Типичные проблемы

Что дальше

Модели и цены

Вызов функций

Запрос чату

Ошибки

​Установка

​Ключ и идентификатор модели

​Настройка подключения

​Конфигурация файлом

​Первый запрос и проверка

​Что работает

​Про контекст

​Типичные проблемы

​Что дальше

Модели и цены

Вызов функций

Запрос чату

Ошибки

Установка

Ключ и идентификатор модели

Настройка подключения

Конфигурация файлом

Первый запрос и проверка

Что работает

Про контекст

Типичные проблемы

Что дальше