docs.near.aicloud › guides › integrations › open webui

NEAR AI Cloud: Open WebUI

Updated 02-11-2026

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.
The current NEAR AI Cloud model ID from 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:

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:

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:

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:

Open Admin Settings or Connections.
Go to Connections and add an OpenAI-compatible or OpenAI connection.
Set URL to https://cloud-api.near.ai/v1.
Set API Key to your NEAR AI Cloud API key. Open WebUI sends it as Authorization: Bearer <key>.
Save or verify the connection.
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:

Open Workspace -> Models -> z-ai/glm-5.2 -> Advanced Params (or the chat Advanced Params panel).
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:

Run curl https://cloud-api.near.ai/v1/models and copy the new model's id.
Re-open the NEAR AI Cloud connection in Open WebUI.
Save or re-save the connection so Open WebUI verifies the provider and fetches models again.
Refresh the browser tab and check the model picker.
If the model still is not listed, restart Open WebUI, then check the model picker again.
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:

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:

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`).

Sources Checked

Sources checked on 2026-06-23:

Back to Documentation