Documentação

Open WebUI

O Open WebUI trata qualquer endpoint compatível com OpenAI como uma conexão. Adicione uma em Configurações do administrador ou defina duas variáveis de ambiente ao iniciar o contêiner — ambos os caminhos levam ao mesmo resultado.

Uma conexão OpenAI em Admin Settings, ou OPENAI_API_BASE_URL e OPENAI_API_KEY na inicialização do contêiner — ambas terminam no mesmo /v1.

Connection ou docker run

# Settings → Admin Settings → Connections → Manage OpenAI API Connections → +
URL                https://api.kunavo.com/v1
API Key            sk-kn-...
Model IDs (Filter) claude-sonnet-5, claude-opus-5, claude-haiku-4-5, gpt-5-6-terra

# …or at container start, same thing:
docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=https://api.kunavo.com/v1 \
  -e OPENAI_API_KEY=sk-kn-... \
  -v open-webui:/app/backend/data \
  --name open-webui ghcr.io/open-webui/open-webui:main

Preencha IDs de modelos (filtro). Sem isso, o seletor lista o catálogo inteiro — incluindo modelos de imagem, vídeo e música que uma janela de chat não pode chamar —, e o primeiro clique do usuário acaba em um deles. O filtro também deve ser usado quando um endpoint não tem uma rota /models; a Kunavo tem essa rota, então a verificação é bem-sucedida de qualquer forma.

A URL mantém o /v1. Se o Open WebUI estiver em execução no Docker e você o estiver apontando para algo no mesmo host, substitua localhost por host.docker.internal — isso não se aplica a um endpoint hospedado, mas é o problema que as pessoas encontram logo depois deste.

Ainda não tem uma chave? Crie uma conta na Kunavo, gere uma chave (ela começa com sk-kn-) e adicione crédito a partir de $10 — as chamadas são pagas com esse saldo, e chamadas malsucedidas não são cobradas. O painel então abre na configuração de Open WebUI.

Passo a passo

Crie uma chave em /app/keys e copie-a — ela é exibida uma única vez.
No Open WebUI, acesse Configurações → Administrador → Conexões e localize Gerenciar conexões de API OpenAI.
Clique em ➕ Adicionar conexão e informe a URL e a chave de API.
Adicione os IDs desejados em IDs de modelos (filtro), salve e deixe a conexão fazer a verificação.
Inicie um novo chat — os modelos aparecem no seletor com o nome da conexão como prefixo.

Verificado em Guia de provedores compatíveis com OpenAI do Open WebUI em 6 de setembro de 2026. As configurações de terceiros podem mudar; se o nome de um campo aqui já não corresponder ao que você vê, aquela página é a autoridade, não esta.

Verifique antes de depurar o cliente

Uma solicitação determina se a falha está no endpoint, na chave ou no arquivo de configuração. Se isto retornar JSON, a mesma URL base e a mesma chave funcionarão em Open WebUI.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Qual ID de modelo inserir no campo

Todo modelo de texto pode ser acessado como um ID de modelo — a lista atual está em GET /v1/models, e o catálogo com preços está na página de modelos. As tarifas são em USD por 1 milhão de tokens, entrada / saída.

ID do modelo	Entrada / saída da Kunavo	Onde se encaixa em Open WebUI
`claude-sonnet-5`	$1.40 / $7.00	o padrão geral para chat
`claude-opus-5`	$3.50 / $17.50	conversas analíticas longas
`claude-haiku-4-5`	$0.70 / $3.50	rápido, barato e adequado para a maioria dos turnos
`gpt-5-6-terra`	$0.70 / $4.20	documentos longos colados na janela de chat

A cobrança é por token, usando um saldo pré-pago e sem tarifa mensal — consulte billing. Em contextos repetidos — que representam a maior parte do que um editor ou cliente de chat envia — o cache de prompt altera a conta mais do que a escolha do modelo.

Perguntas frequentes

Como conecto o Open WebUI a uma API compatível com OpenAI?

Acesse Configurações → Administrador → Conexões, abra "Gerenciar conexões de API OpenAI" e clique em Adicionar conexão. Em seguida, informe a URL do endpoint — a raiz /v1 — e a chave de API. Também é possível fazer isso ao iniciar o contêiner, usando as variáveis de ambiente OPENAI_API_BASE_URL e OPENAI_API_KEY. Ambos os caminhos criam a mesma conexão.

Para que serve IDs de modelos (filtro) no Open WebUI?

Essa opção restringe quais IDs de modelos dessa conexão aparecem no seletor e também serve de alternativa para endpoints que não implementam uma rota /models — nesse caso, você adiciona os IDs manualmente, a verificação falha, mas o chat continua funcionando. Em um gateway com um catálogo multimodal extenso, vale a pena defini-la de qualquer forma, para que o seletor de chat mostre apenas os modelos que uma janela de chat pode realmente chamar.

A URL base do Open WebUI inclui /v1?

Sim. O Open WebUI acrescenta somente a rota à URL informada, então a URL da conexão é a raiz /v1 — https://api.example.com/v1. Os próprios exemplos de endpoints da documentação incluem esse sufixo. Sem ele, a conexão é salva, mas todas as solicitações retornam erro 404.

O Open WebUI consegue usar modelos Claude e GPT?

Sim, quando são disponibilizados por meio de um endpoint compatível com OpenAI. O Open WebUI envia o ID do modelo diretamente para a URL da conexão, então os IDs de qualquer fornecedor são resolvidos no endpoint, não no Open WebUI. Isso também significa que uma conexão e uma chave podem colocar IDs Claude e GPT no mesmo seletor de modelos.