Open WebUI no llama herramientas: revisa Native Mode, Tool Search y compatibilidad

La herramienta aparece activada y el modelo afirma que va a usarla, pero no existe ninguna llamada real en el registro. Ese síntoma no basta para culpar al modelo, a Open WebUI o al servidor MCP/OpenAPI. La forma más rápida de aislar el fallo es crear una línea base con un reverse_string sin efectos secundarios y, después, cambiar Native Mode, Tool Search y la conexión del modelo de uno en uno.

No hace falta eliminar la conexión original. Al terminar tendrás cuatro pruebas comparables con llamadas y ejecuciones verificables, y podrás escoger el cambio mínimo: desactivar Tool Search, mantener ciertas herramientas en Always Loaded o usar para tareas con herramientas una conexión que haya superado el mismo control.

Divide el recorrido en cinco capas

Que la interfaz muestre una herramienta como activada solo confirma el estado de la interfaz. Para que haya una ejecución real deben funcionar cinco capas.

Capa	Qué debe cumplirse	Síntoma engañoso
1. Visibilidad y acceso	El usuario actual puede ver y leer la herramienta	Funciona para un administrador, pero desaparece para otro usuario
2. Chat, modo y capacidad	El chat usa Native y tiene activada la herramienta; si es una herramienta integrada del sistema, también están activos Workspace → Models → Capabilities → Builtin Tools y la categoría correspondiente	Builtin Tools está desactivado o se interpreta erróneamente como interruptor general de Workspace, MCP y OpenAPI
3. Carga de la solicitud	El backend recibe la definición completa o los auxiliares de herramientas diferidas compatibles con la versión instalada	Tool Search aplaza el schema aunque la interfaz siga mostrando la herramienta
4. Backend del modelo	El backend devuelve la llamada estructurada del objetivo correcto con argumentos válidos	El modelo afirma en texto que llamó la herramienta, elige otra operación o envía argumentos incorrectos
5. Ejecución	Open WebUI, MCP o el servidor OpenAPI ejecuta la llamada correcta y devuelve el resultado	La llamada correcta existe, pero falla la autenticación, la ruta, el protocolo o el servidor

Diagnostica de arriba abajo. Reconstruir MCP antes de comprobar acceso y evidencia de la llamada objetivo puede destruir información útil.

Conserva la configuración original y registra la línea base

Antes de cambiar nada, guarda como mínimo:

• versión de Open WebUI y método de despliegue;
• nombre de conexión, Model ID exacto, nombre mostrado y provider, gateway, Base URL o ruta reales;
• valor efectivo de Model Settings → Advanced Params → Function Calling;
• para una herramienta integrada, estado de Workspace → Models → Capabilities → Builtin Tools y de las categorías relevantes;
• herramientas activadas en este chat mediante Integrations → Tools y permiso de lectura del usuario de prueba;
• cuatro valores efectivos mostrados en Settings → Admin → Interface → Chat: Tool Search, Defer Built-in Tools, Deferral Threshold (characters) y Always Loaded Tools;
• sus nombres completos de configuración: ENABLE_TOOL_SEARCH, TOOL_SEARCH_DEFER_BUILTIN_TOOLS, TOOL_SEARCH_DEFER_THRESHOLD y TOOL_SEARCH_ALWAYS_LOADED;
• si el fallo afecta a una herramienta integrada, Workspace Tool, MCP u OpenAPI;
• un prompt fallido, su hora, exportación o captura del chat y logs de Open WebUI/servidor del mismo intervalo.

Puedes desactivar una conexión con su interruptor sin borrar la configuración. Para comparar, crea otra conexión con un nombre como control-tool-test; no sobrescribas la conexión de producción.

Separa dos afirmaciones:

1. El chat normal funciona: solo demuestra que terminó una petición de texto.
2. La llamada de herramientas funciona: exige la llamada estructurada objetivo, argumentos válidos, registro de ejecución y resultado devuelto.

Una frase como «he usado reverse_string» no es una prueba.

Confirma que el chat usa Native Mode

La documentación actual de Open WebUI presenta Native como modo predeterminado y compatible. Legacy se conserva como opción no compatible para comportamiento antiguo.

Comprueba los tres ámbitos que pueden sobrescribirse:

1. Model Defaults globales;
2. Advanced Params del modelo seleccionado;
3. Chat Controls de la conversación actual.

Para la prueba fija el valor efectivo en Native. No mezcles una prueba de Legacy con el diagnóstico de Tool Search, porque Tool Search se aplica a Native Mode.

Si falta una herramienta integrada del sistema de Open WebUI, abre Workspace → Models, edita el modelo seleccionado y revisa Capabilities. Deben estar activados Builtin Tools y la categoría necesaria. Ese interruptor controla la inyección de herramientas integradas en Native Mode; no es un interruptor general para el Workspace Tool reverse_string, MCP u OpenAPI.

Para Workspace, MCP y OpenAPI comprueba sus controles independientes:

• abre Integrations junto al cuadro de mensaje;
• entra en Tools y activa la herramienta de diagnóstico o externa para este chat;
• si está asociada al modelo, verifica también que el usuario actual tenga permiso de lectura.

Asociar una Workspace Tool al modelo no evita el control de acceso. Sin permiso de lectura, Open WebUI puede omitirla sin entregarla al modelo.

Crea una herramienta mínima y de solo lectura

Workspace Tools ejecuta Python dentro del servidor de Open WebUI. Solo un administrador de confianza debe crear o importar código. Para el diagnóstico, usa una función que no acceda a archivos, red, bases de datos ni comandos del sistema.

En Workspace → Tools, crea:

"""
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:
        """
        Invierte el texto recibido sin leer ni modificar datos externos.

        :param string: Texto que debe invertirse exactamente.
        :return: Texto en orden inverso.
        """
        return string[::-1]

Guárdala, concede acceso al usuario de prueba y actívala desde Integrations → Tools.

En un chat nuevo, usa siempre este prompt:

Debes usar la herramienta reverse_string con la cadena tool-check-7.
No la inviertas por tu cuenta ni adivines.
Cuando la herramienta responda, muestra únicamente su resultado.

Resultado esperado:

7-kcehc-loot

Obtener el mismo texto no basta. Considera PASS solo si ves las cuatro pruebas:

• tool call estructurado a reverse_string;
• argumento tool-check-7;
• entrada de ejecución correspondiente en Open WebUI o en el servidor;
• retorno 7-kcehc-loot, usado por la respuesta final.

Guarda el chat, los detalles de la llamada y las líneas de log con la misma hora. Ejecuta cada condición posterior en un chat nuevo.

Ejecuta cuatro condiciones controladas

Cambia una sola variable cada vez y hazlo en la interfaz administrativa existente, no usando únicamente los nombres de variables de entorno:

1. Abre Settings → Admin → Interface → Chat.
2. Configura Tool Search, Defer Built-in Tools, Deferral Threshold (characters) y Always Loaded Tools según cada condición.
3. Guarda, vuelve a abrir la página y registra los valores que realmente muestra.
4. Inicia un chat nuevo y usa el mismo prompt fijo.

Los cuatro campos corresponden a ENABLE_TOOL_SEARCH, TOOL_SEARCH_DEFER_BUILTIN_TOOLS, TOOL_SEARCH_DEFER_THRESHOLD y TOOL_SEARCH_ALWAYS_LOADED; todos son ConfigVar. Con el valor predeterminado ENABLE_PERSISTENT_CONFIG=True, lo guardado en Admin UI/base de datos tiene prioridad sobre las variables de entorno. Por tanto, editar .env y reiniciar no garantiza que haya cambiado la condición. Si el despliegue usa deliberadamente ENABLE_PERSISTENT_CONFIG=False, regístralo: los valores de entorno mandan al arrancar y los cambios de UI solo duran durante la sesión actual y se pierden al reiniciar.

Condición	Native	Tool Search	Defer Built-in Tools	Umbral	Always Loaded	Objetivo
A	Sí	No	Registrar el valor; no controla esta Workspace Tool	No aplica	No aplica	Línea base con la definición completa de reverse_string
B	Sí	Sí	Sí y registrado; afecta a herramientas integradas, no a reverse_string	0	Nombre exacto visible para el modelo	Probar la ruta Always Loaded
C	Sí	Sí	Sí y registrado	0	Vacío	Forzar la ruta diferida y observar search_tools y la llamada objetivo
D	Sí	Igual que C	Igual que C	0	Vacío	Calificar antes la segunda conexión con A y, si hace falta, B; después repetir C

El umbral 0 es importante. La regla normal solo difiere definiciones serializadas cuya longitud supera el número configurado. Una función pequeña como reverse_string puede quedar cargada con el umbral predeterminado; entonces C no probaría la ruta diferida. Restaura los valores de producción al terminar.

Condición A: demuestra primero la ruta Native básica

En Settings → Admin → Interface → Chat, desactiva Tool Search, guarda, vuelve a abrir la página y comprueba el valor efectivo. Después usa un chat nuevo con el prompt fijo. Un reinicio por sí solo no demuestra que la configuración haya cambiado.

• A pasa: acceso, Native, esa ruta de modelo y ejecución de Workspace Tool funcionan en el caso mínimo.
• No hay llamada estructurada objetivo: revisa selección de herramienta, permiso de lectura, Function Calling efectivo y soporte de llamadas estructuradas nativas del backend.
• Hay llamada, pero falla la ejecución: el modelo llegó a la etapa de llamada; revisa argumentos, schema y logs de ejecución de Open WebUI.

Si A no pasa, todavía no diagnostiques Tool Search.

Condición B: comprueba Always Loaded

En la misma interfaz, activa Tool Search, activa y registra Defer Built-in Tools, establece Deferral Threshold (characters) en 0 y añade a Always Loaded Tools el nombre exacto que ve el modelo. Guarda, vuelve a abrir y verifica antes de usar un chat nuevo.

La coincidencia de Always Loaded distingue mayúsculas y acepta nombre exacto o glob. En MCP, el nombre visible suele ser <server ID>_<tool name>. Cópialo de la lista real o del trace, no del nombre interno del método.

• B pasa: Tool Search puede estar activo y la herramienta sigue funcionando cuando su schema completo permanece en la solicitud.
• A pasa y B falla: comprueba los valores guardados y releídos, nombre y mayúsculas, origen real de la configuración y la instancia probada.

Condición C: fuerza la ruta aplazada

Mantén Tool Search y Defer Built-in Tools activos, el umbral en 0 y vacía Always Loaded Tools. Guarda, vuelve a comprobar los valores y ejecuta el mismo prompt en un chat nuevo.

Registra por separado las dos etapas:

• si apareció una llamada a search_tools;
• si devolvió la definición de reverse_string;
• si después apareció la llamada estructurada objetivo;
• en Open WebUI v0.12.2 o posterior, si apareció call_tool y sus tool_name/argumentos JSON apuntan a reverse_string y tool-check-7;
• si reverse_string se ejecutó realmente y devolvió el valor esperado;
• si el modelo eligió otra herramienta, escribió una supuesta llamada en texto o no llamó nada.

Si A y B pasan pero C ni siquiera produce search_tools, revisa los valores efectivos de UI, el umbral, la versión y si el modelo/ruta selecciona el auxiliar de Tool Search. Si search_tools funciona pero no aparece la llamada objetivo, mantén abiertas las ramas de capacidad del modelo, nombre/schema visible, ruta real del provider, versión y compatibilidad diferida.

La interpretación de un backend estricto depende de la versión. Desde Open WebUI v0.12.2, las herramientas diferidas se invocan mediante el call_tool ya declarado, con tool_name y argumentos JSON, lo que permite trabajar con backends que solo aceptan herramientas presentes en la lista tools. Versiones anteriores llamaban directamente por el nombre diferido y un backend estricto podía rechazarlo. Comprueba la versión antes de aplicar un Issue antiguo; un Issue público es un informe de usuario sobre un despliegue y una familia de backend, no una regla universal.

Condición D: cambia únicamente la conexión

La etiqueta Native no basta para considerar la segunda conexión un control válido de compatibilidad diferida. Registra su Model ID exacto, provider/gateway real, Base URL o ruta y versión de Open WebUI. Con Tool Search desactivado, ejecuta primero la misma línea base de solo lectura A y, si hace falta, B. Solo después de pasar la ruta ordinaria y Always Loaded, repite C como D sin cambiar herramienta, prompt, valores de UI, umbral ni el campo Always Loaded vacío.

• D pasa y C falla: la ruta original del modelo es la diferencia. Consérvala para chat normal si sirve y usa la ruta verificada para herramientas diferidas.
• La segunda conexión falla A o B: todavía no es un control válido; corrige o sustituye esa línea base.
• A/B pasan en ambas, pero C/D fallan: conserva la posibilidad de que ambos backends o rutas reales no admitan el flujo diferido de la versión instalada. Dos nombres de modelo distintos pueden compartir el mismo provider, gateway o router estricto. Comprueba ruta y versión, y decide según aparezcan search_tools y la llamada objetivo; no lo reduzcas únicamente a configuración, nombre o ejecución.
• C y D pasan: el problema apunta más a la definición visible, elección de operación, argumentos, permisos o servidor de la herramienta de producción.

Elige el cambio mínimo

Evidencia	Siguiente paso
A falla y no hay llamada objetivo	Corregir acceso, activación en el chat, Native o usar un backend con llamadas nativas reales
A y B pasan; C no llama search_tools	Verificar valores efectivos de UI, umbral, versión instalada y selección del auxiliar
search_tools funciona, pero no hay llamada objetivo	Revisar capacidad, nombre/schema visible, ruta real, versión y compatibilidad; fallback mínimo: Always Loaded o desactivar Tool Search
Hay llamada objetivo, pero reverse_string no se ejecuta	Revisar logs de ejecución y objetivo/argumentos de call_tool
A–C pasan, pero falla la herramienta real	Revisar definición visible, operación elegida, argumentos, tratamiento de Tool Search, ruta, acceso y evidencia del servidor
Solo falla una conexión ya calificada	Conservarla para texto; usar para herramientas una conexión que pase el mismo A/B/C
Ambas conexiones calificadas fallan C/D	Mantener la rama de incompatibilidad de ambos backends o ruta compartida y comparar search_tools, llamada objetivo, ruta y versión

Con pocas herramientas, desactivar Tool Search suele ser la opción más sencilla y fiable. Con muchos schemas grandes, mantenlo, pero carga siempre las herramientas frecuentes y de bajo riesgo, y califica cada conexión por separado.

Si el test local pasa, baja al nivel MCP/OpenAPI

Que reverse_string funcione solo demuestra que esa ruta puede usar una Workspace Tool sencilla con un único string. No demuestra que el mismo modelo elija una herramienta externa compleja, la operación correcta, argumentos válidos o complete un flujo de varios pasos. La documentación de MCP y OpenAPI mantiene expresamente esas limitaciones incluso con una conexión funcional.

Antes de pasar al servidor, captura la definición de producción tal como la ve el modelo y la evidencia real de la llamada objetivo:

• No hay llamada objetivo, se elige otra operación o los argumentos son inválidos: conserva las ramas de modelo, nombre/descripción/schema, Tool Search y ruta real.
• Se emite la llamada correcta, pero no llega al servidor o devuelve error de transporte/autenticación: revisa URL, acceso, autenticación, protocolo, proxy, TLS y servidor.
• El servidor recibe la operación correcta, pero rechaza argumentos o devuelve error de aplicación: compara la llamada con el schema expuesto y revisa el servidor.

MCP: transporte, acceso y nombre visible

La conexión MCP nativa de Open WebUI usa MCP (Streamable HTTP). Un servidor local que solo expone stdio necesita un bridge o proxy adecuado.

Comprueba:

• Type es MCP y no OpenAPI;
• la URL Streamable HTTP es accesible desde el host o contenedor de Open WebUI;
• la autenticación es válida para el usuario actual;
• Access Control incluye al usuario de prueba;
• la definición y el nombre visibles siguen <server ID>_<tool name>;
• el modelo eligió el objetivo correcto con argumentos válidos;
• la llamada correcta llega a los logs del servidor MCP;
• el servidor devuelve resultado de protocolo y no error HTTP, de autorización o de aplicación.

Sin una llamada objetivo correcta, permanece en modelo/schema/Tool Search/ruta. Si la llamada correcta existe pero no llega al servidor, revisa URL, proxy, certificados y red. Si llega y se rechazan los argumentos, compáralos con el schema mostrado al modelo.

OpenAPI: verifica el descubrimiento de operaciones

Open WebUI descubre operaciones mediante la estructura path-item de OpenAPI 3.x. Comprueba métodos HTTP estándar, parámetros utilizables y nombres/descripciones estables que permitan distinguir la operación correcta.

Guarda:

• URL y versión de la especificación;
• nombres y definiciones que Open WebUI mostró realmente al modelo;
• operación seleccionada y argumentos estructurados;
• access log y estado de respuesta;
• cuerpo que Open WebUI devolvió al modelo.

Guardar una conexión no prueba la ejecución. Un fallo de /models tampoco demuestra automáticamente incompatibilidad: algunos proveedores compatibles no implementan ese endpoint. Introduce el Model ID exacto y decide con A/B/C y una llamada real de la herramienta de producción.

Opción de comparación con BetterToken

Conserva la conexión original y añade otra OpenAI-compatible. La API Base URL de BetterToken es:

https://www.bettertoken.ai/v1

Selecciona del catálogo actual un Model ID exacto cuyo supported_endpoint_types incluya openai, y usa tu propia API key. No adivines el ID por el nombre visible. Un chat normal correcto no certifica Tool Search.

Ejecuta A–D también en esa conexión. BetterToken actúa aquí como ruta API alternativa y fuente de observación de uso, no como prueba de que Open WebUI, un modelo o Tool Search estén corregidos.

Referencias:

• Open WebUI Tools
• Desarrollo de Workspace Tools
• Conexiones OpenAI-compatible
• Open WebUI MCP
• OpenAPI Tool Servers
• BetterToken Chat Completions
• Catálogo de modelos y protocolos

Guarda una ficha reproducible

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:

Úsala como prueba de regresión después de actualizar Open WebUI, cambiar el modelo o migrar un servidor.

Empieza por una llamada real

Mantén la conexión original, usa Native, desactiva Tool Search y ejecuta reverse_string con tool-check-7. Solo cuando veas llamada estructurada, ejecución y 7-kcehc-loot, activa el aplazamiento forzado y compara conexiones.

Así sabrás si el arreglo mínimo está en permisos, modo, Always Loaded, Tool Search, backend o servidor externo, sin fiarte de una afirmación escrita por el modelo.