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

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

Архитектура

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

Расположение среды выполнения

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

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

Open WebUI общается с VibeOS по схеме «сервер-сервер», поэтому для этой интеграции вам не нужен API_SERVER_CORS_ORIGINS.

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

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

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

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

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

проверяет, что ~/.vibeos/.env содержит API_SERVER_ENABLED, API_SERVER_HOST, API_SERVER_KEY, API_SERVER_PORT и API_SERVER_MODEL_NAME
перезапускает шлюз VibeOS, чтобы API-сервер запустился
устанавливает Open WebUI в ~/.local/open-webui-venv
создаёт лаунчер в ~/.local/bin/start-open-webui-vibeos.sh
на macOS устанавливает пользовательский сервис launchd; на Linux с systemd --user устанавливает пользовательский сервис там же

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

API VibeOS: http://127.0.0.1:8642/v1
Open WebUI: http://127.0.0.1:8080
имя модели, передаваемое в Open WebUI: VibeOS

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

OPEN_WEBUI_NAME='My VibeOS UI' \
OPEN_WEBUI_ENABLE_SIGNUP=true \
VIBEOS_API_MODEL_NAME='My VibeOS' \
bash scripts/setup_open_webui.sh

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

OPEN_WEBUI_ENABLE_SERVICE=false bash scripts/setup_open_webui.sh

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

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

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

vibeos gateway stop && vibeos gateway

2. Запустите шлюз VibeOS

vibeos 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":"vibeos-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 успокоится, прежде чем открывать интерфейс.

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

Перейдите на http://localhost:3000. Создайте учётную запись администратора (первый пользователь становится администратором). Вы должны увидеть своего агента в выпадающем списке моделей (названного по вашему профилю или vibeos-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-ключ: то же самое значение, что и API_SERVER_KEY в VibeOS
Нажмите галочку, чтобы проверить подключение
Сохраните

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

предупреждение

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

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

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

Перейдите в Настройки администратора → Подключения → OpenAI → Управление
Отредактируйте подключение vibeos-agent
Измените Тип API с «Chat Completions» на «Responses (Experimental)»
Сохраните

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

примечание

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

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

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

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

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

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

Прогресс инструментов

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

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

VibeOS (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 VibeOS (включая `/v1`)
`OPENAI_API_KEY`	Должен быть непустым. Должен совпадать с вашим `API_SERVER_KEY`.

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

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

Проверьте, что URL содержит суффикс /v1: http://host.docker.internal:8642/v1 (не просто :8642)
Проверьте, что шлюз запущен: curl http://localhost:8642/health должен возвращать {"status": "ok"}
Проверьте список моделей: curl -H "Authorization: Bearer your-secret-key" http://localhost:8642/v1/models должен возвращать список с vibeos-agent
Сеть Docker: Изнутри Docker localhost означает контейнер, а не ваш хост. Используйте host.docker.internal или --network=host.
Пустой бэкенд Ollama затеняет выбор: Если вы опустили ENABLE_OLLAMA_API=false, Open WebUI показывает пустой раздел Ollama над вашими моделями VibeOS. Перезапустите контейнер с -e ENABLE_OLLAMA_API=false или отключите Ollama в Настройки администратора → Подключения.

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

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

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

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

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

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

предупреждение

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

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

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

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

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

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

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

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

vibeos -p alice gateway &
vibeos -p bob gateway &

3. Добавьте подключения в Open WebUI

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

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

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

Пользовательские имена моделей

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

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

Linux Docker (без Docker Desktop)

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

# Вариант 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 ...

Архитектура​

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

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

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

2. Запустите шлюз VibeOS​

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

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

5. Откройте интерфейс​

Настройка через Docker Compose​

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

Тип API: Chat Completions vs Responses​

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

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

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

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

VibeOS (API-сервер)​

Open WebUI​

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

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

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

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

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

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

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

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

3. Добавьте подключения в Open WebUI​

Linux Docker (без Docker Desktop)​