Open WebUI com Ollama: guia complet

#Por que Open WebUI

Open WebUI (anteriormente Ollama WebUI) tornou-se o frontend de referência para LLMs auto-hospedados. É uma aplicação web de código aberto (licença permissiva) que se comunica nativamente com Ollama, mas também com qualquer endpoint compatível com OpenAI — LM Studio, vLLM, servidor llama.cpp, ou até mesmo uma chave OpenAI, se você tiver uma.

Interface familiar

Barra lateral com histórico, área central de chat, seletor de modelo na parte superior. Quem já abriu o ChatGPT consegue se orientar em 30 segundos.

RAG integrado

Arraste um PDF, um .docx, um .md ou um .txt para a conversa: o Open WebUI divide o arquivo em blocos, gera seus embeddings e o usa como contexto. Não é preciso montar uma stack RAG manualmente.

Multiusuário nativo

Contas locais, papéis admin/user/pending, validação manual de inscrições. Perfeito para uma equipe ou família.

100% offline após a instalação

O contêiner, a interface e os modelos rodam na sua máquina. Nenhuma telemetria obrigatória, nenhuma requisição de saída se você bloquear OpenAI/HuggingFace nas configurações.

Extensível

Pipelines Python (funções, filtros, RAG personalizado), ferramentas MCP, integração de pesquisa web (SearXNG, Tavily), TTS/STT, geração de imagens via ComfyUI ou Automatic1111.

#Pré-requisitos

Ollama instalado e funcionando

O daemon deve escutar em http://localhost:11434. Verifique com curl http://localhost:11434/api/tags — você deve obter um JSON (vazio ou com seus modelos).

Docker Desktop ou Docker Engine

Windows/macOS: Docker Desktop. Linux: docker-ce via o gerenciador de pacotes da sua distribuição. Compose v2 está incluído.

2 GB de RAM livre

Open WebUI consome pouco (200-400 MB). A maior parte da RAM/VRAM será usada por Ollama, que carrega os modelos.

Um modelo Ollama já baixado

Se a lista estiver vazia, ollama pull qwen3.5:4b ou ollama pull granite4.2:8b antes de começar — caso contrário, não haverá nada para selecionar na interface.

#1. Instalação do Docker em um comando

A imagem oficial está publicada no GitHub Container Registry. Um único comando basta para iniciar o Open WebUI e conectá-lo automaticamente ao seu Ollama local.

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

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

Vamos analisar os flags. Cada um tem um propósito preciso:

-p 3000:8080

O Open WebUI escuta na porta 8080 dentro do contêiner. Essa porta é publicada na porta 3000 da sua máquina. Você acessará o serviço por http://localhost:3000.

--add-host=host.docker.internal:host-gateway

Obrigatório no Linux: permite que o contêiner acesse Ollama que está rodando fora do Docker via o hostname host.docker.internal. No Windows/macOS, o Docker Desktop já configura isso.

-v open-webui:/app/backend/data

Volume nomeado que preserva o histórico das conversas, as contas dos usuários e os documentos indexados. Sem isso, tudo desaparece ao reiniciar o contêiner.

--restart always

O contêiner reinicia automaticamente no boot da máquina. Open WebUI torna-se um serviço permanente.

ghcr.io/open-webui/open-webui:main

Tag main = versão estável mais recente. Para fixar uma versão, use :v0.5.0 (ou a release atual). Em produção, não dependa de main.

#2. Primeiro acesso e conta de administrador

Depois que o contêiner estiver iniciado, abra no navegador a URL abaixo.

http://localhost:3000

1. 01
   Criação da conta de administrador

   Na primeira execução, o Open WebUI pede que você crie uma conta. O primeiro usuário registrado se torna administrador automaticamente. E-mail, senha — tudo permanece local, no volume Docker.
2. 02
   Verifique os modelos disponíveis

   No seletor no topo da tela, seus modelos Ollama devem aparecer. Se a lista estiver vazia, é porque a conexão com o Ollama falhou (ver seção 3 abaixo).
3. 03
   Inicie uma conversa de teste

   Escolha um modelo, digite uma mensagem. Se a resposta chegar em streaming, tudo está conectado. Caso contrário, abra Settings > Admin Panel > Connections para diagnosticar.

#3. Conectar o Open WebUI ao Ollama

Em 95% dos casos, a conexão é feita automaticamente através de host.docker.internal. Se isso não ocorrer, segue como forçar manualmente.

Acesse Settings (ícone no canto inferior esquerdo) > Admin Panel > Connections > Ollama API. Insira a URL:

http://host.docker.internal:11434

Clique no botão de teste (ícone de atualização ao lado do campo). Um indicador verde confirma a conexão. A lista de seus modelos é recarregada imediatamente.

Para verificar via CLI se Ollama está realmente acessível fora do contêiner:

# Depuis l'hôte
curl http://localhost:11434/api/tags

# Depuis le conteneur Open WebUI (Linux)
docker exec -it open-webui curl http://host.docker.internal:11434/api/tags

#4. RAG com seus documentos em 2 minutos

É provavelmente a funcionalidade que, por si só, justifica a instalação. O Open WebUI inclui um pipeline RAG completo: extração de texto (PDF, DOCX, MD, TXT, HTML, código-fonte), chunking, embeddings, busca vetorial e injeção no contexto.

#Método 1: anexo enviado na hora

Em uma conversa, clique no ícone de clipe (ou digite # para navegar pelos documentos indexados). Selecione um arquivo — ele é ingerido, dividido em blocos e convertido em embeddings em poucos segundos. O modelo agora pode responder a perguntas sobre seu conteúdo.

#Método 2: Knowledge (base persistente)

Para uso recorrente — documentação interna, base de conhecimento, arquivos de projeto — crie uma Knowledge. Workspace > Knowledge > Create Knowledge. Dê um nome a ela (ex.: "Documentação do produto"), carregue seus documentos em massa e associe-a a um modelo personalizado via Workspace > Models.

Chunking padrão

1000 caracteres com sobreposição de 100. Ajustável em Settings > Documents. Para texto técnico denso, reduza para 500/50. Para texto narrativo, mantenha 1500/200.

Top K

Número de chunks fornecidos ao modelo. Valor padrão: 4. Aumente para 6-8 em perguntas que abrangem vários temas, reduza para 2-3 se o modelo perder o foco.

Busca híbrida

Ativável na mesma página. Combina busca lexical BM25 e similaridade vetorial. Essencial para consultas contendo termos técnicos exatos (referências de produto, nomes próprios, códigos).

#5. Múltiplos usuários e autenticação

O Open WebUI gerencia três papéis: admin (tudo), user (chat + suas próprias bases de conhecimento), pending (conta criada, mas aguardando validação). O sistema foi projetado para que um admin controle quem entra na instância.

1. 01
   Habilitar o cadastro controlado

   Admin Panel > Settings > General. Defina Default User Role como 'pending'. Todo novo cadastro exigirá sua aprovação manual em Admin Panel > Users.
2. 02
   Criar usuários

   Seus colegas acessam http://votre-ip:3000 e criam uma conta. Você vê a solicitação em Admin Panel > Users e a aprova com um clique. Eles podem então fazer login.
3. 03
   Restringir modelos por usuário

   Workspace > Models > selecione um modelo > Visibility. Você pode tornar um modelo público, privado ou expô-lo apenas a alguns usuários (útil para um modelo sensível com ajuste fino).
4. 04
   Forçar HTTPS se a instância estiver exposta

   O Open WebUI não gerencia TLS por conta própria. Coloque Caddy, Traefik ou nginx à frente do contêiner. Sem HTTPS, não exponha o Open WebUI fora da sua LAN — as senhas são transmitidas em texto claro.

#Open WebUI vs Msty vs LobeChat

Três interfaces maduras dividem o mercado em 2026. Veja como escolher entre elas de acordo com seu perfil.

Open WebUI

O mais completo e extensível. RAG, pipelines em Python, múltiplos usuários, MCP, busca na web. Requer Docker. Ideal se você quer UMA interface para toda a equipe.

Msty

Aplicativo desktop nativo (Windows/Mac/Linux), sem Docker, instalação em 1 clique. Excelente experiência de usuário para uso individual. RAG integrado também. Menos extensível que Open WebUI. Ideal para um desenvolvedor ou curioso que quer testar rapidamente.

LobeChat

Mais voltado para um "clone visual do ChatGPT". Visual bonito, plugins e marketplace de agentes. Suporte a múltiplos provedores muito bem implementado. RAG menos avançado. Ideal se você alterna entre Ollama local e várias APIs (OpenAI, Anthropic, Mistral na nuvem).

Veredito rápido

Uso individual + máquina pessoal: Msty. Equipe + servidor dedicado: Open WebUI. Usuário avançado que quer um frontend bonito com vários provedores: LobeChat.

#Solução de problemas

Lista de modelos vazia

O Open WebUI não consegue se conectar ao Ollama. Verifique: (1) se ollama list exibe modelos, (2) se curl http://localhost:11434/api/tags responde e (3) se, no Linux, OLLAMA_HOST=0.0.0.0:11434 está definido. Teste a URL em Admin Panel > Connections.

Erro 502 Bad Gateway

O contêiner não inicia corretamente. docker logs open-webui mostra a causa. Muitas vezes: volume montado em modo somente leitura, porta 3000 já ocupada ou conflito com uma instância anterior (docker rm -f open-webui e depois iniciar novamente).

Baixa taxa de tokens por segundo

O gargalo está em Ollama, não em Open WebUI. O comando ollama ps deve mostrar 100% de GPU. Se for CPU ou parcial, o modelo ultrapassa a VRAM — mude para uma quantização menor (Q4_K_M em vez de Q5_K_M).

Documentos não indexados

O primeiro upload baixa o modelo de embeddings (1-2 GB), o que pode levar algum tempo. Consulte docker logs open-webui. Verifique também se o arquivo não excede o tamanho máximo (ajustável em Settings > Documents > Max Upload File Size).

Atualização

docker pull ghcr.io/open-webui/open-webui:main puis docker stop open-webui && docker rm open-webui et relancez la commande run d'origine. Le volume open-webui:/app/backend/data préserve vos données.

Backup

docker run --rm -v open-webui:/data -v $(pwd):/backup alpine tar czf /backup/openwebui-backup.tar.gz -C /data . cria um arquivo com todo o seu histórico, contas e conhecimentos. Faça isso antes de cada atualização importante.

#Para se aprofundar

Com o Open WebUI instalado e conectado ao Ollama, você tem um ambiente de trabalho de IA local completo. Alguns próximos passos naturais:

Melhorar o RAG

O RAG integrado do Open WebUI é bastante satisfatório, mas, para grandes conjuntos de documentos ou buscas mais específicas, o guia de RAG com ChromaDB deste site mostra como montar um pipeline dedicado, com melhor desempenho e mais possibilidades de ajuste.

Escolher a quantização correta

Q4_K_M por padrão, mas o equilíbrio entre vantagens e desvantagens muda conforme a sua VRAM. O guia de quantização Q4/Q5/Q8 detalha as ordens de grandeza — muitas vezes decisivas para conseguir rodar um 14B ou ter que ficar com um 7B.

Comparar com outros frontends

Se você ainda está hesitando entre Open WebUI, LibreChat, AnythingLLM, SillyTavern, o guia comparativo dos frontends de chat lista suas respectivas vantagens em uma página.