Open WebUI 接入

在 Open WebUI 里接入 QCode.cc：管理员连接页填 URL 与密钥、手动加模型 ID 白名单，以及为什么这里用不了 Claude

需要 API Key？ 前往注册 →·端点与 Base URL →

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

接入速览¶

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

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。

用哪条协议¶

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

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 路径。

安装¶

下面三条命令均照抄官方 Quick Start。

Docker——官方要求先装 Docker，并把 your-secret-key 换成 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

端口映射怎么读：官方参数表写「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

官方说明「Open WebUI is now on http://localhost:8080. Set DATA_DIR to choose where your data lives」。

uv（不全局安装，macOS/Linux 示例）：

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，看国产模型接入与模型选择；计费按 token，单价见 qcode.cc/models。

自部署环境变量¶

官方把两条路径视为等价：「Open WebUI is configured via environment variables, and you can also set the same values from the Open WebUI admin panel.」

# 给上面的 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，差异看国产模型接入。

验证¶

官方把预期说得很清楚：「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 侧分开排查，就直接打端点：

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

本轮没有测试密钥，所以页首只标 📄：本页不声称任何状态码或响应内容。你自己请求到的结果，按故障排查对照处理。

已知限制¶

QCode 侧还需要知道的限制：

• 本页工具用不了 Claude：QCode 不在 OpenAI 兼容端点上提供 Claude 的调用路径，Claude 请求属于 Anthropic Messages 端点，而 Open WebUI 不调该协议。要用 Claude，请改用支持 Anthropic 协议的工具或 Claude Code，见工具兼容总览。
• 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 路径。

相关文档¶

• 接入点与 API 路径——哪个模型族能走哪条协议
• 工具兼容总览——要 Claude 时挑支持 Anthropic 协议的工具
• 国产模型接入——GLM / Kimi / DeepSeek / Qwen 的 ID 与差异
• 模型选择——按任务选 ID
• 故障排查指南——QCode 侧报错对照
• Cherry Studio 接入——带 Anthropic 类型连接的客户端
• SillyTavern 接入——另一个 OpenAI 兼容客户端

企业团队版 →