API-ключ в Roo Code определяет, к какому поставщику уходят запросы, какие модели доступны, на кого ложатся расходы и каковы последствия утечки. Многие случаи «ключ не работает» на деле оказываются ошибкой в Base URL, имени модели или типе Provider.

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

Примечание: Roo Code — товарный знак своего правообладателя, VS Code — товарный знак Microsoft. Статья носит технический характер и не означает аффилированности с упомянутыми компаниями. Расширение Roo Code прекратило поддержку 15 мая 2026 года, репозиторий в тот же день архивирован; актуальный статус проверяйте в официальном репозитории и документации. Модели и цены — по тарифам на модели.

1. Сначала определите ситуацию и тип ключа

Roo Code — открытый AI-агент для программирования в VS Code, работающий по модели BYOK (bring your own key): расширение не собирает плату за модели, вызовы тарифицируются ключом поставщика, который вы указали. Оно поддерживает нескольких поставщиков и OpenAI-совместимые эндпоинты.

Сначала о статусе: по публичной информации, расширение Roo Code прекратило поддержку 15 мая 2026 года, исходный репозиторий архивирован, новых функций, исправлений ошибок и патчей безопасности больше не будет. Установленные копии обычно продолжают работать, но при долгом использовании отсутствие патчей нужно учитывать как риск. Форк сообщества Zoo Code развивается на основе исходного кода под лицензией Apache-2.0.

«API-ключ Roo Code» обычно означает ключ поставщика, совместимый ключ шлюза или адрес локальной модели вроде Ollama. Здесь речь о втором варианте: он не используется для входа в Roo Code и не даёт доступа к его облачным сервисам.

2. Создание ключа: сначала границы, потом копирование

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

  1. Откройте страницу регистрации ZSQH AI Gateway, зарегистрируйтесь и войдите в консоль.
  2. Перейдите в раздел «API-ключи» и нажмите создание.
  3. Укажите пользователя и устройство в названии, например roo-zhang-macbook, а не просто test.
  4. Задайте лимит и срок действия; тестовому ключу сначала дайте небольшой лимит.
  5. Если консоль поддерживает ограничение по моделям, отметьте только те, которые действительно нужны.
  6. Скопируйте полный ключ в менеджер паролей — большинство консолей показывает его целиком только один раз.

Ключи часто начинаются с sk-, но префикс не доказывает подлинность или права. При копировании следите за пробелами и переводами строк в начале и конце — это частая причина Invalid API Key.

3. Настройка OpenAI-совместимого эндпоинта

Путь: Settings → Providers, в поле API Provider выберите OpenAI Compatible. Заполнить нужно три основных поля:

  • Base URL: корневой адрес вида https://ai.zhongshangqihang.com/v1, а не главная страница сайта и не путь до /chat/completions.
  • API Key: вставьте только что созданный ключ шлюза.
  • Model: точный ID модели со страницы тарифов, не угадывайте суффиксы.

В разделе Model Configuration можно задать Max Output Tokens, Context Window, Image Support, Computer Use, Input Price и Output Price. Последние два поля нужны только для локальной оценки расходов и не меняют фактическое списание; контекстное окно не завышайте, иначе длинные задачи могут падать с ошибкой.

Roo Code опирается на нативные вызовы инструментов модели, без XML-фолбэка. Совместимый эндпоинт должен не только поддерживать чат, но и реализовывать function calling в стиле OpenAI; иначе обычный диалог работает, а агент ломается при первом же вызове инструмента.

curl https://ai.zhongshangqihang.com/v1/chat/completions \
  -H "Authorization: Bearer $ZSQH_ROO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<ID модели>","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'

Если curl работает, а Roo Code выдаёт ошибку, проверьте лишний путь в Base URL, совпадение ID модели и поддержку вызова инструментов.

4. API Configuration Profiles: основа мультимодельности

API Configuration Profiles — это сохраняемые наборы настроек модели, которые можно переключать. Каждый профиль отдельно хранит поставщика, ключ, модель, температуру, бюджет рассуждений, ограничения и параметры дифф-редактирования. Для работы с несколькими моделями это первое, что стоит освоить.

В Settings → Providers нажмите + рядом с выбором профиля, задайте имя, выберите поставщика, введите ключ, выберите модель и при необходимости настройте Rate Limit. Rate Limit задаёт минимальный интервал между двумя запросами профиля и по умолчанию выключен. Переключать профиль можно в панели настроек или в выпадающем списке API Configuration в интерфейсе чата.

Более тонкое управление находится на вкладке Prompts: к каждому режиму можно привязать профиль. Задача фиксирует профиль на момент старта и сохраняет его при восстановлении из истории; подзадачи Orchestrator наследуют профиль родителя на весь жизненный цикл. Поэтому не привязывайте Orchestrator к дорогой модели в расчёте на то, что подзадачи автоматически подешевеют.

Имя профиля Назначение Класс модели Стратегия ключа Примечание
plan-strong Архитектура, сложный рефакторинг Сильная рассуждающая модель Отдельный ключ, высокий лимит Привязан к Architect
code-daily Повседневное кодирование, исправление ошибок Основная модель По ключу на человека Привязан к Code
ask-cheap Вопросы по коду, объяснения Лёгкая модель Ключ с низким лимитом Привязан к Ask
batch-cheap Массовые правки комментариев, форматирование Дешёвая модель Ключ проекта Ограничить скорость
backup Переключение при сбое основной модели Резервная модель Отдельный ключ Регулярно проверять

Имена лучше строить по схеме «сценарий-класс», так удобнее сверять. ID моделей и цены меняются — ориентируйтесь на тарифы на модели.

5. Безопасность ключа: хранение, права и границы данных

Согласно документации, ключ хранится в Secret Storage VS Code и не записывается открытым текстом в обычные файлы настроек. Но это не абсолютная защита: она опирается на учётную запись ОС, поэтому человек, вошедший на ваш компьютер, или процесс с вашими правами всё равно может получить доступ.

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

Смысл минимальных прав — «даже при утечке убыток ограничен»: лимит, срок действия, белый список моделей; если шлюз поддерживает IP-белый список или ограничение по проекту, включите и их. Разделяйте три ключа: тестовый, повседневный и автоматизационный, не используйте один на все сценарии.

6. Ротация, отзыв и действия при инциденте

Рекомендуется менять ключ каждые 90 дней или немедленно при уходе сотрудника, потере устройства, подозрении на утечку. Roo Code больше не поддерживается, старые версии не получают патчей безопасности, поэтому интервал можно сделать короче.

Безопасный порядок — «сначала параллельно, потом переключение, затем отключение»: создайте ключ с суффиксом даты; сохраните его в менеджер паролей и временно оставьте старый; замените ключ в профиле и протестируйте; убедитесь, что в логах шлюза появились записи нового ключа; наблюдайте ошибки и расход пару дней; после этого отключите старый ключ.

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

7. Командное использование: личные настройки становятся регламентом

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

  • Именованные ключи: в названии — сотрудник и назначение; отключать в день ухода; не заводить общий «командный ключ».
  • Изоляция проектов: производство, эксперименты и автоматизация — разные ключи с раздельными лимитами.
  • Ключи вне рабочей области: в репозитории только Base URL, имя модели и описание режимов; ключ остаётся в пользовательском хранилище.
  • Отдельные аккаунты для сервисов: CI, скрипты и боты используют сервисные ключи, не смешиваясь с сотрудниками.
  • Ежемесячный аудит: проверять давно неиспользуемые ключи, аномальные лимиты и резкий рост ошибок авторизации.
  • Минимум прав: для лёгких сценариев не выдавать сильную модель; задачам только на чтение не давать автоматического выполнения команд терминала.

Автоодобрение ускоряет работу, но усиливает последствия ошибок и расход токенов; команда должна явно определить, какие команды требуют подтверждения.

8. Типичная диагностика

  • Invalid API Key: ключ неполный, содержит пробелы или вставлен в специальный Provider Anthropic или Gemini. Переключитесь на OpenAI Compatible и повторите.
  • Model Not Found / 404: опечатка в ID модели или лишний /chat/completions в Base URL. Скопируйте значение со страницы тарифов, Base URL оставьте до /v1.
  • 401 / 403: ключ отключён, лимит исчерпан, нет прав на модель. Проверьте статус в консоли и потребление.
  • 429: сработало ограничение скорости или лимит. Снизьте параллельность, проверьте Rate Limit и лимиты ключа.
  • Диалог работает, вызов инструментов падает: эндпоинт или модель не поддерживают нативный function calling. Возьмите модель или эндпоинт с поддержкой инструментов.
  • Долгая задача обрывается посередине: завышено Context Window или неверен лимит вывода. Укажите реальные характеристики.

Держитесь трёх уровней проверки: Provider, Base URL, имя модели; воспроизведите через curl; посмотрите в логах шлюза, пришёл ли соответствующий запрос. Если все три совпали, проблема обычно не в ключе.

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

Roo Code ещё можно использовать?

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

Где хранится ключ?

По документации — в VS Code Secret Storage, не открытым текстом в обычных настройках. Это по-прежнему локальный секрет, и уровень защиты зависит от системной учётной записи и безопасности машины. На общих устройствах используйте отдельные аккаунты и не синхронизируйте чувствительные настройки.

Можно ли использовать один ключ в нескольких профилях?

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

Почему обычный диалог работает, а инструменты агента падают?

Roo Code использует только нативные вызовы инструментов, без XML-фолбэка. Совместимый эндпоинт должен реализовывать function calling в стиле OpenAI, а модель — поддерживать его. Сначала проверьте модель с поддержкой инструментов, потом решайте, в чём проблема — в эндпоинте или модели.

Стоит ли команде использовать общий ключ?

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

Итог

Если вы ещё пользуетесь Roo Code или Zoo Code, сначала создайте тестовый ключ с низким лимитом, проверьте его через curl и одной реальной задачей агента, затем раздавайте команде. Начать можно со страницы регистрации; модели, лимиты и тарификация — в тарифах на модели, цены меняются вместе с версиями моделей и политикой поставщиков.

Читайте также: