Open WebUI¶
Add the gateway as an OpenAI connection in Open WebUI and every chat on your deployment is checked against your policies, charged to a team and recorded in Request logs. The model picker shows exactly the models your key may call, from every provider, side by side.
What it is¶
Open WebUI is a self-hosted chat interface for teams. It talks to any server that speaks the OpenAI format, from the server it runs on, through connections an admin sets up.
The two settings¶
In Open WebUI, go to Settings › Admin › Connections, and under Manage OpenAI API Connections choose Add Connection:
| Field | Value |
|---|---|
| URL | https://<your-gateway>/v1 |
| Auth | Bearer |
| API Key | Your Vidai key (starts vk_), never a provider's key |
| API Type | Chat Completions (the default) |
| Model IDs | Leave empty to list every model your key may call, or add the ones to show |
| Prefix ID | Optional: a prefix that keeps these models apart from another connection's |
Or set them as environment variables when you start Open WebUI:
OPENAI_API_BASE_URL="https://<your-gateway>/v1"
OPENAI_API_KEY="vk_…"
# several connections: OPENAI_API_BASE_URLS and OPENAI_API_KEYS, separated by ";"
The gateway's address is under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once.
A minimal call¶
- Save the connection; Verify Connection checks the address and key.
- Start a new chat and pick a model, for example
gpt-4o-miniorclaude-sonnet-4.5. - Send "Reply with exactly: ok". A short answer means the connection works.
Streaming¶
Open WebUI streams every answer. A stream from Claude or Gemini arrives as OpenAI chunks; Vidai records the tokens and the cost either way.
Tool calls¶
Open WebUI's tools and functions travel as OpenAI tool calls in Native function calling, the default in current versions, and work on every provider the gateway translates to. If a model's Function Calling (under Advanced Params) is set to Legacy, Open WebUI handles tools with its own prompts, which are ordinary chat calls. Each round trip is its own call in Request logs.
Reading what the gateway did¶
Open WebUI doesn't show response headers. Look the call up in Request logs: filter on Key, Model or
Path (/v1/chat/completions). Cost is never in the answer.
Errors¶
Open WebUI shows the gateway's error message in the chat. Common ones: 401 invalid_api_key (wrong key), 403
model_not_allowed (the key may not call that model), 403 content_guardrail_blocked (a guardrail stopped the
message), 429 (a limit on the key or team). The full list is in Headers and errors.
Model names¶
Open WebUI fills the picker from GET /v1/models, which the gateway answers with exactly the models your key may call,
named as your organisation approved them under Models in the Control room. A model added there shows up after
Open WebUI refreshes its list (save the connection again, or restart if Cache Base Model List is on).
What goes through the gateway¶
| Open WebUI feature | Through the gateway |
|---|---|
| Chats, streaming, images in messages, tools, background tasks (titles, tags, follow-up suggestions) | Yes, to OpenAI, Azure OpenAI, Anthropic, Gemini and Vertex AI models |
| Embeddings for documents and knowledge, when the engine is set to OpenAI with the gateway's address | OpenAI and Azure OpenAI embedding models only |
| Image generation, speech to text and text to speech, when set to OpenAI with the gateway's address | OpenAI and Azure OpenAI models only |
| A connection with API Type set to Responses | OpenAI and Azure OpenAI models only; another provider gets a clear 400 |
| Ollama connections and local models | No: they don't pass through the gateway |
Check it works in a minute¶
Send "Reply with exactly: ok" to a gateway model, then open Request logs a few seconds later and filter on the connection's key.
Good to know¶
- One key, every user. A connection set up by an admin uses one key for everyone, so calls show under that key and are charged to the team it acts for. To split costs, add one connection per team, each with that team's key, and limit each connection's models to that team's group in Open WebUI.
- Each person's own key. Turn on Direct Connections (Settings › Admin › Connections); each person then adds the gateway under their own Settings › Connections with a key they issue themselves in Keys › Issue a key, and their calls show under them. Direct connections are called from the person's browser, not from the server, and the gateway doesn't answer a browser's cross-origin (CORS) check: keep connections on the server, with one key per workspace or per group of users, unless something in front of the gateway adds CORS.
- Open WebUI can send user headers (
ENABLE_FORWARD_USER_INFO_HEADERS); the gateway doesn't read them, so they don't change who a call is charged to. - Settings saved in the admin panel are stored and win over the environment variables on later starts (unless
ENABLE_PERSISTENT_CONFIGisfalse). - Open WebUI's own docs: Environment variables.