Add Router One to Open WebUI as one OpenAI API connection
Open WebUI is an open-source, self-hosted chat interface, and any OpenAI-compatible endpoint can sit behind it. An admin adds Router One once as a connection, and the chat models you choose from the catalog, GPT, Claude, Gemini, Grok and DeepSeek among them, appear in the model selector for every user on the instance. Each reply, and each small background request Open WebUI makes around it, becomes a request in Dashboard → Logs with its model, tokens, cost and status. A few Open WebUI defaults decide how many of those requests there are and which models your users see: model discovery lists every catalog ID, image-generation models included; titles, tags and follow-up suggestions run on the chat model; and Docker environment variables only apply on the first launch. This guide covers the connection form field by field, a Model IDs allowlist, task-model settings, tool calling and usage reporting, the Responses option, and the Docker settings that survive a container rebuild. Checked against Open WebUI v0.11.4 on 2026-09-27.
Configure Open WebUI to use the Router One base URL
On a running instance, open Admin Panel → Settings → Connections, and under Manage OpenAI API Connections click the + button to add a connection. URL is the base URL with exactly one /v1. The key is your Router One key, sent as a Bearer token. Connection Type stays External and Provider stays Default. API Type stays Chat Completions, so every chat is a POST to /v1/chat/completions, which serves every chat model in the catalog. Under Model IDs, add the exact catalog IDs you want users to see, one at a time with the + icon (next section). Prefix ID is optional. Verify Connection calls GET /v1/models with the key and reports Server connection verified; saving does not test anything by itself, so verify, then save. A fresh Docker deployment can seed the same connection with environment variables on its first launch:
- URL
- https://api.router.one/v1
# Open WebUI → Admin Panel → Settings → Connections → Manage OpenAI API Connections → + URL: https://api.router.one/v1 Key: sk-your-router-one-key Connection Type: External API Type: Chat Completions Model IDs: anthropic/claude-sonnet-5, openai/gpt-5.6-sol, google/gemini-3.7-flash, deepseek-v4.1-flash # Or seed the connection on the first launch (ConfigVar: later env changes are ignored): docker run -d -p 3000:8080 -v open-webui:/app/backend/data \ -e OPENAI_API_BASE_URL=https://api.router.one/v1 \ -e OPENAI_API_KEY=sk-your-router-one-key \ -e WEBUI_SECRET_KEY=<output of: openssl rand -hex 32> \ --name open-webui --restart always ghcr.io/open-webui/open-webui:main
Choose what users see with a Model IDs allowlist
With Model IDs empty, Open WebUI lists whatever GET /v1/models returns, and Router One returns the whole catalog: channel IDs such as the azure/, aws/ and vertex/ variants, and image-generation models (gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst, gemini-3-pro-image-preview, gemini-3.1-flash-image-preview, grok-imagine-image, grok-imagine-image-quality) that cannot answer a chat message. Adding IDs to the allowlist replaces the fetched list: Open WebUI stops calling /models for that connection and shows exactly the IDs you typed. A practical list is a few chat IDs, for example anthropic/claude-sonnet-5, anthropic/claude-haiku-4.5, openai/gpt-5.6-sol, openai/gpt-6-sol, google/gemini-3.7-flash, deepseek-v4.1-flash and grok-4.7. Exact catalog IDs also avoid a rewrite in Open WebUI v0.11.4: for bare names that start with o and a digit, or with gpt- and a version of 5 or higher, it renames max_tokens to max_completion_tokens and sends the system prompt with the developer role. Vendor-prefixed IDs such as openai/gpt-5.6-sol are sent as written. Prefix ID only changes the picker label: Open WebUI joins it to each ID with a dot (a prefix of ro shows ro.anthropic/claude-sonnet-5) and strips it again before the request, so leave it empty unless two connections list the same IDs.
Task models: the requests behind every message
Open WebUI makes small background calls around each chat: a title for new chats, tags, follow-up suggestions, and query rewrites for knowledge retrieval and web search when those features are used. By default they all run on the model the user is chatting with, so on a flagship model one message can produce three or four entries in Dashboard → Logs, each billed at that model's rate. In Admin Panel → Settings → Interface, under Tasks, set External Task Model to a fast, non-reasoning, low-cost ID such as anthropic/claude-haiku-4.5; External is the picker used for every model that is not from a Local connection, which includes Router One. Titles have a built-in limit of 1,000 output tokens, while tag, follow-up and query requests carry no output limit of their own. Task Model Parameters applies one set of parameters to all background calls, and setting anything there drops the built-in title limit, so include max_tokens, for example {"max_tokens": 1000}. Tasks you do not need can be switched off under Generation: Title Generation, Tags Generation and Follow Up Generation are on by default, Autocomplete Generation is off. The environment equivalents are TASK_MODEL_EXTERNAL, TASK_MODEL_PARAMS, ENABLE_TITLE_GENERATION, ENABLE_TAGS_GENERATION, ENABLE_FOLLOW_UP_GENERATION and ENABLE_AUTOCOMPLETE_GENERATION.
Tool calling, usage, Responses and embeddings
Since v0.10.0 every chat that has not chosen a mode uses Native tool calling, which relies on the model's own function calling, and in Native mode Open WebUI also exposes web search, memory and knowledge retrieval to the model as tools. Prefer IDs whose model page lists tool calling; for other IDs, test one tool turn before you attach tools. Token counts are the next setting: Open WebUI shows usage only when it asks for it, and the Usage capability, off by default, is what makes it send stream_options.include_usage. Enable it per model in Admin Panel → Settings → Models → Capabilities to get token figures in the chat and in Open WebUI's analytics; Dashboard → Logs records tokens and cost either way. API Type Responses is experimental in Open WebUI; if you want it, add a second connection with API Type Responses and an allowlist of GPT-family, DeepSeek and Grok chat IDs only, because Claude and Gemini IDs are not served on /v1/responses. Finally, documents and knowledge bases need an embeddings engine. Router One has no /v1/embeddings, so keep Open WebUI's document embedding on its default local model or on another provider.
Docker: settings that only apply once, and a stable secret key
OPENAI_API_BASE_URL, OPENAI_API_KEY and most other connection and task settings are ConfigVar variables: Open WebUI reads them on the first launch, stores them in its database, and from then on uses the stored values. Changing the environment later has no effect; edit the connection in the Admin Panel instead. ENABLE_PERSISTENT_CONFIG=False reverses the priority, so environment variables win on every restart, but anything changed in the Admin Panel is then lost at the next restart. Two more flags belong in the docker run command. -v open-webui:/app/backend/data keeps chats, users and settings in a named volume; without it they are lost with the container. WEBUI_SECRET_KEY signs login tokens and encrypts stored secrets; when it is not set, the image generates one inside the container, so recreating the container (not just restarting it) logs every user out. Generate a value once with openssl rand -hex 32 and pass the same one on every run.
Which model ID should Open WebUI send?
Copy the exact model ID from /models, preserving case, hyphens, and version suffixes; do not substitute a display name. Open its detail page and match the supported API endpoints, context window, and capabilities such as tool calling to the provider and features selected in Open WebUI. A catalog listing does not mean the client can use every feature of that model. Give each client or application a dedicated API key with a maxSpend cap.
Which API protocol is Open WebUI using?
OpenAI-compatible describes an interface format; it does not make Chat Completions (/v1/chat/completions), Responses (/v1/responses), and Anthropic Messages (/v1/messages) interchangeable. Check the installed client version, provider configuration, and actual request path against the model detail page and API compatibility fact sheet. A successful plain-text chat does not establish support for hosted tools, conversation state, or file-editing features.
Verify the Open WebUI call in your request trace
Send a simple text request from Open WebUI, then match its trace in Dashboard → Logs by time, model, and request_id: tokens, cost, latency, and status. Next, test streaming, tool calls, and multi-turn history separately. For failures, retain the actual request path, full error message, and request_id. If there is no matching log, check client configuration and connectivity before attributing the error to the gateway or upstream.
FAQ
I changed OPENAI_API_BASE_URL but Open WebUI ignores it. Why?
OPENAI_API_BASE_URL is a ConfigVar: Open WebUI applies it on the first launch, saves it to its database, and ignores the environment variable on later starts. Edit the connection under Admin Panel → Settings → Connections instead, or start with a fresh data volume. If you manage configuration only through the environment, set ENABLE_PERSISTENT_CONFIG=False so environment variables win on every restart; changes made in the Admin Panel are then lost at the next restart.
Why do image models show up in the model selector?
Because Open WebUI lists everything GET /v1/models returns, and Router One returns the whole catalog, including image-generation IDs such as gpt-image-2 and grok-imagine-image that cannot answer a chat. Add the chat IDs you want to the connection's Model IDs allowlist: the allowlist replaces the fetched list, so only those IDs appear. Image generation in Open WebUI is configured separately, under Admin Panel → Settings → Images.
One chat message shows up as three or four entries in Dashboard → Logs. Is that expected?
Yes, with default settings. Besides the reply itself, Open WebUI generates a title for a new chat, tags and follow-up suggestions, and rewrites queries for knowledge retrieval or web search when those are used, all on the chat's own model unless an External Task Model is set. Point background tasks at a low-cost ID such as anthropic/claude-haiku-4.5 and set Task Model Parameters with a max_tokens, or switch off the generations you do not need.
Should I set the connection's API Type to Responses?
Only for a separate connection that lists GPT-family, DeepSeek or Grok chat IDs, and only if you need it: Open WebUI marks Responses support as experimental, and Router One serves /v1/responses for those families only. A Claude-family ID on a Responses connection fails with HTTP 400 must be called via … before any model runs, and Gemini IDs are not served there either. Keep the main connection on Chat Completions, which serves every chat model.
Can each user bring their own Router One key?
Yes, through Direct Connections, which is experimental and off by default (ENABLE_DIRECT_CONNECTIONS, or the toggle under Admin Panel → Settings → Connections). Each user then adds a connection in their own settings, the browser calls Router One directly, and the key is stored in that browser's local storage rather than on the server. Router One allows cross-origin requests from browsers, so this works, but admin-managed connections remain the simpler default. With per-user keys, each request is billed to the key of the person who sent it.
Open WebUI shows no token counts for Router One models.
Turn on the Usage capability for the model in Admin Panel → Settings → Models. It is off by default, and only with it does Open WebUI send stream_options.include_usage and receive token counts for streamed replies. Router One records tokens and cost for every request in Dashboard → Logs whether or not Open WebUI displays them.
Can Router One provide embeddings for Open WebUI's documents and knowledge?
No. Router One has no /v1/embeddings endpoint, so pointing Open WebUI's embedding engine at the Router One URL fails. Keep document embeddings on Open WebUI's default local model or another provider, and use Router One for chat. The chat model still reads retrieved passages as ordinary input tokens, which Dashboard → Logs counts.
Which models can Open WebUI use through the gateway?
Choose a current catalog model that supports both the endpoint and the features Open WebUI uses. Check /models and the model detail page for the exact ID, current rates, and capabilities; a family name such as GPT or Claude is not a compatibility guarantee. A client that lists a model has only read the ID, from its own configuration or from GET /v1/models; verify an actual request too.
Models are listed, but requests fail with 400 or 404. What should I check?
Record the actual request path and error message, then check the exact model ID. A 400 can indicate invalid parameters, unsupported tools, or a model/endpoint mismatch; a 404 can indicate an incorrect path or missing resource, so it does not by itself establish that a model was retired. If the error says must be called via, use the named endpoint or select a model supported on the current endpoint. Do not add or remove /v1 or /chat/completions across all clients indiscriminately.
Does this work from Mainland China?
Yes. The gateway is reachable from Mainland China without a VPN, and the configuration is identical to the global setup.
How do I debug a 401/402/403/429?
Match the request and error message in Dashboard → Logs. For 401, check whether the key was sent and is valid; for 402, check wallet balance and maxSpend; for 403, check key permissions and access restrictions. For 429, distinguish request/token limits from upstream throttling using the error details. Keep the request_id and follow the error-codes reference.