# Open WebUI 接入

> **最后核实**：2026-10-13 · 📄 依据官方文档（Open WebUI v0.12.0）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | Claude ❌ **不可用**（见下两节）· GPT ✅ · 国产 ✅ · Gemini ❌（QCode 暂不提供 Gemini 系列，请改用 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/) |

🔴 **Open WebUI 里用不了 Claude。** Open WebUI 只发 OpenAI Chat Completions 请求，而 QCode 的 Claude 模型只能走 Anthropic 协议端点 ⇒ 要用 Claude，请改用支持 Anthropic 协议的工具或 Claude Code。各工具的协议支持情况见[工具兼容总览](/docs/ide/tool-compatibility)。

Open WebUI 是一个自部署的聊天 Web 界面，用 Docker、pip 或 uv 起。官方文档把边界写得很明白：Open WebUI「connects to any server or provider that implements the OpenAI-compatible API」，它负责界面与工具，而后端「it expects your backend to follow the universal Chat Completions standard」。本页核对的版本是 **v0.12.0**，发布于 2026-10-10。计费按 token，各模型单价见 [qcode.cc/models](https://qcode.cc/models)。

## 用哪条协议

官方列出的连接协议有多种——Ollama、OpenAI 兼容 API，以及对 Open Responses 的实验性支持。本页只讲 **OpenAI Chat Completions** 这一条，也正是 QCode 的 OpenAI 端点所服务的协议。

| 模型族 | 在 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 | QCode 的 Claude 模型只在 Anthropic Messages 端点 `https://api.qcode.cc/api` 上提供，Open WebUI 无法调用该协议 |
| Gemini 系列 | ❌ QCode 暂不提供 | 改用 GPT 或国产模型 |

Claude 这一行为什么是硬「不可用」，用官方原话：

- Open WebUI 自称「a **protocol-centric** platform」，连 OpenAI 模型也「we do so 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 的连接地址里不含它。
- 同一版发布的源码里（tag `v0.12.0` 的 `backend/open_webui/config.py`），OpenAI 基础地址相关变量一应俱全，而对 `anthropic` 做忽略大小写的检索结果是 0 条——没有任何面向外部网关的 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**，并不是把 Open WebUI 变成能对服务商说 Anthropic 协议的客户端。
- 遇到 Open WebUI 未实现的 API，官方给的兜底办法是 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)；计费按 token，单价见 [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
# 给上面的 docker 命令加 -e，或在 open-webui serve 之前 export
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`。把要用的填进 **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.」 | 在 **Model IDs** 里逐个补 ID |
| 拉模型列表很慢，或存了不可达地址后界面卡住 | 「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 不在 OpenAI 兼容端点上提供 Claude 的调用路径，Claude 请求属于 Anthropic Messages 端点，而 Open WebUI 不调该协议。要用 Claude，请改用支持 Anthropic 协议的工具或 Claude Code，见[工具兼容总览](/docs/ide/tool-compatibility)。
- QCode 暂不提供 `gpt-6-luna` / `gpt-5.6-luna`，也不提供 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 时挑支持 Anthropic 协议的工具
- [国产模型接入](/docs/usage/cn-models)——GLM / Kimi / DeepSeek / Qwen 的 ID 与差异
- [模型选择](/docs/usage/model-selection)——按任务选 ID
- [故障排查指南](/docs/reference/troubleshooting)——QCode 侧报错对照
- [Cherry Studio 接入](/docs/ide/cherry-studio)——带 Anthropic 类型连接的客户端
- [SillyTavern 接入](/docs/ide/sillytavern)——另一个 OpenAI 兼容客户端