Open WebUI Installation and OmniProxy Configuration

Open WebUI is a self-hosted chat interface that can be installed on your own computer or server and can also run completely offline. It is not tied to any one model provider: it can connect to tools such as Ollama that run models locally, as well as OpenAI-compatible endpoints—addresses that provide model services using the same request format. This lets you switch between local and cloud models in the same window.

It is suitable for long-term use by teams and organizations. Capabilities that receive faster updates appear first in Computer, the product Open WebUI uses to try out new features.

Before You Start

Open WebUI is available on macOS, Linux, and Windows. You can install it using Docker, Python, or Kubernetes. Docker packages the application and its runtime environment in a relatively isolated container and is the recommended method. If Docker is unavailable, you can also use the tested Python command below. Kubernetes is a system for deploying and managing containers; see the Quick Start linked at the end of this guide for the corresponding steps.

Officially recommended

Docker

• One docker run command
• Open 3000 in the browser
• Data is stored in the volume

Just want to chat

slim image

• Smaller download size
• Change the tag to :slim
• Chat functionality remains available

Not covered here

Two other options

• Manual Python installation
• Kubernetes deployment
• See the official Quick Start

Before starting, prepare the following:

• Docker installed and running.
• A secret string used only by you. Run openssl rand -hex 32 to generate one, then enter it as WEBUI_SECRET_KEY. Save this value permanently. If you change it when rebuilding the container, users who are already signed in will be signed out.
• A running OmniProxy instance and a model ID from its current model list. The model ID is the complete name used to select a specific model.

Install and Launch for the First Time

Open a terminal and run the command from the Quick Start. First replace your-secret-key with the secret you just generated:

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data -e WEBUI_SECRET_KEY=your-secret-key --name open-webui --restart always ghcr.io/open-webui/open-webui:main

The following parts of this command serve different purposes:

• -p 3000:8080: Lets you open the interface through port 3000 on this computer. If port 3000 is already in use, change the number on the left.
• -v open-webui:/app/backend/data: Stores chats, users, and settings in a data volume. A data volume is a location outside the container where data is retained long-term, so its contents remain after the container is updated. Do not remove this option.
• --add-host=host.docker.internal:host-gateway: Allows the container to access other services running on this computer.
• --restart always: Starts the container again after the computer reboots.

After the command finishes, open http://localhost:3000 in a browser and follow the on-screen instructions to create the first account.

If you only need to chat through an API, you can change the image tag from :main to :slim. slim is a smaller image that does not include local speech and embedding models inside the container, but the chat interface remains available. Continue using :main if you need those local capabilities.

For manual updates, first run docker rm -f open-webui, then run docker pull ghcr.io/open-webui/open-webui:main, and restart it with the same docker run command. Keep both the data volume and WEBUI_SECRET_KEY unchanged.

If Docker Is Unavailable

The Quick Start also provides a Python installation method. On 2026-10-09, the following command was used on macOS to install Open WebUI v0.11.4 and complete one conversation. Docker Desktop was not installed on that computer at the time.

DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve

After startup, open http://localhost:8080 in a browser. This is the port used by the Python installation, not Docker’s port 3000.

An embedding model is downloaded during the first startup, which may take several minutes. An embedding model converts text into data that is easier to search and match. Wait for the sign-in page to appear before continuing. The first registered account becomes the administrator. The interface language follows the system language; Simplified Chinese was displayed during this test.

DATA_DIR must point to a directory that will be retained long-term and used to store Open WebUI data. If it is not set, the data may be stored in a temporary directory and lost after shutdown. If WEBUI_SECRET_KEY is not set, the program writes .webui_secret_key in the current directory. Start it from a directory you intend to retain, or set this variable yourself.

Get Connection Details from OmniProxy

Copy the following three items from your own OmniProxy instance:

URL:      https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy from the current OmniProxy model list

The URL is the address Open WebUI uses to connect to the endpoint and must end with /v1. Do not add /chat/completions after it; Open WebUI appends that part automatically.

Copy the complete model ID from OmniProxy’s current list. If the ID includes a source prefix and slash, preserve them as well. The following two short names are only references from provider documentation as of 2026-10-09. Do not use them if they are not in the current list:

• Claude API ID for Claude Sonnet 5.5: claude-sonnet-5-5
• API name for Gemini 3.8 Flash: gemini-3.8-flash

Do not enter a provider key in Open WebUI. If the gateway does not validate keys, leave the API key blank instead of inventing another key.

Browser

Local port 3000

• Open the chat page
• Complete registration first
• Then open settings

Inside the container

Open WebUI

• Do not use localhost
• Use the host machine name instead
• The URL ends with /v1

Same computer

OmniProxy

• Keep the key in the gateway
• Use the gateway's model list
• Then review the request logs

If the model service runs on the host while Open WebUI runs in a Docker container, replace localhost in the URL with host.docker.internal. The host is the computer running Docker directly. If OmniProxy listens only on this computer, the URL can be written as http://host.docker.internal:port/v1, replacing port with the port OmniProxy actually uses.

If Open WebUI is running locally through the Python command in the previous section and OmniProxy is also running locally, use 127.0.0.1 or localhost in the address. Do not use host.docker.internal in this case.

Enter the Configuration

In the Simplified Chinese interface of v0.11.4 tested on 2026-10-09, the names differed from Settings > Admin > Connections in the English instructions. Follow the options shown in the tested interface, translated below:

1. Expand the left sidebar.
2. Click the user menu at the bottom.
3. Click Settings.
4. In the administrator section below, click External Connections.
5. Open OpenAI API.
6. Click + to the right of Manage OpenAI API Connections.
7. In the Edit Connection dialog, enter the URL ending in /v1. Keep the API type set to Chat Completions.
8. Keep Authentication Method set to Key (Bearer). Bearer authentication places the API key in the request for identity verification. If OmniProxy gave you a key, enter it under API Key. If the gateway does not validate keys, leave this field blank. On 2026-10-09, both validation and one conversation succeeded with the field left blank.
9. Click Verify Connection next to the URL. If OmniProxy provides /models, the model list will be retrieved here.
10. Open Advanced. If Model ID is left blank, all models returned by /models at that address will be used. Only if validation fails, enter a complete ID from the list under Add Model ID, then click Add. Add each ID only once; leading and trailing spaces are removed.
11. Click Save in this window, then click Save in the lower-right corner of the External Connections page.

Saving the configuration alone does not replace validation. Verify Connection requests the other service’s /models endpoint, which lists available models. Some services do not provide this endpoint, so validation may report an error even though chat can still work. In that case, add the model ID manually.

Verify a Real Task

Return to the chat page, open the model menu next to the input box, and select the complete ID from the OmniProxy list. Send a very short message, such as asking it to reply with only one word. A response must actually appear in the chat box.

On 2026-10-09, this conversation was completed using the Python installation of v0.11.4. Docker remains the recommended method, but the test was not repeated in Docker.

Next, open OmniProxy’s request logs and confirm the source and model ID for this request. Seeing only a successful save, or only seeing the model in the menu, does not count as completion.

Interface

The model can be selected

• Connections has been saved
• The model appears in the list
• Send a short question

Response

The chat box shows an answer

• It is not a blank message
• It is not a connection error
• Try again with another model

Logs

Visible in the gateway

• Source is this connection
• Model ID matches
• No key was entered on the page

Common Errors

• localhost or 127.0.0.1 was used inside the container: These addresses point to the container itself, not the host. Change the address to host.docker.internal and confirm that the startup command includes --add-host=host.docker.internal:host-gateway. The reverse applies when Open WebUI is not running in a container: use a local address instead.
• The browser cannot open the page: For Docker, check port 3000; for Python, check port 8080. During the first startup, wait for the embedding model download to finish. You can use docker ps to confirm whether the container is running. If port 3000 is already in use, change the port on the left side of -p.
• The ID in the model menu is longer than the provider’s short name: Use the complete ID from the menu, including any slashes.
• Everyone is signed out after an update: WEBUI_SECRET_KEY changed. Restart using the secret generated the first time.
• Verify Connection fails: First manually add the model ID under Advanced, then confirm it with a real one-sentence chat. Some services do not provide /models, so chat may still work when validation reports an error.
• The model does not exist: Copy the ID again from OmniProxy’s current list instead of continuing to use an outdated name.

Official References

For installation commands, see Open WebUI Quick Start. For connection steps, see the OpenAI-compatible connection instructions. For the model IDs used in the examples, see the Claude model overview and Gemini model list.

Replace every placeholder with values from your own OmniProxy configuration. Never publish a real key.

A saved result or HTTP 200 alone does not prove full Agent compatibility. Check the source and model in OmniProxy's call record.

Official sources · Open WebUI ↗