---
title: "Open WebUI"
description: "Open WebUI calls pirouter through an OpenAI-compatible connection: set the URL to https://api.pirouter.ai/v1 and the key to a pirouter API key, limit the models with a Model IDs allowlist, and run background tasks on Claude Haiku 5.5."
canonical: "https://pirouter.ai/docs/integrations/open-webui"
last-updated: "2026-10-18"
lang: "en"
source: "content/docs/en/integrations/open-webui.mdx"
---

# Open WebUI

Open WebUI calls pirouter through an OpenAI-compatible connection: set the URL to https://api.pirouter.ai/v1 and the key to a pirouter API key, limit the models with a Model IDs allowlist, and run background tasks on Claude Haiku 5.5.

[Open WebUI](https://github.com/open-webui/open-webui) works with pirouter once you add one OpenAI-compatible connection: the URL is `https://api.pirouter.ai/v1` and the key is a pirouter key. Add it in the admin settings, or set it with environment variables when you start the Docker container. Fill in a Model IDs allowlist as well, and give background tasks a cheap model.

## Prerequisites

- A pirouter API key. If you do not have one, create it with the [quickstart](https://pirouter.ai/docs/quickstart.md) and store it in an environment variable:

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

- A running Open WebUI instance and its admin account, or Docker installed so you can start a new one with option 2 below. This page was verified on Open WebUI v0.12.3.
- The model IDs you want to use. For the models available, see the OpenAI column of the protocol table in [Models & protocols](https://pirouter.ai/docs/models.md#which-protocols-each-model-accepts), and pick text models only.

## Configure

Open WebUI calls pirouter over the OpenAI protocol: chat requests go to `POST /v1/chat/completions`, with the key in the `Authorization: Bearer` header. Keep `/v1` in the URL and leave off the trailing slash.

### Option 1: add it in the admin settings

1. Open **Settings → Admin → Connections**, and click **+** on the **Manage OpenAI API Connections** row.
2. Set **URL** to `https://api.pirouter.ai/v1` and **API Key** to your pirouter key.
3. Under **Model IDs**, add each model you want, for example `anthropic/claude-sonnet-5.5`, `anthropic/claude-haiku-5.5`, `openai/gpt-6.1-sol` and `google/gemini-4-argon`.
4. Optionally click **Verify Connection** to check the URL and key, then click **Save**. Saving does not test the connection by itself.

Once saved, the pirouter connection appears in the list, showing only its URL:

![The Connections page in Open WebUI admin settings: OpenAI API is on, the connection list shows https://api.pirouter.ai/v1, and Ollama API is off](/docs/shots/open-webui-connections.en.webp)

With an empty Model IDs allowlist, Open WebUI fetches `https://api.pirouter.ai/v1/models` and puts pirouter's whole catalog in the model picker, image models included, which cannot chat. With an allowlist, the picker shows only the models you listed.

### Option 2: start Docker with environment variables

When you start a new container, you can put the connection in environment variables. Create an env file first:

`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
```

What each line does:

- `OPENAI_API_BASE_URL`: the URL of the OpenAI-compatible connection.
- `ENABLE_OLLAMA_API=false`: turns off the Ollama connection. Otherwise Open WebUI keeps trying to reach a local Ollama.
- `OPENAI_API_CONFIGS`: the Model IDs allowlist for connection 0. Keep the JSON on one line, without quotes.
- `TASK_MODEL_EXTERNAL`: the model for background tasks, covered in the next section.

Then start the container, passing the key from your shell's environment:

```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
```

The `slim` image leaves out local models and speech components, which is all you need to chat with hosted models. Once it is up, open `http://localhost:3000` and sign up for the first account.

These variables are written to Open WebUI's database on the first start only. If you later edit the env file and restart the container, the settings in the UI stay the same; change them in the admin settings instead.

### Run background tasks on a cheap model

When you chat in the browser, Open WebUI sends extra requests in the background to write the chat title, tags and follow-up suggestions. By default they run on the model you are chatting with, so on a flagship model every message adds a few flagship-priced requests.

Set the task model to `anthropic/claude-haiku-5.5`. Option 2 already does this with `TASK_MODEL_EXTERNAL`; with option 1, pick **External Task Model** in the task settings under **Admin Settings → Interface**. The task model must also be in the Model IDs allowlist.

## Verify

In the browser, start a new chat, pick `anthropic/claude-sonnet-5.5` and send `Reply with exactly: pong`.

You should see the reply `pong`, and a few seconds later the chat gets its title.

To skip the browser, use Open WebUI's HTTP API. Sign in with your Open WebUI account to get a 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)
```

Then send a chat request:

```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'
```

You should see `pong` printed in the terminal.

The request shows up in the console [Logs](https://pirouter.ai/docs/guides/logs.md), with `/v1/chat/completions` in the **Endpoint** column. The first message of a browser chat adds a few background task requests, on the task model.

## Troubleshooting

### Only OpenAI-compatible connections work

Open WebUI treats a connection as Anthropic only when its URL contains `api.anthropic.com`, so pirouter's URL is never recognized as Anthropic. Always add pirouter as an OpenAI-compatible connection. Claude models are still available, since they accept the OpenAI protocol on pirouter too.

### Changed environment variables have no effect

The connection URL, allowlist and task model variables apply on the first start only; after that, the values in the database win. Change them in the admin settings, or set `ENABLE_PERSISTENT_CONFIG=false` so every start reads the environment variables.

### Background tasks still run on the chat model

If the task model is not in the model list, Open WebUI does not show an error: background tasks quietly fall back to the current chat model. With an allowlist, add the task model's ID to it.

## Not verified yet

- With the connection's API type set to Responses (experimental), Open WebUI sends requests to `/v1/responses` instead. This has not been verified.
- Streaming replies with tool calling turned on in Open WebUI, built-in tools included, have not been verified.

## Related links

- [Open WebUI](https://github.com/open-webui/open-webui) (GitHub)
- [Quick start](https://docs.openwebui.com/getting-started/quick-start): Docker install and image tags
- [Connect an OpenAI-compatible provider](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible)
- [Environment variable reference](https://docs.openwebui.com/reference/env-configuration)
- [Task models](https://docs.openwebui.com/features/administration/task-models)