Cherry Studio

Cherry Studio — настольный клиент для работы с несколькими моделями на Windows, macOS и Linux. Добавив пользовательского поставщика OpenAI, вы можете использовать совместимую точку входа Chat Completions платформы AGTCloud.

В этом руководстве рассматривается только обычный чат. Поддержка файлов, изображений, вызова инструментов, рассуждений, баз знаний, Agent, MCP и других расширенных возможностей зависит от версии Cherry Studio и фактических возможностей целевой модели.

Подготовка

Перед началом убедитесь, что вы:

Подготовили поддерживаемое устройство Windows, macOS или Linux;
Зарегистрировались и вошли в AGTCloud;
Создали ключ API AGTCloud на странице API Keys;
Скопировали из каталога моделей ID модели, доступной текущему ключу API и поддерживающей Chat Completions.

Загрузка и установка Cherry Studio

Загрузите установочный пакет с официальной страницы Cherry Studio. Страница загрузки и имена пакетов могут меняться между версиями; выбирайте актуальную версию для своей ОС и архитектуры процессора.

Для обычных компьютеров Intel или AMD выберите стандартный установщик Windows x64;
Для устройств Windows ARM выберите пакет ARM64;
После загрузки запустите установщик и следуйте подсказкам.

Если архитектура неизвестна, откройте Параметры → Система → О системе и проверьте «Тип системы».

После установки запустите Cherry Studio. Если при первом запуске появляются настройки инициализации, каталога данных или обновления, выполните их в интерфейсе текущей версии.

Добавление поставщика AGTCloud

Открытие настроек моделей

Откройте Cherry Studio и перейдите в Settings → Model Provider. В китайском интерфейсе название соответствует «Настройки → Сервис моделей».

Добавление пользовательского поставщика

Нажмите Add или «Добавить» в списке поставщиков и создайте пользовательского поставщика. Укажите AGTCloud в Provider Name и OpenAI в Provider Type.

Заполнение параметров подключения

Поле Cherry Studio	Значение
`Provider Name`	`AGTCloud`
`Provider Type`	`OpenAI`
`Chat Endpoint / Protocol` (если доступно)	`OpenAI Chat Completions`
`API Key`	`your-api-key`
`API Host`	`https://api.agtcloud.cn/v1/`
`Custom Headers`	По умолчанию оставьте пустым

Замените your-api-key ключом API AGTCloud, созданным на странице API Keys. Если текущая версия предлагает выбор протокола чата, используйте OpenAI Chat Completions.

Включение поставщика

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

API Host должен оканчиваться на /

Укажите https://api.agtcloud.cn/v1/. Не указывайте полный адрес запроса /v1/chat/completions: при добавлении пути Cherry Studio может получить повторяющийся Endpoint.

Интерфейс добавления поставщика Cherry Studio

Получение и добавление моделей

Открытие управления моделями

Нажмите Manage на странице конфигурации поставщика AGTCloud. Cherry Studio попытается получить доступные модели с текущими API Host и ключом API.

Добавление модели в список

Найдите в полученном списке модель с поддержкой Chat Completions и нажмите + справа. Только модели, добавленные в список поставщика, отображаются в селекторе моделей страницы чата.

Ручное добавление при ошибке загрузки

Если список не загрузился, сначала проверьте API Host, ключ API и включение поставщика. Также можно скопировать ID из каталога моделей и ввести MODEL_ID через функцию ручного добавления текущей версии Cherry Studio.

Проверка подключения

Нажмите кнопку проверки подключения рядом с полем ключа API. Cherry Studio обычно использует последнюю модель чата в добавленном списке. При ошибке убедитесь, что в списке есть хотя бы одна модель чата, вызываемая текущим ключом API.

Настраивайте модели по их фактическим возможностям

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

Интерфейс управления моделями Cherry Studio

Первый диалог

Создание темы

Вернитесь на страницу чата Cherry Studio и создайте новую тему.

Выбор модели AGTCloud

Откройте селектор моделей и выберите AGTCloud → MODEL_ID. MODEL_ID — заполнитель; в реальном интерфейсе отображается ID только что добавленной модели.

Отправка минимального тестового вопроса

Введите в поле сообщения:

Представьтесь в трёх предложениях.

Проверка результата

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

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

Симптом	Что проверить сначала	Решение
Модель AGTCloud не отображается	Переключатель поставщика и добавление модели	Включите поставщика и убедитесь, что нужная модель добавлена в его список
`Manage` возвращает пустой список	API Host, ключ API и доступные аккаунту модели	Задайте API Host и ключ API заново либо скопируйте `MODEL_ID` из каталога моделей и добавьте вручную
Проверка подключения не проходит	Добавленные модели, протокол и права ключа	Убедитесь, что последняя модель чата в списке вызывается текущим ключом через Chat Completions
Ответ `401`	Содержимое ключа API и состояние токена	Скопируйте действующий ключ API заново и удалите лишние пробелы
Ответ `403`	Права токена, доступ к модели и состояние аккаунта	Проверьте ключ API и доступные аккаунту модели в консоли
Ответ `404`	API Host, повторные пути и ID модели	Используйте `https://api.agtcloud.cn/v1/` без полного Endpoint и проверьте ID модели
Путь запроса повторяется	Не содержит ли API Host полного адреса запроса	Верните адрес с завершающим `/`: `https://api.agtcloud.cn/v1/`, затем проверьте подключение заново
Расширенные функции не работают	Реальные возможности модели, протокол и версию клиента	Сначала отключите файлы, инструменты, базу знаний и рассуждения и проверьте обычный текст
Ответ прерывается или поступает медленно	Сетевой прокси, длину контекста и состояние модели	Повторите с короткой новой темой и проверьте локальную сеть и работу модели

Если причину найти не удаётся, запишите время запроса, ID модели, HTTP-статус и обезличенную ошибку, затем обратитесь к разделу ошибок и диагностики. Не отправляйте полный ключ API.