OpenWebUI API — программный доступ к Open WebUI: внешний скрипт может отправить запрос модели через чат, а настроенный инструмент может связать диалог с внутренним сервисом. Это два разных маршрута интеграции. Первый вызывает Open WebUI извне; во втором сам чат получает доступ к разрешённому инструменту. Перед запуском проверьте права аккаунта, источник данных и запись каждого действия в целевой системе. Если нужен только чат для людей, API лишний: хватит интерфейса и ролей.
Что умеет API
Начните с безопасного запроса GET /api/models, затем проверьте POST /api/chat/completions. Для действия во внутренней системе настройте отдельный инструмент и права на стороне этой системы.
API Open WebUI принимает запросы к моделям и диалогам от скриптов и приложений. Внешняя программа отправляет модель и сообщения на endpoint chat completions, а в ответ получает текст модели. Такой путь подходит для формы заявки, корпоративного портала или пакетной обработки: интерфейс сотрудника может находиться вне Open WebUI. Если же сотрудник уже работает в чате, подключение внутренней системы строится через разрешённый инструмент, например заранее настроенный OpenAPI или MCP сервер. У инструмента собственная схема вызова, а у целевой системы — собственные учётные данные и правила записи. Изменение учётной системы требует отдельного инструмента с правами записи.
Разделите два теста. Первый подтверждает, что ключ видит нужную модель и получает ответ. Второй проверяет реальный маршрут до внутреннего сервиса: какой инструмент был вызван, какие аргументы он получил, что записалось в целевой системе и что увидел пользователь. В API chat completions серверные инструменты можно выбирать через tool_ids, если они заранее подключены в Open WebUI и доступны аккаунту ключа. Для чувствительных действий добавьте подтверждение на стороне инструмента или бизнес-системы. Устройство самого чата поверх локальных моделей разобрано в статье про корпоративный чат на Open WebUI; здесь важен программный маршрут и контроль действий.
Ключи и права
| Уровень | Что ограничивает | Где проверять |
|---|---|---|
| Ключ API | Действует от имени аккаунта, который его создал | Настройки аккаунта и групповые разрешения |
| Доступ к endpoint | Набор доступных маршрутов API | Глобальные ограничения маршрутов у администратора |
| Инструмент | Доступ аккаунта к настроенному серверу инструментов | Права Open WebUI и инструмента |
| Внутренний сервис | Чтение или запись конкретных данных | Учётная запись целевой системы |
| Журнал | Трасса запроса и подтверждение внешнего действия | Шлюз, инструмент и целевая система |
Ключ Open WebUI — персональный токен аккаунта: он наследует роль и группы создателя, а права проверяются при каждом запросе. Для серверной интеграции используйте отдельную служебную учётную запись с минимальными разрешениями, если это допускает политика вашей установки. Администратор сначала включает API Keys; обычному пользователю дополнительно нужно разрешение на создание ключа. В актуальной справке Open WebUI у аккаунта один активный ключ: выпуск нового заменяет прежний. Поэтому ротацию планируйте вместе с обновлением всех клиентов, которые используют этот аккаунт. Ключ передавайте в заголовке Bearer и храните в менеджере секретов, вне промптов и репозитория.
Ограничение доступных endpoint настраивается у администратора для ключей установки в целом, единым правилом, без отдельного списка маршрутов для каждого токена. Для разных уровней доступа разделяйте аккаунты и роли. Даже если чат разрешил вызвать инструмент, внутренний сервис должен самостоятельно проверить учётную запись и допустимость операции. Например, служебный аккаунт может читать карточки заявок, а изменение статуса оформляется отдельным маршрутом с подтверждением. Подход к кастомным инструментам описан в материале про собственный MCP-сервер.
Тестовый запрос
- Включите API Keys у администратора и создайте ключ в настройках отдельного аккаунта.
- Запросите список моделей через GET /api/models и убедитесь, что видна нужная модель.
- Отправьте короткое тестовое сообщение на POST /api/chat/completions.
- Для сценария действия отдельно настройте инструмент и проверьте доступ аккаунта.
- Прогоните безопасный пример от сообщения до ответа инструмента и записи в целевой системе.
- Сверьте журнал шлюза, инструмента и системы по общему идентификатору запроса.
Начните с вымышленных тестовых данных: номер заявки, фамилия и дата должны выглядеть как реальные поля, без раскрытия личной информации клиента при настройке. Простое «привет» проверяет только доступ к модели. Затем дайте вопрос, где нужен внутренний инструмент, и заранее определите ожидаемый результат. Если ответ модели выглядит верным, а записи в учётной системе нет, интеграция пока неполна. И наоборот: запись без понятного пользователю подтверждения создаёт риск повторного действия. Для операций с изменением данных предусмотрите повторный запрос и проверку, что он оставляет ровно одну заявку.
При тесте API chat completions отличайте результат модели от результата инструмента. Серверный вызов через tool_ids требует существующего инструмента и разрешения на него; для защищённого OAuth MCP подключения аккаунт ключа должен пройти авторизацию заранее. Для вашего сервиса дополнительно проверьте кодировки, ошибки сети, превышение времени ожидания и корректный отказ при отсутствии прав.
Какой внутренний сервис подключили бы к чату первым?
Аудит действий
Ключ идентифицирует аккаунт, поэтому человека за общим скриптом нужно фиксировать отдельно. Если несколько сотрудников пользуются одной интеграцией, передавайте в неё отдельный идентификатор пользователя и связывайте его с записью целевой системы. Журналирование проектируется на стороне приложения, шлюза и инструмента: завершение операции в CRM подтверждает запись самой CRM. Для каждой операции сохраните время, идентификатор запроса, вызванный инструмент, результат и решение подтверждающего сотрудника. Секреты, содержимое закрытых документов и лишние персональные данные исключите из логов.
Сверяйте одну цепочку от запроса до ответа в обоих направлениях: в Open WebUI видна попытка, в инструменте — параметры, в учётной системе — итоговая запись. При расхождении ищите точку обрыва по общему идентификатору, без опоры на похожий текст сообщения. Для отправок и записей полезен отдельный журнал подтверждений. Срок хранения и доступ к нему задаются правилами компании. Практика наблюдения за ИИ-приложениями разобрана в статье про наблюдение за ИИ-приложениями.
- Время и идентификатор запроса на каждом участке маршрута.
- Аккаунт ключа и пользователь, который инициировал действие.
- Имя инструмента и итог операции без секретов.
- Отдельная запись о подтверждении действия с записью.
- Проверка отказов, повторов и вызовов с недопустимыми правами.
Где API заканчивается
API Open WebUI решает программный доступ к чату, но связь с учётной системой требует адаптера или инструмента. Сложные маршруты согласования остаются в системе, которая владеет процессом; чат показывает пользователю запрос и результат. Если сценарий требует нескольких шагов, ветвлений и ожидания человека, проектируйте отдельный рабочий процесс с постоянным состоянием. Этапы роста от чата к агентам и состав работ описаны на странице про внедрение ИИ. Для первого выпуска выберите чтение одного типа данных, а запись включайте после теста отказов и проверки полномочий.
Сценарий готов к рабочему пилоту, когда запрос проходит через разрешённый инструмент, результат виден в целевой системе, ошибки дают понятный отказ, а журнал связывает действие с конкретным инициатором. Отдельно проверьте повторный вызов: второй запрос должен оставлять единственную запись.