Skip to main content
API7.ai Logo

Open WebUI

Open WebUI is a web interface for chatting with models, managing conversations, attaching knowledge, and using tools. It connects to model services through protocol-based connections, including OpenAI-compatible APIs.

An Open WebUI administrator can add AISIX as an OpenAI-compatible connection. Open WebUI then discovers the model aliases available to the AISIX caller key and sends chat requests through the gateway. AISIX governs the model request path, while Open WebUI continues to manage users, chats, knowledge, tools, and interface behavior.

Prerequisites​

Before starting, prepare the following:

  • An Open WebUI account with administrator access.
  • An AISIX proxy URL the Open WebUI deployment can reach.
  • An AISIX caller API key dedicated to Open WebUI.
  • A chat-capable model alias the caller key can access through the OpenAI-Compatible API.

If Open WebUI runs in a container, an AISIX gateway on the container host is not reachable through localhost. Use a hostname that resolves from the Open WebUI container, such as the gateway service name on a shared container network.

Add the AISIX Connection​

Configure AISIX as a standard OpenAI-compatible connection:

  1. In Open WebUI, open Settings → Admin → Connections.
  2. Under Manage OpenAI API Connections, select Add Connection.
  3. Set URL to the AISIX proxy API root, including /v1, for example https://gateway.example.com/v1.
  4. Keep Auth set to Bearer and set API Key to the AISIX caller API key.
  5. Keep API Type set to Chat Completions so Open WebUI sends requests to /v1/chat/completions.
  6. Under Advanced, leave Provider set to Default.
  7. Leave Model IDs empty so Open WebUI discovers the aliases that the caller key can access.
  8. Select Save.

Open WebUI requests GET /v1/models with the caller key. AISIX returns only the model aliases that key can use, so the Open WebUI model selector follows the gateway's access policy.

If you want to expose only part of that returned list, add the selected AISIX aliases under Model IDs. This filter narrows what Open WebUI displays; it does not grant access that the AISIX caller key does not already have.

Verify Chat and Streaming​

Start a new chat, select a chat-capable AISIX model alias, and send a short prompt such as “Reply with one sentence about AI gateways.”

Confirm these results:

  • Open WebUI displays the streamed response.
  • AISIX records a successful POST /v1/chat/completions request.
  • The recorded caller key and model match the Open WebUI connection and selected alias.

Open WebUI may use models for background tasks in addition to the visible chat. If you configure separate models or endpoints for tasks, embeddings, image generation, speech, or reranking, verify those paths independently before treating all Open WebUI model traffic as governed by AISIX.

Verify Tools Separately​

Open WebUI's native tool path expects OpenAI-compatible streamed tool-call fragments. Each fragment must retain its tool-call index so Open WebUI can assemble the function name and arguments before executing the tool.

AISIX preserves the indexed tool-call stream on the Chat Completions path. The upstream model must also support the requested tool, and Open WebUI must enable and authorize it. Run one real tool-using turn and confirm these outcomes:

  • Open WebUI executes the expected tool.
  • AISIX records the model request that produces the tool call and the follow-up request containing the tool result.
  • The final answer appears in the chat.

A successful plain-text chat does not prove that this multi-request tool loop works.

Troubleshoot the Connection​

SymptomCheck
No models appearConfirm the URL ends in /v1, the caller key is valid, and GET /v1/models returns the expected aliases. Add an alias to Model IDs only after confirming the request path.
Connection returns 401Confirm API Key contains the AISIX caller key, not an upstream provider key.
Chat returns 403Confirm the caller key can access the selected AISIX model alias.
Chat returns 404Remove /chat/completions from URL. Open WebUI appends that path to the /v1 API root.
Container deployment cannot connectUse a gateway hostname reachable from the Open WebUI container instead of localhost.
A tool turn returns an empty replyVerify the selected model emits indexed OpenAI-compatible tool-call stream fragments, then inspect the AISIX and Open WebUI logs for the tool request.

Next Steps​