Open WebUI ruft Tools nicht auf: Native Mode, Tool Search und Modellkompatibilität prüfen

Das Tool ist aktiviert und das Modell kündigt seine Nutzung an, doch es erscheint kein echter tool call. Dieses Symptom allein zeigt nicht, ob das Modell, Open WebUI oder der MCP/OpenAPI-Server verantwortlich ist. Am schnellsten grenzt du die Ursache ein, indem du zuerst mit einem nebenwirkungsfreien reverse_string eine Basislinie schaffst und danach Native Mode, Tool Search und die Modellverbindung einzeln veränderst.

Die ursprüngliche Verbindung bleibt dabei erhalten. Am Ende hast du vier vergleichbare Bedingungen mit tatsächlichen Aufruf- und Ausführungsnachweisen. Damit kannst du die kleinste Korrektur wählen: Tool Search ausschalten, wichtige Tools in Always Loaded aufnehmen oder Tool-Workflows über eine Verbindung ausführen, die denselben Test bestanden hat.

Den Ablauf in fünf Ebenen zerlegen

Ein aktiviertes Tool in der Oberfläche bestätigt nur den UI-Status. Für eine echte Ausführung müssen fünf Ebenen funktionieren.

Ebene	Was stimmen muss	Irreführendes Symptom
1. Sichtbarkeit und Zugriff	Der aktuelle Benutzer kann das Tool sehen und lesen	Beim Administrator funktioniert es, für einen anderen Benutzer verschwindet es still
2. Chat, Modus und Capability	Der Chat nutzt Native und das Ziel-Tool ist aktiv; bei einem integrierten System-Tool sind außerdem Workspace → Models → Capabilities → Builtin Tools und die passende Kategorie eingeschaltet	Builtin Tools ist aus oder wird fälschlich als gemeinsamer Hauptschalter für Workspace, MCP und OpenAPI verstanden
3. Request-Payload	Das Backend erhält die vollständige Definition oder die von der installierten Version unterstützten Deferred-Tool-Helper	Tool Search verschiebt das Schema, obwohl die UI das Tool weiterhin als aktiv zeigt
4. Modell-Backend	Das Backend liefert den strukturierten Call für das richtige Ziel mit gültigen Argumenten	Das Modell behauptet im Text einen Call, wählt eine andere Operation oder sendet falsche Argumente
5. Ausführung	Open WebUI, MCP oder der OpenAPI-Server führt den richtigen Call aus und liefert das Ergebnis	Der richtige Call existiert, scheitert aber an Authentifizierung, Routing, Protokoll oder Server

Diagnostizieren Sie von oben nach unten. MCP neu aufzubauen, bevor Zugriff und tatsächlicher Ziel-Call geprüft sind, kann nützliche Belege zerstören.

Ausgangszustand sichern

Notieren Sie vor Änderungen mindestens:

• Open-WebUI-Version und Deployment-Methode;
• Connection-Name, exakte Model ID, angezeigten Namen sowie tatsächlichen Provider, Gateway, Base URL oder Route;
• den wirksamen Wert von Model Settings → Advanced Params → Function Calling;
• bei einem integrierten System-Tool den Status von Workspace → Models → Capabilities → Builtin Tools und der relevanten Kategorien;
• die im Chat über Integrations → Tools aktivierten Tools und die Leseberechtigung des Testbenutzers;
• die vier tatsächlich angezeigten Werte unter Settings → Admin → Interface → Chat: Tool Search, Defer Built-in Tools, Deferral Threshold (characters) und Always Loaded Tools;
• die vollständigen Konfigurationsnamen ENABLE_TOOL_SEARCH, TOOL_SEARCH_DEFER_BUILTIN_TOOLS, TOOL_SEARCH_DEFER_THRESHOLD und TOOL_SEARCH_ALWAYS_LOADED;
• ob ein integriertes System-Tool, Workspace Tool, MCP oder OpenAPI betroffen ist;
• einen fehlgeschlagenen Prompt, Zeitstempel, Chat-Export/Screenshot und Logs von Open WebUI und Tool-Server aus demselben Zeitraum.

Eine Connection lässt sich per Toggle deaktivieren, ohne ihre Konfiguration zu löschen. Legen Sie zum Vergleich eine getrennte Connection wie control-tool-test an und überschreiben Sie die Produktionsverbindung nicht.

Trennen Sie zwei Aussagen:

1. Normaler Chat funktioniert: Nur ein Text-Request wurde abgeschlossen.
2. Tool Calling funktioniert: Ziel-Call, gültige Argumente, Ausführungsnachweis und Rückgabewert müssen vorliegen.

Ein Satz wie „Ich habe reverse_string verwendet“ ist kein Beleg.

Sicherstellen, dass der Chat Native Mode verwendet

Die aktuelle Open-WebUI-Dokumentation beschreibt Native als Standard und unterstützten Tool-Calling-Modus. Legacy bleibt als nicht unterstützte Option für altes Verhalten erhalten.

Prüfen Sie die drei Ebenen, die sich überschreiben können:

1. globale Model Defaults;
2. Advanced Params des gewählten Modells;
3. Chat Controls des aktuellen Chats.

Setzen Sie für den Test den wirksamen Wert auf Native. Vermischen Sie keinen Legacy-Test mit der Tool-Search-Diagnose, denn Tool Search gilt für Native Mode.

Fehlt ein integriertes System-Tool von Open WebUI, öffnen Sie Workspace → Models, bearbeiten Sie das ausgewählte Modell und prüfen Sie Capabilities. Builtin Tools und die benötigte Kategorie müssen aktiv sein. Dieser Schalter steuert nur die Injection integrierter System-Tools in Native Mode; er ist kein Hauptschalter für das Workspace Tool reverse_string, MCP oder OpenAPI.

Für Workspace, MCP und OpenAPI prüfen Sie die getrennten Controls:

• Integrations neben dem Eingabefeld öffnen;
• unter Tools das Diagnose- oder externe Tool für diesen Chat aktivieren;
• auch bei Model-Attachment die Leseberechtigung des aktuellen Benutzers prüfen.

Ein Workspace Tool am Modell zu befestigen umgeht die Zugriffskontrolle nicht. Ohne Leserecht kann Open WebUI es auslassen, bevor das Modell es erhält.

Ein minimales read-only Tool erstellen

Workspace Tools führen Python innerhalb der Open-WebUI-Umgebung aus. Nur vertrauenswürdige Administratoren sollten solchen Code erstellen oder importieren. Für die Diagnose verwendest du eine Funktion ohne Datei-, Netzwerk-, Datenbank- oder Systemzugriff.

Erstelle unter Workspace → Tools:

"""
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:
        """
        Kehrt den übergebenen Text um, ohne externe Daten zu lesen oder zu ändern.

        :param string: Text, der exakt umgekehrt werden soll.
        :return: Text in umgekehrter Reihenfolge.
        """
        return string[::-1]

Speichere das Tool, gib dem Testbenutzer Zugriff und aktiviere es in Integrations → Tools.

Verwende in jedem neuen Chat denselben Prompt:

Du musst das Tool reverse_string auf die Zeichenfolge tool-check-7 anwenden.
Kehre sie nicht selbst um und rate nicht.
Gib nach der Tool-Antwort ausschließlich das Tool-Ergebnis aus.

Erwartetes Ergebnis:

7-kcehc-loot

Der richtige Text allein ist noch kein PASS. Verlange alle vier Signale:

• strukturierter reverse_string call im trace oder in der Tool-Aktivität;
• Argument tool-check-7;
• passender Ausführungseintrag in Open WebUI oder im Server-Log;
• Rückgabe 7-kcehc-loot, die in der finalen Antwort verwendet wird.

Speichere Chat, Aufrufdetails und Logzeilen mit derselben Uhrzeit. Jede spätere Bedingung läuft in einem neuen Chat mit identischem Tool und Prompt.

Vier kontrollierte Bedingungen ausführen

Ändern Sie jeweils nur eine Variable und nutzen Sie die vorhandene Admin UI statt lediglich Environment-Variablennamen:

1. Settings → Admin → Interface → Chat öffnen.
2. Für jede Bedingung Tool Search, Defer Built-in Tools, Deferral Threshold (characters) und Always Loaded Tools setzen.
3. Speichern, die Seite erneut öffnen und die tatsächlich angezeigten Werte protokollieren.
4. Einen neuen Chat mit demselben festen Prompt starten.

Die vier Felder entsprechen ENABLE_TOOL_SEARCH, TOOL_SEARCH_DEFER_BUILTIN_TOOLS, TOOL_SEARCH_DEFER_THRESHOLD und TOOL_SEARCH_ALWAYS_LOADED; alle sind ConfigVar. Beim Standard ENABLE_PERSISTENT_CONFIG=True haben bereits in Admin UI/Datenbank gespeicherte Werte Vorrang vor Environment-Variablen. Eine Änderung an .env plus Neustart garantiert daher nicht, dass sich die Testbedingung geändert hat. Nutzt das Deployment bewusst ENABLE_PERSISTENT_CONFIG=False, dokumentieren Sie das: Beim Start sind die Environment-Werte maßgeblich, UI-Änderungen gelten nur für die laufende Sitzung und gehen beim Neustart verloren.

Bedingung	Native	Tool Search	Defer Built-in Tools	Threshold	Always Loaded	Zweck
A	Ein	Aus	Aktuellen Wert notieren; steuert dieses Workspace Tool nicht	Entfällt	Entfällt	Baseline mit vollständiger reverse_string-Definition
B	Ein	Ein	Ein und protokolliert; betrifft Built-in Tools, nicht reverse_string	0	Exakter model-visible Name	Always-Loaded-Pfad prüfen
C	Ein	Ein	Ein und protokolliert	0	Leer	Deferred-Pfad erzwingen und search_tools plus Ziel-Call beobachten
D	Ein	Wie C	Wie C	0	Leer	Zweite Connection zuerst mit A, falls nötig B, qualifizieren und dann C wiederholen

Threshold 0 ist wichtig. Die normale Regel verschiebt nur serialisierte Definitionen, die länger als der konfigurierte Wert sind. Ein kleines reverse_string kann beim Standard vollständig geladen bleiben; dann prüft C nicht den Deferred-Pfad. Stellen Sie danach die Produktionswerte wieder her.

Bedingung A: zuerst den grundlegenden Native-Weg beweisen

Unter Settings → Admin → Interface → Chat Tool Search ausschalten, speichern, die Seite erneut öffnen und den wirksamen Wert prüfen. Danach einen neuen Chat mit dem festen Prompt verwenden. Ein Neustart allein beweist keine geänderte Einstellung.

• A besteht: Zugriff, Native, diese Modellroute und Workspace-Ausführung funktionieren im Minimalfall.
• Kein strukturierter Ziel-Call: Tool-Auswahl im Chat, Leserecht, wirksames Function Calling und native Structured-Call-Unterstützung des Backends prüfen.
• Call vorhanden, Ausführung fehlerhaft: Das Modell hat die Call-Stufe erreicht; Argumente, Schema und Open-WebUI-Ausführungslogs prüfen.

Solange A nicht besteht, ist eine Tool-Search-Diagnose verfrüht.

Bedingung B: Always Loaded prüfen

In derselben UI Tool Search einschalten, Defer Built-in Tools einschalten und protokollieren, Deferral Threshold (characters) auf 0 setzen und unter Always Loaded Tools den exakten model-visible Namen eintragen. Speichern, erneut öffnen, prüfen und erst dann einen neuen Chat verwenden.

Always-Loaded-Matching ist case-sensitive und akzeptiert exakte Namen oder Globs. Bei MCP lautet der model-visible Name meist <server ID>_<tool name>. Kopieren Sie ihn aus der realen Tool-Liste oder dem Trace statt aus dem internen Methodennamen.

• B besteht: Tool Search kann aktiv bleiben und das Tool funktioniert, wenn sein vollständiges Schema im Request bleibt.
• A besteht, B nicht: Gespeicherte/erneut gelesene UI-Werte, Name und Groß-/Kleinschreibung, echte Konfigurationsquelle und getestete Instanz prüfen.

Bedingung C: den verzögerten Weg erzwingen

Tool Search und Defer Built-in Tools eingeschaltet lassen, Threshold 0, Always Loaded Tools leeren, speichern und die wirksamen Werte erneut prüfen. Danach denselben Prompt in einem neuen Chat ausführen.

Die beiden Stufen getrennt protokollieren:

• Gab es einen search_tools-Call?
• Wurde die reverse_string-Definition zurückgegeben?
• Erschien danach der strukturierte Ziel-Call?
• Bei Open WebUI v0.12.2 oder neuer: Erschien call_tool, und zeigen tool_name/JSON-Argumente auf reverse_string und tool-check-7?
• Wurde reverse_string tatsächlich ausgeführt und das erwartete Ergebnis geliefert?
• Wählte das Modell ein anderes Tool, schrieb einen vermeintlichen Call als Text oder rief gar nichts auf?

Bestehen A/B, aber C erzeugt nicht einmal search_tools, prüfen Sie wirksame UI-Werte, Threshold, Version und ob Modell/Route den Helper wählen kann. Funktioniert search_tools, aber kein Ziel-Call folgt, bleiben Modellfähigkeit, sichtbarer Name/Schema, reale Provider-Route, Version und Deferred-Kompatibilität offen.

Das Verhalten strenger Backends ist versionsabhängig. Seit Open WebUI v0.12.2 wird ein Deferred Tool über das bereits deklarierte call_tool mit tool_name und JSON-Argumenten aufgerufen, was Backends unterstützt, die nur Tools aus der aktuellen tools-Liste zulassen. Ältere Versionen riefen den Deferred-Namen direkt auf und konnten abgewiesen werden. Prüfen Sie die installierte Version, bevor Sie ein altes Issue anwenden. Ein öffentliches Issue bleibt ein User-Report zu einem Deployment und einer Backend-Familie, keine allgemeine Regel.

Bedingung D: nur die Modellverbindung wechseln

Das Label Native qualifiziert die zweite Connection nicht automatisch als Deferred-Kompatibilitätskontrolle. Notieren Sie exakte Model ID, tatsächlichen Provider/Gateway, Base URL oder Route und Open-WebUI-Version. Führen Sie bei ausgeschaltetem Tool Search zuerst dieselbe read-only Baseline A aus, bei Bedarf B. Erst wenn der normale und Always-Loaded-Pfad bestehen, wiederholen Sie C als D, ohne Tool, Prompt, UI-Werte, Threshold oder das leere Always-Loaded-Feld zu ändern.

• D besteht, C nicht: Die ursprüngliche Modellroute ist der Unterschied. Für normalen Chat kann sie bleiben; Deferred Tools laufen über die geprüfte Route.
• Die zweite Connection scheitert an A oder B: Sie ist noch keine valide Kontrolle; Baseline reparieren oder ersetzen.
• A/B bestehen auf beiden, C/D nicht: Halten Sie die Möglichkeit offen, dass beide realen Backends/Routen den Deferred Flow der installierten Version nicht unterstützen. Verschiedene Modellnamen können denselben strengen Provider, Gateway oder Router teilen. Reale Route und Version prüfen und anhand von search_tools und Ziel-Call weiter verzweigen; nicht nur Konfiguration, Name oder Ausführung verantwortlich machen.
• C und D bestehen: Sichtbare Definition, Operationswahl, Argumente, Rechte oder Server des Produktionstools sind wahrscheinlicher.

Die kleinste Korrektur aus den Ergebnissen ableiten

Beleg	Nächster Schritt
A scheitert ohne Ziel-Call	Zugriff, Chat-Toggle, Native oder Backend mit echten nativen Calls korrigieren
A/B bestehen, C ruft search_tools nicht auf	Wirksame UI-Werte, Threshold, Version und Helper-Auswahl prüfen
search_tools besteht, Ziel-Call fehlt	Fähigkeit, sichtbaren Namen/Schema, reale Route, Version und Kompatibilität prüfen; minimaler Fallback: Always Loaded oder Tool Search aus
Ziel-Call vorhanden, reverse_string wird nicht ausgeführt	Open-WebUI-Logs sowie Ziel/Argumente von call_tool prüfen
A–C bestehen, Produktionstool scheitert	Sichtbare Definition, Operation, Argumente, Tool-Search-Behandlung, Route, Zugriff und Serverbelege prüfen
Nur eine qualifizierte Connection scheitert	Für Text behalten; für Tools eine Connection mit denselben bestandenen A/B/C verwenden
Beide qualifizierten Connections scheitern C/D	Inkompatibilität beider Backends oder einer gemeinsamen Route offenhalten und search_tools, Ziel-Call, Route und Version vergleichen

Bei wenigen Tools ist das Abschalten von Tool Search meist am einfachsten und zuverlässigsten. Bei vielen großen Schemas Tool Search beibehalten, häufige risikoarme Tools Always Loaded setzen und jede Connection separat qualifizieren.

Nach der lokalen Basislinie MCP oder OpenAPI prüfen

Ein erfolgreicher reverse_string-Call beweist nur, dass diese Route ein einfaches Workspace Tool mit einem String aufrufen kann. Er beweist nicht, dass dasselbe Modell ein komplexes externes Tool, die richtige Operation, gültige Argumente oder einen mehrstufigen Ablauf bewältigt. Die MCP- und OpenAPI-Dokumentation hält diese Modellgrenzen auch bei funktionierender Verbindung ausdrücklich fest.

Vor der Serverdiagnose die Produktionstool-Definition so erfassen, wie das Modell sie wirklich sieht, und die tatsächlichen Ziel-Call-Belege sichern:

• Kein Ziel-Call, falsche Operation oder ungültige Argumente: Modellfähigkeit, Name/Beschreibung/Schema, Tool Search und reale Modell-/Provider-Route weiter prüfen.
• Richtiger strukturierter Call wird erzeugt, erreicht den Server aber nicht oder liefert Transport/Auth-Fehler: URL, Zugriff, Authentifizierung, Protokoll, Proxy, TLS und Server prüfen.
• Server erhält die richtige Operation, weist aber Argumente ab oder liefert Anwendungsfehler: Call mit exponiertem Schema vergleichen und Serververarbeitung prüfen.

MCP: Transport, Rechte und sichtbarer Name

Die native MCP-Connection von Open WebUI nutzt MCP (Streamable HTTP). Ein lokaler Server mit nur stdio benötigt eine geeignete Bridge/einen Proxy.

Prüfen Sie:

• Type ist MCP, nicht OpenAPI;
• Streamable-HTTP-URL ist vom Open-WebUI-Host/Container erreichbar;
• Authentifizierung ist für den aktuellen Benutzer gültig;
• Access Control enthält den Testbenutzer;
• sichtbare Definition und Name folgen <server ID>_<tool name>;
• Modell wählt das richtige Ziel mit gültigen Argumenten;
• richtiger Call erreicht die MCP-Server-Logs;
• Server liefert Protokollergebnis statt HTTP-, Auth- oder Anwendungsfehler.

Ohne richtigen Ziel-Call im Modell/Schema/Tool-Search/Route-Zweig bleiben. Existiert der Call, erreicht den Server aber nicht, URL, Proxy, Zertifikate und Netzwerk prüfen. Erreicht er den Server und Argumente werden abgewiesen, mit dem sichtbaren Schema vergleichen.

OpenAPI: Operation Discovery bestätigen

Open WebUI entdeckt Operationen über die Path-Item-Struktur von OpenAPI 3.x. Prüfen Sie Standard-HTTP-Methoden, nutzbare Parameter und stabile Namen/Beschreibungen, mit denen das Modell die richtige Operation unterscheiden kann.

Speichern Sie:

• URL und Version der Spezifikation;
• tatsächlich dem Modell gezeigte Tool-Namen und Definitionen;
• gewählte Operation und strukturierte Argumente;
• Server-Access-Log und Response-Status;
• den Body, den Open WebUI an das Modell zurückgab.

Eine gespeicherte Connection beweist keine Ausführung. Auch ein fehlgeschlagenes /models beweist nicht automatisch Inkompatibilität; manche kompatiblen Provider implementieren diesen Endpoint nicht. Exakte Model ID eintragen und anhand von A/B/C plus echtem Produktionstool-Call entscheiden.

Optional eine BetterToken-Vergleichsverbindung anlegen

Behalte die ursprüngliche Verbindung und füge eine OpenAI-compatible Verbindung hinzu. Die BetterToken API Base URL lautet:

https://www.bettertoken.ai/v1

Wähle im aktuellen Katalog eine exakte Model ID, deren supported_endpoint_types openai enthält, und nutze deinen eigenen API key. Leite die ID nicht aus dem Anzeigenamen ab. Ein erfolgreicher normaler Chat zertifiziert Tool Search nicht.

Führe A–D auch über diese Verbindung aus. BetterToken dient hier nur als alternativer Modell-API-Weg und zur Beobachtung der Request-Nutzung; es ist kein Beleg für eine Reparatur von Open WebUI, einem Modell oder Tool Search.

Referenzen:

• Open WebUI Tools
• Workspace-Tool-Entwicklung
• OpenAI-compatible Connections
• Open WebUI MCP
• OpenAPI Tool Servers
• BetterToken Chat Completions
• BetterToken Modell- und Protokollkatalog

Reproduzierbaren Diagnoseeintrag speichern

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:

Dieser Datensatz eignet sich nach Updates, Modellwechseln oder Servermigrationen als Regressionstest.

Mit einem echten Call beginnen

Behalte die Originalverbindung, verwende Native, schalte Tool Search aus und rufe reverse_string mit tool-check-7 auf. Erst wenn strukturierter Call, Ausführungseintrag und 7-kcehc-loot vorhanden sind, aktivierst du erzwungene Verzögerung und vergleichst Verbindungen.

So erkennst du, ob die kleinste Korrektur bei Rechten, Modus, Always Loaded, Tool Search, Backend oder externem Server liegt, statt einer Textbehauptung des Modells zu vertrauen.