Last reviewed: August 13, 2026

Direct answer

Connect Open WebUI to CometAPI by adding CometAPI as an OpenAI-compatible connection. In current Open WebUI documentation, the path is Admin Settings → Connections → OpenAI → Add Connection. Set the connection to use HTTPS with the host api.cometapi.com and the /v1 base path, place an active CometAPI credential in the administrative key field, and save the connection. The CometAPI Open WebUI guide documents that base address and a simple chat test.

Next, choose an exact, current model ID rather than guessing an alias. The CometAPI model catalog reference documents a public catalog containing model IDs, providers, capability fields, endpoint hints, and pricing metadata. Select a text-capable model whose endpoint information fits the OpenAI-compatible chat route.

If Open WebUI displays the model automatically, select it and send a small test prompt. If connection verification or model discovery fails, do not immediately conclude that chat is incompatible. The Open WebUI OpenAI-compatible provider guide explains that its verification step calls a standard /models route and that some otherwise compatible providers require model IDs to be added manually under Model IDs (Filter). Add the catalog ID, save again, and test an actual chat completion.

A successful setup has three observable results: the connection remains enabled after saving, the selected model appears in the model picker, and a minimal chat receives a nonempty assistant reply.

Who this is for

This guide is for developers and administrators who already run Open WebUI or are preparing a self-hosted instance. It assumes you can access administrator settings and have an active CometAPI credential, but it does not require changing Open WebUI source code.

If Open WebUI is not running yet, the official Open WebUI Quick Start covers Docker, Python, Kubernetes, and desktop installation paths. Its Docker guidance recommends persistent storage so chats and settings survive container recreation, requires WebSocket-capable networking, and recommends pinning a specific release for reproducible production deployments.

This article focuses on the provider boundary: connection address, model discovery, model selection, a happy-path chat test, and evidence to capture when the test fails.

Key takeaways

  • Configure CometAPI under Open WebUI’s OpenAI-compatible connections, not as a proprietary provider module.
  • Use the documented /v1 base path. Omitting that path changes the route Open WebUI builds for provider calls.
  • Choose model IDs from current CometAPI catalog data and verify that the model is suitable for text or chat.
  • Treat connection verification and an actual chat request as separate tests. Discovery can fail even when chat remains usable.
  • Never place the provider credential in a repository, screenshot, browser export, prompt, or diagnostic log.
  • Record sanitized operational evidence so a failed setup can be reproduced without exposing conversation content.
  • Before changing a model selection, use the site’s model catalog validation guide to confirm the ID and capability boundary.

Sources checked

These sources serve different purposes. The CometAPI integration page provides provider-specific values. Open WebUI defines how its connection screen and verification behavior work. The catalog supplies current model metadata. The installation guide helps separate a provider problem from a broken Open WebUI deployment.

Contract details to verify

Before opening the connection form, verify four boundaries independently.

First, confirm the Open WebUI instance itself works. You should be able to sign in, reach administrator settings, and open the model selector. A missing page, failed WebSocket connection, or container that loses settings on restart is an Open WebUI deployment issue, not evidence about CometAPI compatibility.

Second, verify the connection values:

  • Connection type: OpenAI-compatible.
  • API address: HTTPS with host api.cometapi.com and base path /v1.
  • Credential field: an active CometAPI value entered only in the protected administrative form.
  • Connection state: enabled after saving.
  • Model selection: an exact text-capable catalog ID, added to Model IDs (Filter) when discovery does not populate it.

The menu wording can vary by Open WebUI version. The current Open WebUI source uses Admin Settings → Connections → OpenAI, while the CometAPI-specific source describes Admin Panel → Settings → External Connections and an OpenAI API option. Follow the OpenAI-compatible connection area in the version you actually run; do not substitute an Ollama or unrelated native-provider field.

Third, distinguish the two model routes described by the sources. CometAPI documents its public catalog at /api/models. Open WebUI says its connection verification calls /models relative to the configured provider base. These are not the same documented path. The public catalog is the source for selecting an ID; the Open WebUI verification call is a compatibility check. When that check fails, the manual model filter provides a documented way to expose a known model in the selector before testing chat.

Fourth, use an intentionally small validation prompt. Ask for a short, deterministic response that does not contain personal, confidential, or production data. Confirm that the UI displays a nonempty assistant message and that the chosen model remains selected.

Happy-path operator workflow

  1. Confirm Open WebUI loads and retains its settings after a normal restart.
  2. Review the public CometAPI catalog and select one current text-capable model ID with suitable endpoint metadata.
  3. Open Open WebUI’s OpenAI-compatible connection settings.
  4. Add the documented CometAPI address and active credential, then enable and save the connection.
  5. Select the chosen model. If it is absent, add its exact ID to Model IDs (Filter) and save again.
  6. Send a small test prompt and confirm a nonempty reply.
  7. Record the time, model ID, outcome, status if available, and latency. Do not record the credential, request headers, prompt, or generated text.
  8. Repeat one test after the next planned Open WebUI restart to verify that the saved connection persists.

A sanitized success record can look like this:

{
  "event": "provider_connection_test",
  "provider": "cometapi",
  "endpoint_family": "openai_compatible_chat",
  "model_id": "selected-model-id",
  "outcome": "success",
  "http_status": 200,
  "latency_ms": 842,
  "request_id": "record-only-if-returned",
  "response_bytes": 417
}

The numeric values are illustrative measurements, not service guarantees. Keep identifiers only when the service actually returns them, and apply your normal retention policy.

Error-path operator workflow

  1. Stop repeated test submissions and capture the visible symptom, timestamp, selected model ID, and status code if one is shown.
  2. Verify that the connection is enabled and that its address includes the documented /v1 path.
  3. Check the model ID against the current public catalog. Confirm its model type, capabilities, and endpoint hints.
  4. If verification fails before the model picker is populated, add the verified model ID to Model IDs (Filter). Then test chat separately.
  5. For a 400, inspect the connection address, selected model, and request stage before retrying. For a 401 or 403, verify that the configured credential is active and permitted, but never copy it into a ticket or log.
  6. If the Open WebUI interface itself disconnects, loses settings, or cannot maintain WebSockets, repair the deployment or proxy path before changing provider settings.
  7. Retest once with the same minimal prompt. Change only one variable at a time so the result is attributable.
  8. If escalation is necessary, provide sanitized evidence and the source links above, not screenshots containing credentials or conversation data.

A sanitized failure record can look like this:

{
  "event": "provider_connection_test",
  "provider": "cometapi",
  "endpoint_family": "openai_compatible_chat",
  "model_id": "selected-model-id",
  "outcome": "error",
  "http_status": 403,
  "failure_stage": "connection_verification",
  "request_id": "record-only-if-returned"
}

Failure modes

The connection saves, but no models appear

Open WebUI may be unable to verify or populate models through its expected /models call. Confirm an exact model through the public CometAPI catalog, add it to Model IDs (Filter), save, and run a chat test. A failed discovery check alone does not prove the chat route is unusable.

Verification succeeds, but chat fails

Discovery and generation exercise different operations. Confirm that the selected catalog entry is text-capable and has endpoint metadata appropriate for chat. Also confirm that the model ID shown in Open WebUI exactly matches the catalog ID rather than a remembered alias.

The connection returns 400

Treat this as a configuration or request-stage signal. Recheck the base address, model ID, and whether the failure occurred during verification or chat. Avoid changing several settings at once; doing so makes the actual cause harder to identify.

The connection returns 401 or 403

Re-enter or replace the credential through the administrative settings without exposing it elsewhere. Confirm that the connection uses the intended CometAPI account and access boundary. Do not log the key field, headers, or complete error payload if it echoes sensitive data.

Open WebUI forgets the connection after a restart

This points to deployment persistence rather than model compatibility. The Open WebUI Quick Start identifies its backend data volume as persistent storage. Repair that storage boundary, recreate the connection if necessary, and repeat the post-restart happy-path test.

The interface freezes or disconnects during testing

Open WebUI’s Quick Start states that WebSocket support is required. Check the Open WebUI deployment and any reverse proxy before modifying the CometAPI model or credential. A broken browser-to-WebUI connection can mask a healthy provider connection.

Logs are detailed but unsafe to share

Remove prompts, response text, credentials, headers, cookies, and user identifiers. Retain the event name, provider, endpoint family, model ID, failure stage, timestamp, HTTP status, latency, response size, and a request identifier only if one was returned. This is enough to compare attempts without reproducing sensitive content.

FAQ

Does Open WebUI need a CometAPI-specific plugin?

No. The CometAPI documentation describes the service as an external OpenAI-compatible connection. Open WebUI’s protocol-oriented design supports providers that implement the expected chat-completions behavior through its standard connection screen.

Which CometAPI model should I enter?

Use a current text-capable ID from the public catalog. Do not copy an arbitrary model name from an old screenshot or unrelated provider guide. Review model_type, features, and endpoints where present, then use the exact id value in Open WebUI.

Why can verification fail even if chat may work?

Open WebUI verifies compatible connections through a /models request. Its guide explicitly notes that some providers do not implement that route as expected, even though chat completions still work. In that situation, add the model ID manually and test the chat operation itself.

Should I use the public catalog route as the Open WebUI base address?

No. The catalog and provider base serve different purposes. Use the documented /v1 base path in the connection form. Use the public catalog only to inspect model metadata and choose an exact ID.

What should a production readiness check include?

At minimum, verify that settings persist, the intended model is allowlisted, a minimal chat succeeds, sanitized operational fields are recorded, and the same test succeeds after the next planned restart. For a deeper request-contract check, follow the site’s CometAPI chat smoke-test guide .

What data should not appear in a support bundle?

Do not include provider credentials, request headers, cookies, full prompts, generated answers, or user-identifying fields. Share the sanitized fields shown in this guide and describe which stage failed.

Reader next step

Choose one current text-capable model from the CometAPI catalog, add the OpenAI-compatible connection in Open WebUI, and run one minimal chat test. Record the sanitized result, then repeat the test after a planned restart.

If model discovery is the only failing stage, add the verified catalog ID to Model IDs (Filter) before changing any other setting. If the chat request still fails, follow the error-path workflow in order: address, model contract, credential state, and finally the Open WebUI deployment boundary. That sequence produces evidence another operator can use without exposing private data.