Roo Code и собственный API: Base URL, ключ и модели (2026)

Roo Code — популярный агент для программирования в VS Code с несколькими режимами, назначением моделей по режимам и поддержкой собственных OpenAI-совместимых провайдеров. Для команд, работающих через единый шлюз, это удобно: фиксированный путь доступа, консолидированный счёт и лимиты по проектам.

Сначала важное изменение: по объявлению в репозитории Roo Code, Roo Code Inc. 15 мая 2026 года прекратила поддержку расширения Roo Code, основной репозиторий в тот же день архивирован, последняя версия — v3.54.0. Поддержку продолжил форк сообщества Zoo Code, сохранивший большую часть прежней конфигурации. Основной текст посвящён Zoo Code, различия старой версии Roo Code отмечены отдельно.

Примечание: Roo Code — товарный знак Roo Code, Inc.; Zoo Code — форк сообщества; VS Code — товарный знак Microsoft Corporation; OpenAI — товарный знак OpenAI, Inc. Материал носит технический характер и не означает подчинения или сотрудничества с указанными субъектами. Статус проекта, интерфейс и меню определяются объявлениями репозитория и документацией текущей версии.

1. Определите, что у вас: Roo Code или Zoo Code

Панели и настройки провайдера похожи, но статус поддержки разный:

Roo Code: ID расширения RooVeterinaryInc.roo-cline, основной репозиторий архивирован 15 мая 2026 года, расширение больше не обновляется. Установленная версия может работать, но исправлений и адаптации к новым моделям не будет.
Zoo Code: форк сообщества Roo Code под лицензией Apache-2.0, публикуется в VS Code Marketplace как ZooCodeOrganization.zoo-code, документация — на docs.zoocode.dev. Сохраняет режимы Code, Architect, Ask, Debug и другие.
Каталог настроек, .roomodes и .rooignore унаследованы, поэтому при миграции их обычно можно оставить; точные шаги — в документации по миграции Zoo Code.
При единой конфигурации в команде сначала убедитесь, что у всех установлено одно и то же расширение. Смешение старого Roo Code и Zoo Code даёт разные меню и настройки.

2. Подготовьте ключ, Base URL и модель

Перед началом нужны три вещи: API-ключ, OpenAI-совместимый адрес и точный ID модели.

Откройте страницу регистрации ZSQH AI Gateway, зарегистрируйтесь и войдите в консоль.
Перейдите в «API-ключи», создайте новый и укажите назначение в имени, например zoo-code-work.
Задайте лимит и срок действия. Даже для личного аккаунта это полезно, чтобы избежать аномального расхода.
Скопируйте ключ в менеджер паролей. Обычно консоль показывает его целиком только один раз.
Откройте цены на модели и запишите нужный ID. Цены и состав моделей меняются, ориентируйтесь на текущую страницу.

Три параметра выглядят так:

API Provider: OpenAI Compatible
Base URL:     https://ai.zhongshangqihang.com/v1
API Key:      sk-... (создан в консоли, хранится в менеджере паролей)
Model:        ID модели по текущей странице цен

Base URL — OpenAI-совместимый адрес, оканчивающийся на /v1. Не вписывайте корневой адрес Anthropic и не добавляйте /chat/completions вручную: иначе путь задвоится и появится 404.

3. Установка расширения в VS Code

Zoo Code требует VS Code 1.84.0 или новее. Порядок:

Откройте VS Code и нажмите Cmd/Ctrl + Shift + X, чтобы перейти к расширениям.
Найдите Zoo Code, выберите запись с издателем ZooCodeOrg и установите.
Если всё ещё используется старый Roo Code, ищите Roo Code от RooVeterinaryInc; помните, что поддержка прекращена.
После установки перезагрузите VS Code по подсказке. В панели активности появится значок расширения.
В VSCodium, Windsurf и других редакторах без Marketplace ищите то же расширение в Open VSX или установите VSIX из Releases вручную.
Если значок не появился, перезапустите VS Code, проверьте, что расширение включено, и посмотрите канал вывода в View → Output.

4. Настройка OpenAI Compatible Provider

Откройте панель настроек расширения и в списке API Provider выберите OpenAI Compatible. Этот пункт предназначен для совместимых сервисов не от OpenAI и не совпадает со встроенным провайдером OpenAI.

Поля для заполнения и проверки:

Base URL: https://ai.zhongshangqihang.com/v1, без /chat/completions.
API Key: ключ из консоли, без пробелов и переводов строк.
Model: ID модели, а не отображаемое имя и не комментарий.
Model Configuration: при необходимости укажите Context Window, Max Output Tokens, Image Support, Computer Use и цены входа/выхода. Поля цен влияют только на оценку стоимости в интерфейсе и не меняют фактический биллинг; если не уверены — оставьте пустыми.
Вызов инструментов: OpenAI Compatible Provider в Zoo Code и Roo Code поддерживает только нативный вызов инструментов OpenAI, без XML-фолбэка. Модель должна поддерживать OpenAI-совместимый function calling, иначе обычный чат может работать, а чтение и запись файлов агентом — нет.

Если шлюз реализует лишь часть протокола инструментов, сначала проверьте обычный диалог, затем чтение одного небольшого файла. Не начинайте с многофайлового рефакторинга — иначе причину ошибки не локализовать.

5. Как распределить модели по режимам

Roo Code и Zoo Code поддерживают несколько режимов и отдельную модель для каждого. Это позволяет балансировать стоимость и возможности:

Режим или сценарий	Рекомендуемый класс	Что учесть
Code: повседневная правка кода	Основная кодовая модель	Обязателен вызов инструментов, точно указать контекстное окно
Architect: проектирование	Сильная модель	Контекст можно увеличить, следить за стоимостью
Ask: объяснения и вопросы	Лёгкая быстрая модель	Без инструментов можно использовать дешёвый класс
Debug: поиск проблем	Основная или сильная модель	Достаточная длина вывода, чтобы не обрезало
Orchestrator: оркестрация задач	Модель со стабильными инструментами	Задать резервную модель для переключения

Каждому режиму стоит назначить резервную модель. Если основная упёрлась в лимит или недоступна, переключение на модель с тем же протоколом и теми же инструментами надёжнее повторных попыток. Доступность и цены — на странице цены на модели.

6. Проверка, что настройка действует

Смотреть только на ответ в панели недостаточно: ответ может прийти из другого режима. Проверяйте по порядку:

Создайте новую задачу, чтобы не мешал накопленный контекст.
Явно выберите только что настроенную модель, а не маршрут по умолчанию.
Отправьте короткий запрос, например попросите объяснить код до десяти строк.
Посмотрите журнал запросов шлюза: должна появиться запись с тем же временем, моделью и ключом.
Попросите прочитать небольшой файл — так проверяется цепочка вызова инструментов.
Если записи в журнале нет, запрос не дошёл до шлюза: возвращайтесь к Base URL и провайдеру.

Типичные ошибки:

Invalid API Key: ключ неверен, отключён, лимит исчерпан или заполнено не то поле провайдера.
Model Not Found: опечатка в ID или модель не открыта текущему аккаунту.
Connection Errors: Base URL недоступен либо проблема в прокси, TLS, межсетевом экране.
Ошибка вызова инструментов: модель не поддерживает нативный вызов или шлюз совместим лишь частично.
Результат не тот: сначала проверьте, какая модель привязана к режиму, затем промпт и контекст.

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

7. Права и автоодобрение

Агент для программирования читает и пишет файлы и выполняет команды, поэтому настройки прав важнее выбора модели. Меню Auto-Approve находится рядом с полем ввода; в нём есть общий переключатель Enabled и категории Read, Write, Execute, Browser, MCP.

Безопасная отправная точка:

Сначала включите только Read и убедитесь, что область чтения соответствует ожиданиям.
Write держите выключенным; включайте по необходимости и задайте задержку записи не менее 1000 мс.
Для Execute используйте белый и чёрный списки, не открывайте все команды через *.
Отключите чтение и запись вне рабочей области и редактирование защищённых файлов.
Не включайте автоодобрение в продуктивных репозиториях, каталогах с секретами и клиентскими данными.
Автоодобрение пропускает подтверждение и может привести к потере данных или повреждению файлов; выполнение команд особенно опасно.

Пример конфигурации команд в документации Roo Code использует префикс roo-cline.:

{
  "roo-cline.allowedCommands": ["git status", "npm run", "python -m pytest"],
  "roo-cline.deniedCommands": ["git push", "npm publish", "rm", "sudo"]
}

Zoo Code сохраняет прежние привычки настройки, но имена ключей и расположение меню могут меняться; ориентируйтесь на страницу настроек. Белый список сопоставляется по префиксу, запреты имеют приоритет; команды с опасными подстановками блокируются даже при совпадении префикса.

8. Чек-лист безопасности

Один ключ на одно назначение, без повторного использования между устройствами и проектами.
Задавайте лимит и срок действия, меняйте ключ регулярно; при подозрении на утечку сначала отключите, потом разбирайтесь.
Не записывайте ключ в код, .env, .vscode/settings.json или историю коммитов.
Исключайте через .rooignore файлы .env, учётные данные, артефакты сборки и журналы — меньше шансов, что агент их прочитает.
Не включайте автоодобрение в недоверенном репозитории; сначала убедитесь, что рабочая область безопасна.
Просматривайте изменения агента и команды терминала; перед важными операциями делайте коммит или контрольную точку.
В команде используйте единый шлюз, отдельные ключи каждому и журналы запросов для аудита и отзыва при увольнении.
Помните, что код и промпты покидают компьютер; команды с требованиями к хранению данных должны оценить это заранее.

9. Частые вопросы

Roo Code ещё работает?

По объявлению в репозитории расширение Roo Code прекратило работу 15 мая 2026 года, основной репозиторий архивирован. Установленная версия может запускаться, но исправлений и поддержки новых моделей не будет. Новым проектам стоит сразу брать форк сообщества Zoo Code.

Шаги настройки Roo Code и Zoo Code одинаковы?

В целом да: выбрать OpenAI Compatible, заполнить Base URL, ключ и модель. Отдельные названия меню и ключей настроек могут отличаться; сверяйтесь с текущими настройками и docs.zoocode.dev.

Base URL — корень или `/v1`?

При OpenAI-совместимом протоколе указывайте до /v1, например https://ai.zhongshangqihang.com/v1. Не добавляйте /chat/completions, иначе путь задвоится.

Что делать при Invalid API Key или Model Not Found?

Сначала убедитесь, что ключ вписан в форму OpenAI Compatible и Base URL соответствует окружению ключа; затем проверьте авторизацию через /v1/models. Model Not Found чаще означает опечатку в ID или отсутствие доступа к модели.

Почему не работает вызов инструментов?

OpenAI Compatible Provider поддерживает только нативный вызов инструментов, без XML-фолбэка. Модель или шлюз должны поддерживать OpenAI-совместимый function calling; иначе чат работает, а чтение и запись файлов падают. Попробуйте модель с поддержкой инструментов.

Дальше

Сначала зарегистрируйтесь в ZSQH AI Gateway, создайте отдельный ключ для Zoo Code и заполните Base URL и модель по этой инструкции. Когда заработают обычный диалог и чтение небольшого файла, настройте основные модели и лимиты для режимов по странице цены на модели.

Полезное чтение:

Примечание: Roo Code — товарный знак Roo Code, Inc.; Zoo Code — форк сообщества; VS Code — товарный знак Microsoft Corporation; OpenAI — товарный знак OpenAI, Inc. Материал носит технический характер и не означает подчинения или сотрудничества с указанными субъектами. Статус проекта, интерфейс и поведение интерфейсов могут меняться; ориентируйтесь на объявления репозитория и документацию проекта.