# Open WebUI Integration

> **Last verified**: 2026-10-13 · 📄 Per official docs (Open WebUI v0.12.0)

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ❌ **not available** (see the next two sections) · GPT ✅ · Chinese models ✅ · Gemini ❌ — QCode does not offer the Gemini family, use a GPT or Chinese model instead |
| Protocol & Base URL | OpenAI Chat Completions only: `https://api.qcode.cc/openai/v1` |
| Where to configure | **Settings → Admin → Connections**, in the **Manage OpenAI API Connections** list |
| Official docs | [docs.openwebui.com](https://docs.openwebui.com/) |

🔴 **Claude is not available in Open WebUI.** Open WebUI only sends OpenAI Chat Completions requests, and QCode serves its Claude models exclusively on the Anthropic Messages endpoint — for Claude, use a tool that speaks the Anthropic protocol, or Claude Code. The per-tool overview is in [Tool compatibility](/docs/ide/tool-compatibility).

Open WebUI is a self-hosted chat web interface that you run with Docker, pip, or uv. Its own documentation states the scope plainly: Open WebUI “connects to any server or provider that implements the OpenAI-compatible API”, and while Open WebUI handles the interface and tools, “it expects your backend to follow the universal Chat Completions standard”. The build checked here is **v0.12.0**, published 2026-10-10. Pricing is per token; per-model rates are listed at [qcode.cc/models](https://qcode.cc/models).

## Which protocol

The docs list several connection protocols — Ollama, OpenAI-compatible APIs, and experimental support for Open Responses. This page covers only the **OpenAI Chat Completions** route, which is the one QCode's OpenAI endpoint serves.

| Model family | Works in Open WebUI | What to fill in |
|---|---|---|
| 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` | ✅ | same URL |
| Claude | ❌ **not available** — use a tool that speaks the Anthropic protocol, or Claude Code | QCode serves Claude on the Anthropic Messages endpoint `https://api.qcode.cc/api`; Open WebUI cannot call that protocol |
| Gemini family | ❌ QCode does not offer the Gemini family | use a GPT or Chinese model |

Why the Claude row is a hard “no”, in the project's own words:

- Open WebUI calls itself “a **protocol-centric** platform”, and even for OpenAI models “we do so mainly through the **OpenAI Chat Completions API protocol**”. The docs are blunt about the boundary: “We do not implement provider-specific, non-standard APIs in the core”, and the FAQ repeats “We avoid implementing proprietary, provider-specific APIs in the core”.
- The built-in Anthropic special case is narrow. The official Anthropic guide: “Open WebUI detects Anthropic URLs (any URL containing `api.anthropic.com`)” — and even for such a URL, “Chat requests themselves are sent unchanged to Anthropic's OpenAI-compatible `/v1/chat/completions` with Bearer auth.” The special case is still Chat Completions, keyed to one specific hostname, and a QCode connection address does not contain it.
- In the released source of that same version (`backend/open_webui/config.py` at tag `v0.12.0`), the OpenAI base-URL variables are all present while a case-insensitive search for `anthropic` returns zero matches — there is no outbound Anthropic Messages setting to point at a gateway.
- One detail that gets misread: Open WebUI does expose an Anthropic Messages compatible endpoint of its own, but the docs state its purpose as allowing “tools, SDKs, and applications built for the Anthropic API to work directly against Open WebUI” — the direction is **inward**. It does not turn Open WebUI into an Anthropic-protocol client for your provider.
- Where a provider speaks an API Open WebUI does not implement, the documented route is a pipe function or a translation proxy such as LiteLLM. We have not verified either against QCode, so this page gives no such recipe — if you need Claude today, pick a client that speaks the Anthropic protocol.

For the full protocol × model-family table, see [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths).

## Install

All three commands below are copied from the official quick start.

**Docker** — the docs require Docker and tell you to replace `your-secret-key` with the output of `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
```

Reading the port mapping: the official flag table says “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
```

Per the docs, “Open WebUI is now on [http://localhost:8080](http://localhost:8080). Set `DATA_DIR` to choose where your data lives”.

**uv** (no global install; the macOS/Linux example):

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

Python versions: “Open WebUI supports **Python 3.11 and 3.12**. **Python 3.13 is not supported yet**”.

## Configure

### The admin connections route (recommended)

1. Open Open WebUI in your browser.
2. As the docs put it, “Go to **Settings > Admin > Connections** and find the **Manage OpenAI API Connections** list.”
3. “Click ➕ **Add Connection**.”
4. Keep **Connection Type**: External.
5. **URL**: `https://api.qcode.cc/openai/v1`. The official guide notes that “The URL field will **suggest common provider endpoints** as you type” — those suggestions are other vendors' addresses, so type the QCode address in full. The docs do not state whether a custom gateway address must end in `/v1`; use exactly the address your gateway publishes. For QCode that is `https://api.qcode.cc/openai/v1`, with no trailing slash.
6. **API Key**: your QCode key (starts with `cr_`).
7. **Model IDs** (under **Advanced**): add every ID you want to see in the model selector, one at a time — the official wording is “In the connection settings, find **Model IDs**, type the model ID, and click the **+** icon, then save.” Once a connection verifies, “the **Model IDs** field suggests the provider's model IDs as you type”.
   Leaving the field empty keeps auto-detection (“_Default (Empty)_: Auto-detects all available models from the provider.”); filling it in changes the behaviour: “Open WebUI stops calling the provider's `/models` for that connection and lists exactly the IDs you typed”.
8. **Prefix ID** (optional): the docs recommend a prefix when “you connect multiple providers that have models with the same name” and state that “Open WebUI joins the prefix and the model ID with a dot” — so with the prefix `qcode` and the id `glm-5.3`, the selector shows `qcode.glm-5.3`.
9. **Provider** (under **Advanced**): leave it at **Default**. “Leaving it at **Default** is always safe.” The dropdown exists for OpenAI connections only.
10. Click **Save**. Every stored connection also carries a toggle switch that lets you enable or disable it without deleting it.

Pick the IDs you actually want from [China-family models](/docs/usage/cn-models) and [Model selection](/docs/usage/model-selection); billing is per token, rates at [qcode.cc/models](https://qcode.cc/models).

### Environment variables (self-hosted instances)

The docs treat the two routes as equivalent: “Open WebUI is configured via environment variables, and you can also set the same values from the Open WebUI admin panel.”

```bash
# add these -e flags to the docker command above, or export them before `open-webui serve`
OPENAI_API_BASE_URL=https://api.qcode.cc/openai/v1
OPENAI_API_KEY=cr_your_qcode_key
```

Documented meanings: `OPENAI_API_BASE_URL` “Configures the OpenAI base API URL” (its shipped default is `https://api.openai.com/v1`), `OPENAI_API_KEY` “Sets the OpenAI API key”. To balance two gateways in one instance, `OPENAI_API_BASE_URLS` “Supports balanced OpenAI base API URLs, semicolon-separated.”

Two caveats straight from that reference page:

- These variables are marked `ConfigVar`, so “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.” Set them before the first start, or change them later in the admin UI.
- The same page says it “is up-to-date with Open WebUI release version [v0.11.1]”, while the release verified here is v0.12.0 — re-check the variable names after an upgrade.

### Chinese models

The Chinese families all work on this same OpenAI-compatible connection: `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`. Add the ones you want to **Model IDs**, then read [China-family models](/docs/usage/cn-models) for the differences.

## Verify

Open WebUI's own docs set the expectation: “**Saving a connection does not test it.**” The button beside the URL field is described precisely: “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**.” Providers that do not implement that endpoint, or protect it differently, are documented to behave like this: “The connection verification will **fail with an error** (e.g., 400, 401 or 403).” — and “This does **not** mean the provider is incompatible: **chat completions will still work**.” The documented remedy is manual: “You just need to **manually add model names** to the **Model IDs** allowlist in the connection settings.”

So, in practice:

1. Put the IDs you intend to use into **Model IDs** — that is the reliable path regardless of what the verification button says.
2. Send one message to one allowlisted model in the chat. That round trip is the real test.
3. If you want to separate the QCode side from the Open WebUI side, call the endpoint directly:

```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"}]}'
```

We hold no test key for this round, which is why the marker at the top stays 📄: no status code and no response body is claimed here. Compare what your own request returned with the entries under [Troubleshooting](/docs/reference/troubleshooting).

## Troubleshooting / Known limitations

| Symptom | Official wording | What to do |
|---|---|---|
| Model list is empty or missing entries | `/models` is “Used for model discovery and selecting models in the UI. If not available, add models to the allowlist manually.” | Add each ID under **Model IDs** |
| Model list fetch is slow, or a saved unreachable address stalls the UI | “Raise the timeout for slower connections. The default is 10 seconds, and an empty value disables it”, e.g. `AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=30` | Set the variable, or clear the bad URL |
| A server on your own machine is not reachable from the container | “If running Open WebUI in Docker and your model server is on the host machine, replace `localhost` with `host.docker.internal` in the URL.” | Rewrite the URL |
| Admin connection fails while user connections work | The docs list “502 Bad Gateway on admin-configured connections while user connections work fine” and explain that for admin/global requests “the Open WebUI backend resolves that hostname, and inside a Docker container, it may resolve to `127.0.0.1`”; official advice: “For backend/admin connections, use the **internal URL** that the backend can actually reach” | Check the address the backend resolves, not the one your browser sees |
| pip or uv install breaks | “Open WebUI supports **Python 3.11 and 3.12**. **Python 3.13 is not supported yet**” | Use 3.11 or 3.12 |
| The Provider dropdown is nowhere to be found | “The **Provider** dropdown belongs to OpenAI connections only.” | It is not offered on other connection types |

QCode-side limits worth knowing before you plan a rollout:

- **Claude is not reachable from this tool.** QCode does not publish a Claude path on the OpenAI-compatible endpoint; Claude requests belong on the Anthropic Messages endpoint, which Open WebUI does not call. For Claude, use a tool that speaks the Anthropic protocol, or Claude Code — see [Tool compatibility](/docs/ide/tool-compatibility).
- QCode does not offer `gpt-6-luna` / `gpt-5.6-luna`, or the Gemini family; use `gpt-6.1-sol`, `gpt-6-sol`, `gpt-5.6-terra`, or a Chinese model.
- **Direct Connections** (users pointing their browser straight at a provider) is documented as “currently **experimental**”, and off unless the admin turns it on — “**Settings > Admin > Connections > Direct Connections**: Toggle **On**”, or `ENABLE_DIRECT_CONNECTIONS=true`, which “Enables or disables direct connections” — and there the key lives client-side: “keys are stored in the browser's local storage”. Because the browser makes the call, the official page requires that “the API provider must have **Cross-Origin Resource Sharing (CORS)** configured to allow requests from your Open WebUI domain”; whether QCode answers browser-direct requests for your domain is not verified here, so treat the admin connection as the supported route.
- Nothing on this page was run against a live key. Field names, menu paths, variable names, and commands are quoted from the official docs; the QCode endpoint values come from [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths).

## Related

- [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths) — which model family works on which protocol
- [Tool compatibility](/docs/ide/tool-compatibility) — tools that do speak the Anthropic protocol, for Claude
- [China-family models](/docs/usage/cn-models) — ids and differences for GLM / Kimi / DeepSeek / Qwen
- [Model selection](/docs/usage/model-selection) — choosing an id for a task
- [Troubleshooting](/docs/reference/troubleshooting) — QCode-side error lookup
- [Cherry Studio Integration](/docs/ide/cherry-studio) — a client with an Anthropic-type connection, if you need Claude
- [SillyTavern Integration](/docs/ide/sillytavern) — another OpenAI-compatible client