🏠 Главная › user guide › open webui

Интеграция с открытым WebUI

Open WebUI (126k★) — самый популярный саморазмещаемый чат-интерфейс для ИИ. Благодаря встроенному API-серверу Hermes Agent вы можете использовать Open WebUI в качестве отполированного веб-интерфейса для вашего агента — с управлением беседами, учетными записями сеансов и современным чат-интерфейсом.

Архитектура

flowchart LR
    A["Open WebUI<br/>браузерный интерфейс<br/>порт 3000"]
    B["hermes-agent<br/>шлюз API-сервера<br/>порт 8642"]
    A -->|POST /v1/chat/completions| B
    B -->|SSE потоковый ответ| A

Open WebUI привязан к API-серверу Hermes Agent так же, как подключался бы к OpenAI. Гермес обрабатывает запросы со всем набором инструментов — терминал, файлы своих операций, веб-поиск, память, навыки — и возвращает итоговый ответ.:::важно Расположение среды выполнения API-сервер — это среда выполнения агента Hermes, а не чистый прокси LLM. Для каждого запроса Hermes создает серверный AIAgent на хосте API-сервера. Вызовы инструментов выполняются там, где запущен этот API-сервер.

Например, если ноутбук направляет Open WebUI или другой клиент OpenAI на API-сервере Hermes на удаленной машине, то pwd, инструменты файлов, инструменты браузера, локальные MCP-инструменты и другие рабочие инструменты выполняются на удаленном хосте API-сервера, а не на ноутбуке.

Открытый веб-интерфейс взаимодействует с Hermes по шаблону сервер-сервера, поэтому для этого предприятия не требуется API_SERVER_CORS_ORIGINS.

Быстрая настройка

Однокомандная локальная загрузка (macOS/Linux, без Docker)

Если вы хотите, чтобы облачность Hermes + Open WebUI была локально с переиспользуемым лаунчером, выполните:

cd ~/.hermes/hermes-agent
bash scripts/setup_open_webui.sh

Что делает скрипт:

Значения по умолчанию:

Полезные переопределения:

OPEN_WEBUI_NAME='My Hermes UI' \
OPEN_WEBUI_ENABLE_SIGNUP=true \
HERMES_API_MODEL_NAME='My Hermes Agent' \
bash scripts/setup_open_webui.sh

В Linux автоматическая настройка фонового сервиса требует рабочей сессии systemd --user. Если вы находитесь на безголовом SSH-сервере и хотите отправить установку сервиса, выполните:

OPEN_WEBUI_ENABLE_SERVICE=false bash scripts/setup_open_webui.sh

1. Включите API-сервер

hermes config set API_SERVER_ENABLED true
hermes config set API_SERVER_KEY your-secret-key

hermes config set автоматически направляет флаг в config.yaml, а секрет — в ~/.hermes/.env. Если шлюз уже запущен, перезапустите его, чтобы изменения вступили в силу:

hermes gateway stop && hermes gateway

2. Запустить шлюз Hermes Agent

hermes gateway

Вы увидите должны:

[API Server] API server listening on http://127.0.0.1:8642

3. Проверьте доступность API-сервера

curl -s http://127.0.0.1:8642/health
# {"status": "ok",...}

curl -s -H "Authorization: Bearer your-secret-key" http://127.0.0.1:8642/v1/models
# {"object":"list","data":[{"id":"hermes-agent",...}]}

Если /health не работает, шлюз не под захватом API_SERVER_ENABLED=true — перезапустите его. Если /v1/models возвращает 401, ваш заголовок Authorization не соответствует API_SERVER_KEY.

4. Запустите Open WebUI

docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY=your-secret-key \
  -e ENABLE_OLLAMA_API=false \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

ENABLE_OLLAMA_API=false запрещает стандартный бэкенд Ollama, который в случае отключения отключался бы пустым и засорял выбор модели. Пропустите этот параметр, если у вас действительно запущен Оллама.

Первый запуск занимает 15–30 секунд: Открытие WebUI загружает модели встраивания предложений-трансформеров (~150 МБ) при первом запуске. Дождитесь, пока docker logs open-webui успокоится, прежде чем открыть интерфейс.

5. Открыть интерфейс

Перейдите по адресу http://localhost:3000. Сделайте учётную запись администратора (первый пользователь становится администратором). Вы должны увидеть своего агента в выпадающем списке моделей (названном в соответствии с вашим профилем или hermes-agent для профиля по умолчанию). Начинайте общение!

Настройка с Docker Compose

Для более постоянной настройки создайте docker-compose.yml:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1
      - OPENAI_API_KEY=your-secret-key
      - ENABLE_OLLAMA_API=false
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

Затем:

docker compose up -d

Настройка через интерфейс администратора

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

  1. Войдите в Open WebUI по адресу http://localhost:3000
  2. Нажмите на аватар профиля → Настройки администратора
  3. Перейдите в Подключения
  4. В разделе OpenAI API нажмите иконку гаечного ключа (Управление)
  5. Нажмите + Добавить новое подключение
  6. Введите:
  7. URL: http://host.docker.internal:8642/v1
  8. API Key: то же самое значение, что и API_SERVER_KEY в Hermes
  9. Нажмите галочку, чтобы проверить подключение
  10. Сохраните

Ваша модель агента теперь должна появиться в выпадающем списке моделей (названная в соответствии с вашим профилем или hermes-agent для профиля по умолчанию).

⚠️ Warning

Переменные окружения действуют только при первом запуске Open WebUI. После этого настройки подключения сохраняются во внутренней базе данных. Чтобы изменить их позже, используйте интерфейс администратора или удалите том Docker и начните заново.

Тип API: Chat Completions vs Responses

Open WebUI поддерживает два режима API при подключении к бэкенду:

Режим Формат Когда использовать
Chat Completions (по умолчанию) /v1/chat/completions Рекомендуется. Работает из коробки.
Responses (экспериментальный) /v1/responses Для состояния беседы на стороне сервера через previous_response_id.

Использование Chat Completions (рекомендуется)

Это режим по умолчанию и не требует дополнительной настройки. Open WebUI отправляет запросы в стандартном формате OpenAI, и Hermes Agent отвечает соответствующим образом. Каждый запрос включает полную историю беседы.

Использование Responses API

Чтобы использовать режим Responses API:

  1. Перейдите в Настройки администратора → Подключения → OpenAI → Управление
  2. Отредактируйте ваше подключение hermes-agent
  3. Измените Тип API с "Chat Completions" на "Responses (Experimental)"
  4. Сохраните

С Responses API Open WebUI отправляет запросы в формате Responses (массив input + instructions), и Hermes Agent может сохранять полную историю вызовов инструментов между оборотами через previous_response_id. Когда stream: true, Hermes также передаёт специфичные для протокола элементы function_call и function_call_output, что позволяет создавать пользовательский структурированный интерфейс вызовов инструментов в клиентах, которые обрабатывают события Responses.

📝 Note

Open WebUI в настоящее время управляет историей беседы на стороне клиента даже в режиме Responses — он отправляет полную историю сообщений в каждом запросе, а не использует previous_response_id. Основное преимущество режима Responses на сегодня — это структурированный поток событий: дельты текста, элементы function_call и function_call_output приходят как события SSE OpenAI Responses, а не как фрагменты Chat Completions.

Как это работает

Когда вы отправляете сообщение в Open WebUI:

  1. Open WebUI отправляет запрос POST /v1/chat/completions с вашим сообщением и историей беседы
  2. Hermes Agent создаёт экземпляр AIAgent на стороне сервера, используя профиль API-сервера, конфигурацию модели/провайдера, память, навыки и настроенные наборы инструментов API-сервера
  3. Агент обрабатывает ваш запрос — он может вызывать инструменты (терминал, файловые операции, веб-поиск и т.д.) на хосте API-сервера
  4. По мере выполнения инструментов встроенные сообщения о прогрессе передаются в интерфейс, так что вы видите, что делает агент (например, `💻 ls -la`, `🔍 Python 3.12 release`)
  5. Итоговый текстовый ответ агента передаётся обратно в Open WebUI
  6. Open WebUI отображает ответ в своём чат-интерфейсе

Ваш агент имеет доступ к тем же инструментам и возможностям, что и этот экземпляр Hermes на API-сервере. Если API-сервер удалённый, эти инструменты также удалённые.

Если вам нужно, чтобы инструменты выполнялись в вашей локальной рабочей среде, запустите Hermes локально и направьте его на чистого LLM-провайдера или чистый совместимый с OpenAI прокси модели (например, vLLM, LiteLLM, Ollama, llama.cpp, OpenAI, OpenRouter и т.д.). Будущий режим раздельной среды выполнения для "удалённый мозг, локальные руки" отслеживается в #18715; это не поведение текущего API-сервера.

💡 Tip

Прогресс инструментов При включённой потоковой передаче (по умолчанию) вы будете видеть краткие встроенные индикаторы по мере выполнения инструментов — эмодзи инструмента и его ключевой аргумент. Они появляются в потоке ответов до финального ответа агента, давая вам представление о том, что происходит за кулисами.

Справочник по конфигурации

Hermes Agent (API-сервер)

Переменная По умолчанию Описание
API_SERVER_ENABLED false Включить API-сервер
API_SERVER_PORT 8642 Порт HTTP-сервера
API_SERVER_HOST 127.0.0.1 Адрес привязки
API_SERVER_KEY (обязательно) Bearer-токен для аутентификации. Должен совпадать с OPENAI_API_KEY.

Open WebUI

Переменная Описание
OPENAI_API_BASE_URL URL API Hermes Agent (включая /v1)
OPENAI_API_KEY Должен быть непустым. Должен совпадать с вашим API_SERVER_KEY.

Устранение неполадок

Модели не отображаются в выпадающем списке

Тест подключения проходит, но модели не загружаются

Это почти всегда отсутствующий суффикс /v1. Тест подключения Open WebUI — это базовая проверка связности; он не проверяет, работает ли список моделей.

Ответ занимает много времени

Hermes Agent может выполнять несколько вызовов инструментов (чтение файлов, выполнение команд, веб-поиск) перед тем, как сформировать итоговый ответ. Это нормально для сложных запросов. Ответ появляется целиком, когда агент завершает работу.

Ошибки "Invalid API key"

Убедитесь, что ваш OPENAI_API_KEY в Open WebUI совпадает с API_SERVER_KEY в Hermes Agent.

⚠️ Warning

Open WebUI сохраняет настройки подключения, совместимые с OpenAI, в своей собственной базе данных после первого запуска. Если вы случайно сохранили неверный ключ в интерфейсе администратора, исправления только переменных окружения недостаточно — обновите или удалите сохранённое подключение в Настройки администратора → Подключения, или сбросьте каталог данных / базу данных Open WebUI.

Многопользовательская настройка с профилями

Чтобы запускать отдельные экземпляры Hermes для каждого пользователя — каждый со своей конфигурацией, памятью и навыками — используйте профили. Каждый профиль запускает свой собственный API-сервер на другом порту и автоматически рекламирует имя профиля как модель в Open WebUI.

1. Создайте профили и настройте API-серверы

API_SERVER_* — это переменные окружения, а не ключи конфигурации YAML, поэтому запишите их в .env каждого профиля. Выберите порты вне стандартного диапазона платформы (8644 — адаптер вебхуков, 8645 — wecom-callback, 8646 — msgraph-webhook), например, 8650+:

hermes profile create alice
cat >> ~/.hermes/profiles/alice/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8650
API_SERVER_KEY=alice-secret
EOF

hermes profile create bob
cat >> ~/.hermes/profiles/bob/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8651
API_SERVER_KEY=bob-secret
EOF

2. Запустите каждый шлюз

hermes -p alice gateway &
hermes -p bob gateway &

3. Добавьте подключение в открытый веб-интерфейс

В Настройки администратора → Подключения → OpenAI API → Управление страниц по одному подключению для каждого профиля:

Подключение URL-адрес API-ключ
Алиса http://host.docker.internal:8650/v1 алиса-секрет
Боб http://host.docker.internal:8651/v1 боб-секрет

Выпадающий список моделей показывает «Алису» и «Боба» в качестве моделей производителя. Вы можете назначать модели пользователей. Откройте WebUI через панель администратора, предоставляя каждому пользователю изолированного агента Hermes.

💡 Tip

Пользовательские названия моделей Имя модели по умолчанию соответствует имени профиля. Чтобы переопределить его, установите API_SERVER_MODEL_NAME в профиле .env:

hermes -p alice config set API_SERVER_MODEL_NAME "Alice's Agent"
```</div>
## Linux Docker (без Docker Desktop)

В Linux без Docker Desktop `host.docker.internal` не разрешен по умолчанию. Варианты:
```bash
# Вариант 1: Добавить сопоставление хоста
docker run --add-host=host.docker.internal:host-gateway...

# Вариант 2: Использовать сеть хоста
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1...

# Вариант 3: Использовать IP моста Docker
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1...