API-шлюз

API-шлюз предоставляет уже настроенные в Cherry Studio возможности моделей локальным программам через совместимый с OpenAI и Anthropic HTTP API. Это также внутренний сервис, необходимый для работы Agent.

Путь: 【Настройки】→【API-шлюз】.

Перед подключением внешних программ сначала проверьте статус и порт; ключ предоставляйте только доверенным локальным программам или в контролируемой сети.

Использование Agent и внешних вызовов нужно различать

• Если используете только Cherry Studio Agent: достаточно нажать 【Включить и запустить】 по подсказке приложения, не нужно копировать URL или ключ в другие программы;
• Если локальной программе нужно вызывать Cherry Studio: запустите шлюз, скопируйте URL и API-ключ и выберите совместимый интерфейс согласно документации API;
• Если нужно предоставить доступ другим устройствам: это расширит область экспозиции, поэтому нужно самостоятельно проверить сетевое прослушивание, брандмауэр и контроль доступа; не рекомендуется открывать доступ без мер безопасности.

Запуск и подключение

1

1. Проверьте порт

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

2

2. Запустите шлюз

Нажмите 【Запустить】; после того как статус станет 【В работе】, на странице отобразится доступный URL и будет доступен вход в 【Документацию API】.

3

3. Настройте авторизацию

Использование внешними программами Authorization: Bearer <API-ключ>На странице можно напрямую скопировать заголовок авторизации; не записывайте ключ в репозиторий кода или на скриншоты.

4

4. Проверьте минимальным запросом

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

Сценарий использования: позволить локальному скрипту вызывать модель

Сначала в 【Настройки】→【Сервис моделей】 убедитесь, что модель нормально отвечает, затем запустите API-шлюз. Скрипт сохраняет только адрес локального шлюза и ключ, сначала запрашивает список моделей, затем отправляет короткий текст. Перед подключением полноценной программы убедитесь, что клиент поддерживает совместимый с OpenAI или Anthropic интерфейс.

Настройка	Рекомендуемая отправная точка	Роль	Примечания
Область прослушивания	Только для локального использования	Сократить сетевую экспозицию	Не открывать напрямую в локальную сеть или в интернет ради удобства отладки
API-ключ	Хранить отдельно для текущего шлюза	Проверить запросы клиента	Не записывать в репозиторий, скриншоты или общие журналы
Проверка запросов	Сначала проверьте список моделей и короткий текст	Проверяйте соединение и генерацию отдельно	При сбое записывайте код состояния, не записывайте полный ключ

Критерии завершения

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

Безопасные действия

API-ключ может вызывать сервисы моделей, настроенные вами в Cherry Studio. Если ключ утёк, сначала остановите шлюз, затем в состоянии остановки нажмите 【Сгенерировать заново】 и после этого обновите всех локальных клиентов.

• Когда шлюз запущен, порт и ключ остаются только для чтения; перед изменением сначала остановите его;
• Не показывайте ключ в публичных репозиториях, issue, журналах или на скриншотах в инструкциях;
• Сохраняйте ключ только для программ, которым он нужен для вызова;
• Потребление и расходы по-прежнему формируются реальным поставщиком модели; записи Cherry Studio можно посмотреть в 【Настройки】→【Статистика использования】.

Какова связь между API-шлюзом и сервисом моделей?

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

Что делать, если порт в порядке, но клиент возвращает неавторизован?

Убедитесь, что заголовок запроса — Authorization: Bearer ...без лишних кавычек или пробелов, и проверьте, что ключ, используемый клиентом, всё ещё соответствует текущему значению на странице.