Cherry Studio и свой API: Base URL, ключ и модели (2026)

Cherry Studio — популярный настольный клиент для работы с ИИ: несколько провайдеров, переключение моделей, ассистенты и база знаний. Своих моделей у клиента нет — они берутся из настроенного API. Многие пользователи останавливаются на одном и том же шаге: что указать в Base URL, куда вставить ключ и как добавить ID модели. Пройдём полный путь на примере распространённой версии.

Примечание: Cherry Studio — продукт соответствующего правообладателя; статья носит технический характер. Названия элементов интерфейса и расположение функций могут меняться — ориентируйтесь на текущую версию; модели и цены смотрите в разделе тарифов.

1. Что подготовить до подключения

Для любого шлюза собственному провайдеру нужны всего три параметра:

API-ключ: создайте в консоли после регистрации в ZSQH AI Gateway, назовите по проекту или окружению.
Base URL: OpenAI-совместимый адрес шлюза, обычно https://ai.zhongshangqihang.com/v1.
ID модели: скопируйте со страницы тарифов; нужен API-идентификатор, а не отображаемое имя.

Сначала проверьте ключ и модель одной командой, а уже потом настраивайте клиент — это экономит время:

export ZSQH_API_KEY="sk-ваш-ключ"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "Ответь только OK"}]
  }'

Если в ответе есть choices, ключ, адрес и модель как минимум работают, и проблему стоит искать в настройках клиента.

2. Как правильно заполнить Base URL

Название поля в Cherry Studio зависит от версии — часто это «API-адрес» или «API Host». Рекомендуется придерживаться такого варианта:

Параметр	Что указать	Пояснение
Тип провайдера	OpenAI	Используется OpenAI-совместимый протокол
Адрес API	`https://ai.zhongshangqihang.com/v1`	Без слэша в конце
API-ключ	`sk-...`	Ключ, созданный в консоли
ID модели	По странице тарифов	Особенно важно проверять при ручном добавлении

Версии по-разному обращаются с /v1: одни добавляют его автоматически, другие требуют полный адрес. Определить причину просто: 401 чаще связан с ключом, 404 — с путём. Если полный адрес даёт 404, попробуйте убрать /v1; если домен без пути даёт 404 — добавьте /v1. Меняйте только один параметр за раз, не меняйте одновременно ключ, адрес и модель.

3. Добавление своего провайдера

На примере распространённой версии порядок такой (названия кнопок зависят от вашей версии):

Откройте Cherry Studio и нажмите настройки в левом нижнем углу (значок шестерёнки).
Перейдите в «Сервисы моделей» или «Провайдеры моделей».
Нажмите «+ Добавить провайдера».
Выберите тип OpenAI или вариант с поддержкой OpenAI-совместимости.
Укажите название провайдера, API-ключ и адрес API.
Сохраните и вернитесь к списку моделей, чтобы добавить ID.

Если в вашей версии нет пункта «Добавить провайдера», сначала обновите клиент. В старых версиях вход и поля могут отличаться, и настройка по старой инструкции легко попадает не туда.

4. Добавление ID модели

После сохранения провайдера доступны два способа:

Получить список моделей: клиент запрашивает у шлюза доступные модели, затем вы отмечаете нужные.
Добавить вручную: нажмите «+» и введите ID модели. Этот способ нужен, если шлюз не открывает интерфейс списка моделей или запрос списка не удался.

ID модели должен полностью совпадать со страницей тарифов, включая регистр, суффикс версии и дефисы. При ручном добавлении также проверьте, что тип модели — «диалог» или «чат»: при неверном типе модель не появится в выборе в окне диалога.

Тип модели	Типичное назначение	На что обратить внимание
Диалоговая	Повседневные вопросы, тексты, код	Самая востребованная, начните с неё
Рассуждающая	Сложный анализ, математика, планирование	Обычно выше задержка и стоимость
Визуальная	Понимание изображений, вопросы по скриншотам	Уточните поддержку изображений на шлюзе
Эмбеддинги	База знаний, векторный поиск	Отдельно проверьте интерфейс и модель

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

5. Проверка и порядок разбора ошибок

После настройки создайте диалог, выберите добавленную модель и отправьте «Ответь только OK». При сбое идите по порядку, не переустанавливайте клиент сразу:

Симптом	Частая причина	Что делать
`401 Unauthorized`	Ключ неверный, просрочен или не сохранён	Вставьте ключ заново, проверьте пробелы
`404 Not Found`	Неверный `/v1` в Base URL	Добавьте или уберите `/v1`, как описано выше
`model not found`	Неверный ID или модель не включена	Скопируйте точный идентификатор со страницы тарифов
Не удаётся получить список моделей	Шлюз не открывает интерфейс списка	Добавьте ID модели вручную
Диалог обрывается	Сеть или тайм-аут	Проверьте прокси, снизьте параллельность, повторите
Ошибка базы знаний	Не настроена модель эмбеддингов	Отдельно настройте доступную модель эмбеддингов

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

6. Несколько моделей и повседневная работа

Ценность Cherry Studio в разделении задач. Практичный подход:

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

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

7. Безопасность и командное использование

Ключ хранится локально на клиенте; на общем компьютере стоит подумать об изоляции учётных записей системы.
Не сохраняйте долгосрочные ключи на общих устройствах.
Выпускайте ключи по проектам, чтобы видеть расход и отзывать доступ на шлюзе.
Не вставляйте в клиент персональные данные клиентов, тексты договоров и необезличенные данные.
Регулярно проверяйте расход в шлюзе; при резком росте сначала остановите ключ, затем разбирайтесь.

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

Cherry Studio бесплатен?

Сам клиент можно использовать бесплатно, но за вызовы моделей платит ваш API-провайдер. Актуальные условия смотрите в текущей версии клиента и на странице тарифов шлюза.

Почему с указанным ключом всё равно 401?

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

Нужно ли добавлять `/v1` в Base URL?

Ориентируйтесь на подсказку текущей версии. Большинству OpenAI-совместимых настроек нужен /v1, но некоторые клиенты добавляют его сами. Критерий — попадает ли запрос на /v1/chat/completions; при 404 корректируйте окончание адреса.

Можно ли использовать модели Claude или Gemini?

Да, если шлюз предоставляет их в OpenAI-совместимом формате и вы указываете точный ID. У моделей с иным нативным протоколом часть параметров может быть несовместима — сверяйтесь с документацией.

Можно ли работать офлайн после настройки?

Нет. Клиент — только интерфейс, вычисления происходят на удалённом API. Без сети или при недоступном шлюзе диалог не завершится.

Что дальше

Настройка Cherry Studio несложная; сложность в том, чтобы согласовать Base URL, ключ и ID модели. Сначала проверьте через curl, затем настраивайте клиент; при сбое идите по порядку 401, 404, model not found. Если нужен единый вход к моделям и управление расходом, можно зарегистрироваться в ZSQH AI Gateway; модели и цены смотрите в разделе тарифов.