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

Разберём на примере распространённых версий октября 2026 года: какие параметры подготовить, как развернуть в Docker, настроить переменные окружения и интерфейс, а также как искать ошибки.

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

1. Как выбрать из трёх способов подключения

Способ Когда подходит Где настраивается Плюсы
Настройка в интерфейсе Личное использование, быстрая проверка AI-провайдеры в настройках Действует сразу, без перезапуска
Переменные Docker Свой сервер, командное использование docker run или compose Версионируется и легко копируется
Переменные облака Хостинг вроде Vercel Настройки окружения проекта Без администрирования, подходит небольшим командам

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

2. Подготовьте три параметра

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

Сначала проверьте связку через curl, чтобы не принять проблему шлюза за ошибку настройки LobeChat:

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, все три параметра корректны и можно переходить к развёртыванию.

3. Развёртывание в Docker

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

docker run -d --name lobechat \
  -p 3210:3210 \
  -e OPENAI_API_KEY="sk-ваш-ключ" \
  -e OPENAI_PROXY_URL="https://ai.zhongshangqihang.com/v1" \
  -e CUSTOM_MODELS="-all,+your-model-id" \
  lobehub/lobe-chat

После запуска откройте http://адрес-сервера:3210. Значение параметров:

  • OPENAI_API_KEY — ключ шлюза; передавайте его через переменные окружения или менеджер секретов, не храните в публичном compose-файле.
  • OPENAI_PROXY_URL — переопределяет адрес OpenAI по умолчанию и указывает на совместимый шлюз.
  • CUSTOM_MODELS — управляет списком моделей: -all очищает список по умолчанию, +ID добавляет модель.

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

4. Переменные окружения и список моделей

Переменная Обязательна Пример Назначение
OPENAI_API_KEY Да sk-... Ключ, созданный в шлюзе
OPENAI_PROXY_URL Да https://ai.zhongshangqihang.com/v1 Переопределяет Base URL по умолчанию
CUSTOM_MODELS Рекомендуется -all,+model-a,+model-b Управляет видимыми моделями
OPENAI_MODEL_LIST Зависит от версии +model-a В старых версиях мог использоваться этот вариант

Синтаксис CUSTOM_MODELS:

  • +ID добавляет модель, -ID скрывает её.
  • -all сначала очищает список по умолчанию, чтобы не показывать модели, которые нельзя вызвать.
  • Разделитель — запятая без пробелов.
  • Переименовать можно через ID=Отображаемое имя, но сам ID менять нельзя.

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

5. Настройка через интерфейс

Если не хотите менять переменные окружения, настройте всё в интерфейсе. На примере распространённой версии:

  1. Откройте LobeChat и перейдите в настройки.
  2. Найдите раздел «AI-провайдеры» или «Языковые модели».
  3. Выберите OpenAI, укажите API-ключ и адрес прокси.
  4. Добавьте ID своей модели в список.
  5. Сохраните, создайте новый диалог и проверьте выбранную модель.

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

6. Проверка и обратный прокси

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

docker logs -f lobechat

Затем отправьте сообщение в интерфейсе. Если приложение доступно из интернета, поставьте перед ним Nginx или Caddy и как минимум сделайте три вещи:

  1. Настройте HTTPS: не передавайте ключ по открытому HTTP.
  2. Ограничьте доступ, чтобы приложение не было открыто всем подряд.
  3. Настройте тайм-ауты и буферизацию; для потоковых ответов буферизацию прокси нужно отключить.

В Nginx для потоковых ответов обычно отключают proxy_buffering и увеличивают тайм-аут чтения. Иначе ответ либо появляется целиком в конце, либо обрывается на середине.

7. Чек-лист перед продакшеном

  1. Передавайте ключ через менеджер секретов или переменные окружения, не встраивайте в образ.
  2. Выпустите для LobeChat отдельный ключ, чтобы удобно задавать лимиты и отзывать доступ.
  3. Настройте базу данных, иначе диалоги и конфигурация могут храниться только локально.
  4. Включите HTTPS и контроль доступа — публичное развёртывание не должно оставаться открытым.
  5. Задайте бюджет и лимит параллельных запросов на шлюзе, чтобы циклы не выжигали квоту.
  6. Регулярно делайте резервные копии базы и загруженных файлов.
  7. Перед обновлением читайте changelog и фиксируйте тег образа вместо постоянного latest.

8. Типовые ошибки и их решение

Симптом Частая причина Что делать
После запуска нет моделей CUSTOM_MODELS не применился Проверьте имя переменной, запятые и пересоздание контейнера
401 Unauthorized Ключ не передан или недействителен Проверьте переменную внутри контейнера, создайте ключ заново
404 Not Found Неверный путь прокси Сверьте /v1, при необходимости добавьте или уберите его
model not found ID модели не совпадает со страницей тарифов Скопируйте точный идентификатор
Ответ обрывается Буферизация или тайм-аут прокси Отключите буферизацию, увеличьте тайм-аут чтения
Не загружается файл Не настроено хранилище или возможности модели Проверьте хранилище и поддержку файлов у модели
База знаний не работает Не настроена модель эмбеддингов Отдельно настройте доступную модель эмбеддингов

При разборе сначала определите, «приложение не видит конфигурацию» или «шлюз отклонил запрос». В первом случае смотрите переменные и логи контейнера, во втором — HTTP-код. Подходы к исправлению совершенно разные.

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

LobeChat бесплатен?

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

Обязательно ли использовать Docker?

Нет. Можно запустить через Node.js или развернуть на облачной платформе с поддержкой Next.js. Docker даёт одинаковое окружение и простое переносимость, поэтому в командах его используют чаще.

Чем OPENAI_PROXY_URL отличается от адреса прокси в интерфейсе?

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

Почему в списке появились неработающие модели?

Скорее всего, не использован -all для очистки списка по умолчанию или допущена ошибка в синтаксисе CUSTOM_MODELS. Оставьте одну заведомо рабочую модель, проверьте её, затем добавляйте остальные.

Можно ли подключить Claude или Gemini?

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

Что дальше

Подключение LobeChat сводится к двум шагам: сначала убедиться через curl, что шлюз доступен, затем согласовать Base URL, ключ и модель в переменных окружения или интерфейсе. Для команды предпочтительны переменные окружения, для личной проверки — интерфейс. Если нужен единый вход к моделям и управление расходом, можно зарегистрироваться в ZSQH AI Gateway; модели и цены смотрите в разделе тарифов.

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