---
title: "Open WebUI"
description: "Open WebUI 通过 OpenAI 兼容连接调用 pirouter：连接地址填 https://api.pirouter.ai/v1、key 填 pirouter 的 API key，再用模型 ID 白名单限定模型，并把后台任务模型设成 Claude Haiku 5.5。"
canonical: "https://pirouter.ai/zh/docs/integrations/open-webui"
last-updated: "2026-10-18"
lang: "zh"
source: "content/docs/zh/integrations/open-webui.mdx"
---

# Open WebUI

Open WebUI 通过 OpenAI 兼容连接调用 pirouter：连接地址填 https://api.pirouter.ai/v1、key 填 pirouter 的 API key，再用模型 ID 白名单限定模型，并把后台任务模型设成 Claude Haiku 5.5。

[Open WebUI](https://github.com/open-webui/open-webui) 加一条 OpenAI 兼容连接就能用 pirouter：地址填 `https://api.pirouter.ai/v1`，key 填 pirouter 的 key。可以在管理员设置里加，也可以在启动 Docker 容器时用环境变量写好。建议同时填模型 ID 白名单，并给后台任务指定一个便宜的模型。

## 前提

- 一个 pirouter API key。还没有的话，按[快速开始](https://pirouter.ai/zh/docs/quickstart.md)创建一个，并存进环境变量：

```bash
export PIROUTER_API_KEY="sk-pi-..."
```

- 一个已经在运行的 Open WebUI 实例和它的管理员账号；或者装好 Docker，按下面的方式二新起一个。本页在 Open WebUI v0.12.3 上验证。
- 想用的模型 ID。能用哪些模型，见[模型与协议](https://pirouter.ai/zh/docs/models.md#每个模型接受哪些协议)的协议表里 OpenAI 一列，只选文本模型。

## 配置

Open WebUI 用 OpenAI 协议调用 pirouter：聊天请求发到 `POST /v1/chat/completions`，key 放在 `Authorization: Bearer` 请求头里。地址要带 `/v1`，末尾不加斜杠。

### 方式一：在管理员设置里添加

1. 打开 **设置 → 管理员 → 外部连接**（英文界面是 **Admin → Connections**），在 **管理 OpenAI 接口连接** 一行点 **+**。
2. URL 填 `https://api.pirouter.ai/v1`，API 密钥填你的 pirouter key。
3. 在模型 ID（Model IDs）里逐个加上要用的模型，例如 `anthropic/claude-sonnet-5.5`、`anthropic/claude-haiku-5.5`、`openai/gpt-6.1-sol`、`google/gemini-4-argon`。
4. 可以先点 **Verify Connection** 检查地址和 key，再点 **Save** 保存。保存本身不会测试连接。

保存后，连接列表里出现这条 pirouter 连接，只显示地址：

![Open WebUI 管理员设置的外部连接页：OpenAI 接口已开启，连接列表里是 https://api.pirouter.ai/v1，Ollama 接口已关闭](/docs/shots/open-webui-connections.zh.webp)

模型 ID 白名单为空时，Open WebUI 会拉取 `https://api.pirouter.ai/v1/models`，把 pirouter 的整个模型目录放进模型选择器，其中包括不能用来聊天的图像模型。填了白名单，选择器里就只有你填的这几个。

### 方式二：用 Docker 环境变量启动

新起一个容器时，可以把连接写进环境变量。先建一个 env 文件：

`open-webui.env`:

```bash
OPENAI_API_BASE_URL=https://api.pirouter.ai/v1
ENABLE_OLLAMA_API=false
OPENAI_API_CONFIGS={"0":{"enable":true,"model_ids":["anthropic/claude-sonnet-5.5","anthropic/claude-haiku-5.5","openai/gpt-6.1-sol","google/gemini-4-argon"]}}
TASK_MODEL_EXTERNAL=anthropic/claude-haiku-5.5
```

各项的作用：

- `OPENAI_API_BASE_URL`：OpenAI 兼容连接的地址。
- `ENABLE_OLLAMA_API=false`：关掉 Ollama 连接。不关的话，Open WebUI 会一直去连本机的 Ollama。
- `OPENAI_API_CONFIGS`：第 0 条连接的模型 ID 白名单。JSON 写在一行里，不加引号。
- `TASK_MODEL_EXTERNAL`：后台任务用的模型，见下一节。

然后启动容器，key 从当前终端的环境变量传进去：

```bash
docker run -d -p 3000:8080 \
  --env-file open-webui.env \
  -e OPENAI_API_KEY="$PIROUTER_API_KEY" \
  -v open-webui:/app/backend/data \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:v0.12.3-slim
```

`slim` 镜像不带本地模型和语音组件，只用外部模型聊天时够用。启动后打开 `http://localhost:3000`，注册第一个账号。

这些环境变量只在第一次启动时写进 Open WebUI 的数据库。之后再改 env 文件、重启容器，界面里的设置不会变，要改就去管理员设置里改。

### 后台任务用便宜的模型

在浏览器里聊天时，Open WebUI 会在后台额外发请求：生成对话标题、标签和追问建议。默认这些请求用你正在聊天的模型，聊天模型是旗舰模型时，每条消息都多出几笔旗舰模型的费用。

把任务模型设成 `anthropic/claude-haiku-5.5`：方式二里已经用 `TASK_MODEL_EXTERNAL` 设好；方式一在 **管理员设置 → 界面** 的任务设置里选 **External Task Model**。任务模型必须也在模型 ID 白名单里。

## 验证

在浏览器里新建一个对话，选 `anthropic/claude-sonnet-5.5`，发一句 `Reply with exactly: pong`。

你应该看到模型回复 `pong`，几秒后对话标题也自动生成。

不想开浏览器的话，用 Open WebUI 的 HTTP API。先用你的 Open WebUI 账号登录，拿到 token：

```bash
TOKEN=$(curl -s -X POST http://localhost:3000/api/v1/auths/signin \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}' | jq -r .token)
```

再发一次聊天请求：

```bash
curl -s http://localhost:3000/api/chat/completions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-sonnet-5.5","messages":[{"role":"user","content":"Reply with exactly: pong"}]}' \
  | jq -r '.choices[0].message.content'
```

你应该看到终端打印 `pong`。

在控制台[日志](https://pirouter.ai/zh/docs/guides/logs.md)里能看到这次请求，**端点** 一栏是 `/v1/chat/completions`。浏览器里的第一条消息会多出几条后台任务请求，模型是任务模型。

## 排障

### 只能用 OpenAI 兼容连接

Open WebUI 只在连接地址包含 `api.anthropic.com` 时才按 Anthropic 处理，pirouter 的地址不会被识别成 Anthropic。在 Open WebUI 里接 pirouter 一律加 OpenAI 兼容连接；Claude 模型照样能选，它们在 pirouter 上也接受 OpenAI 协议。

### 改了环境变量不生效

连接地址、白名单、任务模型这些环境变量只在第一次启动时生效，之后以数据库里的值为准。去管理员设置里改；或者设 `ENABLE_PERSISTENT_CONFIG=false`，让每次启动都读环境变量。

### 任务模型没生效，后台请求还是用聊天模型

任务模型不在模型列表里时，Open WebUI 不报错，后台任务直接改用当前聊天模型。用了白名单的话，把任务模型的 ID 也加进白名单。

## 目前没有验证的用法

- 连接的 API 类型选 Responses（实验功能）时，Open WebUI 改为请求 `/v1/responses`。这种用法还没有验证。
- 在 Open WebUI 里开启工具调用（包括内置工具）后的流式回复还没有验证。

## 相关链接

- [Open WebUI](https://github.com/open-webui/open-webui)（GitHub）
- [快速开始](https://docs.openwebui.com/getting-started/quick-start)：Docker 安装与镜像说明
- [连接 OpenAI 兼容服务](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible)
- [环境变量参考](https://docs.openwebui.com/reference/env-configuration)
- [任务模型](https://docs.openwebui.com/features/administration/task-models)