Open WebUI: подключение к Zukko через Docker и панель администратора

Open WebUI — веб-интерфейс для работы с языковыми моделями, который вы запускаете у себя в Docker. Он умеет обращаться к любому OpenAI-совместимому API, поэтому подключение Open WebUI к Zukko сводится к двум параметрам: адресу https://api.zukko.pro/v1 и ключу fetch_.... Ниже — команда запуска, настройка через панель администратора, выбор модели по цене и разбор типичных ошибок.

Что понадобится

• Docker на компьютере или сервере.
• Ключ Zukko вида fetch_.... Полный ключ показывается один раз при создании — сохраните его сразу.
• По желанию — лимиты на ключе. В кабинете каждому ключу можно задать дневной и месячный лимит в долларах и список разрешённых моделей. Для чата, которым пользуются несколько человек, это простая страховка от неожиданного расхода.

Как подключить Open WebUI к Zukko через Docker

Команда основана на официальной инструкции Open WebUI, к ней добавлены две переменные для Zukko:

docker run -d \
  -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e WEBUI_SECRET_KEY="ваш_секрет" \
  -e OPENAI_API_BASE_URL="https://api.zukko.pro/v1" \
  -e OPENAI_API_KEY="fetch_ваш_ключ" \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

Что здесь важно:

• -p 3000:8080 — интерфейс будет доступен на http://localhost:3000. Если порт 3000 занят, поменяйте левое число.
• -v open-webui:/app/backend/data — чаты, пользователи и настройки хранятся в томе. Без него всё пропадёт при пересоздании контейнера.
• WEBUI_SECRET_KEY — ключ для подписи сессий. Документация Open WebUI советует задать постоянное значение, иначе после пересоздания контейнера всех разлогинит. Сгенерировать можно командой openssl rand -hex 32.
• OPENAI_API_BASE_URL и OPENAI_API_KEY — адрес Zukko (обязательно с /v1) и ваш ключ.
• :main — тег из официальной документации. Для продакшена можно закрепить конкретную версию вида vX.Y.Z.

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

Подключение через панель администратора

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

1. Откройте Admin Panel → Settings → Connections (в документации путь записан как Settings > Admin > Connections).
2. В блоке OpenAI API нажмите «+» (Add Connection).
3. В поле URL укажите https://api.zukko.pro/v1, в поле API Key — ключ fetch_....
4. Поле Model IDs можно оставить пустым: Open WebUI сам запросит список моделей через /models, а Zukko отдаёт его по GET /v1/models. Если хотите показывать пользователям только часть моделей, перечислите нужные id.
5. Сохраните. У каждого подключения есть переключатель, которым его можно временно выключить, не удаляя.

Переменные окружения применяются только при первом запуске

OPENAI_API_BASE_URL и OPENAI_API_KEY в Open WebUI относятся к сохраняемым настройкам: при первом старте значения записываются в базу внутри тома, и дальше приложение берёт их оттуда. Если вы поменяете ключ в команде docker run и пересоздадите контейнер со старым томом, ничего не изменится. Правильный способ — поменять ключ в Admin Panel → Settings → Connections. Временный вариант — переменная ENABLE_PERSISTENT_CONFIG=False: тогда Open WebUI читает значения из окружения, но изменения, сделанные в интерфейсе, не сохраняются.

Таблица: что куда писать

Какую модель выбрать: считаем по цене

Все модели доступны по одному адресу. Claude-модели тоже работают через OpenAI-совместимое подключение: шлюз сам конвертирует формат.

Пример: сообщение в чате, где история и вопрос занимают 3 000 токенов, а ответ — 1 000. Всего 4 000 токенов:

• claude-sonnet-5, claude-opus-5-5, gpt-5.6-sol: 4 000 × $0.3 / 1 000 000 = $0.0012;
• gpt-5.6-luna, glm-5.3: 4 000 × $0.1 / 1 000 000 = $0.0004;
• glm-5.3-flash: 4 000 × $0.04 / 1 000 000 = $0.00016.

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

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

Ещё одна статья расхода — служебные запросы: Open WebUI сам генерирует названия чатов, теги и поисковые запросы. Для них можно назначить отдельную дешёвую модель через TASK_MODEL_EXTERNAL (это тоже сохраняемая настройка, её можно поменять и в настройках администратора).

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

Частые ошибки и как их исправить

404 или пустой список моделей

Почти всегда это адрес. Правильно: https://api.zukko.pro/v1. Неправильно: без /v1 или с лишним /chat/completions на конце.

401: неверный ключ

Ключ скопирован не полностью, с пробелом или был удалён в кабинете. Создайте новый ключ и обновите его в Connections — именно там, а не в docker run (см. раздел о сохраняемых настройках).

402: не хватает баланса

Пополните баланс в кабинете: доступны СБП, карта РФ, криптовалюта, минимальная сумма — $1.

403: model_not_allowed_for_key

Модели нет в списке разрешённых для этого ключа. Добавьте её в настройках ключа или уберите из Model IDs подключения.

400 на моделях Claude

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

429 или 503

429 — слишком частые запросы, подождите и повторите. 503 — провайдер модели временно недоступен; переключитесь на другую модель или повторите позже.

Подробности о запросе ищите в логах контейнера: docker logs open-webui.

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

Можно ли дать доступ к Open WebUI коллегам?

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

Видно ли баланс Zukko в Open WebUI?

Нет. Баланс и история расходов — в кабинете, раздел «Использование», а также через API баланса↗.

Как обновить Open WebUI и не потерять чаты?

Удалите контейнер командой docker rm -f open-webui, скачайте новый образ docker pull ghcr.io/open-webui/open-webui:main и запустите ту же команду docker run. Данные и настройки подключений останутся в томе open-webui.

Нужен ли отдельный ключ для Open WebUI?

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