LobeChat (LobeHub): подключение Zukko через интерфейс и env

LobeChat — открытый чат-интерфейс, который проект теперь развивает под названием LobeHub. Подключить в нём свой API можно двумя способами: в настройках провайдера в интерфейсе или переменными окружения при самостоятельном развёртывании. Для Zukko понадобятся адрес https://api.zukko.pro/v1 и ключ fetch_.... Ниже — оба способа по официальной документации LobeHub, настройка списка моделей, расчёт стоимости и разбор ошибок.

LobeChat и LobeHub: что важно знать перед настройкой

Многие инструкции в интернете показывают запуск одной командой docker run с образом lobe-chat. Актуальная документация описывает другой вариант: образ lobehub/lobehub, порт 3210 и серверную версию с базой данных — PostgreSQL, секреты для авторизации и S3-хранилище для файлов. Полное развёртывание лучше делать по официальной инструкции LobeHub, а в этой статье разбираем только то, что касается подключения моделей.

Способ 1: через интерфейс

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

1. Откройте настройки приложения → AI Providers (в документации — App Settings → AI Providers).
2. Выберите провайдера OpenAI и включите его переключателем.
3. Вставьте ключ fetch_... в поле API Key.
4. В поле Proxy URL укажите https://api.zukko.pro/v1.
5. Нажмите Check, чтобы проверить подключение.
6. Включите нужные модели в списке. Если моделей Zukko там нет, загрузите список или добавьте модели вручную по id — например, claude-sonnet-5.

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

Способ 2: LobeChat и свой API через переменные окружения

При самостоятельном развёртывании провайдера удобно задать сразу на сервере — тогда пользователям не нужно вводить ключ. Добавьте строки в env-файл, который вы создали по инструкции LobeHub (в документации он называется lobehub.env):

OPENAI_API_KEY=fetch_ваш_ключ
OPENAI_PROXY_URL=https://api.zukko.pro/v1
OPENAI_MODEL_LIST=-all,+claude-sonnet-5=Claude Sonnet 5<1000000>,+claude-opus-5-5=Claude Opus 5.5<1000000>,+gpt-5.6-sol=GPT-5.6 Sol<1000000>,+gpt-5.6-luna=GPT-5.6 Luna<1000000>,+glm-5.3-flash=GLM 5.3 Flash<128000>
SYSTEM_AGENT=default=openai/glm-5.3-flash

Что делает каждая переменная:

• OPENAI_API_KEY — ключ Zukko.
• OPENAI_PROXY_URL — переопределяет базовый адрес OpenAI. По умолчанию там https://api.openai.com/v1, мы заменяем его на адрес Zukko.
• OPENAI_MODEL_LIST — список моделей в интерфейсе (синтаксис ниже).
• SYSTEM_AGENT — модель для служебных задач LobeHub (о ней — отдельный раздел).

Провайдер OpenAI включён по умолчанию; отключить его можно переменной ENABLED_OPENAI=0.

Почему обязательно /v1

В документации LobeHub к OPENAI_PROXY_URL есть отдельное предупреждение: одни прокси ожидают адрес с /v1, другие без него, и если в ответ приходит пустое сообщение, нужно попробовать добавить /v1. Для Zukko вопрос решён заранее: адрес всегда https://api.zukko.pro/v1.

Синтаксис OPENAI_MODEL_LIST

По документации LobeHub:

• +id — добавить модель, -id — скрыть модель, записи разделяются запятыми;
• -all — сначала скрыть все встроенные модели, чтобы остались только перечисленные через +;
• id=Название — задать отображаемое имя;
• <число> после имени — максимальный контекст в токенах. Через двоеточие можно добавить возможности, например fc (вызов функций) или vision (картинки). Указывайте их, только если уверены, что модель это поддерживает.

-all здесь важен. Без него в списке останутся встроенные модели OpenAI, которых нет в Zukko, и запрос к ним завершится ошибкой.

Актуальные id моделей — GET https://api.zukko.pro/v1/models (см. документацию по моделям↗) или страница «Модели» в кабинете.

Модель для служебных задач: SYSTEM_AGENT

Кроме ваших сообщений LobeHub сам отправляет запросы: придумывает названия тем, переводит, сжимает длинную историю, генерирует описания агентов, а при включённом автодополнении — подсказывает продолжение текста. Если модель для этих задач не задана явно, LobeHub может обратиться к модели, которой нет в Zukko, и фоновые функции перестанут работать.

Формат переменной: default=провайдер/модель для всех задач сразу или задача=провайдер/модель для конкретной. Так как Zukko подключён через провайдера OpenAI, провайдер здесь — openai. Пример с отдельной моделью для сжатия истории:

SYSTEM_AGENT=default=openai/glm-5.3-flash,historyCompress=openai/claude-sonnet-5

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

Как применить изменения

Переменные окружения читаются при создании контейнера. Команда docker restart lobehub их не перечитает: контейнер нужно удалить и создать заново той же командой docker run, что и при установке. Если вы разворачивали LobeHub через Docker Compose, после правки env-файла выполните docker compose up -d — Compose пересоздаст контейнер с новыми значениями.

Логи смотрите командой docker logs -f lobehub (подставьте имя своего контейнера).

Выбор модели по цене

Пример на месяц: 30 сообщений в день в течение 30 дней, то есть 900 сообщений. Каждое — 4 000 входных токенов (вопрос с историей) и 800 выходных. Итого 3 600 000 входных и 720 000 выходных, всего 4 320 000 токенов:

• claude-sonnet-5: 4 320 000 × $0.3 / 1 000 000 = $1.296 в месяц;
• gpt-5.6-luna: 4 320 000 × $0.1 / 1 000 000 = $0.432;
• glm-5.3-flash: 4 320 000 × $0.04 / 1 000 000 = $0.1728.

Для сравнения, тот же объём на claude-sonnet-5 по официальной цене вендора ($2 и $10 за 1M входных и выходных токенов): 3.6 млн × $2 + 0.72 млн × $10 = $7.2 + $7.2 = $14.4. Оговорка: у вендоров повторно отправляемый контекст может читаться из кэша примерно за 10% входной цены, а в Zukko кэшированные токены оплачиваются по обычной входной цене. В длинных диалогах с большой повторяющейся историей реальная разница поэтому меньше, чем при расчёте в лоб. Подробнее — в документации о лимитах ключей и кэше↗.

Какую модель выбрать для основного общения, решайте на своих задачах: подключите две-три модели, задайте им одни и те же 10–20 типичных вопросов и сравните ответы и расход в разделе «Использование» кабинета.

Разбор ошибок

Пустой ответ

Типичный признак адреса без /v1 — об этом прямо пишет документация LobeHub. Проверьте, что OPENAI_PROXY_URL или Proxy URL равен https://api.zukko.pro/v1.

В списке встроенные модели OpenAI, запросы к ним падают

В OPENAI_MODEL_LIST нет -all, поэтому видны модели, которых Zukko не обслуживает. Добавьте -all в начало списка.

Не появляются названия тем, не работает перевод

Служебные задачи обращаются к модели, которой нет в Zukko. Задайте SYSTEM_AGENT=default=openai/glm-5.3-flash или выберите модель для системных задач в настройках.

Поменяли env-файл, а ничего не изменилось

Контейнер не пересоздан. docker restart переменные не перечитывает — нужен docker rm -f и повторный docker run либо docker compose up -d.

400 на моделях Claude

Модели claude-sonnet-5 и claude-opus-5-5 могут отклонять запрос с ошибкой 400, если temperature отличается от 1 или top_p меньше 0.99. Если в настройках модели агента вы меняли эти параметры, для Claude верните значения по умолчанию.

401, 402, 403, 429

401 — ключ скопирован не полностью или удалён в кабинете. 402 — закончился баланс. 403 model_not_allowed_for_key — модели нет в списке разрешённых для ключа. 429 — слишком частые запросы, подождите и повторите.

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

Обязательно ли разворачивать LobeHub на своём сервере?

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

Можно ли подключить Zukko как провайдера Anthropic?

В LobeHub есть отдельный провайдер Anthropic со своим прокси-адресом, а Zukko принимает и Anthropic-формат. Но проще оставить один OpenAI-провайдер: шлюз сам конвертирует запросы к Claude, и все модели будут в одном списке. Чем отличаются форматы, описано в документации о выборе формата↗.

Безопасно ли держать ключ на сервере?

Ключ из env-файла используют все пользователи вашего LobeHub, поэтому не открывайте экземпляр в интернет без авторизации. Дополнительно задайте ключу дневной и месячный лимит и список разрешённых моделей в кабинете.

Где взять ключ?

Создайте его в кабинете Zukko↗ — полный ключ показывается один раз, сразу перенесите его в env-файл или в настройки провайдера.