Open WebUI não chama ferramentas: teste Native Mode, Tool Search e compatibilidade

A ferramenta está habilitada e o modelo diz que vai usá-la, mas nenhum tool call real aparece. Esse sintoma, sozinho, não prova se a falha está no modelo, no Open WebUI ou no servidor MCP/OpenAPI. A forma mais confiável de separar as causas é criar uma linha de base com um reverse_string sem efeitos colaterais e, depois, alterar Native Mode, Tool Search e a conexão do modelo um item por vez.

Você não precisa excluir a conexão original. Ao final, terá quatro condições comparáveis com registros reais de chamada e execução. Com essa evidência, fica possível escolher a menor correção: desligar o Tool Search, manter ferramentas essenciais em Always Loaded ou usar uma conexão que tenha passado pelo mesmo teste.

Trate o uso de ferramentas como uma cadeia de cinco camadas

Ver uma ferramenta como ativada na interface confirma apenas o estado da UI. Para haver execução real, cinco camadas precisam funcionar.

Camada	O que precisa ser verdadeiro	Sintoma enganoso
1. Visibilidade e acesso	O usuário atual consegue ver e ler a ferramenta	Funciona para o administrador, mas desaparece silenciosamente para outro usuário
2. Chat, modo e capability	O chat usa Native e tem a ferramenta-alvo ativada; para ferramenta de sistema integrada, Workspace → Models → Capabilities → Builtin Tools e a categoria correspondente também estão ligados	Builtin Tools está desligado ou é tratado incorretamente como chave geral para Workspace, MCP e OpenAPI
3. Payload da requisição	O backend recebe a definição completa ou os auxiliares de ferramenta adiada compatíveis com a versão instalada	Tool Search adia o schema, embora a UI continue mostrando a ferramenta
4. Backend do modelo	O backend retorna a chamada estruturada do alvo correto com argumentos válidos	O modelo afirma em texto que chamou, escolhe outra operação ou envia argumentos errados
5. Execução	Open WebUI, MCP ou o servidor OpenAPI executa a chamada correta e devolve o resultado	A chamada correta existe, mas falha em autenticação, rota, protocolo ou servidor

Diagnostique de cima para baixo. Refazer MCP antes de conferir acesso e a chamada-alvo pode apagar evidências úteis.

Preserve a conexão original e registre a linha de base

Antes de alterar qualquer coisa, registre pelo menos:

• versão do Open WebUI e método de implantação;
• nome da conexão, Model ID exato, nome exibido e provider, gateway, Base URL ou rota reais;
• valor efetivo de Model Settings → Advanced Params → Function Calling;
• para ferramenta integrada, estado de Workspace → Models → Capabilities → Builtin Tools e das categorias relevantes;
• ferramentas ativadas no chat por Integrations → Tools e acesso de leitura do usuário de teste;
• quatro valores efetivos em Settings → Admin → Interface → Chat: Tool Search, Defer Built-in Tools, Deferral Threshold (characters) e Always Loaded Tools;
• nomes completos correspondentes: ENABLE_TOOL_SEARCH, TOOL_SEARCH_DEFER_BUILTIN_TOOLS, TOOL_SEARCH_DEFER_THRESHOLD e TOOL_SEARCH_ALWAYS_LOADED;
• se a falha está em ferramenta de sistema integrada, Workspace Tool, MCP ou OpenAPI;
• um prompt que falhou, horário, exportação/captura do chat e logs de Open WebUI/servidor do mesmo intervalo.

A conexão pode ser desativada pelo toggle sem apagar a configuração. Para comparar, crie outra com nome claro, como control-tool-test; não sobrescreva a de produção.

Separe duas afirmações:

1. O chat normal funciona: prova apenas que uma requisição de texto terminou.
2. Tool calling funciona: exige chamada estruturada do alvo, argumentos válidos, registro de execução e resultado devolvido.

Uma frase como “usei reverse_string” não é prova.

Confirme que o chat está realmente em Native Mode

A documentação atual do Open WebUI apresenta Native como modo padrão e suportado. Legacy permanece como opção não suportada para comportamento antigo.

Confira os três escopos que podem se sobrepor:

1. Model Defaults globais;
2. Advanced Params do modelo escolhido;
3. Chat Controls da conversa atual.

Para o teste, fixe o valor efetivo em Native. Não misture um teste de Legacy com o diagnóstico de Tool Search, porque Tool Search se aplica a Native Mode.

Se estiver faltando uma ferramenta de sistema integrada do Open WebUI, abra Workspace → Models, edite o modelo selecionado e confira Capabilities. Builtin Tools e a categoria necessária devem estar ativados. Essa chave controla apenas a injeção das ferramentas de sistema integradas em Native Mode; não é uma chave geral para o Workspace Tool reverse_string, MCP ou OpenAPI.

Para Workspace, MCP e OpenAPI, confira os controles separados:

• abra Integrations ao lado da caixa de mensagem;
• entre em Tools e ative a ferramenta de diagnóstico ou externa neste chat;
• se ela estiver associada ao modelo, confirme também o acesso de leitura do usuário atual.

Associar uma Workspace Tool ao modelo não ignora o controle de acesso. Sem leitura, o Open WebUI pode omiti-la sem entregá-la ao modelo.

Crie uma ferramenta mínima e somente leitura

Workspace Tools executam Python dentro do ambiente do Open WebUI. Apenas administradores confiáveis devem criar ou importar esse código. Para diagnóstico, use uma função sem acesso a arquivos, rede, banco de dados ou comandos do sistema.

Em Workspace → Tools, crie:

"""
title: Read-only Tool Check
description: Reverses a string for tool-call diagnostics
version: 1.0.0
"""

class Tools:
    async def reverse_string(self, string: str) -> str:
        """
        Inverte o texto informado sem ler ou alterar dados externos.

        :param string: Texto que deve ser invertido exatamente.
        :return: Texto em ordem inversa.
        """
        return string[::-1]

Salve, conceda acesso ao usuário de teste e habilite a ferramenta em Integrations → Tools.

Use sempre o mesmo prompt em um chat novo:

Você deve usar a ferramenta reverse_string na string tool-check-7.
Não inverta por conta própria e não adivinhe.
Depois que a ferramenta responder, mostre somente o resultado dela.

Resultado esperado:

7-kcehc-loot

O texto correto, sozinho, ainda não é PASS. Exija os quatro sinais:

• tool call estruturado para reverse_string;
• argumento contendo tool-check-7;
• registro correspondente de execução no Open WebUI ou no servidor;
• retorno 7-kcehc-loot, usado pela resposta final.

Guarde o chat, os detalhes da chamada e as linhas de log com o mesmo horário. Use um chat novo para cada condição seguinte.

Rode quatro condições controladas

Altere uma variável por vez e faça a mudança na Admin UI existente, não apenas pelos nomes das variáveis de ambiente:

1. Abra Settings → Admin → Interface → Chat.
2. Defina Tool Search, Defer Built-in Tools, Deferral Threshold (characters) e Always Loaded Tools conforme cada condição.
3. Salve, reabra a página e registre os valores realmente exibidos.
4. Abra um chat novo e execute o mesmo prompt fixo.

Os quatro campos correspondem a ENABLE_TOOL_SEARCH, TOOL_SEARCH_DEFER_BUILTIN_TOOLS, TOOL_SEARCH_DEFER_THRESHOLD e TOOL_SEARCH_ALWAYS_LOADED; todos são ConfigVar. Com o padrão ENABLE_PERSISTENT_CONFIG=True, valores já salvos na Admin UI/banco têm prioridade sobre variáveis de ambiente. Portanto, editar .env e reiniciar não garante que a condição tenha mudado. Se o ambiente usa deliberadamente ENABLE_PERSISTENT_CONFIG=False, registre isso: os valores de ambiente prevalecem na inicialização, enquanto mudanças na UI valem apenas na sessão atual e somem após reiniciar.

Condição	Native	Tool Search	Defer Built-in Tools	Threshold	Always Loaded	Objetivo
A	On	Off	Registrar o valor atual; não controla esta Workspace Tool	Não se aplica	Não se aplica	Linha de base com a definição completa de reverse_string
B	On	On	On e registrado; afeta ferramentas integradas, não reverse_string	0	Nome exato visível ao modelo	Testar o caminho Always Loaded
C	On	On	On e registrado	0	Vazio	Forçar o caminho adiado e observar search_tools e a chamada-alvo
D	On	Igual a C	Igual a C	0	Vazio	Qualificar a segunda conexão com A e, se necessário, B; depois repetir C

O threshold 0 é importante. A regra normal só adia definições serializadas maiores que o número configurado. Uma função pequena como reverse_string pode continuar totalmente carregada com o valor padrão; então C não testa o caminho adiado. Restaure os valores de produção ao terminar.

Condição A: valide primeiro o caminho Native básico

Em Settings → Admin → Interface → Chat, desligue Tool Search, salve, reabra a página e confirme o valor efetivo. Depois use um chat novo com o prompt fixo. Reiniciar, por si só, não prova que a configuração mudou.

• A passa: acesso, Native, essa rota do modelo e execução de Workspace Tool funcionam no caso mínimo.
• Não há chamada estruturada do alvo: confira seleção da ferramenta, leitura, Function Calling efetivo e suporte nativo a chamadas estruturadas no backend.
• A chamada existe, mas a execução falha: o modelo chegou à etapa de chamada; verifique argumentos, schema e logs de execução do Open WebUI.

Se A não passa, ainda não diagnostique Tool Search.

Condição B: valide o caminho Always Loaded

Na mesma tela, ligue Tool Search, ligue e registre Defer Built-in Tools, defina Deferral Threshold (characters) como 0 e coloque em Always Loaded Tools o nome exato visto pelo modelo. Salve, reabra e confirme antes de usar um chat novo.

A correspondência de Always Loaded diferencia maiúsculas e aceita nome exato ou glob. Em MCP, o nome visível costuma ser <server ID>_<tool name>. Copie da lista real ou do trace, não do nome interno do método.

• B passa: Tool Search pode estar ativo e a ferramenta continua chamável quando o schema completo permanece na requisição.
• A passa e B falha: confira os valores salvos/reabertos, nome e capitalização, fonte real de configuração e a instância testada.

Condição C: force o caminho adiado

Mantenha Tool Search e Defer Built-in Tools ligados, threshold 0 e esvazie Always Loaded Tools. Salve, reabra para confirmar os valores e execute o mesmo prompt em um chat novo.

Registre separadamente as duas etapas:

• se houve chamada a search_tools;
• se ela devolveu a definição de reverse_string;
• se depois surgiu a chamada estruturada do alvo;
• no Open WebUI v0.12.2 ou posterior, se apareceu call_tool e se tool_name/argumentos JSON apontam para reverse_string e tool-check-7;
• se reverse_string realmente executou e devolveu o valor esperado;
• se o modelo escolheu outra ferramenta, escreveu uma suposta chamada em texto ou não chamou nada.

Se A e B passam, mas C nem produz search_tools, confira valores efetivos da UI, threshold, versão e capacidade do modelo/rota de escolher o auxiliar. Se search_tools funciona e não há chamada-alvo, mantenha abertas as hipóteses de capacidade do modelo, nome/schema visível, rota real do provider, versão e compatibilidade adiada.

O comportamento de backend estrito depende da versão. Desde Open WebUI v0.12.2, a ferramenta adiada é invocada pelo call_tool já declarado, com tool_name e argumentos JSON, permitindo backends que só aceitam ferramentas da lista tools atual. Versões anteriores chamavam diretamente pelo nome adiado, e um backend estrito podia rejeitar. Confira a versão antes de aplicar um Issue antigo; um Issue público é relato de usuário sobre um ambiente e uma família de backend, não regra universal.

Condição D: troque somente a conexão do modelo

O rótulo Native não basta para tornar a segunda conexão um controle válido de compatibilidade adiada. Registre Model ID exato, provider/gateway real, Base URL ou rota e versão do Open WebUI. Com Tool Search desligado, execute primeiro o mesmo baseline A somente leitura e, se necessário, B. Só depois de passar o caminho comum e Always Loaded repita C como D, sem alterar ferramenta, prompt, valores de UI, threshold nem o campo Always Loaded vazio.

• D passa e C falha: a rota original do modelo é o diferencial. Mantenha-a para chat normal e use a rota verificada para ferramentas adiadas.
• A segunda conexão falha A ou B: ela ainda não é um controle válido; corrija ou substitua o baseline.
• A/B passam nas duas, mas C/D falham: mantenha a possibilidade de que ambos os backends ou rotas reais não suportem o fluxo adiado da versão instalada. Dois nomes de modelo podem compartilhar o mesmo provider, gateway ou router estrito. Confira rota e versão e decida conforme search_tools e a chamada-alvo apareçam; não reduza o resultado apenas a configuração, nome ou execução.
• C e D passam: a causa tende a estar na definição visível, operação escolhida, argumentos, permissões ou servidor da ferramenta de produção.

Escolha a correção mínima a partir da evidência

Evidência	Próximo passo
A falha e não há chamada-alvo	Corrigir acesso, ativação no chat, Native ou usar backend com chamadas nativas reais
A e B passam; C não chama search_tools	Verificar valores efetivos da UI, threshold, versão e seleção do auxiliar
search_tools funciona, mas não há chamada-alvo	Revisar capacidade, nome/schema visível, rota real, versão e compatibilidade; fallback mínimo: Always Loaded ou desligar Tool Search
Há chamada-alvo, mas reverse_string não executa	Revisar logs e alvo/argumentos de call_tool
A–C passam, mas a ferramenta real falha	Revisar definição visível, operação, argumentos, Tool Search, rota, acesso e evidência do servidor
Só uma conexão qualificada falha	Mantê-la para texto; usar em ferramentas uma conexão que passe o mesmo A/B/C
Duas conexões qualificadas falham C/D	Manter a hipótese de incompatibilidade dos dois backends ou rota compartilhada e comparar search_tools, alvo, rota e versão

Com poucas ferramentas, desligar Tool Search costuma ser a opção mais simples e confiável. Com muitos schemas grandes, mantenha-o, mas deixe sempre carregadas as ferramentas frequentes e de baixo risco e qualifique cada conexão separadamente.

Depois da linha de base local, examine MCP ou OpenAPI

O sucesso de reverse_string só prova que a rota chama uma Workspace Tool simples de uma string. Não prova que o mesmo modelo escolherá uma ferramenta externa complexa, a operação correta, argumentos válidos ou concluirá um fluxo de várias etapas. A documentação de MCP e OpenAPI preserva explicitamente essas limitações mesmo com a conexão funcionando.

Antes de ir para o servidor, capture a definição de produção como o modelo realmente a vê e a evidência da chamada-alvo:

• Sem chamada-alvo, operação errada ou argumentos inválidos: mantenha as hipóteses de modelo, nome/descrição/schema, Tool Search e rota real.
• A chamada correta é emitida, mas não chega ao servidor ou retorna erro de transporte/autenticação: verifique URL, acesso, autenticação, protocolo, proxy, TLS e servidor.
• O servidor recebe a operação correta, mas rejeita argumentos ou retorna erro de aplicação: compare a chamada com o schema exposto e revise o servidor.

MCP: transporte, acesso e nome visível

A conexão MCP nativa do Open WebUI usa MCP (Streamable HTTP). Um servidor local que só expõe stdio precisa de bridge/proxy apropriado.

Confirme:

• Type é MCP, não OpenAPI;
• a URL Streamable HTTP é acessível do host/contêiner do Open WebUI;
• autenticação é válida para o usuário atual;
• Access Control inclui o usuário de teste;
• definição e nome visíveis seguem <server ID>_<tool name>;
• o modelo escolheu o alvo correto e argumentos válidos;
• a chamada correta chega aos logs MCP;
• o servidor devolve resultado de protocolo, não erro HTTP, de autorização ou de aplicação.

Sem chamada-alvo correta, continue no ramo modelo/schema/Tool Search/rota. Se a chamada existe, mas não chega ao servidor, revise URL, proxy, certificados e rede. Se chega e os argumentos são rejeitados, compare com o schema mostrado ao modelo.

OpenAPI: confirme a descoberta das operações

O Open WebUI descobre operações pela estrutura path-item do OpenAPI 3.x. Verifique métodos HTTP padrão, parâmetros utilizáveis e nomes/descrições estáveis que permitam distinguir a operação correta.

Salve:

• URL e versão da especificação;
• nomes e definições realmente mostrados ao modelo;
• operação escolhida e argumentos estruturados;
• access log e status da resposta;
• body devolvido ao modelo pelo Open WebUI.

Salvar uma conexão não prova execução. Uma falha em /models também não prova incompatibilidade automaticamente: alguns provedores compatíveis não implementam esse endpoint. Informe o Model ID exato e decida com A/B/C e uma chamada real da ferramenta de produção.

Comparação opcional com BetterToken

Preserve a conexão original e adicione outra OpenAI-compatible. A API Base URL do BetterToken é:

https://www.bettertoken.ai/v1

Escolha no catálogo atual um Model ID exato cujo supported_endpoint_types inclua openai e use sua própria API key. Não adivinhe pelo nome exibido. Chat comum funcionando não certifica Tool Search.

Execute A–D nessa conexão também. Aqui, BetterToken é apenas uma rota alternativa de API e uma forma de observar uso de requisições; não é prova de correção do Open WebUI, do modelo ou do Tool Search.

Referências:

• Open WebUI Tools
• Desenvolvimento de Workspace Tools
• Conexões OpenAI-compatible
• Open WebUI MCP
• OpenAPI Tool Servers
• BetterToken Chat Completions
• Catálogo de modelos e protocolos

Salve um registro reproduzível

Open WebUI version:
Deployment:
Connection:
Exact model ID:
Actual provider/gateway route:
Function Calling:
Builtin Tools capability/categories:
Tool Search UI value:
Defer Built-in Tools UI value:
Deferral Threshold UI value:
Always Loaded Tools UI value:
ENABLE_PERSISTENT_CONFIG mode:
ENABLE_TOOL_SEARCH:
TOOL_SEARCH_DEFER_BUILTIN_TOOLS:
TOOL_SEARCH_DEFER_THRESHOLD:
TOOL_SEARCH_ALWAYS_LOADED:
Tool visible name:
Prompt:
search_tools call observed:
target call_tool / structured invocation observed:
reverse_string execution log observed:
Returned value:
Timestamp:

Ele serve como teste de regressão após atualização, troca de modelo ou migração de servidor.

Comece por uma chamada real

Mantenha a conexão original, use Native, desligue Tool Search e execute reverse_string com tool-check-7. Só depois de ver chamada estruturada, execução e 7-kcehc-loot, habilite o adiamento forçado e compare conexões.

Assim você identifica se a menor correção está em acesso, modo, Always Loaded, Tool Search, backend ou servidor externo, sem confiar em uma afirmação escrita pelo modelo.