sidebar_position: 8 title: "Open WebUI" description: "Connect Open WebUI to Hermes Agent via the OpenAI-compatible API server" lang: ru

Открытая интеграция WebUI

Open WebUI (126k★) — самый популярный автономный интерфейс чата для ИИ. Благодаря встроенному API-серверу агента Hermes вы можете использовать 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_SERVER_CORS_ORIGINS.

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

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.

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. Запустите открытый веб-интерфейс.

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 секунд: Open 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

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

Если вы предпочитаете настраивать соединение через пользовательский интерфейс вместо переменных среды:

Войдите в Open WebUI по адресу http://localhost:3000.
Нажмите на свой аватар профиля → Настройки администратора.
Перейдите в раздел Подключения.
В разделе OpenAI API нажмите значок гаечного ключа (Управление).
Нажмите + Добавить новое соединение.
Введите:
URL: http://host.docker.internal:8642/v1
API Key: your key or any non-empty value (e.g., not-needed)
Click the checkmark to verify the connection
Save

Your agent model should now appear in the model dropdown (named after your profile, or hermes-agent for the default profile).

⚠️ Warning

Environment variables only take effect on Open WebUI's **first launch**. After that, connection settings are stored in its internal database. To change them later, use the Admin UI or delete the Docker volume and start fresh.

API Type: Chat Completions vs Responses

Open WebUI supports two API modes when connecting to a backend:

Mode	Format	When to use
Chat Completions (default)	`/v1/chat/completions`	Recommended. Works out of the box.
Responses (experimental)	`/v1/responses`	For server-side conversation state via `previous_response_id`.

Using Chat Completions (recommended)

This is the default and requires no extra configuration. Open WebUI sends standard OpenAI-format requests and Hermes Agent responds accordingly. Each request includes the full conversation history.

Using Responses API

To use the Responses API mode:

Go to Admin Settings → Connections → OpenAI → Manage
Edit your hermes-agent connection
Change API Type from "Chat Completions" to "Responses (Experimental)"
Save

With the Responses API, Open WebUI sends requests in the Responses format (input array + instructions), and Hermes Agent can preserve full tool call history across turns via previous_response_id. When stream: true, Hermes also streams spec-native function_call and function_call_output items, which enables custom structured tool-call UI in clients that render Responses events.

📝 Note

Open WebUI currently manages conversation history client-side even in Responses mode — it sends the full message history in each request rather than using `previous_response_id`. The main advantage of Responses mode today is the structured event stream: text deltas, `function_call`, and `function_call_output` items arrive as OpenAI Responses SSE events instead of Chat Completions chunks.

How It Works

When you send a message in Open WebUI:

Open WebUI sends a POST /v1/chat/completions request with your message and conversation history
Hermes Agent creates an AIAgent instance with its full toolset
The agent processes your request — it may call tools (terminal, file operations, web search, etc.)
As tools execute, inline progress messages stream to the UI so you can see what the agent is doing (e.g. `💻 ls -la`, `🔍 Python 3.12 Release`)
The agent's final text response streams back to Open WebUI
Open WebUI displays the response in its chat interface

Your agent has access to all the same tools and capabilities as when using the CLI or Telegram — the only difference is the frontend.

💡 Tip

Tool Progress With streaming enabled (the default), you'll see brief inline indicators as tools run — the tool emoji and its key argument. These appear in the response stream before the agent's final answer, giving you visibility into what's happening behind the scenes.

Configuration Reference

Hermes Agent (API server)

Variable	Default	Description
`API_SERVER_ENABLED`	`false`	Enable the API server
`API_SERV ER_PORT`	`8642`	HTTP server port
`API_SERVER_HOST`	`127.0.0.1`	Bind address
`API_ SERVER_KEY`	(required)	Bearer token for auth. Match `OPENAI_API_KEY`.

Open WebUI

Variable	Description
`OPENAI_API_BASE_URL`	Hermes Agent's API URL (include `/v1@@ IC0043@@OPENAI_API_KEY`

Troubleshooting

Check the URL has /v1 suffix: http://host.docker.internal:8642/v1 (не только :8642)
Убедитесь, что шлюз работает: curl http://localhost:8642/health should return {"status": "ok"}
Check model listing: curl -H "Авторизация: предъявитель вашего секретного ключа" http://localhost:8642/v1/models должен вернуть список с hermes-agent
Сеть Docker: изнутри Docker localhost означает контейнер, а не ваш хост. Используйте host.docker.internal или --network=host.
Пустой сервер Ollama, скрывающий средство выбора: если вы пропустили ENABLE_OLLAMA_API=false, Open WebUI отобразит пустой раздел Ollama над вашими моделями Hermes. Перезапустите контейнер с помощью -e ENABLE_OLLAMA_API=false или отключите Ollama в Настройки администратора → Подключения.

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

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

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

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

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

Убедитесь, что ваш OPENAI_API_KEY в открытом веб-интерфейсе соответствует API_SERVER_KEY в Hermes Agent.

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

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

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

hermes profile create alice
hermes -p alice config set API_SERVER_ENABLED true
hermes -p alice config set API_SERVER_PORT 8643
hermes -p alice config set API_SERVER_KEY alice-secret

hermes profile create bob
hermes -p bob config set API_SERVER_ENABLED true
hermes -p bob config set API_SERVER_PORT 8644
hermes -p bob config set API_SERVER_KEY bob-secret

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

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

3. Добавьте соединения в Open WebUI

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

Подключение	URL-адрес	API-ключ
Алиса	`http://host.docker.internal:8643/v1`	`alice-secret`
Bob	`http://host.docker.internal:8644/v1`	`bob-secret`

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

💡 Tip

Пользовательские названия моделей Имя модели по умолчанию совпадает с именем профиля. Чтобы переопределить его, установите `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 ...

Открытая интеграция WebUI

Архитектура

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

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

2. Запустите шлюз агента Hermes.

3. Убедитесь, что сервер API доступен.

4. Запустите открытый веб-интерфейс.

5. Откройте пользовательский интерфейс

Настройка Docker Compose

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

API Type: Chat Completions vs Responses

Using Chat Completions (recommended)

Using Responses API

How It Works

Configuration Reference

Hermes Agent (API server)

Open WebUI

Troubleshooting

No models appear in the dropdown

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

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

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

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

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

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

3. Добавьте соединения в Open WebUI

Linux Docker (без Docker Desktop)