Instalação do Open WebUI e configuração do OmniProxy

O Open WebUI é uma interface de chat que você pode implantar por conta própria, instalando-a em seu computador ou servidor, e que também pode funcionar totalmente offline. Ele não fica vinculado a um único fornecedor de modelos: pode se conectar tanto a ferramentas como o Ollama, que executam modelos localmente, quanto a APIs compatíveis com o formato da OpenAI, ou seja, endereços que fornecem serviços de modelos usando o mesmo formato de requisição. Assim, é possível alternar entre modelos locais e modelos na nuvem na mesma janela.

Ele é adequado para uso contínuo por equipes e organizações. Recursos atualizados com mais rapidez aparecem primeiro no Computer, produto usado pelo Open WebUI para experimentar novas funcionalidades.

Preparação antes da instalação

O Open WebUI pode ser usado no macOS, Linux e Windows. Você pode instalá-lo por Docker, Python ou Kubernetes. O Docker coloca o aplicativo e o ambiente de execução em um contêiner relativamente isolado e é o método recomendado. Se você não tiver Docker, também poderá usar o comando Python testado abaixo. O Kubernetes é um sistema para implantar e gerenciar contêineres; as etapas correspondentes estão no Quick Start indicado no final deste guia.

Recomendação oficial

Docker

Um único docker run
Abra a porta 3000 no navegador
Os dados ficam no volume

Se você só quer conversar

Imagem slim

O download é menor
Altere a tag para :slim
O recurso de chat continua disponível

Não abordado neste guia

Outras duas opções

Instalação manual com Python
Implantação no Kubernetes
Consulte o Quick Start oficial

Primeiro instale o Docker e depois inicie usando o comando oficial recomendado. Se você usar apenas o chat por API, poderá trocar a tag da imagem por slim.

Antes de começar, prepare:

Uma instalação do Docker que já esteja funcionando.
Uma sequência secreta para uso exclusivamente pessoal. Execute openssl rand -hex 32 para gerá-la e insira o resultado em WEBUI_SECRET_KEY. Guarde esse valor de forma permanente; se ele for alterado ao recriar o contêiner, os usuários que já estiverem conectados serão desconectados.
Uma instância do OmniProxy em execução e o ID de um modelo presente na lista atual de modelos. O ID do modelo é o nome completo usado para selecionar um modelo específico.

Instalação e primeira inicialização

Abra o terminal e execute o comando do Quick Start. Primeiro, substitua your-secret-key pela sequência secreta que você acabou de gerar:

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data -e WEBUI_SECRET_KEY=your-secret-key --name open-webui --restart always ghcr.io/open-webui/open-webui:main

As principais opções desse comando têm as seguintes funções:

-p 3000:8080: permite abrir a interface pela porta 3000 deste computador. Se a porta 3000 estiver ocupada, altere o número à esquerda.
-v open-webui:/app/backend/data: armazena chats, usuários e configurações em um volume de dados. Um volume de dados é um local fora do contêiner usado para manter dados permanentemente; seu conteúdo permanece após a atualização do contêiner, portanto não remova esta opção.
--add-host=host.docker.internal:host-gateway: permite que o contêiner acesse outros serviços executados neste computador.
--restart always: faz o contêiner iniciar novamente quando o computador for reiniciado.

Depois de executar o comando, abra http://localhost:3000 no navegador e siga as instruções da página para criar a primeira conta.

Se você pretende apenas conversar por meio da API, pode trocar a tag da imagem de :main para :slim. A slim é uma imagem menor que não inclui os modelos locais de voz e de embeddings dentro do contêiner, mas a interface de chat continua disponível. Se precisar desses recursos locais, continue usando :main.

Para atualizar manualmente, primeiro execute docker rm -f open-webui, depois execute docker pull ghcr.io/open-webui/open-webui:main e, em seguida, reinicie usando o mesmo comando docker run. Tanto o volume de dados quanto o WEBUI_SECRET_KEY devem permanecer inalterados.

Quando não houver Docker

O Quick Start também oferece uma forma de instalação por Python. Em 2026-10-09, o comando abaixo foi usado no macOS para instalar o Open WebUI v0.11.4 e concluir uma conversa. Na ocasião, esse computador não tinha o Docker Desktop.

DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve

Depois da inicialização, abra http://localhost:8080 no navegador. Essa é a porta usada pela instalação por Python, e não a porta 3000 usada pelo Docker.

Na primeira inicialização, será baixado um modelo de embeddings, o que pode levar alguns minutos. O modelo de embeddings converte o texto em dados adequados para pesquisa e correspondência. Aguarde até a página de login aparecer antes de continuar; a primeira conta registrada se tornará administradora. O idioma da interface acompanha o sistema; nesse teste, ela apareceu em chinês simplificado.

DATA_DIR deve apontar para um diretório que será mantido permanentemente e usado para armazenar os dados do Open WebUI. Se ele não for definido, os dados poderão ser armazenados em um diretório temporário e perdidos após o encerramento. Quando WEBUI_SECRET_KEY não está definido, o programa grava .webui_secret_key no diretório atual. Inicie o programa em um diretório que você pretende manter ou defina essa variável manualmente.

Obter os parâmetros de conexão do OmniProxy

Copie os três itens abaixo da sua própria instância do OmniProxy:

URL:      https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: copie o ID completo da lista atual de modelos do OmniProxy

A URL é o endereço que o Open WebUI usará para se conectar à API e deve terminar em /v1. Não acrescente /chat/completions depois disso, pois o próprio Open WebUI adicionará esse trecho.

O ID do modelo deve ser copiado integralmente da lista atual do OmniProxy. Se o ID tiver um prefixo de origem e barras, eles também deverão ser mantidos. Os dois nomes curtos abaixo servem apenas como referência na documentação dos fornecedores em 2026-10-09; não os use se eles não estiverem na lista atual:

ID do Claude Sonnet 5.5 na Claude API: claude-sonnet-5-5
Nome do Gemini 3.8 Flash na API: gemini-3.8-flash

Não insira a chave do fornecedor no Open WebUI. Se o gateway não validar chaves, deixe a chave de API em branco; não invente outra sequência para preencher o campo.

Navegador

Porta local 3000

Abra a página de chat
Primeiro, conclua o cadastro
Depois, acesse as configurações

No contêiner

Open WebUI

Não use localhost
Use o nome do host
A URL deve terminar em /v1

No mesmo computador

OmniProxy

Mantenha a chave no gateway
Use a lista de modelos do gateway como referência
Depois, confira os registros de chamadas

Quando o Open WebUI estiver no Docker e o OmniProxy estiver na máquina host, não use localhost dentro do endereço configurado no contêiner.

Se o serviço de modelos estiver sendo executado na máquina host e o Open WebUI estiver em um contêiner Docker, substitua localhost na URL por host.docker.internal. A máquina host é o computador que executa o Docker diretamente. Se o OmniProxy estiver escutando apenas nesse computador, a URL poderá ser http://host.docker.internal:porta/v1, substituindo porta pela porta realmente usada pelo OmniProxy.

Se o Open WebUI estiver sendo executado localmente por meio do comando Python da seção anterior e o OmniProxy também estiver no mesmo computador, use 127.0.0.1 ou localhost no endereço. Nesse caso, não use host.docker.internal.

Preencher a configuração da ferramenta

Em 2026-10-09, a interface em chinês simplificado da versão v0.11.4 usava nomes diferentes de Settings > Admin > Connections, presentes nas instruções em inglês. Siga as opções realmente exibidas na interface, apresentadas abaixo em português:

Expanda a barra lateral esquerda.
Clique no menu do usuário, na parte inferior.
Clique em Configurações.
No grupo de administração abaixo, clique em Conexões externas.
Ative API OpenAI.
À direita de Gerenciar conexões da API OpenAI, clique em +.
Na janela Editar conexão, preencha a URL até /v1. Mantenha o tipo de API como Chat Completions.
Mantenha o Método de autenticação como Chave (Bearer). Bearer é uma forma de autenticação que inclui a chave de API na requisição. Se o OmniProxy tiver fornecido uma chave, insira-a em Chave de API. Se o gateway não validar chaves, deixe esse campo em branco. Em 2026-10-09, a validação e uma conversa foram concluídas com sucesso deixando-o em branco.
Clique em Validar conexão, ao lado da URL. Quando o OmniProxy fornece /models, a lista de modelos será obtida nesse momento.
Abra Avançado. Quando ID do modelo estiver vazio, serão usados todos os modelos retornados por /models nesse endereço. Somente se a validação falhar, insira em Adicionar ID do modelo o ID completo presente na lista e clique em Adicionar. Adicione cada ID apenas uma vez; os espaços antes e depois dele serão removidos.
Clique em Salvar nessa janela e depois clique em Salvar no canto inferior direito da página de conexões externas.

Salvar a configuração não substitui a validação. Validar conexão envia uma requisição ao endpoint /models do outro serviço, usado para listar os modelos disponíveis. Alguns serviços não oferecem esse endpoint; nesse caso, a validação apresentará um erro, mas o chat ainda poderá funcionar. Se isso acontecer, adicione manualmente o ID do modelo.

Verificar uma tarefa real

Volte à página de chat, abra o menu de modelos ao lado da caixa de entrada e selecione o ID completo da lista do OmniProxy. Envie uma frase bem curta, por exemplo pedindo que o modelo responda com apenas uma palavra. A resposta precisa realmente aparecer na caixa de chat.

Em 2026-10-09, essa conversa foi concluída usando a instalação por Python da versão v0.11.4. O Docker continua sendo o método recomendado, mas o teste não foi repetido no Docker nessa ocasião.

Em seguida, abra o registro de chamadas do OmniProxy e confirme a origem da requisição e o ID do modelo. Ver apenas uma mensagem de que a configuração foi salva ou apenas ver o modelo no menu ainda não significa que o processo foi concluído.

Interface

O modelo pode ser selecionado

Connections foi salvo
O modelo aparece na lista
Envie uma pergunta curta

Resposta

Há uma resposta no chat

Não é uma mensagem em branco
Não é um erro de conexão
Troque de modelo e tente novamente

Registros

Visível no gateway

A origem é esta conexão
O ID do modelo corresponde
Nenhuma chave foi inserida na página

A conexão só pode ser considerada utilizável quando os três pontos estiverem corretos.

Erros comuns

Uso de localhost ou 127.0.0.1 dentro do contêiner: esses dois endereços apontam para o próprio contêiner, não para a máquina host. Troque-os por host.docker.internal e confirme se o comando de inicialização contém --add-host=host.docker.internal:host-gateway. Quando o Open WebUI não estiver em um contêiner, faça o contrário e use o endereço local.
O navegador não abre a página: para o Docker, verifique a porta 3000; para o Python, verifique a porta 8080. Na primeira inicialização, é necessário aguardar o download do modelo de embeddings. Use docker ps para confirmar se o contêiner está em execução. Se a porta 3000 estiver ocupada, altere a porta à esquerda em -p.
O ID no menu de modelos é mais longo que o nome curto do fornecedor: use o ID completo exibido no menu, incluindo as barras.
Todos foram desconectados depois de uma atualização: o valor de WEBUI_SECRET_KEY mudou. Reinicie usando a sequência secreta gerada na primeira vez.
Falha em Validar conexão: primeiro adicione manualmente o ID do modelo em Avançado e depois confirme com uma conversa real de uma frase. Alguns serviços não oferecem /models; mesmo que a validação apresente erro, o chat ainda poderá funcionar.
O modelo não existe: copie novamente o ID da lista atual do OmniProxy e não continue usando um nome desatualizado.

Referências oficiais

Consulte os comandos de instalação em Open WebUI Quick Start. Consulte as etapas de conexão em instruções de conexão OpenAI-compatible. Os IDs de modelo usados como exemplos estão disponíveis na visão geral dos modelos Claude e na lista de modelos Gemini.

Substitua todos os espaços reservados por valores de sua própria configuração do OmniProxy. Nunca publique uma chave real.

Um resultado salvo ou HTTP 200 sozinho não prova compatibilidade total com o Agente. Verifique a origem e o modelo no registro de chamadas do OmniProxy.

Fontes oficiais · Open WebUI ↗