> ## Documentation Index
> Fetch the complete documentation index at: https://docs.near.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Open WebUI

> Configure Open WebUI to use NEAR AI Cloud as an OpenAI-compatible provider.

Open WebUI can use NEAR AI Cloud through its OpenAI-compatible provider connection. Configure the NEAR AI Cloud gateway as the base URL, use a NEAR AI Cloud API key as the bearer token, and select models that Open WebUI discovers from NEAR AI Cloud's `/v1/models` endpoint.

## Prerequisites

* An Open WebUI instance where you can open Admin Settings or Connections.
* A NEAR AI Cloud API key from the [NEAR AI Cloud Dashboard](https://cloud.near.ai/dashboard/organizations).
* The current NEAR AI Cloud model ID from [Model Discovery](/cloud/guides/integrations/model-discovery) if you are not using `z-ai/glm-5.2`.

Store the API key only in Open WebUI's provider API key field or your deployment secret manager. Do not put real API keys in checked-in configuration files.

## Base URL

Use the NEAR AI Cloud gateway base URL:

```text theme={"dark"}
https://cloud-api.near.ai/v1
```

Do not append `/chat/completions` to the Open WebUI URL field. Open WebUI appends `/models` for model discovery and `/chat/completions` for chat requests.

Do not use Open WebUI's own internal `/api` route as the upstream NEAR AI Cloud URL. The upstream provider must be the NEAR AI Cloud gateway URL above.

## Model ID

Use the NEAR AI Cloud gateway model ID:

```text theme={"dark"}
z-ai/glm-5.2
```

Open WebUI verifies OpenAI-compatible connections by calling the provider's `/models` endpoint with a standard bearer token. With the NEAR AI Cloud base URL above, that verification reaches:

```text theme={"dark"}
https://cloud-api.near.ai/v1/models
```

If verification succeeds, select `z-ai/glm-5.2` from Open WebUI's model picker. If the picker is stale, use the refresh steps below before entering a manual model filter.

## Configure

In Open WebUI:

1. Open **Admin Settings** or **Connections**.
2. Go to **Connections** and add an **OpenAI-compatible** or **OpenAI** connection.
3. Set **URL** to `https://cloud-api.near.ai/v1`.
4. Set **API Key** to your NEAR AI Cloud API key. Open WebUI sends it as `Authorization: Bearer <key>`.
5. Save or verify the connection.
6. Select `z-ai/glm-5.2` from the model list.

If your Open WebUI version shows **Model IDs (Filter)**, leave it empty first so Open WebUI can read `/v1/models`. Add `z-ai/glm-5.2` to the filter only if you want to limit the picker or model discovery is not refreshing.

### Native tool calling

If you use Open WebUI to orchestrate tools (workspace Tools, MCP servers, or built-in tools), set the model's **Function Calling** mode to **Native**. Open WebUI defaults each model to **Default**, which emulates tool use through a prompt template and does **not** forward the OpenAI `tools` array to NEAR AI Cloud. GLM 5.2 supports native tools (`/v1/models` lists `tools` in `supported_features`), so switch to Native to use them:

1. Open **Workspace** -> **Models** -> `z-ai/glm-5.2` -> **Advanced Params** (or the chat **Advanced Params** panel).
2. Change **Function Calling** from `Default` to `Native` (stored as `params.function_calling = "native"`).

A plain chat with no tools attached behaves the same in either mode, so this only matters when tools are in play.

## Refresh models

When NEAR AI Cloud releases a new model:

1. Run `curl https://cloud-api.near.ai/v1/models` and copy the new model's `id`.
2. Re-open the NEAR AI Cloud connection in Open WebUI.
3. Save or re-save the connection so Open WebUI verifies the provider and fetches models again.
4. Refresh the browser tab and check the model picker.
5. If the model still is not listed, restart Open WebUI, then check the model picker again.
6. If the model remains missing, test NEAR AI Cloud directly with the curl commands below and add the model ID to **Model IDs (Filter)** only after confirming `/v1/models` returns it.

## Quick test

Before debugging Open WebUI, verify that NEAR AI Cloud lists the model:

```bash theme={"dark"}
curl -fsSL https://cloud-api.near.ai/v1/models \
  | jq -e '.data[] | select(.id == "z-ai/glm-5.2")'
```

Then test a chat completion with the same key and model:

```bash theme={"dark"}
curl https://cloud-api.near.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEARAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.2",
    "messages": [
      {"role": "user", "content": "Reply with only: near-ai-ok"}
    ],
    "max_tokens": 20
  }'
```

If either curl command fails, fix the NEAR AI Cloud key, model ID, or network path before changing Open WebUI settings.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| `model not listed` | Open WebUI cached an older model list, the connection was not re-saved, or **Model IDs (Filter)** hides the model. | Confirm `curl https://cloud-api.near.ai/v1/models` returns `z-ai/glm-5.2`, re-save the connection, refresh the browser tab, restart Open WebUI if needed, and clear or update the model filter. |
| `401` | Missing, invalid, or expired NEAR AI Cloud API key. | Paste a valid NEAR AI Cloud API key into Open WebUI's API key field. Open WebUI should send it as a bearer token; do not log or share the key while testing. |
| Wrong base URL includes `/chat/completions` | A full request URL was pasted into Open WebUI's URL field. | Use `https://cloud-api.near.ai/v1` as the base URL. Keep `/chat/completions` only in curl or HTTP request URLs. |
| Connection verification fails but curl works | Open WebUI did not refresh the provider's `/models` response or a model filter is blocking the picker. | Re-save the connection, restart Open WebUI, then manually add `z-ai/glm-5.2` to **Model IDs (Filter)** if `/v1/models` works from curl. |
| Requests reach the wrong service | The URL field points at Open WebUI's internal API route instead of the NEAR AI Cloud gateway. | Replace the upstream URL with `https://cloud-api.near.ai/v1` and save the connection again. |
| Tools/function calling are ignored or emulated | The model's Function Calling mode is left at `Default`, so Open WebUI uses prompt-based emulation instead of passing the OpenAI `tools` array. | Set Function Calling to `Native` in the model's Advanced Params (Workspace -> Models -> `z-ai/glm-5.2`). |

## Related guides

* [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)
* [OpenAI Compatibility](/cloud/guides/openai-compatibility)
* [Available Models](/cloud/models)
* [LibreChat](/cloud/guides/integrations/librechat)
* [Dify](/cloud/guides/integrations/dify)

## Sources Checked

Sources checked on 2026-06-23:

* [Open WebUI OpenAI-compatible provider](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible/)
* [Model Discovery and Refresh](/cloud/guides/integrations/model-discovery)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.