From Login to Model Call
Open WebUI's model selector looks simple, but the name a user chooses is not yet a model request. This chapter follows the specific route from an authenticated caller to an upstream runtime. The aim is practical: by the end, you should be able to distinguish a provider connection, an upstream model, and a workspace model, and identify where authorization and compatibility decisions happen before text begins streaming back.
That distinction matters because Open WebUI is designed to offer choice without making every backend identical. A deployment may expose models from several Ollama servers, several OpenAI-compatible endpoints, or a mixture of local and hosted services. The application has to create one usable surface for the user while still respecting the differences in authentication, payloads, streaming, model capabilities, and failure behavior.
A model name is not a model runtime
Start with three layers.
A provider connection is a configured route to a service. It may point to an Ollama backend or to an OpenAI-compatible API. A connection has its own URL, credentials, enablement setting, optional model allowlist, labels, and metadata. In a deployment with several connections, Open WebUI can ask each enabled service for its model catalog and combine the responses. For Ollama, duplicate model names can be merged while retaining the information about which backends host them. For OpenAI-compatible services, each returned model can be annotated with its connection and provider information.
An upstream model is the model runtime exposed by that service. It is the thing that ultimately receives the adapted request and generates the answer. Its behavior depends on the provider: a local runtime may expose one set of model-management operations, while a hosted API may expose another. Even when two services use an OpenAI-shaped interface, they may disagree about supported parameters, authentication, streaming, or tool calls.
A workspace model is Open WebUI's own record around that upstream capability. It can supply a display name, default parameters, a system instruction, capabilities, attached knowledge, an owner, and access grants. It can also point to a base_model_id, allowing a customized or shared model entry to use an underlying model without making the user select that underlying runtime directly.
The wrapper is useful for more than presentation. It creates a policy surface. An administrator can expose a useful configuration of a model rather than every raw provider detail. The workspace record can say which users may read it and what behavior it should advertise. It can carry knowledge or capabilities that affect how the chat request is assembled. The same model identity can therefore be meaningful inside the workspace even though its answer still comes from an upstream service.
That indirection creates a responsibility: access cannot stop at the wrapper. If a workspace model points to another model, Open WebUI checks the chain of reachable base models. A user who can see a customized entry must not gain an indirect route to a base model they could not use directly. When a registered model is absent, non-administrator access is rejected rather than treated as public. In this design, model inheritance is also an authorization relationship.
The model catalog itself is not a permanent truth. Open WebUI caches model discovery, and configuration changes clear the relevant caches. A provider can be disabled, a model can be restricted to an allowlist, or a prefix can be added to distinguish names from different connections. Catalog discovery can also fail independently of chat generation. That means an empty or stale selector can indicate a connection or cache problem, not necessarily that the underlying model does not exist.
Four decisions before the provider call
When a chat request arrives, the route has four logically separate decisions.
First, who is calling? Open WebUI can resolve a browser session, a bearer token, or an API key. A verified user is different from a pending account, and an administrator is different from an ordinary user. The authentication result is attached to the request so later parts of the path can reuse the identity instead of treating the request as anonymous text.
Second, which workspace model is being requested? The application looks up the selected model in its current model state and, when applicable, retrieves the workspace record that supplies its parameters and base-model relationship. If the model is not present, the request stops. If the user cannot read the model or one of its bases, the request stops before it reaches the upstream provider.
Third, which provider connection owns the upstream model? Open WebUI's aggregated catalog records enough routing information to select an Ollama or OpenAI-compatible connection. A workspace model may replace the visible identifier with its base model for the provider request. A configured prefix may then be removed before sending the actual upstream name. These transformations preserve the distinction between a stable workspace identity and a provider-specific identifier.
Fourth, what request shape does that provider accept? The shared chat dispatcher separates several paths. A direct connection may send the work back through an active browser session. A pipe model may execute a server-side function that presents itself as a model. An Ollama model uses a conversion from the application-facing chat shape to Ollama's request and response format. Other models use the OpenAI-compatible forwarding route. The caller sees one chat experience, but the application chooses the path based on the resolved model.
This sequence is easier to understand as a set of boundaries than as a list of endpoints:
The diagram shows a causal order, not a promise that all requests use the same provider or response format. Direct browser and pipe paths may terminate at a different boundary. The important invariant is that a model route and its access decision precede an upstream call.
The catalog is therefore a control plane, not just a dropdown feed. Suppose an operator connects one local Ollama server for private drafting and one hosted, OpenAI-compatible service for a task that needs a different capability. Open WebUI can discover both sets of models, attach connection metadata, and expose selected entries through the same workspace. The operator may restrict a connection to an allowlist, add a prefix so similarly named models remain distinguishable, or attach tags that help people choose. Those choices shape what the user can see before any prompt is sent.
A workspace model adds another level of intentionality. Instead of asking each user to understand a provider's raw model name and parameter quirks, the operator can publish a configured entry with a meaningful name, a system instruction, default parameters, a capability description, and an owner. That entry can be shared with a group without sharing every model in the underlying provider catalog. It can also be disabled without removing the provider connection itself. The resulting selector is a curated view of available capability, not a mirror of upstream reality.
Curation is useful only if its state remains legible. A provider connection can be enabled in configuration while its catalog request fails. A model can disappear from an upstream catalog while a workspace record still refers to it. A cached list can make an old route visible for a time, while a newly changed permission can make that route invalid for a particular user. Open WebUI clears relevant caches when provider configuration changes, but cache invalidation does not solve every mismatch between catalog state, database records, and the upstream runtime. Operators still need to distinguish “not listed,” “not authorized,” “not loaded,” and “not reachable.”
This distinction also explains why a model's advertised capabilities should be treated as routing input rather than a guarantee. A workspace entry may say that a model supports files, tools, or another feature, and the chat pipeline can use that information to decide what to assemble. The upstream model may nevertheless reject a request, interpret a parameter differently, or return a response shape that needs conversion. The catalog helps Open WebUI make a deliberate choice; the provider remains the final test of whether the call succeeds.
Compatibility is active translation
“OpenAI-compatible” is a useful entry point, not a guarantee of sameness. Open WebUI's forwarding code applies the workspace model's parameters, selects authentication behavior, adds optional user or session information, and then adapts the request for the configured provider. Azure connections may require a deployment-specific URL and an API version, while an Azure v1 shape can keep the model in the request body. Responses API connections need a different representation of messages, stored output items, tools, and token limits. Native Anthropic messages are resolved through the same connection machinery but use Anthropic-specific authentication rules when the target requires them.
The application also handles model-specific parameters. Reasoning models may require max_completion_tokens rather than max_tokens, or a different interpretation of the initial system instruction. Older or non-OpenAI services may need the reverse compatibility adjustment. The route filters parameters that a provider-specific API does not support and sanitizes model names when they are inserted into deployment URL paths.
These adaptations are mediators between two contracts. The first contract belongs to Open WebUI: a workspace request with a model, messages, parameters, optional tools, and a streaming preference. The second belongs to the upstream service. The adapter succeeds when it translates the first into a valid form of the second without losing the meaning the user or workspace model intended.
It can fail in several ways. A workspace model may resolve correctly but point to a base model that is no longer present. A catalog may be available while the provider's completion endpoint is unavailable. A parameter may be meaningful in one provider and rejected by another. A provider may return an error using server-sent-event formatting, which would otherwise look like a normal stream to the caller. Open WebUI explicitly reads such error bodies and turns them into an ordinary error response when possible. That is not cosmetic work: it prevents a failed provider call from being mistaken for a successful answer that merely contains an error event.
The same principle applies to successful responses. If the provider sends a stream, Open WebUI returns a stream and removes stale transport headers when its HTTP client has already decompressed or transformed the body. If the provider returns a non-streaming Responses API result, the application extracts the message output into a simpler chat-completion shape so downstream tasks and the frontend can continue to work. Normalization reduces the number of formats that the rest of the workspace must understand, but it cannot erase provider behavior that affects quality, cost, latency, or capability.
What the abstraction buys—and what it cannot buy
The abstraction has a clear benefit: users and surrounding workspace features can address a model through a common surface. Model parameters, access checks, chat persistence, source context, and later tool orchestration do not need a separate user experience for every provider. Operators can combine local and remote runtimes and expose only the connections or model IDs they want to make available.
The cost is hidden coupling. A provider's unusual authentication method, response format, context limit, model-management API, or tool behavior still has to be represented somewhere. Every compatibility rule becomes another condition that may differ by connection. A provider catalog can report a model but not reveal whether it handles a particular capability the way Open WebUI expects. A workspace model can advertise capabilities, but the upstream runtime remains the final authority on what succeeds.
This is why provider choice should be judged as a routing decision, not a shopping list. A local Ollama connection can support a self-hosted path and reduce dependence on a hosted API, but the operator owns the runtime and its capacity. An OpenAI-compatible connection can widen the set of available models or services, but it introduces network access, credentials, upstream availability, and provider-specific semantics. The gateway makes the choice easier to use; it does not make the consequences disappear.
The practical rule is simple: inspect the full route, not just the model label. Ask who authenticated, which workspace record was selected, which base model it reaches, which provider connection owns that model, how the payload will be adapted, and what response format will come back. Once those decisions are clear, the next problem is equally important: what conversation history, files, knowledge, memory, or web evidence should be assembled around the request before the provider sees it?