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

Ниже — чек-лист в порядке «создание — несколько моделей — хранение — ротация — права — команда — диагностика». Интерфейс и способ хранения могут меняться от версии к версии; сверяйтесь с текущей версией и официальной документацией.

Примечание: Cline — товарный знак Cline Bot Inc. Статья носит технический характер и не означает аффилированности, агентских или партнёрских отношений с Cline Bot Inc.; функции продукта, интерфейс и правила тарификации — по официальной документации Cline.

1. Сначала определите, что такое «API-ключ Cline»

Термин часто смешивают, имея в виду три вещи:

  • Учётные данные платформы Cline: для собственной системы аккаунтов или API платформы, квоту определяет Cline.
  • Ключ поставщика модели: выдан OpenAI, Anthropic, Google и другими, вводится в соответствующее поле Provider в Cline.
  • Ключ шлюза: выдан совместимым сервисом вроде ZSQH AI Gateway, обычно начинается с sk- и даёт доступ к нескольким моделям по OpenAI-совместимому протоколу.

Здесь речь о третьем типе. Он не используется для входа в Cline и не даёт доступа к API платформы Cline. Правильная точка входа — OpenAI Compatible, а не специальные поля OpenAI, Anthropic или Azure.

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

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

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

Рекомендуется вести запись в таком формате — удобно для ротации и передачи:

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

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

3. Как настроить несколько моделей

В расширении VS Code API Provider, Base URL и модель обычно образуют один действующий набор настроек; для смены модели приходится менять настройки или выбирать её в селекторе задачи. Возможность хранить несколько наборов для разных проектов зависит от текущей версии и официальной документации.

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

Сценарий Класс модели Стратегия ключа Примечание
Повседневные вопросы, мелкие правки Лёгкая быстрая модель Личный ключ Низкая стоимость, ограниченные возможности на сложных задачах
Основная правка кода, задачи агента Основная кодовая модель Личный ключ Обязательна поддержка вызова инструментов
Архитектура, сложная диагностика Сильная модель Ключ проекта, подтверждение по необходимости Дороже, ограничьте область применения
Автоматизация, CI, скрипты Стабильная версия модели Отдельный сервисный ключ Отдельный лимит, не смешивать с личными ключами
Временное тестирование Дешёвая модель Краткосрочный ключ Минимальный срок действия

В командной строке можно настроить Provider, ключ, модель и Base URL через cline auth; параметры зависят от версии — сначала посмотрите локальную справку:

export ZSQH_API_KEY="sk-... (взять из менеджера паролей, не писать в скрипт)"
cline auth -p <provider-id> -k "$ZSQH_API_KEY" \
  -m <model-id> -b https://ai.zhongshangqihang.com/v1

Учтите: ключ, переданный через -k, может сохраниться в постоянной конфигурации Provider. Используйте только на доверенной машине и убедитесь, что история shell, список процессов и логи не оставляют открытый текст. CLI поддерживает изоляцию каталога конфигурации через --config, --data-dir или переменные CLINE_DIR, CLINE_DATA_DIR.

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

В новых версиях глобальные настройки находятся в ~/.cline/data/settings/:

  • providers.json: конфигурация Provider, по официальной документации содержит API-ключ.
  • global-settings.json: общие глобальные настройки.
  • cline_mcp_settings.json: настройки MCP-серверов, могут содержать токены сторонних сервисов.

Проектные настройки обычно лежат в каталоге .cline/ в корне репозитория: правила, процессы, hooks, agents и т. п. Разные версии могут использовать хранилище ключей VS Code или общий каталог данных; нельзя предполагать, что ключ обязательно зашифрован.

Поэтому относитесь к нему как к чувствительному локальному файлу:

  • Включите шифрование диска и пароль блокировки, ограничьте локальные права.
  • Не размещайте ~/.cline в публичном облаке, репозитории или общих резервных копиях.
  • Перед коммитом проверяйте .vscode/, .cline/, .clinerules и скрипты на отсутствие ключей.
  • Токены в конфигурации MCP также считаются секретами.
  • Закрывайте страницы настроек на скриншотах, записях экрана и при удалённой помощи.
  • Перед синхронизацией настроек уточните область и способ шифрования и решите, включать ли файлы с ключами.

5. Ротация и отзыв

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

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

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

Перед ротацией перечислите места использования: расширение VS Code, CLI, CI, другие редакторы и временные скрипты. Если заменить ключ только в IDE, старый может продолжать работать в автоматизации.

6. Минимальные права и командная политика

  • Ключ на человека: общий ключ не разделяет потребление и плохо локализуется при утечке. Для общих сервисов — отдельные ключи.
  • Ключ на назначение: повседневная разработка, автоматизация и временные тесты раздельно — проще ограничивать и отключать.
  • Задавайте лимиты: срок действия, квоту и набор моделей, если доступны; минимум первые два.
  • Единая точка входа: по возможности подключайтесь через общий шлюз, сохраняя логи по людям, моделям и потреблению для аудита и распределения затрат.
  • Ведите реестр: только имя ключа, владелец, назначение, дата создания и срок действия; полный ключ не записывайте.
  • Регулярный аудит: ежемесячно проверяйте давно неиспользуемые ключи, превышения и резкий рост ошибок аутентификации.
  • Процесс приёма и увольнения: создание, передача и отключение ключей в чек-листах onboarding и offboarding.
  • Классификация данных: какие модели и каналы допустимы для каких репозиториев; чувствительные проекты оценивайте заранее.
  • Контроль прав агента: автоодобрение и режим YOLO усиливают риск ошибок и prompt injection — команда должна задать права по умолчанию и порядок исключений.
  • Проверка расширений и MCP: устанавливайте только из доверенных источников; hooks, плагины и MCP-серверы могут выполнять код или обращаться к сети.

Расчёт стоимости — по тарифам на модели. Не судите о дороговизне по одной задаче, считайте по числу запросов, длине контекста и классу модели.

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

  • 401 или Invalid API Key: неверный или отключённый ключ, либо пробелы и переводы строк при вставке. Удалите и скопируйте заново целиком.
  • 403: квота исчерпана, недостаточно прав ключа или модель вне разрешённого набора.
  • 404 или Model Not Found: неверный путь Base URL или несуществующий ID модели. Оставьте адрес до /v1, без /chat/completions.
  • 429: сработало ограничение скорости или лимит ключа. Проверьте потребление и лимиты в консоли.
  • Таймаут: эндпоинт недоступен, проблема сетевого маршрута или вмешательство прокси. Сначала проверьте связность простым запросом.
  • Переполнение контекста: проверьте, соответствует ли Context Window в Cline реальной спецификации модели, и сократите задачу.
  • Обычный чат работает, операции агента падают: сначала подозревайте отсутствие поддержки инструментов, а не недействительный ключ.
  • CLI работает, расширение нет: они могут читать разные каталоги конфигурации — проверьте ~/.cline и настройки текущего проекта отдельно.
  • Сбой сразу после смены ключа: убедитесь, что настройка сохранилась, и проверьте в логах шлюза, приходят ли запросы с новым ключом.

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

Где хранится ключ Cline и безопасно ли это?

В новых версиях — в ~/.cline/data/settings/providers.json вместе с конфигурацией Provider и API-ключом; настройки MCP могут содержать отдельные токены. Официальная документация не обещает шифрование, поэтому обращайтесь с файлом как с секретом: шифрование диска и никакой синхронизации в публичные места.

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

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

Как дать команде общие модели, не раскрывая ключ?

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

Повлияет ли ротация на выполняющиеся задачи?

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

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

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

Итог

Настройка ключа в Cline несложна; сложна долгосрочная дисциплина: прослеживаемые имена, лимиты, защищённое хранение и умение остановить убыток при утечке. Зарегистрируйтесь в ZSQH AI Gateway, создайте отдельный ключ для Cline, проверьте работу, затем постепенно ужесточайте права по командной политике и регулярно сверяйте расходы с тарифами на модели.

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