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

Статья идёт по порядку «создание — привязка — сопоставление — проверка — ротация — защита от утечек — командные политики» и даёт выполнимый чек-лист. Названия интерфейсов зависят от версии; ориентируйтесь на установленные у вас Cursor Settings.

Примечание: Cursor — товарный знак Anysphere, Inc. Статья носит технический характер; автор не связан с Cursor/Anysphere. Функции продукта и правила биллинга определяются официальными страницами Cursor.

1. Сначала уточните, какой именно ключ вы настраиваете

«Cursor API Key» часто смешивают в трёх значениях:

  • Ключ платформы Cursor: используется для Cloud Agents, управляющих интерфейсов и других функций Cursor, создаётся в аккаунте Cursor.
  • Ключ поставщика моделей: выдан OpenAI, Anthropic, Google, Azure, AWS Bedrock и т. п. и вставляется в раздел API Keys Cursor.
  • Ключ шлюза: выдан совместимым сервисом вроде ZSQH AI Gateway, обычно начинается с sk- и через OpenAI-совместимый протокол даёт доступ к нескольким моделям.

Статья описывает третий вариант в Cursor. Он не используется для входа в Cursor и не вызывает интерфейсы платформы Cursor. Ключ шлюза вставляется в поле OpenAI API Key с переопределением Base URL; в специальные поля Anthropic или Google он обычно не подходит.

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

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

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

Рекомендуется хранить запись в менеджере паролей в таком формате — это упрощает ротацию и передачу:

Назначение: cursor-рабочий-ноутбук
Base URL: https://ai.zhongshangqihang.com/v1
Key: sk-... (хранится только в менеджере паролей)
Модель: ID со страницы «Тарифы» на текущий момент

Ключ обычно показывается полностью только один раз. Если он потерян, создайте новый и удалите старый, не пытайтесь восстановить. Модели и цены меняются; ориентируйтесь на страницу тарифов.

3. Привязка ключа в Cursor

Обычный путь — Cursor Settings → Models → API Keys. Следите за сохранением на каждом шаге.

  1. Откройте Cursor Settings; сочетание клавиш обычно Cmd/Ctrl + ,.
  2. Перейдите в Models и разверните API Keys.
  3. Откройте OpenAI API Key, вставьте ключ и нажмите Save.
  4. Откройте Override OpenAI Base URL и укажите https://ai.zhongshangqihang.com/v1.
  5. Нажмите + Add Custom Model (в некоторых версиях + Add model), введите точный ID модели и включите её.
  6. Выберите модель в диалоге и отправьте короткий тестовый запрос.

Три частые ошибки:

  • В Base URL указан адрес сайта https://ai.zhongshangqihang.com без /v1.
  • В Base URL добавлен /chat/completions, путь дублируется и возвращает 404.
  • Ключ шлюза вставлен в поля Azure OpenAI или Bedrock. Эти поля относятся к аутентификации соответствующих облачных сервисов и не подходят для обычного совместимого шлюза.

Если в текущей версии нет Override OpenAI Base URL, значит, она не поддерживает пользовательский совместимый адрес. Не пытайтесь обойти это другими полями — обновите версию или используйте сборку с этим переключателем.

4. Сопоставление моделей: превратите «имя» в поддерживаемую таблицу

Название модели — не текст для отображения, а маршрутный идентификатор. Команде стоит вести таблицу соответствия с назначением, ID модели в Cursor, моделью на стороне шлюза, границами возможностей и датой отключения.

Назначение Что указать в Cursor Основание на шлюзе Что проверять
Повседневные вопросы ID лёгкой модели Одноимённая модель на странице тарифов Полное совпадение имени
Основная работа с кодом ID основной модели Одноимённая модель на странице тарифов Поддержка вызова инструментов
Задачи с длинным контекстом Модель с длинным контекстом Одноимённая модель на странице тарифов Лимит контекста
Резерв при сбое ID резервной модели Одноимённая модель на странице тарифов Возможность ручного переключения

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

5. Проверка: конфигурация, запрос, биллинг

Не ограничивайтесь ответом «есть ли ответ»: ответ может приходить из встроенного канала. Надёжнее проверять в три уровня.

  1. Конфигурация: ключ сохранён, Base URL заканчивается на /v1, пользовательская модель включена.
  2. Запрос: создайте новый пустой диалог, явно выберите пользовательскую модель и отправьте короткий запрос.
  3. Биллинг: откройте расход или журнал запросов в консоли шлюза и убедитесь, что появилась запись с нужным временем, моделью и ключом. Если записи нет, запрос не дошёл до шлюза.

Частые ошибки:

  • 401 или 403: неверный ключ, отключённый ключ или исчерпанная квота.
  • 404: неверный путь Base URL или несуществующее имя модели.
  • 429: сработал лимит частоты или достигнут потолок квоты.
  • Тайм-аут: endpoint недоступен или проблема в сетевом пути.
  • Обычный диалог работает, агент падает: вероятно, несовпадение возможностей интерфейса, а не ключа.

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

6. Ротация, отзыв и обработка инцидентов

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

  1. Создайте новый ключ с теми же правами и суффиксом даты в названии.
  2. Замените ключ в Cursor и сохраните.
  3. Отправьте тестовый запрос и убедитесь, что в журнале шлюза появилась запись нового ключа.
  4. Некоторое время наблюдайте долю ошибок и расход, чтобы не пропустить забытых клиентов.
  5. Отключите старый ключ и удалите его после периода наблюдения.

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

7. Защита от утечек: откуда ключ может уйти

  • Код и конфигурация: .env, конфигурация контейнеров и Notebook могут попасть в коммит. Используйте менеджер секретов и сканирование перед коммитом.
  • Скриншоты и запись экрана: страница настроек показывает ключ целиком. Закрывайте его перед снимком и не открывайте поле ключа во время демонстрации.
  • Чаты и тикеты: не отправляйте полный ключ коллегам или поддержке. Для идентификации достаточно названия или последних четырёх символов.
  • Синхронизация настроек IDE и плагины: проверьте область синхронизации и права плагинов; на корпоративных устройствах нужен явный белый список плагинов.
  • Общий компьютер: используйте отдельную учётную запись системы, не включайте долгое сохранение и выходите из аккаунта после работы.
  • Журналы и отчёты об ошибках: отладочные логи могут содержать заголовки. Перед отправкой удаляйте данные аутентификации.
  • Путь передачи: по странице помощи Cursor ключ отправляется на серверы Cursor в зашифрованном виде вместе с запросом и не сохраняется; но собственный ключ не обязательно попадает под политику нулевого хранения. Используйте отдельный ключ с ограниченной квотой.

8. Командные политики: сделайте ключи управляемыми

  • Один ключ на человека; для общих сервисов — отдельные ключи, не смешивать с личными.
  • Единые лимиты квоты, сроки действия и белые списки моделей.
  • По возможности подключаться через единый шлюз, сохраняя журналы участников, моделей и расхода.
  • Ежемесячно проверять давно неиспользуемые и превышающие лимит ключи, а также рост неудачных аутентификаций.
  • Определить уровни данных: для чувствительных репозиториев разрешать только проверенные модели и каналы.
  • Включить создание, передачу и отключение ключей в чек-листы приёма и увольнения.
  • Даже при собственном ключе командная версия может брать плату за платформу; расчёт стоимости — по странице биллинга Cursor и тарифам.

9. Чек-лист диагностики

  • При вставке ключа попали пробелы или переводы строк: удалите и скопируйте заново целиком.
  • В Base URL добавлен /chat/completions: оставьте только до /v1.
  • В имени модели не хватает суффикса версии: скопируйте со страницы тарифов как есть.
  • Квота ключа исчерпана: проверьте баланс и лимит в консоли, при необходимости поднимите потолок.
  • Ограничение тарифа: проверьте, разрешает ли текущий тариф Cursor собственный ключ и нужные функции.
  • Endpoint недоступен: убедитесь, что Base URL — публичный адрес, и проверьте его простым запросом вне браузера.
  • Агент падает, а обычный диалог работает: сначала подозревайте несовпадение возможностей интерфейса, а не ключ.
  • Автодополнение Tab не использует ключ: по документации Cursor оно работает на встроенной модели — это ожидаемое поведение.

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

Чем Cursor API Key отличается от ключа модели?

Первый обычно означает ключ платформы Cursor для собственных интерфейсов Cursor; второй выдаётся поставщиком модели или шлюзом для вызова моделей. В статье настраивается второй; смешивать их нельзя.

Можно ли ограничить ключ одной моделью?

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

Прервёт ли ротация текущий диалог?

Уже отправленные запросы могут не пострадать, но последующие будут использовать новый ключ. Переключайтесь в часы низкой нагрузки, сразу отправьте тестовый запрос и только потом отключайте старый ключ.

Что делать в первую очередь при утечке ключа?

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

Достаточно ли бесплатной квоты для теста?

Ориентируйтесь на текущие акции консоли и тарифы. Для теста используйте ключ с небольшой квотой, проверяйте только доступность и имя модели, не пуская в эксперимент рабочий трафик.

Итог

Настройка ключа в Cursor несложна; сложность в долгосрочном управлении: прослеживаемые названия, лимиты квоты, сопоставление моделей и возможность остановить потери при утечке. Сначала зарегистрируйтесь в ZSQH AI Gateway и создайте отдельный ключ для Cursor, а после успешной проверки постепенно ужесточайте права по командным правилам.

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