OpenWebUI integration

Recommended connection

Use OpenWebUI's Ollama provider connection with the gateway base URL (no /api suffix) and a dedicated gateway API key. You can either configure a durable key in auth.api_keys or create a persistent key under Admin -> Sicherheit -> API Keys.

Gateway configuration:

"auth": {
  "oidc": { "enabled": false },
  "api_keys": [
    {
      "name": "openwebui",
      "key": "${OPENWEBUI_GATEWAY_KEY}",
      "tenant": "interactive",
      "subject": "openwebui",
      "application": "openwebui",
      "scopes": []
    }
  ],
  "ip_bypass": [],
  "trusted_proxies": []
}

Create the key in the web interface

Open Admin -> Sicherheit -> API Keys -> API-Key erstellen and use, for example:

Name:        openwebui
Tenant:      interactive
Application: openwebui
Scopes:      (empty)

Copy the generated ofg_... secret immediately and paste it into OpenWebUI. The gateway does not retain the plaintext value. The plaintext is shown once; only its SHA-256 hash and metadata are persisted, so the same OpenWebUI credential remains valid across gateway restarts.

OpenWebUI connection:

URL:     http://host.docker.internal:8080
API Key: <same value as OPENWEBUI_GATEWAY_KEY>

OpenWebUI's backend appends native Ollama paths itself. Do not configure the URL as ...:8080/api.

Diagnostics

From a machine that can reach the gateway:

curl -i -H "Authorization: Bearer $OPENWEBUI_GATEWAY_KEY" http://GATEWAY:8080/api/version
curl -i -H "Authorization: Bearer $OPENWEBUI_GATEWAY_KEY" http://GATEWAY:8080/api/tags

Expected status for both is HTTP 200. /api/tags must contain a models array and every returned model is normalized to contain both name and model.

OpenAI-compatible discovery is also available:

curl -i -H "Authorization: Bearer $OPENWEBUI_GATEWAY_KEY" http://GATEWAY:8080/v1/models

Docker networking

The default example IP bypass only trusts loopback. An OpenWebUI Docker container normally reaches the gateway from a Docker/host network address, so loopback bypass does not apply. Prefer a dedicated API key over widening the bypass CIDR.

On Docker Desktop for macOS, host.docker.internal normally resolves to the host. On Linux, use an address/service name reachable from the OpenWebUI backend or configure Docker's host-gateway mapping.

Gateway compatibility behavior

The gateway owns model discovery instead of forwarding it to a single control worker:

GET /api/tags: parallel inventory across all workers, deduplicated by model ID.
GET /api/ps: aggregated loaded-model view.
GET /v1/models: OpenAI model list generated from the same aggregate inventory.
POST /api/show: routed to a worker that owns the requested installed model when known.
Compute requests are constrained to workers known to own the model; a loaded copy receives additional affinity preference.

If one worker fails during discovery but another returns models, the gateway returns the available model set and sets X-Gateway-Partial-Errors. If no worker can provide tags, discovery returns HTTP 503 rather than an empty, misleading list.

OpenWebUI with "Authentication: None" and IP bypass

If the OpenWebUI connection is configured with Authentication: None, the gateway must authenticate the OpenWebUI backend through auth.ip_bypass. The bypass is evaluated against the source IP observed by the gateway, not against the gateway URL.

For example, if the gateway log shows:

authentication rejected client_ip=10.10.11.42 ... path=/api/version ...

add only that OpenWebUI host address when possible:

"ip_bypass": [
  {
    "cidrs": ["10.10.11.42/32"],
    "tenant": "interactive",
    "subject": "openwebui",
    "application": "openwebui",
    "scopes": []
  },
  {
    "cidrs": ["127.0.0.1/32", "::1/128"],
    "tenant": "local",
    "subject": "localhost",
    "application": "local-tools",
    "scopes": ["gateway:admin"]
  }
]

Then OpenWebUI may remain configured with:

URL:              http://10.10.11.123:8080
Authentication:   None

Do not blindly add 10.10.11.123/32 just because that is the gateway URL. That is the destination address. Use the client_ip value printed by the gateway when OpenWebUI performs /api/version or /api/tags.

For Docker, the observed source may be a Docker bridge/VM address rather than the LAN address of the host. A dedicated static API key is more stable than allowing a broad Docker subnet.

Authentication diagnostics

Authentication failures now log the resolved client address and include it in the X-Gateway-Client-IP response header. Native Ollama endpoints also return Ollama-compatible errors such as:

{"error":"authentication required"}

rather than an OpenAI-shaped nested object. This prevents OpenWebUI from rendering the gateway error as [object Object].

4.8 KiB Raw Blame History