# Подключение Open WebUI

> **Последняя проверка**: 2026-10-13 · 📄 По официальной документации (Open WebUI v0.12.0)

## Кратко

| Параметр | Описание |
|---|---|
| Доступные модели | Claude ❌ **недоступен** (см. два раздела ниже) · GPT ✅ · китайские модели ✅ · Gemini ❌ (семейство Gemini в QCode не предлагается — используйте GPT или китайскую модель) |
| Протокол и Base URL | Только OpenAI Chat Completions: `https://api.qcode.cc/openai/v1` |
| Где настраивать | **Settings → Admin → Connections**, в списке **Manage OpenAI API Connections** |
| Официальная документация | [docs.openwebui.com](https://docs.openwebui.com/) |

🔴 **Claude в Open WebUI недоступен.** Open WebUI отправляет только запросы OpenAI Chat Completions, а модели Claude у QCode работают исключительно на эндпоинте Anthropic Messages ⇒ для Claude возьмите инструмент с поддержкой протокола Anthropic или Claude Code. Какие инструменты что умеют — в [обзоре совместимости](/docs/ide/tool-compatibility).

Open WebUI — это размещаемый у себя чатовый веб-интерфейс, который запускают через Docker, pip или uv. Границы описаны в документации прямым текстом: Open WebUI «connects to any server or provider that implements the OpenAI-compatible API», и пока интерфейс и инструменты на стороне Open WebUI, «it expects your backend to follow the universal Chat Completions standard». Проверялась сборка **v0.12.0** от 2026-10-10. Оплата по токенам, цены по моделям — на [qcode.cc/models](https://qcode.cc/models).

## Какой протокол выбрать

Документация перечисляет несколько протоколов подключения: Ollama, OpenAI-совместимые API и экспериментальная поддержка Open Responses. Здесь описан только путь **OpenAI Chat Completions** — именно его обслуживает OpenAI-эндпоинт QCode.

| Семейство моделей | Работает в Open WebUI | Что указывать |
|---|---|---|
| GPT — `gpt-6.1-sol`, `gpt-6-sol`, `gpt-6-astra`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.5` | ✅ | URL: `https://api.qcode.cc/openai/v1` |
| GLM / Kimi / DeepSeek / Qwen — `deepseek-v4.1-flash`, `deepseek-v4-flash`, `deepseek-v4-pro`, `glm-5.3`, `glm-5.2`, `qwen3.8-max`, `qwen3.8-flash`, `qwen3.7-plus`, `kimi-k3` | ✅ | тот же URL |
| Claude | ❌ **недоступен** — возьмите инструмент с поддержкой протокола Anthropic или Claude Code | Модели Claude в QCode отдаются только через эндпоинт Anthropic Messages `https://api.qcode.cc/api`; Open WebUI этот протокол не вызывает |
| Семейство Gemini | ❌ в QCode не предлагается | используйте GPT или китайскую модель |

Почему строка с Claude — жёсткое «нет», словами самого проекта:

- Open WebUI называет себя «a **protocol-centric** platform», и даже модели OpenAI поддерживает «mainly through the **OpenAI Chat Completions API protocol**». Граница сформулирована прямо: «We do not implement provider-specific, non-standard APIs in the core», и в FAQ это повторено: «We avoid implementing proprietary, provider-specific APIs in the core».
- Встроенное исключение для Anthropic узко по охвату. В официальной странице про Anthropic сказано: «Open WebUI detects Anthropic URLs (any URL containing `api.anthropic.com`)», и даже для такого URL «Chat requests themselves are sent unchanged to Anthropic's OpenAI-compatible `/v1/chat/completions` with Bearer auth.» То есть исключение тоже говорит на Chat Completions и привязано к одному конкретному имени хоста; в адресе подключения QCode его нет.
- В исходниках этого же релиза (`backend/open_webui/config.py` на теге `v0.12.0`) переменные базового адреса OpenAI присутствуют, а поиск слова `anthropic` без учёта регистра даёт **ноль** совпадений — исходящей настройки Anthropic Messages для внешнего шлюза просто нет.
- Один нюанс, который часто читают наоборот: у Open WebUI действительно есть собственный эндпоинт, совместимый с Anthropic Messages, но в документации его назначение описано так: «This allows tools, SDKs, and applications built for the Anthropic API to work directly against Open WebUI», то есть направление **внутрь**. Open WebUI от этого не становится клиентом протокола Anthropic по отношению к вашему провайдеру.
- Для API, которых в Open WebUI нет, официально предлагают pipe-функцию или прокси-переводчик вроде LiteLLM. Мы это на QCode не проверяли, поэтому готовой настройки здесь нет; если Claude нужен сегодня — берите клиент, который говорит по протоколу Anthropic.

Полная таблица «протокол × семейство моделей» — в разделе [Эндпоинты и пути API](/docs/getting-started/endpoints-and-api-paths).

## Установка

Все три команды ниже дословно взяты из официальной Quick Start.

**Docker** — требуется Docker; вместо `your-secret-key` подставьте вывод `openssl rand -hex 32`:

```bash
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data -e WEBUI_SECRET_KEY=your-secret-key --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```

Как читать про маппинг портов: в официальной таблице параметров написано «The UI is on port 3000 of your machine. Change the left number if 3000 is taken.»

**pip**:

```bash
pip install open-webui
open-webui serve
```

По документации: «Open WebUI is now on [http://localhost:8080](http://localhost:8080). Set `DATA_DIR` to choose where your data lives».

**uv** (без глобальной установки, пример для macOS/Linux):

```bash
DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve
```

Версии Python: «Open WebUI supports **Python 3.11 and 3.12**. **Python 3.13 is not supported yet**».

## Настройка

### Через страницу подключений администратора (рекомендуется)

1. Откройте Open WebUI в браузере.
2. Дословно по документации: «Go to **Settings > Admin > Connections** and find the **Manage OpenAI API Connections** list.»
3. «Click ➕ **Add Connection**.»
4. **Connection Type** оставьте External.
5. **URL**: `https://api.qcode.cc/openai/v1`. Официально отмечено, что «The URL field will **suggest common provider endpoints** as you type» — автоподсказки предлагают адреса других провайдеров, поэтому адрес QCode вводите целиком. Требуется ли у адреса стороннего шлюза окончание `/v1`, документация не указывает; ориентируйтесь на адрес, который публикует ваш шлюз. Для QCode это `https://api.qcode.cc/openai/v1`, без слэша в конце.
6. **API Key**: ваш ключ QCode (начинается с `cr_`).
7. **Model IDs** (в блоке **Advanced**): добавьте по одному все ID, которые должны появиться в выборце моделей; официальная формулировка шага — «In the connection settings, find **Model IDs**, type the model ID, and click the **+** icon, then save.» После успешной проверки подключения «the **Model IDs** field suggests the provider's model IDs as you type».
   Пока поле пустое, автоопределение сохраняется («_Default (Empty)_: Auto-detects all available models from the provider.»); как только вы его заполнили, поведение меняется: «Open WebUI stops calling the provider's `/models` for that connection and lists exactly the IDs you typed».
8. **Prefix ID** (необязательно): документация рекомендует префикс, когда «you connect multiple providers that have models with the same name», и указывает: «Open WebUI joins the prefix and the model ID with a dot» — то есть с префиксом `qcode` и ID `glm-5.3` в списке появится `qcode.glm-5.3`.
9. **Provider** (в блоке **Advanced**): оставьте **Default** — «Leaving it at **Default** is always safe.» Этот раскрывающийся список есть только у подключений OpenAI.
10. Нажмите **Save**. У каждого сохранённого подключения есть переключатель, позволяющий отключить его, не удаляя.

Какие ID брать — в разделах [китайские модели](/docs/usage/cn-models) и [выбор модели](/docs/usage/model-selection); оплата по токенам, цены на [qcode.cc/models](https://qcode.cc/models).

### Переменные окружения (экземпляр у себя)

Документация относится к двум путям как к равносильным: «Open WebUI is configured via environment variables, and you can also set the same values from the Open WebUI admin panel.»

```bash
# добавьте эти -e в команду docker выше или экспортируйте до `open-webui serve`
OPENAI_API_BASE_URL=https://api.qcode.cc/openai/v1
OPENAI_API_KEY=cr_your_qcode_key
```

Официальные формулировки: `OPENAI_API_BASE_URL` — «Configures the OpenAI base API URL» (заводское значение `https://api.openai.com/v1`), `OPENAI_API_KEY` — «Sets the OpenAI API key». Чтобы в одном экземпляре распределить запросы между двумя шлюзами, служит `OPENAI_API_BASE_URLS` с описанием «Supports balanced OpenAI base API URLs, semicolon-separated.»

Там же — два важных нюанса:

- Эти переменные помечены как `ConfigVar`, поэтому «After the initial launch, if you restart the container, `ConfigVar` environment variables will no longer use the external environment variable values. Instead, they will use the internally stored values.» Задавайте их до первого запуска — или меняйте позже в интерфейсе администратора.
- Эта справочная страница говорит, что она «is up-to-date with Open WebUI release version [v0.11.1]», тогда как здесь проверен релиз v0.12.0 — после обновления названия переменных стоит перепроверить.

### Китайские модели

Китайские семейства работают через это же OpenAI-совместимое подключение: `deepseek-v4.1-flash`, `deepseek-v4-flash`, `deepseek-v4-pro`, `glm-5.3`, `glm-5.2`, `qwen3.8-max`, `qwen3.8-flash`, `qwen3.7-plus`, `kimi-k3`. Нужные ID добавьте в **Model IDs**, а различия читайте в разделе [китайские модели](/docs/usage/cn-models).

## Проверка

Ожидание задаёт сама документация: «**Saving a connection does not test it.**» Про кнопку рядом с полем URL есть точный текст: «Clicking the **Verify Connection** button beside the URL field calls the provider's `/models` endpoint using a standard `Bearer` token and reports **Server connection verified**». Провайдеры без такого эндпоинта или с нестандартной авторизацией ведут себя так, как описано: «The connection verification will **fail with an error** (e.g., 400, 401 or 403).» — и дальше: «This does **not** mean the provider is incompatible: **chat completions will still work**». Официальное решение — добавить названия моделей вручную: «You just need to **manually add model names** to the **Model IDs** allowlist in the connection settings.»

Как поступить на практике:

1. Занесите нужные ID в **Model IDs** — это надёжный путь независимо от того, что показала кнопка проверки.
2. Отправьте одно сообщение модели из этого списка: именно такой обмен запросом и ответом и есть настоящая проверка.
3. Чтобы разделить сторону QCode и сторону Open WebUI, можно обратиться к эндпоинту напрямую:

```bash
curl -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $QCODE_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"deepseek-v4.1-flash","messages":[{"role":"user","content":"ping"}]}'
```

Тестового ключа в этом заходе у нас не было, поэтому в начале страницы стоит только 📄: ни код ответа, ни тело ответа здесь не заявляются. Что вернётся у вас — разбирайте по [руководству по устранению неполадок](/docs/reference/troubleshooting).

## Известные ограничения

| Симптом | Что говорит документация | Что делать |
|---|---|---|
| Список моделей пуст или неполон | `/models` нужен для «Used for model discovery and selecting models in the UI. If not available, add models to the allowlist manually.» | Добавляйте каждый ID в **Model IDs** |
| Список моделей загружается медленно, или после сохранения недоступного адреса интерфейс подвисает | «Raise the timeout for slower connections. The default is 10 seconds, and an empty value disables it», например `AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=30` | Задайте переменную или уберите неверный адрес |
| Из контейнера не видно сервис на вашей машине | «If running Open WebUI in Docker and your model server is on the host machine, replace `localhost` with `host.docker.internal` in the URL.» | Перепишите URL |
| Подключение администратора падает, а пользовательские работают | Документация приводит симптом «502 Bad Gateway on admin-configured connections while user connections work fine» и объясняет, что для административных и глобальных запросов «the Open WebUI backend resolves that hostname, and inside a Docker container, it may resolve to `127.0.0.1`»; официальный совет: «For backend/admin connections, use the **internal URL** that the backend can actually reach» | Проверяйте адрес, который разрешает бэкенд, а не тот, что видит браузер |
| Установка через pip или uv не проходит | «Open WebUI supports **Python 3.11 and 3.12**. **Python 3.13 is not supported yet**» | Используйте 3.11 или 3.12 |
| В другом типе подключения нет списка Provider | «The **Provider** dropdown belongs to OpenAI connections only.» | Он там и не предусмотрен |

Что важно знать про ограничения на стороне QCode:

- **Claude из этого инструмента недоступен.** QCode не предоставляет путь к Claude через OpenAI-совместимый эндпоинт; запросы Claude относятся к эндпоинту Anthropic Messages, а Open WebUI его не вызывает. Для Claude возьмите инструмент с поддержкой протокола Anthropic или Claude Code — см. [обзор совместимости](/docs/ide/tool-compatibility).
- `gpt-6-luna` / `gpt-5.6-luna` в QCode не предлагаются, как и семейство Gemini; берите `gpt-6.1-sol`, `gpt-6-sol`, `gpt-5.6-terra` или китайскую модель.
- **Direct Connections** (браузер пользователя идёт прямо к провайдеру) официально помечены как «currently **experimental**» и по умолчанию выключены — включает администратор: «**Settings > Admin > Connections > Direct Connections**: Toggle **On**» либо `ENABLE_DIRECT_CONNECTIONS=true`, что «Enables or disables direct connections.»; ключ при этом хранится на клиенте: «keys are stored in the browser's local storage». Поскольку запрос идёт из браузера, документация требует, чтобы «the API provider must have **Cross-Origin Resource Sharing (CORS)** configured to allow requests from your Open WebUI domain»; отвечает ли QCode на прямые запросы из браузера для вашего домена, здесь не проверялось, поэтому рассчитывайте на подключение администратора.
- Ни одна проверка на этой странице не выполнялась с реальным ключом. Названия полей, пути в меню, имена переменных и команды приведены по официальной документации; значения эндпоинтов QCode взяты из раздела [Эндпоинты и пути API](/docs/getting-started/endpoints-and-api-paths).

## Связанные документы

- [Эндпоинты и пути API](/docs/getting-started/endpoints-and-api-paths) — какое семейство моделей по какому протоколу работает
- [Обзор совместимости инструментов](/docs/ide/tool-compatibility) — чем пользоваться, если нужен Claude
- [Китайские модели](/docs/usage/cn-models) — ID и различия GLM / Kimi / DeepSeek / Qwen
- [Выбор модели](/docs/usage/model-selection) — как подбирать ID под задачу
- [Устранение неполадок](/docs/reference/troubleshooting) — разбор ошибок на стороне QCode
- [Подключение Cherry Studio](/docs/ide/cherry-studio) — клиент с подключением типа Anthropic
- [Подключение SillyTavern](/docs/ide/sillytavern) — ещё один OpenAI-совместимый клиент