Оригинал: https://timofei-ermolaev.ru/courses/open-webui/configure/openai-compatible/ # Подключаем OpenAI-совместимый API Подключим OpenRouter к Open WebUI: разберём адрес API, ключ и ID модели, проверим ответ в чате и найдём причины ошибок соединения. [![Тимофей Ермолаев](https://timofei-ermolaev.ru/_astro/timofei-ermolaev-portrait.s0mCFw-J_Z1x8STQ.webp)]() [Тимофей Ермолаев]() Директор по информационным технологиям (CIO) **Опубликовано** 16 октября 2026 г. **Обновлено** 16 октября 2026 г. **На урок** 11 мин **Тема** [Настройка]() ## После урока вы сможете - Различать базовый адрес API, ключ и идентификатор модели - Добавить серверное подключение к OpenRouter - Проверить ответ модели и разобраться в сообщении об ошибке **Проверяемый результат:** Выбранная модель OpenRouter возвращает полный ответ в чате Open WebUI. Понятно, где сохраняется ключ и кто использует его бюджет. Когда локальная модель не установлена или для задачи нужен внешний сервис, Open WebUI можно подключить к удалённому поставщику по сети. В этом уроке мы настроим такое подключение через панель администратора, выберем одну модель из каталога и получим от неё ответ в обычном чате. ## Разберём, куда уйдёт сообщение Open WebUI показывает чат и хранит историю диалогов, а текст ответа может вычислять внешний сервер. Когда вы отправляете вопрос такой модели, цепочка выглядит так: браузер передаёт сообщение серверу Open WebUI, тот обращается по HTTPS к выбранному API-провайдеру, провайдер направляет запрос поставщику конкретной модели и возвращает ответ обратно через ваш сервер в браузер. Как описано в [руководстве по подключению провайдеров]() , при работе с облачной моделью ваш запрос и включённый в него контекст диалога покидают локальный компьютер и передаются выбранному сервису. Термин «OpenAI-совместимый API» (OpenAI-compatible API) в настройках означает единый формат обмена данными, а не обязательную привязку к компании OpenAI. Многие облачные платформы и шлюзы принимают запросы по тем же правилам, что и оригинальный API OpenAI, поэтому в Open WebUI они подключаются через одно и то же штатное меню. Для примера возьмём [OpenRouter]() : этот сервис использует совместимый формат запросов и открывает доступ к каталогу моделей разных разработчиков через единую точку входа. Настройку выполняем в интерфейсе уже работающего Open WebUI. Подойдёт выбранный ранее способ установки: через `docker run`, Docker Compose или Open WebUI Desktop. Переустанавливать контейнер, открывать терминал или держать запущенной локальную Ollama для этого урока не нужно. Понадобится только вход с правами администратора, который мы настроили в уроке про [первый вход и базовые настройки доступа]() . Если вы используете клиент Open WebUI Desktop для подключения к чужому серверу, учтите, что административные настройки принадлежат тому серверу и регулируются его правилами. ## Подготовим адрес, ключ и имя модели Чтобы сервер Open WebUI смог связаться с внешним сервисом и показать нужную модель в списке, подготовим три значения. | Поле в настройках | Что указывает | Значение для нашего примера | | --- | --- | --- | | **API Base URL** (базовый адрес) | Куда серверу Open WebUI отправлять сетевые запросы | `https://openrouter.ai/api/v1` | | **API Key** (ключ доступа) | По какому секретному токену сервис узнает ваш аккаунт и спишет средства | Ваш собственный ключ, созданный по [инструкции OpenRouter]() | | **Model ID** (идентификатор модели) | Какую именно модель запросить из каталога провайдера | `openai/gpt-4.1-mini` | Разберём назначение каждого значения, чтобы избежать частых опечаток: 1. **Базовый адрес API.** Как указано в [инструкции по подключению совместимых провайдеров]() , для OpenRouter нужно вписать ровно `https://openrouter.ai/api/v1`. Это адрес программного интерфейса, а не главной страницы сайта с веб-чатом. Не удаляйте хвост `/api/v1` и не дописывайте к нему конкретные операции вроде `/models` или `/chat/completions`: сервер Open WebUI сам подставит нужные пути при проверке списка и отправке сообщений. Локальные адреса из уроков по Docker (`localhost` или `host.docker.internal`) здесь не используются, так как обращение идёт к публичному облачному серверу. 2. **Ключ API.** Этот токен заменяет логин и пароль при автоматических обращениях сервера. Он создаётся в вашем личном кабинете OpenRouter и не совпадает ни с паролем от самого Open WebUI, ни с подпиской на веб-чат. При обращении к API ключ передаётся в заголовке Authorization по схеме `Bearer`, но в поле интерфейса нужно вставить только саму строку ключа без слова `Bearer` и без лишних пробелов. При сохранении настроек приложение записывает этот ключ в свою конфигурацию на сервере, чтобы использовать его для будущих запросов. Никогда не публикуйте рабочий ключ в открытых репозиториях Git, общих журналах или на скриншотах. 3. **Идентификатор модели.** Вместо свободного названия используется точный код из каталога провайдера. Мы указываем [`openai/gpt-4.1-mini`]() как пример из каталога. Перед отправкой сообщения загляните в карточку модели и в свой кабинет OpenRouter: проверьте актуальную стоимость токенов, остаток на балансе и лимит, заданный для ключа. Наличие модели в общем каталоге не гарантирует бесплатный доступ, поэтому решения о пополнении счёта или лимитах вы принимаете в своём аккаунте самостоятельно. В [описании разделов конфигурации Open WebUI]() указано: подключение в панели администратора создаётся для всего экземпляра приложения. Пользователи вашего сервера с доступом к выбранной модели будут отправлять запросы через это соединение и расходовать общий бюджет привязанного ключа. В Open WebUI существуют и персональные подключения ([Direct Connections]() ), где ключ хранится локально в браузере конкретного пользователя, а запросы идут напрямую из вкладки браузера. В этом уроке настраиваем серверное подключение через панель администратора. ## Добавим OpenRouter в подключениях администратора Перейдём в интерфейс Open WebUI под учётной записью администратора. Названия пунктов меню могут немного различаться в зависимости от версии приложения и выбранного языка интерфейса, поэтому ориентируйтесь на структуру разделов из официальной документации: 1. Откройте меню профиля, перейдите в **Settings** (Настройки) и выберите раздел **Admin** (Панель администратора). 2. Откройте вкладку **Connections** (Подключения). 3. В блоке **Manage OpenAI API Connections** (Управление подключениями OpenAI API) нажмите кнопку добавления нового соединения (**Add Connection** или значок плюса). В открывшемся окне заполним параметры нашего подключения: - В поле **URL** (или **API Base URL**) введите `https://openrouter.ai/api/v1`. - В поле **API Key** вставьте ваш собственный ключ из кабинета OpenRouter. Если в окне есть поле **Provider**, оставьте **Default** (По умолчанию). - В поле **Model IDs** (Идентификаторы моделей) введите `openai/gpt-4.1-mini` и подтвердите добавление строки в список. Поле **Model IDs** работает как фильтр для интерфейса. У OpenRouter очень большой каталог, и если оставить список пустым, Open WebUI попытается загрузить в выпадающее меню сразу все доступные позиции. Указав один точный идентификатор, мы оставляем от этого подключения в селекторе чата только нужную для проверки модель. Этот фильтр ограничивает список на экране: он не выдаёт права доступа на стороне провайдера и не заменяет финансовые лимиты ключа. Проверка связи и сохранение настроек выполняют разные задачи. Кнопка проверки соединения (**Verify Connection** рядом с полем адреса) отправляет пробный запрос с вашим ключом к списку моделей (`/models`), чтобы убедиться, что сервер OpenRouter отвечает и принимает токен. После проверки нажмите **Save** (Сохранить), чтобы сохранить конфигурацию. Кнопка **Save** сохраняет настройки, а вручную вписанный в **Model IDs** идентификатор `openai/gpt-4.1-mini` может появиться в списке выбора моделей даже без успешной проверки связи или при нулевом балансе. Поэтому ни сохранение формы, ни появление имени модели в меню ещё не доказывают, что генерация текста работает. ## Получим ответ в новом чате Проверим подключение запросом из чата: 1. Вернитесь на главный экран и откройте новый чат (**New Chat**). 2. В верхнем меню выбора модели найдите и выберите `openai/gpt-4.1-mini`. 3. Отправьте один короткий запрос без личных, корпоративных или секретных данных: ``` Ответь одним коротким предложением: для чего нужен список дел? ``` Дождитесь, пока модель полностью допишет ответ. Ответ может быть сформулирован по-разному: совпадение слово в слово не требуется. Главное, чтобы в окне чата появилось законченное осмысленное предложение по теме вопроса, а не плашка с ошибкой или оборванная фраза. Мы не оцениваем здесь стиль или качество рассуждений конкретной модели, а проверяем только исправность канала связи. Даже такой короткий обмен сообщениями может расходовать средства на счету провайдера. Если в вашем кабинете OpenRouter открыт раздел статистики (**Activity**), вы сможете увидеть там запись о выполненном запросе и точный расход токенов. Если ответ почему-то не появился с первого раза, не нажимайте кнопку повторной отправки многократно подряд: сначала проверьте историю операций в кабинете и текст ошибки, чтобы не тратить баланс впустую. Проверка завершена, если модель вернула полный ответ. Особенности других облачных платформ и их тарифы разберём отдельно. ## Найдём причину ошибки по её сообщению Если модель не появилась в списке выбора, первым делом вернитесь в **Admin → Connections**: убедитесь, что само подключение включено и сохранено кнопкой **Save**, в идентификаторе `openai/gpt-4.1-mini` нет лишних символов, а вы настраиваете именно тот сервер Open WebUI, в котором открыли чат. Если же модель выбрана, но вместо ответа в чате или при проверке соединения возвращается ошибка, посмотрите на её текст и код состояния. В [справочнике по отладке OpenRouter]() и [документации по лимитам]() коды ответов служат ориентиром для поиска причины: | Код или симптом | Что обычно означает | Что проверить в первую очередь | | --- | --- | --- | | **401** (Unauthorized) | Ошибка аутентификации | Проверьте, что в поле **API Key** вставлен действующий ключ OpenRouter без слова `Bearer` и пробелов по краям, а сам ключ не был отозван или просрочен в кабинете. | | **402** (Payment Required) | Ограничение по балансу или лимиту стоимости | Проверьте остаток средств на аккаунте, установленный лимит для конкретного ключа и достаточен ли бюджет для выполнения запроса. | | **403** (Forbidden) | Запрет доступа, правил или бюджета | Прочитайте текст сообщения: запрос мог упереться в ограничения прав аккаунта, фильтрацию контента (модерацию) или лимит ключа/рабочего пространства. Не создавайте новые ключи вслепую до чтения причины. | | **404** (Not Found) | Не найден сетевой путь или ресурс | Сверьте базовый адрес (`https://openrouter.ai/api/v1` без лишних сегментов) и точное написание `openai/gpt-4.1-mini` по каталогу. При этом учтите, что отсутствие свободного поставщика для модели может возвращать и другой код. | | **429** (Too Many Requests) | Сработал лимит частоты запросов | Прекратите повторные нажатия, подождите (ориентируясь на заголовок `Retry-After`, если он указан в деталях) и проверьте текущие ограничения вашего тарифа или ключа. | | **Тайм-аут или обрыв ответа** | Сетевая недоступность или сбой при передаче потока | Проверьте, есть ли у самого сервера или контейнера Open WebUI исходящий доступ по DNS и HTTPS к `openrouter.ai`, а также посмотрите статус сервиса и раздел **Activity** в кабинете. | Если сайт `openrouter.ai` открывается в вашем браузере, это ещё не доказывает, что к нему может подключиться серверная часть Open WebUI (особенно если контейнер работает в изолированной среде или за корпоративным прокси). При потоковой генерации (streaming) сервер может сначала успешно установить соединение (код HTTP 200), а сбой у поставщика модели произойдёт уже в процессе передачи текста. Поэтому при оборванном ответе всегда проверяйте итоговое сообщение об ошибке и журнал **Activity** в кабинете OpenRouter, прежде чем отправлять запрос заново. Для исправления ошибок подключения не нужно переустанавливать контейнер, сбрасывать базу данных, удалять тома, отключать проверку TLS-сертификатов или включать пересылку cookies стороннему сервису. После устранения найденной причины сохраните изменённые настройки и повторите контрольный вопрос в новом чате. Урок завершён, когда выбранная модель вернула полный ответ. ## Материалы урока - [Open WebUI: OpenAI-совместимые провайдеры docs.openwebui.com]() - [OpenRouter: начало работы openrouter.ai]() - [OpenRouter: ошибки и диагностика openrouter.ai]() - [OpenRouter: лимиты запросов openrouter.ai]() ## Отметить прохождение Отметьте урок после того, как получили проверяемый результат из практической части. Урок пройден ![Тимофей Ермолаев](https://timofei-ermolaev.ru/_astro/timofei-ermolaev-portrait.s0mCFw-J_2r7Nkv.webp) ## Об авторе ### Тимофей Ермолаев Директор по информационным технологиям (CIO) Пишу о больших языковых моделях, автоматизации и применении ИИ в бизнесе. В статьях разделяю личный опыт, выводы исследований и практические рекомендации. [Подробнее об авторе]()