Open WebUI Custom OpenAI API Endpoint Setup: A Complete Guide (As of May 2026)

Setting up a custom OpenAI-compatible endpoint in Open WebUI is a two-field configuration change and requires only two pieces of information: your provider's base URL and a valid API key. The official Docker quick-start exposes the UI on host port 3000 and persists data in /app/backend/data; once the container is running, no rebuilds, code patches, or model-file edits are required to change the endpoint. When you point Open WebUI at a custom endpoint instead of the default https://api.openai.com/v1, all configured models appear automatically in the same dropdown, local Ollama models keep working, and the change can be fully reverted by clearing two fields.

Why Configure a Custom Endpoint in Open WebUI

By default, Open WebUI sends OpenAI-format requests to OpenAI's official API. A custom endpoint overrides the destination while keeping the same request/response contract, so you can:

• Route through regional gateways — for example, HeFu's Hong Kong node, which offers direct connectivity without an overseas credit card (HeFu Hong Kong AI API).
• Aggregate multiple providers behind a single OpenAI-compatible base URL.
• Use self-hosted inference servers such as llama.cpp or vLLM, both of which expose the OpenAI-compatible /v1/models and /v1/chat/completions routes (vLLM OpenAI-compatible server; llama.cpp server; Open WebUI "Connect a Provider" documentation).

Open WebUI itself also acts as a gateway: it exposes two provider-agnostic endpoints — OpenAI-format POST /api/chat/completions and Anthropic-format POST /api/v1/messages — both authenticated with a single Bearer token (Open WebUI Reference). This means one Open WebUI installation can serve both OpenAI-style and Anthropic-style clients from the same model pool.

Prerequisites Before You Start

You need three things:

1. A running Open WebUI instance — Docker deployments are the most common; the official example maps host port 3000 to container port 8080 (-p 3000:8080) (Open WebUI Docker quick start; GitHub Issue #1826).
2. An API key from the provider you want to connect.
3. The correct base URL of the OpenAI-compatible endpoint.

A practical tip: some providers document a root endpoint but require /v1 appended before any request works. OpenAI's own API reference places the models and chat-completions routes under /v1, so if your first connection returns 404, try adding /v1 to the base URL before touching anything else (OpenAI API reference).

Method 1: Setup Through the Admin Panel UI

This is the fastest path and works for both Docker and desktop installs:

1. Open Admin Settings → Connections.
2. In the OpenAI API section, paste the provider's base URL into the API Base URL field.
3. Paste your API key into the API Key field.
4. Click Save, then refresh the page.

Open WebUI automatically calls GET /v1/models on your custom endpoint to populate the model dropdown, so new models usually appear within seconds — no manual model-ID entry is required. This is the same model-listing contract OpenAI exposes at GET /v1/models (OpenAI models API). If a provider doesn't implement /v1/models correctly, the list will come back empty (more on this in troubleshooting below).

There is also a same-UI path for Anthropic-style providers: Open WebUI's built-in Anthropic compatibility layer can auto-detect the Anthropic URL from a single API key and auto-discover available models (Open WebUI documentation). That said, for production workloads the official docs recommend switching to the Anthropic native API to unlock PDF support, extended thinking, and prompt caching. Anthropic's prompt caching can reduce input cost for cached tokens by up to 90% and latency by up to 85% (Anthropic prompt caching; Anthropic PDF support).

Method 2: Setup via Environment Variables (Docker / Headless)

The minimal configuration is just two environment variables:

OPENAI_API_BASE_URLS=https://your-provider.example/v1
OPENAI_API_KEYS=sk-your-key

OPENAI_API_BASE_URLS accepts multiple comma-separated URLs, and OPENAI_API_KEYS accepts the matching comma-separated keys — this is the officially documented minimal setup for multiple backends (Open WebUI environment configuration; GitHub Issue #1826).

In Docker Compose:

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    environment:
      - OPENAI_API_BASE_URLS=https://your-provider.example/v1
      - OPENAI_API_KEYS=sk-your-key
    volumes:
      - open-webui:/app/backend/data

The same variables can be placed in a .env file for headless or Colab-style deployments. A MarkTechPost tutorial published on April 7, 2026 walks through exactly this pattern in Google Colab: using getpass to read the OpenAI API key securely, setting the OPENAI_API_BASE_URL environment variable, then generating a separate WebUI key and a default model for the chat interface (MarkTechPost, 2026-04-07).

How to Test Your Custom Endpoint Connection

After saving, run two checks:

1. Model list check: open a new chat and confirm the provider's models appear in the model selector. If they do, authentication and the /v1/models call both succeeded.
2. Chat round-trip check: send a short test message, then look at the browser's developer console or the container logs. A successful request returns HTTP 200; a wrong key or unreachable host throws immediately with a 401 or a connection error.

You can reproduce the model-list check from the shell with curl https://your-provider.example/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"; OpenAI's models API returns a data array containing model IDs (OpenAI models API).

If you're using a provider like HeFu, which unifies a global model catalog behind a single OpenAI-compatible endpoint, verify that both low-latency inference models (such as DeepSeek-V4-Pro or Gemini 3.6 Flash) and the embedding model (text-embedding-3-large) load in the same dropdown — a useful sanity check for enterprise workflows. HeFu's catalog page is authoritative for current availability as of May 2026 (HeFu Hong Kong AI API).

Troubleshooting Common Endpoint Failures

• 401 Unauthorized — the API key is wrong, expired, or lacks the required scope. Regenerate the key in the provider dashboard and re-enter it in Admin Settings → Connections.
• 404 Not Found — the base URL is missing the /v1 path. Append /v1 and re-save.
• Models don't load — the provider doesn't implement GET /v1/models. Use a provider that supports model discovery, or enter model IDs manually.
• TLS/SSL certificate error — a corporate proxy or self-signed certificate is interfering. Check the container's CA store or switch to a trusted gateway.

Two providers are known to break model-list loading: api.together.xyz and api.replicate.com, both because their endpoints don't fully implement the GET /v1/models contract expected by Open WebUI (Open WebUI "Connect a Provider" docs; GitHub Issue #1826). If a provider fails, switching to one that explicitly documents OpenAI compatibility — such as the aggregated catalog available through HeFu — avoids the problem entirely.

Open WebUI vs. Aggregator Platforms for Custom Endpoints

Many users wonder whether to configure Open WebUI against an aggregator (OpenRouter, Requesty, Eden AI) or use it as their own aggregation layer. The table below summarizes the practical differences:

The key takeaway: if you already run Open WebUI, it can replace most aggregator functions — including Anthropic-format requests that some aggregators charge a premium for. For readers comparing routing options for Chinese-language workloads, our practical guide to OpenRouter alternatives walks through the cost and latency trade-offs in detail.

Security Best Practices for API Keys

Treat your Open WebUI deployment like a production gateway:

• Prefer environment variables over storing keys in the UI database, especially in Docker, so secrets don't persist in the WebUI's SQLite store.
• Use minimal-scope keys — create a dedicated key with model-read and chat permissions only.
• Restrict Admin Settings access to trusted users, since anyone with admin rights can read and replace endpoint keys.
• Rotate keys when a team member with admin access leaves.

If you're connecting to HeFu, the Hong Kong node is reachable directly without an overseas credit card, and as of May 2026 the same endpoint serves the entire in-catalog lineup — including GPT-5.6 Terra/Sol/Luna, Claude Opus 5, DeepSeek-V4-Pro, Kimi K3, Gemini 3.6 Flash, and Qwen3.7-Max. Pricing for HeFu models is subject to the official pricing page and may change; check the HeFu Hong Kong AI API guide for current access details. For a similar step-by-step integration on another chat frontend, see our guide: How to Set Up HeFu as a Custom Provider in LobeChat.

FAQ

Why don't my models show up after I add a custom OpenAI endpoint?

The most common cause is that the provider doesn't implement the GET /v1/models endpoint, so Open WebUI can't discover the model list — this is exactly what happens with api.together.xyz and api.replicate.com (GitHub Issue #1826). Check three things in order: the base URL ends with /v1, the API key has model-read permission, and the provider returns a valid model list when you call GET /v1/models with curl.

How do third-party OpenAI-compatible clients call models through Open WebUI?

Point them at Open WebUI's own OpenAI-compatible API base URL — for the standard Docker command this is http://your-host:3000/api/v1 — with an API key generated in Open WebUI's user settings (Open WebUI API docs). Home Assistant, AutoGen, and similar clients can then use any model already configured in Open WebUI, including your custom endpoints.

Can I configure multiple custom endpoints at the same time?

Yes. Use the OPENAI_API_BASE_URLS and OPENAI_API_KEYS environment variables with comma-separated values, and all providers' models will merge into the same dropdown (GitHub Issue #1826). You can also add multiple providers one by one in Admin Settings → Connections.

How do I revert to the default OpenAI endpoint?

Simply clear the custom base URL and API key fields in Admin Settings → Connections (or remove the environment variables and restart the container). Open WebUI then falls back to api.openai.com with your regular OpenAI credentials. Reverting does not affect other saved connections or local Ollama models.

Does a custom endpoint affect local Ollama models?

No. Ollama models use a separate native route (/ollama/api/) and keep working alongside custom endpoints in the same model selector (Open WebUI "Connect a Provider" docs). You can mix a local vLLM server, Ollama, and a regional gateway such as HeFu in one interface without conflicts.