Как подключить Cursor к OpenRouter: настройка, границы функций и устранение ошибок
Пошаговая настройка Cursor для OpenRouter с проверкой через Activity, отдельными тестами Chat, Agent, Tab и tools, а также диагностикой endpoint, модели, баланса и лимитов.
Содержание
Главный вывод: ответ в Cursor сам по себе не доказывает, что все функции редактора идут через OpenRouter. По состоянию на 4 октября 2026 года OpenRouter помечает интеграцию с Cursor как Beta и требует специальный Base URL https://openrouter.ai/api/v1/cursor. При ручном выборе модели запросы Chat и модельная часть Agent могут идти через OpenRouter. Tab Completion использует встроенные модели Cursor, а tools работают только при правильном endpoint и поддержке инструментов выбранной моделью.
Поэтому проверка должна выглядеть так: правильные поля → модель выбрана вручную → короткий тестовый запрос → совпадающая запись в OpenRouter Activity → отдельная проверка Agent и tools. Ниже разобрана процедура по официальной документации. Здесь нет утверждения, что конкретный аккаунт, ключ или версия Cursor были реально протестированы от начала до конца.
Что действительно использует пользовательский API Key
| Функция Cursor | Ожидаемая маршрутизация | Важная граница | Как проверить |
|---|---|---|---|
| Модель, выбранная вручную в Chat или Ask | Обычно через OpenRouter | Модель должна быть доступна через OpenAI-compatible endpoint OpenRouter | Отправить короткий запрос и сверить время и модель в Activity |
| Модель, выбранная вручную в Agent | Модельный вызов обычно проходит; все внутренние запросы не доказаны | Документация поддерживает выбор модели в Agent, но не описывает каждый вспомогательный вызов | Сверить Activity и видимые действия tools в Cursor |
| Tab Completion | Нет | Tab продолжает использовать встроенные модели Cursor | Не считать подсказку Tab доказательством работы OpenRouter |
| Вызов tools в Agent | Условно | Нужны endpoint /cursor и модель с поддержкой tools | Сначала проверить Chat, затем выполнить безопасную read-only задачу |
| Автоматический выбор модели | Плохой сигнал для приёмки | Клиент может выбрать другой маршрут | На время теста выбрать добавленную модель вручную |
Важно разделять запрос к модели и выполнение инструмента. В документации OpenRouter по tool calling сказано, что модель предлагает вызов инструмента, а клиент выполняет его и возвращает результат модели. Запись в Activity подтверждает модельный запрос через OpenRouter, но сама по себе не доказывает, что чтение файла или команда терминала выполнялись на стороне OpenRouter.
Что подготовить
- Актуальную версию Cursor с разделом
Cursor Settings→Models→API Keys. - Собственный API Key OpenRouter. Не вставляйте его в чат, репозиторий, скриншот или сообщение поддержки.
- Точный Model ID из текущего каталога OpenRouter, а не название, придуманное по интерфейсу.
- Для Agent с инструментами — модель из фильтра моделей с поддержкой tools.
Названия кнопок в Cursor могут меняться: в одной версии это включение, в другой сохранение или проверка. Неизменна логика: ключ OpenRouter помещается в OpenAI API Key, специальный адрес — в Override OpenAI Base URL, а модель задаётся полным ID OpenRouter.
Настройка Cursor по шагам
1. Откройте раздел API Keys
Перейдите в Cursor Settings → Models, раскройте API Keys и найдите поля OpenAI API Key и Override OpenAI Base URL.
2. Введите ключ OpenRouter
Вставьте ключ, созданный в аккаунте OpenRouter, в OpenAI API Key. Используйте только окно настроек Cursor. Выполните действие сохранения, включения или проверки, которое показывает ваша версия клиента.
3. Укажите специальный endpoint
Включите Override OpenAI Base URL и введите:
https://openrouter.ai/api/v1/cursor
Не заменяйте его общим https://openrouter.ai/api/v1 и не добавляйте /chat/completions. Специальный endpoint нормализует формат запросов Cursor. Через общий endpoint часть форматов и tool calls может работать неправильно.
4. Добавьте точный Model ID
В разделе Models нажмите + Add model и скопируйте полный ID с актуальной страницы модели OpenRouter. Для router alias также копируйте полную текущую запись. Не используйте сокращение, маркетинговое имя или ID из старой статьи.
5. Выберите модель вручную
Вернитесь в Chat или Agent и явно выберите добавленную модель. Автоматический режим не подходит для первого теста: ответ может прийти, но его маршрут останется неясным.
Как доказать, что настройка сработала
Отправьте в Chat короткий запрос без кода и секретов, например просьбу вернуть одну фиксированную фразу. Сразу откройте OpenRouter Activity и проверьте:
- время совпадает с тестом;
- записанная модель совпадает с Model ID, выбранным в Cursor;
- запрос завершён успешно и содержит данные об использовании;
- внутренний отчёт не содержит ключ, полный prompt или приватный код.
Ответ Cursor — слабое доказательство; совпадающая запись Activity — более сильное доказательство маршрута. Если ответ есть, а записи нет, пометьте результат как «маршрут не подтверждён» и продолжайте диагностику.
Для командной приёмки сохраните только время, модель, статус, нужный идентификатор запроса, версию Cursor и режим теста. Это позволит повторить проверку, если поведение Beta изменится.
Проверяйте функции по отдельности
Chat: сначала базовая линия
Выберите модель вручную и отправьте короткий детерминированный запрос. Chat считается проверенным только после появления совпадающей записи Activity. Пока этот этап не проходит, Agent тестировать рано: он добавляет переменные модели, контекста, разрешений и инструментов.
Agent: модельный запрос и orchestration — не одно и то же
Используйте тестовый или легко восстанавливаемый репозиторий. Сначала попросите Agent прочитать README и предложить улучшения, не разрешая запись файлов и опасные команды. Проверьте два независимых сигнала:
- В OpenRouter Activity появился модельный запрос.
- Cursor показал ожидаемое чтение файла или другое действие инструмента.
Первое подтверждает маршрутизацию модели, второе — работу Agent в Cursor. Официальные материалы не доказывают, что каждый фоновый вспомогательный запрос Agent обязательно использует тот же пользовательский ключ, поэтому один успешный запуск нельзя распространять на весь внутренний трафик.
Tab: отсутствие записи — нормальное поведение
Подсказка Tab проверяет только Tab Completion Cursor. Документация говорит, что пользовательские ключи работают с chat models, а Tab остаётся на встроенных моделях Cursor. Ситуация «Chat виден в Activity, Tab не виден» ожидаема.
Tools: проверяйте endpoint и модель вместе
После успешного Chat выберите модель, у которой в каталоге указана поддержка tools. В тестовом репозитории попросите Agent выполнить read-only действие: перечислить файлы или прочитать небольшой файл. Если обычный текстовый Chat работает, а инструмент нет, проверьте по порядку:
- Base URL точно равен
https://openrouter.ai/api/v1/cursor; - модель явно поддерживает
tools; - Cursor не переключился на другую модель;
- разрешение на инструмент не было отклонено;
- ошибка воспроизводится на второй модели с подтверждённой поддержкой tools.
Диагностика по симптомам
| Симптом | Вероятная причина | Первая дешёвая проверка | Повторный тест |
|---|---|---|---|
| Ключ отклонён | Недействительный или отозванный ключ, лишний пробел, смешаны ключ и endpoint разных провайдеров | Скопировать активный ключ заново и проверить соответствие провайдера | Перезапустить сессию, повторить короткий Chat и проверить Activity |
| Model not found / 404 | Неверный ID, неполный alias или модель недоступна через совместимый endpoint | Скопировать полный актуальный ID из каталога | Выбрать модель вручную и повторить тот же запрос |
| Chat работает, tools в Agent — нет | Используется общий /api/v1 или модель не поддерживает инструменты | Проверить /cursor и supported_parameters=tools | Выполнить одну read-only задачу и проверить Activity |
| Chat работает, Tab не виден в Activity | Tab не использует пользовательский ключ | Не менять ключ и Base URL | Принимать Chat и Tab как разные функции |
| Ошибка 402 | Недостаточно средств, исчерпан лимит ключа или in-flight budget | Посмотреть страницу ключа/кредитов и metadata ошибки | Подождать, уменьшить запрос или пополнить баланс, затем повторить |
| Ошибка 429 | Лимит OpenRouter или upstream-провайдера | Проверить Retry-After и rate-limit headers, не повторять мгновенно | Подождать с exponential backoff и повторить либо выбрать другой маршрут |
| Ответ есть, записи Activity нет | Встроенная модель, автоматический маршрут или настройки не применились | Выбрать добавленную модель вручную и перепроверить поля | Перезапустить сессию и повторить минимальный запрос |
| В настройках нет нужных полей | Изменилась версия Cursor, план или UI | Обновить клиент и открыть текущую документацию Cursor BYOK | Воссоздать те же связи полей в актуальном интерфейсе |
При 429 следуйте документации по лимитам OpenRouter: учитывайте Retry-After и применяйте exponential backoff. Создание дополнительных ключей не гарантирует обход общей ёмкости. При ошибках tools сначала исправьте endpoint и поддержку модели, а уже потом усложняйте настройки Agent.
BYOK не означает прямое соединение Cursor с OpenRouter
Согласно документации Cursor BYOK, запросы всё равно проходят через backend Cursor для финальной сборки prompt. Для чувствительного кода нужно оценивать правила обработки данных и Cursor, и выбранного провайдера. Не прикладывайте реальные ключи, клиентские данные или приватный исходный код к скриншотам диагностики; используйте обезличенный минимальный пример.
Планы, биллинг и доступность UI могут измениться. Перед командным или production-внедрением заново откройте официальные страницы и проверьте поведение на текущую дату.
BetterToken — отдельная конфигурация
Если нужен другой OpenAI-compatible gateway, а не именно OpenRouter, у BetterToken есть отдельная инструкция для Cursor. Для неё используется https://www.bettertoken.ai/v1 вместе с собственным API Key и Model ID BetterToken.
Не соединяйте ключ OpenRouter с endpoint BetterToken и ключ BetterToken с https://openrouter.ai/api/v1/cursor. При смене провайдера заново выполните минимальный Chat-тест и проверьте usage в панели именно этого провайдера.
Финальный порядок приёмки
Надёжная последовательность: настроить одну модель → выбрать её вручную → отправить минимальный Chat-запрос → найти запись Activity → проверить Agent и tools → принимать Tab отдельно как встроенную функцию Cursor. Так каждая ошибка относится к конкретному слою: endpoint, ключ, модель, tools, баланс или rate limit.
