Conectar provedores de terceiros e auto-hospedados

O Libre WebUI 0.16.0 adiciona um workspace dedicado a Conexões de provedores em Configurações > Plugins. Use-o para ativar um provedor integrado, apontar um plugin compatível para outra API, inspecionar o catálogo efetivo de modelos ou conectar um gateway auto-hospedado em uma rede confiável.

Atualmente, o Libre WebUI oferece suporte a estes formatos de comunicação dos provedores:

• OpenAI Chat Completions;
• OpenAI Responses;
• Anthropic Messages; e
• conteúdo e chamadas de função do Google Gemini.

As definições integradas do Anthropic e do Gemini usam adaptadores dedicados, selecionados pela identidade do provedor. Um provedor recém-importado usa a semântica do OpenAI Chat Completions ou do OpenAI Responses; apontá-lo para uma API compatível com Anthropic ou Gemini não seleciona esses adaptadores integrados. Um provedor com outro formato de solicitação, streaming, chamada de ferramenta ou resposta precisa de um adaptador no backend. O JSON do plugin descreve o roteamento e a configuração; ele não converte um protocolo não relacionado.

Abrir as Conexões de provedores

1. Entre na sua conta e abra Configurações > Plugins.
2. Pesquise na lista de provedores no painel esquerdo.
3. Selecione um provedor para conferir seu estado de ativação e o catálogo efetivo de modelos.
4. Ative o provedor para sua conta.
5. Selecione Configurar somente quando precisar salvar uma credencial ou substituir uma configuração de conexão.

A configuração do provedor fica fechada por padrão. As configurações de conexão aparecem primeiro para administradores, enquanto os controles de amostragem, como temperatura e limites de tokens, permanecem na seção Parâmetros avançados, recolhida separadamente. Os padrões herdados aparecem como sugestões, em vez de substituições de conta já preenchidas.

As definições dos plugins são configurações compartilhadas da instância, portanto somente administradores podem importá-las, instalá-las, atualizá-las ou excluí-las. Cada usuário autenticado controla o próprio estado de ativação, credencial e configurações de geração permitidas.

Adicionar uma conexão rapidamente

Configurações > Conexões é um caminho mais curto para o caso comum: um endpoint compatível com OpenAI e uma chave de API. Administradores veem um cartão do ambiente de execução local do Ollama, com seu status e versão, uma lista das conexões existentes compatíveis com OpenAI e um pequeno formulário para adicionar outra.

Para adicionar uma conexão, informe um nome de exibição, a URL completa de conclusões de chat e uma chave de API opcional. O Libre WebUI deriva o ID da conexão a partir do nome, instala a definição do provedor, armazena a chave no servidor, ativa a conexão e pergunta ao endpoint quais modelos ele oferece. Os modelos descobertos substituem o catálogo provisório e aparecem no seletor de modelos de chat.

Cada linha mostra o endpoint, a quantidade de modelos, se uma chave está armazenada, um botão de ativação, a atualização de modelos e a exclusão. Tudo que vai além disso — modos da API Responses, substituições da URL base, catálogos por recurso e política de parâmetros de geração — continua no workspace mais completo em Configurações > Plugins, descrito acima.

Codex (login do ChatGPT)

O provedor integrado Codex (ChatGPT) não precisa de chave de API. Quando o servidor tem uma sessão iniciada na CLI do Codex (codex login executado pelo usuário do sistema operacional do servidor), o provedor aparece para os administradores e oferece a família documentada de modelos Codex pela sessão do ChatGPT. Os tokens de acesso são lidos do arquivo auth.json da própria CLI, atualizados pelo mesmo cliente OAuth que ela usa e gravados novamente para que a CLI continue funcionando; os valores dos tokens nunca aparecem nos logs.

Como as solicitações são feitas pelo backend — nunca de dentro do contêiner de uma tarefa —, esses modelos também executam o Work com o ciclo normal de ferramentas em sandbox. O provedor é exclusivo para administradores, pois todas as chamadas consomem a assinatura do ChatGPT do proprietário do servidor. Oculte-o por completo com CODEX_OAUTH_MODELS_ENABLED=false ou aponte para outro login com CODEX_HOME.

Escolher um provedor integrado ou importado

O Libre WebUI inclui definições para OpenAI, Anthropic, Gemini, Groq, Mistral, OpenRouter, Kimi Code da Moonshot AI, Hugging Face, GitHub Models, MLX LM local e outros serviços de modelos ou mídia. Comece com uma entrada integrada quando o protocolo e o contrato de autenticação corresponderem ao serviço que você quer usar.

Para outro serviço compatível, um administrador pode importar uma definição JSON de plugin. Este exemplo mínimo descreve um gateway compatível com OpenAI:

{
  "id": "private-ai-gateway",
  "name": "Private AI Gateway",
  "type": "completion",
  "endpoint": "http://ai-gateway:8080/v1/chat/completions",
  "api_mode": "chat_completions",
  "auth": {
    "header": "Authorization",
    "prefix": "Bearer ",
    "key_env": "PRIVATE_AI_GATEWAY_API_KEY"
  },
  "model_map": ["gateway-chat"]
}

Importe o arquivo em Configurações > Plugins, ative-o e salve a chave de API para a conta que usará a conexão. Adicione variáveis de conexão à definição quando administradores precisarem de campos editáveis para URL base, caminho, descoberta ou endpoints específicos de recursos. O arquivo integrado plugins/openai.json é um exemplo completo.

Para um gateway intencionalmente sem autenticação em uma rede confiável, defina auth.header e auth.key_env como strings vazias e omita auth.prefix. Nesse caso, o Libre WebUI não exige nem envia uma chave de API para esse plugin.

Escolher Chat Completions ou Responses

Plugins de conclusão compatíveis com OpenAI podem usar um destes modos de API:

Modo de API	Caminho padrão da solicitação	Campo típico da solicitação
chat_completions	/chat/completions	messages
responses	/responses	input

O provedor OpenAI integrado expõe o Modo da API em sua configuração. O Libre WebUI converte saídas concluídas e transmitidas do Responses para o Chat e o Work, inclusive o estado limitado de reprodução para raciocínio e chamadas de ferramentas.

Alterar o modo afeta o caminho padrão da operação. Isso não muda o protocolo usado pelo servidor upstream; portanto, selecione Responses somente quando o servidor implementar formatos compatíveis de solicitações e eventos do Responses.

Configurar uma URL base ou um endpoint completo

O Libre WebUI resolve a rota de conclusão nesta ordem:

1. Uma substituição de endpoint completo diferente do padrão.
2. base_url mais um api_path opcional.
3. O endpoint declarado pela definição do plugin.

Use URL base para a raiz da API:

https://gateway.example/v1

Sem um caminho personalizado, o modo Chat Completions envia solicitações para:

https://gateway.example/v1/chat/completions

O modo Responses as envia para:

https://gateway.example/v1/responses

Use Caminho da API quando o provedor expuser uma operação compatível em outro caminho relativo a essa raiz. Use Endpoint completo legado somente quando precisar fornecer a URL completa da operação; um endpoint completo real tem precedência sobre a URL base e o caminho da API.

Sufixos de endpoint conhecidos, como /chat/completions, /completions e /responses, também identificam a semântica da solicitação. Um caminho de operação personalizado e não reconhecido mantém o modo de API selecionado explicitamente.

Depois de alterar uma rota ou chave de API, salve novamente o provedor antes de testar o Chat. Quando o plugin declara autenticação, uma rota de conexão personalizada exige uma credencial salva pela mesma conta. Um plugin intencionalmente sem autenticação pode deixar os dois campos de autenticação vazios. O Libre WebUI não envia uma chave de ambiente gerenciada pelo operador para um destino definido pelo usuário; o uso alternativo da variável de ambiente fica reservado à rota integrada confiável.

Descobrir ou manter IDs de modelos

Selecione um provedor de chat ativo e use Atualizar modelos para executar a descoberta. O Libre WebUI recarrega o catálogo do provedor selecionado e a lista de modelos do Chat.

A descoberta também é executada automaticamente: o catálogo de um provedor ativo é descoberto novamente quando está ausente ou ultrapassa a idade definida por PLUGIN_MODEL_DISCOVERY_TTL_MS; assim, os modelos exibidos acompanham o provedor, em vez de refletirem apenas o momento em que ele foi ativado. Atualizar modelos força uma verificação imediata e informa o resultado:

Resultado	Significado
Catálogo atualizado	O provedor respondeu, e sua lista difere da armazenada
Catálogo já está atualizado	O provedor respondeu com a mesma lista
Chave de API necessária	Não há chave utilizável; nenhuma solicitação foi feita, e o catálogo anterior continua visível
Não foi possível carregar o catálogo	O provedor estava inacessível ou não devolveu nada utilizável

Uma chave definida somente no ambiente não é usada para um provedor que executa uma definição instalada, e não a integrada; a mensagem informa quando isso se aplica. Modelos de fala, imagem e embedding encontrados no catálogo de um provedor aparecem aqui com os rótulos de recurso, mas ficam fora do seletor de modelos de chat.

Para uma rota compatível com OpenAI, a descoberta escolhe a URL da lista de modelos da seguinte forma:

• uma rota terminada em /models é usada como está;
• um sufixo de operação conhecido, como /chat/completions, /completions, /responses, /embeddings ou /messages, é substituído por /models; e
• nos demais casos, /models é acrescentado à rota.

Por exemplo, as duas rotas de conclusão abaixo derivam a mesma URL de descoberta:

https://gateway.example/v1/chat/completions
https://gateway.example/v1/responses

-> https://gateway.example/v1/models

Quando a derivação não consegue produzir a URL completa correta, exponha models_endpoint no array variables do plugin:

{
  "name": "models_endpoint",
  "type": "string",
  "label": "Models Endpoint",
  "default": "https://gateway.example/v1/models"
}

O padrão herdado ou o valor salvo pelo administrador tem precedência sobre o endereço derivado. Uma propriedade models_endpoint no nível superior do manifesto não é lida. A descoberta espera uma resposta compatível com OpenAI contendo objetos de modelo em um array data:

{
  "data": [{ "id": "gateway-chat" }, { "id": "gateway-code" }]
}

Os IDs descobertos são armazenados por usuário e não reescrevem o arquivo compartilhado do plugin. Se o provedor não implementar uma descoberta compatível, mantenha IDs de modelos alternativos em model_map no JSON do plugin. O catálogo em Conexões de provedores é somente para leitura; os rótulos de recursos descrevem qual rota do plugin lista um modelo e não são verificações de integridade.

Os IDs de modelos não são exclusivos globalmente. O Chat armazena o ID bruto do modelo junto com a identidade exata do provedor Ollama ou do plugin, portanto um modelo Ollama e vários plugins podem expor com segurança o mesmo nome. Se o provedor salvo ficar indisponível, o Libre WebUI mostra a seleção como indisponível, em vez de direcionar silenciosamente a solicitação a outro provedor.

Configurar a geração de imagens separadamente

O provedor OpenAI integrado disponibiliza a geração de imagens por https://api.openai.com/v1/images/generations e, no momento, usa gpt-image-2 como padrão para novas configurações. IDs antigos do GPT Image continuam no catálogo alternativo para manter a compatibilidade com implantações existentes.

As rotas de chat e imagem são deliberadamente isoladas. Uma URL base personalizada para o Chat não recebe solicitações de imagem automaticamente. Deixe image_endpoint em branco para usar o endpoint de imagem declarado pelo plugin ou defina-o com a URL completa da operação compatível da API de imagens quando o provedor oferecer uma.

As opções de imagem são qualificadas por provedor, assim como as do Chat. Se dois plugins ativos expuserem o mesmo ID de modelo de imagem, o Libre WebUI enviará a solicitação somente ao provedor selecionado no painel de imagens.

Conectar um gateway HTTP com segurança

Endpoints de provedores podem usar URLs HTTP ou HTTPS absolutas. HTTP é útil para um gateway auto-hospedado em uma LAN confiável, rede Tailscale ou rede privada de contêineres, mas envia chaves de API, prompts, resultados de ferramentas e conteúdo gerado sem criptografia de transporte. Prefira HTTPS sempre que a rota atravessar um limite de rede ou o gateway oferecer TLS.

As solicitações saem do backend do Libre WebUI, não do navegador. Escolha um endereço que possa ser acessado pelo backend:

Local do backend	Exemplo de raiz do provedor
Processo nativo, mesma máquina	http://127.0.0.1:8081/v1
Serviço do Docker Compose	http://ai-gateway:8080/v1
Contêiner para host compatível	http://host.docker.internal:8081/v1
Host confiável em LAN ou Tailscale	http://192.168.1.20:8081/v1

Dentro de um contêiner, localhost identifica o próprio contêiner do Libre WebUI. Ele não identifica outro serviço do Compose nem acessa automaticamente o host.

O Libre WebUI aceita somente URLs HTTP e HTTPS para provedores, valida o destino final antes de selecionar uma credencial e não segue redirecionamentos em solicitações ao provedor ou de descoberta. Configure diretamente a URL final da operação.

Verificar o gateway antes de ativá-lo

Teste a descoberta de modelos a partir da máquina ou do contêiner que executa o backend do Libre WebUI:

curl http://ai-gateway:8080/v1/models \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY'

Depois, teste a operação correspondente ao modo de API selecionado.

Chat Completions:

curl http://ai-gateway:8080/v1/chat/completions \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "messages": [{"role": "user", "content": "Reply with: ready"}],
    "stream": false
  }'

Responses:

curl http://ai-gateway:8080/v1/responses \
  -H 'Authorization: Bearer YOUR_GATEWAY_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gateway-chat",
    "input": "Reply with: ready",
    "store": false
  }'

Quando as duas chamadas funcionarem, configure a mesma rota, modo, credencial e ID de modelo em Conexões de provedores. Ative o provedor, selecione Atualizar modelos e escolha no Chat o modelo qualificado por provedor. O Work também pode usá-lo quando o modelo oferecer suporte confiável a chamadas de ferramentas.

Solução de problemas

Sintoma	O que verificar
As solicitações ainda chegam ao endpoint integrado	Remova uma substituição antiga do endpoint completo e salve a URL base e o caminho da API desejados.
O provedor recebe a carga errada	Faça o Modo da API corresponder ao protocolo Chat Completions ou Responses do upstream e verifique o sufixo final.
Atualizar modelos não devolve IDs	Teste /models, verifique o formato data[].id, exponha/configure a variável models_endpoint ou mantenha model_map.
Um modelo anterior permanece após editar a rota	Salve a alteração da conexão; o Libre WebUI limpa o catálogo descoberto obsoleto desse usuário antes da atualização.
A chave de API é informada como ausente	Salve uma credencial por usuário para a rota personalizada; a alternativa de ambiente integrada não acompanha substituições.
Uma implantação Docker não acessa localhost	Use o nome do serviço no Compose, um alias de host compatível ou um endereço acessível da rede privada.
O Chat funciona, mas a geração de imagens não	Configure separadamente o image_endpoint completo e selecione um modelo exposto pelo recurso de imagem.
O Chat funciona, mas o Work rejeita o modelo	Confirme que o modelo aceita chamadas de ferramentas compatíveis; conclusão de texto comum não é suficiente.
O provedor devolve um redirecionamento	Configure diretamente a URL final validada; o Libre WebUI deliberadamente não segue redirecionamentos de provedores.

Para conhecer em detalhes o roteamento, as credenciais, o estado de reprodução e o comportamento de autorização, consulte Plugins. Para falhas específicas da implantação, veja Solução de problemas.

Agradecimento à comunidade

Este guia e a experiência de Conexões de provedores do Libre WebUI 0.16.0 foram moldados por ZhengJin (@fangzhengjin), cujo feedback detalhado sobre provedores de terceiros e conceito de UX assistido por IA no nº 163 ajudaram a definir o fluxo.

Documentação relacionada

• Plugins
• Trabalhar com modelos
• MLX LM no Apple Silicon
• Work: workspaces isolados
• Solução de problemas