Open WebUI Integration

Connect QCode.cc to Open WebUI as an OpenAI-compatible connection: the admin Connections page, the Model IDs allowlist, and why Claude is not available

Need an API key? Sign up →·Endpoints & base URLs →

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

At a glance¶

🔴 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.

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.

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.

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.

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:

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:

pip install open-webui
open-webui serve

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

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

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 and Model selection; billing is per token, rates at 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.”

# 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 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:

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.

Troubleshooting / Known limitations¶

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.
• 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.

Related¶

• Endpoints & API Paths — which model family works on which protocol
• Tool compatibility — tools that do speak the Anthropic protocol, for Claude
• China-family models — ids and differences for GLM / Kimi / DeepSeek / Qwen
• Model selection — choosing an id for a task
• Troubleshooting — QCode-side error lookup
• Cherry Studio Integration — a client with an Anthropic-type connection, if you need Claude
• SillyTavern Integration — another OpenAI-compatible client

Enterprise →