🏠 Главная › Документация › Мессенджеры

Интеграция с Open WebUI

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

Архитектура

flowchart LR
    A["Open WebUI<br/>browser UI<br/>port 3000"]
    B["hermes-agent<br/>gateway API server<br/>port 8642"]
    A -->|POST /v1/chat/completions| B
    B -->|SSE streaming response| A

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

Важно: расположение среды выполнения API-сервер — это среда выполнения агента Hermes, а не просто прокси для LLM. Для каждого запроса Hermes создаёт серверный AIAgent на хосте API-сервера. Вызовы инструментов выполняются там же, где работает API-сервер.

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

Open WebUI общается с 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-s...span class="w"> 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, который иначе отображается пустым и засоряет список моделей. Пропустите этот параметр, если у вас действительно запущен Ollama.

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

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 для профиля по умолчанию).

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

Тип API: Chat Completions и Responses

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

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

Это режим по умолчанию, не требующий дополнительной настройки. 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 в нативном формате, что позволяет создавать кастомный структурированный UI для вызовов инструментов в клиентах, поддерживающих события Responses.

В настоящее время 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. По мере выполнения инструментов встроенные сообщения о прогрессе транслируются в UI, так что вы видите, что делает агент (например, `💻 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-сервера.

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

Справочник по настройке

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 может выполнять несколько вызовов инструментов (чтение файлов, выполнение команд, поиск в интернете) перед тем, как сформировать финальный ответ. Это нормально для сложных запросов. Ответ появляется целиком, когда агент завершает работу.

Ошибки «Неверный API-ключ»

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

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. Добавьте подключения в Open WebUI

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

Подключение URL API Key
Alice http://host.docker.internal:8650/v1 alice-secret
Bob http://host.docker.internal:8651/v1 bob-secret

В выпадающем списке моделей будут отображаться alice и bob как отдельные модели. Вы можете назначать модели пользователям Open WebUI через панель администратора, предоставляя каждому пользователю своего изолированного агента Hermes.

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

hermes -p alice config set API_SERVER_MODEL_NAME "Alice's Agent"

Linux Docker (без Docker Desktop)

На Linux без Docker Desktop host.docker.internal не разрешается по умолчанию. Варианты:

# Option 1: Add host mapping
docker run --add-host=host.docker.internal:host-gateway ...

# Option 2: Use host networking
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1 ...

# Option 3: Use Docker bridge IP
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1 ...