Last reviewed: 2026-08-13

Direct answer

An Open WebUI CometAPI integration uses Open WebUI’s OpenAI-compatible connection rather than a provider-specific plugin. In the current Open WebUI documentation, an administrator opens Admin Settings > Connections > OpenAI, adds a connection, and enters the CometAPI API address by using HTTPS on api.cometapi.com with the /v1 prefix. Supply the CometAPI API key privately, and leave the model filter empty for the first attempt so Open WebUI can query the model catalog.

The labels can vary by release. The CometAPI walkthrough describes Admin Panel > Settings > External Connections, while the current Open WebUI guide uses Admin Settings > Connections > OpenAI. Look for the OpenAI-compatible connection form instead of assuming that every version has identical menu text.

Saving the connection should trigger model discovery. A populated selector proves that the discovery request worked; it does not prove that a chat completion works. Complete the check by sending the same small prompt to two model IDs, one at a time. In this workflow, multi-model validation means repeating a controlled request against two selected models, not broadcasting one request to several models simultaneously.

Happy path

  1. Record the Open WebUI version or container image tag before changing anything. For a reproducible deployment, the Open WebUI Quick Start recommends a pinned stable version rather than the moving main or latest tag. Replace X.Y.Z below with the chosen release:
docker pull ghcr.io/open-webui/open-webui:vX.Y.Z
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:vX.Y.Z
  1. Keep the named volume. It preserves chats and settings when the container is recreated. Ensure the path to the UI permits WebSocket connections, which the Open WebUI Quick Start lists as a requirement.
  2. Create or retrieve the CometAPI credential through the provider’s account interface. Paste it only into the Open WebUI connection form. Any screenshot, ticket, or runbook must show the value as [REDACTED].
  3. Add an OpenAI-compatible connection. Use HTTPS on the CometAPI host with the /v1 prefix, enter the credential privately, and leave Model IDs (Filter) empty for the first discovery attempt.
  4. Save the connection. Confirm that the model selector contains returned model IDs. Choose IDs from that selector rather than copying a marketing name from an older article.
  5. Select the first model and start a new chat with a small prompt such as Reply with exactly: connection-ok. Record the status, duration, selected model ID, and whether a non-empty response arrived.
  6. Start another new chat, select a second discovered model, and repeat the same prompt. Using a fresh chat reduces the chance that model-specific conversation state obscures the transport test.
  7. Treat the integration as healthy only when discovery succeeds and both selected models return usable responses.

Error path

If discovery fails, stop before testing chat. Record the HTTP status and duration, confirm the documented CometAPI host and /v1 prefix, re-enter the credential without exposing it, and confirm that the account can make requests. Do not repeatedly submit the same failing request.

If discovery succeeds but chat fails, keep the working connection unchanged. Re-select the exact returned model ID, use a plain text prompt with tools and uploads disabled, and capture the completion status. A discovery success followed by a completion failure narrows the problem to the selected model, completion route, request behavior, or account state.

If one model succeeds and the other fails, the basic Open WebUI-to-CometAPI path is working. Investigate the failing model ID or capability instead of replacing the whole connection. If both time out, the CometAPI guide recommends allowing at least 60 seconds for models that take longer to produce their first output.

Who this is for

This guide is for developers and self-hosters who already run Open WebUI, or who can deploy it with Docker, and want to connect its browser interface to CometAPI. It is also useful for operators who need a repeatable acceptance test before making a shared model connection available to other users.

You should be comfortable managing an administrator-only setting, protecting an API key, reading HTTP status codes, and checking container or proxy logs. You do not need to write an Open WebUI plugin. Open WebUI is designed around standard protocols and can connect directly to providers that implement its expected OpenAI-compatible chat contract.

This setup is not a substitute for testing every advanced feature. A successful plain text completion does not establish that tools, uploads, multimodal inputs, or provider-specific parameters work for every model. Establish the basic discovery and chat path first, then validate additional capabilities separately.

Key takeaways

  • Use Open WebUI’s OpenAI-compatible connection and the documented CometAPI host with the /v1 API prefix.
  • Expect navigation labels to differ across Open WebUI versions; identify the connection form by function.
  • Test model discovery and chat completion as separate contracts.
  • Select current model IDs from the returned catalog rather than hardcoding names from an article or screenshot.
  • Validate two models sequentially with the same small plain text prompt.
  • Keep credentials, request headers, prompts, completions, and uploaded content out of routine logs.
  • Preserve the Open WebUI data volume and pin a stable image version for reproducible deployments.
  • Do not use a manually entered model ID to conceal an unexplained discovery failure. It can be a diagnostic step, but it is not evidence that the full connection is healthy.

Sources checked

The provider-specific configuration comes from the CometAPI Open WebUI integration walkthrough . It supplies the CometAPI host and /v1 prefix, describes the Open WebUI connection flow, and separates model-list troubleshooting from chat testing. Promotional pricing, model-count, privacy, and availability claims are not needed for this integration procedure.

The product-side contract comes from the Open WebUI OpenAI-compatible provider guide . It explains that Open WebUI is protocol-oriented, uses the OpenAI Chat Completions contract, verifies connections through the models endpoint, and supports a manual model allowlist when a provider cannot supply discovery normally.

Deployment details come from the Open WebUI Quick Start . It documents the container port, persistent data volume, WebSocket requirement, image variants, and the distinction between rolling tags and pinned stable versions.

These are three distinct deterministically refetched source records with separate roles: provider configuration, application connection behavior, and runtime deployment. The Open WebUI connection guide controls questions about discovery behavior, the Quick Start controls deployment details, and the CometAPI walkthrough controls the provider-specific address and setup instructions.

Contract details to verify

API address and route ownership

Configure the base address with the CometAPI host and /v1 prefix documented by the provider. Open WebUI then performs model discovery and sends chat-completion requests through the compatible connection. Do not append a completion route to the base-address field unless the installed Open WebUI release explicitly asks for a full route; doing so can cause duplicated path segments.

The important distinction is between the base address and the operations performed beneath it. Model discovery and chat completion are different requests. Check which one failed before editing the connection.

Discovery behavior

Open WebUI normally verifies an OpenAI-compatible connection by requesting the provider’s models endpoint. Its documentation notes that some providers omit that endpoint, so verification can fail even when chat works. CometAPI’s integration guide, however, documents model discovery as part of this connection. A discovery failure here should therefore be investigated rather than dismissed as expected behavior.

Start with an empty model filter. If a filter is later needed for diagnosis, enter only model IDs confirmed through current provider evidence. A manually allowed model appearing in the selector shows that the local filter worked; it does not prove that the upstream model exists or that completion requests will succeed.

Chat acceptance test

Use a new conversation, plain text, and no optional tools for the first request. A useful acceptance record includes the selected model ID, HTTP status, elapsed time, streaming setting, and whether the response was non-empty. Repeat against a second discovered model. Exact wording is less important than receiving a valid response, because models can vary in how literally they follow a formatting instruction.

Version and persistence

Capture the Open WebUI version with every test result. The main and latest container tags are rolling builds, while version tags are pinned. A result from a moving image may not be reproducible after the image changes. The named /app/backend/data volume is equally important because it retains configuration and chat data across container replacement.

Sanitized operational logging

Use structured records that help isolate the failing stage without retaining user content. This illustrative success record contains no credential or prompt:

{
  "timestamp": "2026-08-13T12:00:00Z",
  "event": "chat_completion",
  "open_webui_version": "X.Y.Z",
  "base_host": "api.cometapi.com",
  "api_prefix": "/v1",
  "model_id": "model-a",
  "streaming": true,
  "http_status": 200,
  "duration_ms": 840,
  "outcome": "success"
}

For an error, preserve the stage and status while normalizing the error category:

{
  "timestamp": "2026-08-13T12:02:00Z",
  "event": "model_discovery",
  "open_webui_version": "X.Y.Z",
  "base_host": "api.cometapi.com",
  "api_prefix": "/v1",
  "http_status": 401,
  "duration_ms": 310,
  "outcome": "failure",
  "error_type": "authentication_failed"
}

Recommended fields are timestamp, event, Open WebUI version, connection label, base host, API prefix, model ID when applicable, streaming state, HTTP status, duration, outcome, a sanitized error category, and an upstream request identifier only when one is safely returned. Do not log the API key, request headers, prompt text, completion text, uploaded documents, or full unreviewed error bodies.

Failure modes

A 401 response during discovery or chat

Treat this as an authentication or account-access failure. Re-enter the credential privately, check for accidental whitespace, and confirm that the account is able to make requests. Do not print the configured value or attach the raw connection configuration to a ticket. Repeated retries with unchanged input add noise and can obscure the first useful failure record.

A 400 or 403 response while saving the connection

Capture which operation produced the status. Open WebUI’s general documentation warns that connection verification can fail for providers with nonstandard model discovery, but CometAPI’s guide documents compatible model discovery. Confirm the base address, Open WebUI version, and account state before using a manual model filter as a temporary diagnostic.

The connection saves but the selector is empty

Check whether the model-discovery request actually succeeded and whether Model IDs (Filter) contains an unintended allowlist. Do not conclude that the provider has no models based only on the empty UI. Conversely, adding an arbitrary model ID may populate the selector locally while leaving the upstream problem unresolved.

A selected model is rejected

Use the exact model ID returned by current discovery. Display names, screenshots, and older examples can drift from accepted identifiers. If another discovered model works, preserve that evidence and classify the failure as model-specific instead of connection-wide.

The request times out before output begins

The CometAPI guide recommends a timeout of at least 60 seconds for models with a longer delay before first output. Increase the relevant timeout deliberately, run one controlled retry, and record the elapsed time. Do not create an unbounded retry loop.

Streaming disconnects or never completes

Open WebUI’s Quick Start states that WebSocket support is required. Confirm that the network path serving Open WebUI permits WebSocket connections. Keep this check separate from CometAPI authentication: changing credentials will not repair a blocked browser-to-Open-WebUI streaming channel.

Behavior changes after an update

A deployment using main or latest can change whenever a new image is published. Compare the image tag or digest with the last successful test. Pin a stable version for production and repeat both discovery and two-model chat checks after an intentional upgrade.

Settings or chats disappear after container replacement

Verify that the named volume is still mounted at /app/backend/data. The official Quick Start identifies that mount as the persistent storage boundary. Recreating a container without it can produce a fresh instance that looks like a connection failure because the saved configuration is absent.

FAQ

Does a populated model selector prove the integration works?

No. It proves that the discovery stage returned usable model information. You still need a successful chat completion. Test two discovered model IDs separately so one model-specific failure does not get mistaken for a gateway-wide failure.

Does failed connection verification always mean chat is impossible?

No. Open WebUI documents providers that lack a compatible models endpoint and can still support chat when model IDs are allowed manually. CometAPI’s integration guide documents model discovery, though, so a CometAPI verification failure is unexpected and should be diagnosed rather than automatically bypassed.

Should I remove the /v1 prefix when discovery fails?

Start with the documented /v1 prefix. Before changing it, inspect the failing operation and confirm how the installed Open WebUI version constructs its models route. Changing the base blindly can replace one path error with another and makes test results harder to compare.

Can CometAPI and local Ollama models coexist in Open WebUI?

Yes. The checked sources describe Open WebUI as supporting multiple connection types, including Ollama and OpenAI-compatible providers. Label connections and record the selected model ID so an operator can tell which backend handled a test.

Should I hardcode model IDs in the initial setup?

No. Begin with automatic discovery. Use a filter only when you intentionally want an allowlist or when diagnosing a known discovery limitation. Any manually entered ID should come from current provider evidence, and it still requires a real completion test.

Is the rolling container tag suitable for a production acceptance test?

It is useful for evaluating the newest build, but it does not identify an immutable release. Use a pinned version tag when you need repeatable tests, controlled upgrades, or reliable comparisons with an earlier result.

Reader next step

First, verify the CometAPI base URL before changing the UI . Then configure the OpenAI-compatible connection, confirm discovery, and run the same small plain text prompt against two current model IDs.

If the UI remains ambiguous, run a focused chat-completion contract smoke test to separate a provider request failure from an Open WebUI display or streaming problem. Keep the resulting evidence sanitized and tied to the exact Open WebUI version.

When you are ready to create the provider connection, Start with CometAPI .