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

O Open WebUI é uma interface de conversação que pode ser implementada pelo próprio utilizador no seu computador ou servidor e que também funciona totalmente offline. Não está associado a um fornecedor de modelos específico: pode ligar-se a ferramentas como o Ollama, que executam modelos localmente, ou a endpoints compatíveis com o formato OpenAI, ou seja, endereços que fornecem serviços de modelos através do mesmo formato de pedidos. Desta forma, é possível alternar entre modelos locais e modelos na nuvem na mesma janela.

É adequado para utilização prolongada por equipas e organizações. As funcionalidades atualizadas mais rapidamente aparecem primeiro no Computer, o produto utilizado pelo Open WebUI para experimentar novas funcionalidades.

Preparação antes da instalação

O Open WebUI pode ser utilizado no macOS, Linux e Windows. Pode instalá-lo através de Docker, Python ou Kubernetes. O Docker instala a aplicação e o ambiente de execução num contentor relativamente isolado e é o método recomendado. Se não tiver Docker, também pode utilizar o comando Python testado abaixo. O Kubernetes é um sistema de implementação e gestão de contentores; consulte os passos correspondentes 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 de dados

Se só quiser conversar

Imagem slim

A transferência é mais pequena
Altere a etiqueta para :slim
A funcionalidade de conversação mantém-se

Não abordado aqui

Outras duas opções

Instalação manual com Python
Implementação em Kubernetes
Consulte o Quick Start oficial

Instale primeiro o Docker e, em seguida, inicie a aplicação com o comando recomendado. Se apenas conversar através da API, pode alterar a etiqueta da imagem para slim.

Antes de começar, prepare:

Uma instalação do Docker que esteja a funcionar.
Uma cadeia secreta para uso exclusivamente pessoal. Execute openssl rand -hex 32 para a gerar e introduza-a em WEBUI_SECRET_KEY. Guarde este valor sem o alterar; se o substituir ao recriar o contentor, todas as pessoas com sessão iniciada serão desligadas.
Uma instância do OmniProxy em execução e um ID de modelo presente na respetiva lista atual de modelos. O ID de modelo é o nome completo utilizado para selecionar um modelo específico.

Instalação e primeiro arranque

Abra um terminal e execute o comando do Quick Start. Primeiro, substitua your-secret-key pela cadeia secreta que 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 várias opções deste comando têm as seguintes funções:

-p 3000:8080: permite abrir a interface através da porta 3000 deste computador. Se a porta 3000 estiver ocupada, altere o número do lado esquerdo.
-v open-webui:/app/backend/data: guarda as conversas, os utilizadores e as definições num volume de dados. Um volume de dados é uma localização fora do contentor onde os dados são guardados de forma persistente. O conteúdo mantém-se depois de atualizar o contentor, pelo que não deve remover esta opção.
--add-host=host.docker.internal:host-gateway: permite que o contentor aceda a outros serviços em execução neste computador.
--restart always: faz com que o contentor volte a iniciar depois de o computador ser reiniciado.

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

Se apenas pretender conversar através da API, pode alterar a etiqueta da imagem de :main para :slim. A slim é uma imagem mais pequena que não inclui os modelos locais de voz e de embeddings dentro do contentor, mas a interface de conversação continua disponível. Se precisar dessas funcionalidades locais, continue a utilizar :main.

Para atualizar manualmente, execute primeiro docker rm -f open-webui, depois docker pull ghcr.io/open-webui/open-webui:main e, por fim, volte a iniciar com o mesmo comando docker run. Tanto o volume de dados como WEBUI_SECRET_KEY devem permanecer inalterados.

Se não tiver Docker

O Quick Start também disponibiliza um método de instalação com Python. Em 2026-10-09, o comando abaixo foi utilizado no macOS para instalar o Open WebUI v0.11.4 e concluir uma conversação. Nesse momento, o computador não tinha o Docker Desktop.

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

Depois do arranque, abra http://localhost:8080 no navegador. Esta é a porta utilizada pela instalação com Python, e não a porta 3000 utilizada pelo Docker.

No primeiro arranque, será descarregado um modelo de embeddings, o que pode demorar alguns minutos. O modelo de embeddings converte texto em dados adequados para pesquisa e correspondência. Aguarde até aparecer a página de início de sessão antes de continuar. A primeira conta registada torna-se administradora. O idioma da interface segue o sistema; neste teste, a interface apareceu em chinês simplificado.

DATA_DIR deve apontar para um diretório que será mantido a longo prazo e utilizado para guardar os dados do Open WebUI. Se não o definir, os dados podem ser colocados num diretório temporário e perder-se depois de fechar o programa. Quando WEBUI_SECRET_KEY não está definido, o programa grava .webui_secret_key no diretório atual. Inicie-o a partir de um diretório que pretenda conservar ou defina esta variável manualmente.

Obter os parâmetros de ligação do OmniProxy

Copie os três elementos seguintes 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

O URL é o endereço utilizado pelo Open WebUI para estabelecer ligação ao endpoint e deve terminar em /v1. Não acrescente /chat/completions no final, pois o Open WebUI adiciona automaticamente esse segmento.

O ID de modelo deve ser copiado integralmente da lista atual do OmniProxy. Se o ID incluir um prefixo de origem e barras, mantenha-os também. Os dois nomes abreviados abaixo são apenas referências presentes na documentação dos fornecedores em 2026-10-09. Não os utilize se não estiverem na lista atual:

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

Não introduza a chave do fornecedor no Open WebUI. Se o gateway não validar chaves, pode deixar a chave API em branco; não invente outra chave.

Navegador

Porta local 3000

Abra a página de conversação
Conclua primeiro o registo
Depois, aceda às definições

No contentor

Open WebUI

Não use localhost
Use o nome do anfitrião
O URL termina em /v1

No mesmo computador

OmniProxy

Mantenha a chave no gateway
Use a lista de modelos do gateway como referência
Depois, consulte o registo de chamadas

Quando o Open WebUI está no Docker e o OmniProxy está no anfitrião, não utilize o localhost do contentor no endereço.

Se o serviço de modelos estiver em execução no anfitrião e o Open WebUI estiver num contentor Docker, substitua localhost no URL por host.docker.internal. O anfitrião é o computador que executa diretamente o Docker. Se o OmniProxy apenas escutar neste computador, pode utilizar o URL http://host.docker.internal:PORTA/v1, substituindo PORTA pela porta efetivamente utilizada pelo OmniProxy.

Se o Open WebUI estiver a ser executado localmente através do comando Python da secção anterior e o OmniProxy também estiver no mesmo computador, utilize 127.0.0.1 ou localhost no endereço. Neste caso, não utilize host.docker.internal.

Preencher a configuração da ferramenta

Na interface em chinês simplificado da versão v0.11.4, em 2026-10-09, os nomes eram diferentes de Settings > Admin > Connections utilizados nas instruções em inglês. Siga as opções correspondentes apresentadas na interface:

Expanda a barra lateral esquerda.
Clique no menu do utilizador na parte inferior.
Clique em Definições.
No grupo de administração abaixo, clique em Ligações externas.
Abra API OpenAI.
À direita de Gerir ligações à API OpenAI, clique em +.
Na janela Editar ligação, introduza o URL até /v1. Mantenha Chat Completions como tipo de endpoint.
Mantenha Chave (Bearer) como Método de autenticação. Bearer é uma forma de autenticação que inclui a chave API no pedido. Se o OmniProxy lhe tiver fornecido uma chave, introduza-a em Chave API. Se o gateway não validar chaves, deixe este campo em branco. Em 2026-10-09, tanto a validação como uma conversação foram concluídas com êxito deixando-o em branco.
Clique em Validar ligação, junto ao URL. Se o OmniProxy disponibilizar /models, a lista de modelos será obtida neste passo.
Abra Avançado. Se deixar ID de modelo em branco, serão utilizados todos os modelos devolvidos por /models nesse endereço. Apenas se a validação falhar, introduza o ID completo da lista em Adicionar ID de modelo e clique em Adicionar. Adicione cada ID apenas uma vez; os espaços no início e no fim são removidos.
Clique em Guardar nesta janela e, em seguida, clique em Guardar no canto inferior direito da página de ligações externas.

Guardar a configuração não substitui a validação. Validar ligação envia um pedido para /models, o endpoint utilizado para listar os modelos disponíveis. Alguns serviços não têm este endpoint, pelo que a validação pode apresentar um erro mesmo que a conversação continue a funcionar. Nesse caso, adicione manualmente o ID de modelo.

Verificar uma tarefa real

Regresse à página de conversação, abra o menu de modelos junto à caixa de texto e selecione o ID completo apresentado na lista do OmniProxy. Envie uma frase muito curta, por exemplo, pedindo que responda apenas com uma palavra. A resposta deve aparecer efetivamente na caixa de conversação.

Em 2026-10-09, esta conversação foi concluída com a instalação Python da versão v0.11.4. O Docker continua a ser o método recomendado, mas o teste não foi repetido no Docker.

Em seguida, abra o registo de chamadas do OmniProxy e confirme a origem e o ID de modelo deste pedido. Ver apenas uma indicação de que a configuração foi guardada, ou apenas o modelo no menu, ainda não é suficiente para considerar o processo concluído.

Interface

É possível selecionar o modelo

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

Resposta

A resposta aparece na caixa de conversa

Não é uma mensagem em branco
Não é um erro de ligação
Experimente novamente com outro modelo

Registo

Visível no gateway

A origem é esta ligação
O ID do modelo corresponde
A chave não aparece na página

A ligação só deve ser considerada utilizável quando os três pontos estiverem confirmados.

Erros comuns

Utilizou localhost ou 127.0.0.1 dentro do contentor: estes dois endereços apontam para o próprio contentor, não para o anfitrião. Altere para host.docker.internal e confirme que o comando de arranque inclui --add-host=host.docker.internal:host-gateway. Se o Open WebUI não estiver num contentor, faça o contrário e utilize o endereço local.
O navegador não abre a página: para Docker, verifique a porta 3000; para Python, verifique a porta 8080. No primeiro arranque, aguarde que o modelo de embeddings termine de ser descarregado. Pode utilizar docker ps para confirmar se o contentor está em execução. Se a porta 3000 estiver ocupada, altere a porta do lado esquerdo de -p.
O ID no menu de modelos é mais comprido do que o nome abreviado do fornecedor: utilize o ID completo apresentado no menu, incluindo as barras.
Todas as sessões foram terminadas depois de uma atualização: o valor de WEBUI_SECRET_KEY foi alterado. Reinicie utilizando a cadeia secreta gerada inicialmente.
Validar ligação falha: primeiro, adicione manualmente o ID de modelo em Avançado e depois confirme o funcionamento com uma conversação real de uma frase. Alguns serviços não têm /models; mesmo que a validação apresente um erro, a conversação pode continuar a funcionar.
O modelo não existe: volte a copiar o ID da lista atual do OmniProxy e não continue a utilizar um nome desatualizado.

Referências oficiais

Consulte os comandos de instalação em Open WebUI Quick Start. Consulte os passos de ligação em instruções para ligações OpenAI-compatible. Os IDs de modelo utilizados como exemplos podem ser consultados em visão geral dos modelos Claude e lista de modelos Gemini.

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

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

Fontes oficiais · Open WebUI ↗