Agent-Zero-LiteLLM-Modellfehler: Authentifizierung, Modell-IDs und Endpunkte

Ein LiteLLM-Modellfehler in Agent Zero ist häufiger ein Präfix- oder Rollenproblem als ein Schlüsselproblem, weil Agent Zero den von dir eingegebenen Modellnamen nie sendet. Auf agent0ai/agent-zero main erstellt models.py vor jedem LiteLLM-Aufruf f"{provider}/{model}" — Zeile 385 für Chat, Zeile 800 für Embeddings — und die Provider-Hälfte kommt aus conf/model_providers.yaml, nicht aus der Bezeichnung des Dropdowns.

Zwei Versionsfakten bestimmen, wie der Rest zu verstehen ist. Die neueste Version ist v2.12, veröffentlicht am 9. September 2026, und der alte Pfad frdel/agent-zero verweist jetzt auf agent0ai/agent-zero, sodass ältere Clone-Befehle und Issue-Links auf eine Weiterleitung treffen. Außerdem legt requirements.txt litellm==1.88.1 fest, kommentiert mit # CVE-2026-42271 fix: patched floor is 1.83.7. PyPI datiert diese Version auf den 9. Juni 2026; die aktuelle 1.102.0 stammt vom 20. September 2026. Prüfe Symptome gegen 1.88.1, nicht gegen die aktuelle LiteLLM-Dokumentation. Alles geprüft am 21. September 2026.

Lies den Statuscode, bevor du den Schlüssel anfasst

Wenn die Ausnahme einen ganzzahligen Statuscode enthält, entscheidet _is_transient_litellm_error allein danach: wahr für 408, 429, 500, 502, 503 und 504, wahr für jeden anderen 5xx-Status, falsch für jeden anderen Status. Nur wenn kein Statuscode vorhanden ist, greift der Code auf den Abgleich von Ausnahme-Klassen zurück — darunter Timeouts und Verbindungsfehler —; „kein Status“ ist daher der einzige Fall, in dem eine Wiederholung ohne einen 4xx/5xx als Hinweis erfolgen kann. Jede Klasse in der folgenden Tabelle enthält einen Status; sie wurden im litellm-1.88.1-Wheel gelesen.

Eine Ausnahme und ein blinder Fleck. models.py in Zeile 638 löst statt einer Wiederholung aus, wenn got_any_chunk true ist; ein vorübergehender Fehler mitten im Stream wird daher nicht wiederholt — „es ist sofort fehlgeschlagen“ ist ein Hinweis, kein Beweis. Und configure_litellm() läuft beim Import und setzt LITELLM_LOG=ERROR sowie litellm.suppress_debug_info = True. In 1.88.1 ist der Hinweis auf die Provider-Liste in get_llm_provider_logic.py durch if litellm.suppress_debug_info is False geschützt — genau die eine Zeile, mit der LiteLLM dich auf seine Provider-Liste hinweisen würde und die Agent Zero deaktiviert.

Die eingegebene ID ist nicht die gesendete ID

Pro Provider gibt es zwei Identifikatoren, und der Header provider config sagt das ausdrücklich: Die Provider-ID steuert „the settings UI dropdowns“ und die Umgebungsvariable für den API-Schlüssel, während litellm_provider „The corresponding provider name in LiteLLM“ ist. Der zweite Wert wird vorangestellt. Für einen OpenAI-kompatiblen Drittanbieter-Endpunkt ist die Provider-ID other („Other OpenAI compatible“), dessen litellm_provider openai ist; außerdem ordnet _adjust_call_args other ebenfalls openai zu. Der Wert auf der Leitung ist openai/<your-model>, das Formular LiteLLM documents. Gib daher die reine ID ein: Wenn du diese beiden Code-Stellen liest und das Präfix selbst hinzufügst, ergäbe sich openai/openai/gpt-4o — eine Schlussfolgerung aus dem Code, kein beobachteter Fehler.

Wenn die Auflösung fehlschlägt, enthält 1.88.1 zwei verschiedene Zeichenketten, beide mit 400. get_llm_provider_logic.py löst BadRequestError mit „LLM Provider NOT provided … You passed model=…“ aus — aus dem String wurde nichts Verwendbares abgeleitet. LiteLLMUnknownProvider in exceptions.py, Zeile 902, enthält „Unmapped LLM provider for this endpoint. You passed model=…, custom_llm_provider=…“ — ein Provider wurde abgeleitet, aber es gibt an diesem Endpunkt keine Route dafür. Der zweite Fall ist zu erwarten, wenn ein Provider für eine Rolle funktioniert, für eine andere jedoch nicht.

Ein Widerspruch führt Nutzer zum falschen Feld. Agent Zeros FAQ sagt, dass openai/gpt-5.3 für OpenRouter korrekt, für den nativen OpenAI-Provider jedoch falsch ist, „which goes without prefix“, und die Benennungstabelle des Installationsleitfadens führt OpenAI als „Model name only“ auf. Diese Aussagen beschreiben das Textfeld; der Code setzt das Präfix darauf. Beides ist wahr, sobald die Ebene benannt ist. Die Tabelle enthält außerdem einen Dokumentationsfehler — ihre OpenAI-Zeile verwendet eine Anthropic-Modell-ID als Beispiel —; kopiere diese Zelle daher nicht.

Finde heraus, welche der drei Rollen fehlgeschlagen ist

Agent Zero konfiguriert drei Rollen unabhängig voneinander — Chat, Utility und Embeddings — jeweils mit eigenem Provider, Modellnamen und API-Basis. Die Einstellungsbereiche sind chat_model, utility_model und embedding_model, während die alten flachen Schlüssel chat_model_*, util_model_* und embed_model_* lauten; eine Suche nach settings.json nach der falschen Konvention findet nichts. Es gibt eine vierte, optionale Auswahl: Das mitgelieferte Browser-Plugin besitzt ein eigenes model_preset, wird leer ausgeliefert und als „Empty uses the effective Main Model“ dokumentiert — sofern du es nicht setzt, ist ein Fehler des Browser-Tools also ein Fehler der Chat-Rolle unter einem anderen Namen. Und eine erfolgreiche Chat-Antwort beweist, dass eine Rolle funktioniert, nicht drei.

Die Embedding-Rolle unterscheidet sich in zwei Punkten, die die Fehlersuche verändern. LiteLLMEmbeddingWrapper.embed ruft LiteLLMs embedding() ohne try/except und ohne Versuchsschleife auf und schlägt daher unabhängig von der Klasse beim ersten Versuch fehl. Außerdem ist der ausgelieferte Standardwert der Provider huggingface mit dem Namen sentence-transformers/all-MiniLM-L6-v2; models.py leitet jeden huggingface-Namen, der mit sentence-transformers/ beginnt, an einen In-Process-Wrapper weiter, den der Code als Vermeidung von HuggingFace-API-Aufrufen beschreibt; ein Fehler dort muss daher keinen Netzwerkaufruf beinhalten.

Kunavo stellt kein Embedding-Modell bereit; Rollen, die ein Kunavo-Schlüssel in Agent Zero ausfüllen kann, sind daher Chat und Utility.

OpenRouter ist die bestätigte Aufteilung und hier der einzige Zweig mit einer Korrektur der Maintainer statt einer Schlussfolgerung. Issue #1597, „OpenRouter embedding models fail due to LiteLLM missing provider route“, wurde am 2. Mai 2026 eröffnet und am 27. August 2026 geschlossen, wenige Stunden vor der Veröffentlichung von v2.11 am selben Tag. Dabei müssen zwei Dinge getrennt werden, weil sie leicht vermischt werden. Die Konfiguration routet den Provider tatsächlich je nach Rolle — chat behält den nativen litellm_provider: openrouter, während embedding litellm_provider: openai plus eine explizite api_base verwendet, unter dem TODO der Maintainer, dass OpenRouter von LiteLLM „not yet supported“ sei —; diese Aufteilung ist jedoch im Tag v2.10 und auf main identisch und hat das Issue daher nicht geschlossen. Die tatsächliche Änderung ist eine Zeile in models.py: In v2.10 erstellte der Embedding-Wrapper f"{provider}/{model}" if provider != "openai" else model und entfernte damit bei jedem openai-gerouteten Embedding das Präfix; ab v2.11 wird es bedingungslos vorangestellt. Deshalb besagt die abschließende Notiz des Maintainers, dass IDs mit einem Schrägstrich nun unverändert den Endpunkt erreichen. In diesem Zweig ist die Lösung das Upgrade, keine Änderung der Einstellungen.

Die Schlüsselermittlung und warum „den Schlüssel ändern“ oft nicht hilft

get_api_key(service) liest drei Umgebungsnamen in fester Reihenfolge und fällt auf die Literalzeichenkette "None" zurück.

# Provider id `other` ("Other OpenAI compatible"). models.py reads these
# three names in this order and stops at the first non-empty value.
API_KEY_OTHER=sk-...
# OTHER_API_KEY=sk-...
# OTHER_API_TOKEN=sk-...

# A comma in the value is not a syntax error: models.py splits on it
# and rotates the resulting keys round-robin.

Dieser Platzhalter wird herausgefiltert — die Aufrufstelle prüft api_key not in ("None", "NA"), bevor sie ihn hinzufügt —, sodass ein nicht aufgelöster Schlüssel bedeutet, dass überhaupt kein api_key-Argument gesendet wird und LiteLLM stattdessen seine eigene Suche in den Umgebungsvariablen durchführt. Ein 401 kann durch Zugangsdaten ausgelöst werden, die Sie nie ausgewählt haben. Eine zweite Suche verwendet einen anderen service-Wert: _merge_provider_defaults liest den Schlüssel unter der ursprünglichen Anbieter-ID, dann greift _get_litellm_chat auf get_api_key(provider_name) zurück. Zu diesem Zeitpunkt bezeichnet dieser Name bereits den LiteLLM-Anbieter — openai für other. Wenn also API_KEY_OTHER nicht gesetzt ist und sich ein OpenAI-Schlüssel in derselben .env befindet, wird der OpenAI-Schlüssel an Ihren Endpunkt gesendet. Dies wurde aus diesen beiden Funktionen auf main abgeleitet; undokumentiert und hier nicht zur Laufzeit getestet.

Der Installationsleitfaden legt den Schlüssel unter External Services → Other OpenAI-compatible API keys und anschließend OpenAI Compatible als Provider ab. Zwei in der Nähe dokumentierte Symptome sind keine Modell-ID-Fehler: Wenn beim Senden nichts geschieht, macht die FAQ nicht gesetzte Schlüssel in den Einstellungen verantwortlich; und ChatGPT Plus enthält keine API-Guthaben — das mitgelieferte OAuth-Plugin liefert jedoch eine codex_oauth-Verbindung, die sich stattdessen mit einem OpenAI-Konto anmeldet. Daher wäre „kein Abonnement kann Agent Zero antreiben“ falsch.

Der Endpunkt und zwei scheinbar widersprüchliche Regeln

Der Provider other liefert keine Standard-api_base, und ModelConfig.build_kwargs leitet dieses Feld nur weiter, wenn es nicht leer ist — eine leere API-URL sendet also keine Basis, und LiteLLMs Standardwert openai greift. Welche Adresse dies in 1.88.1 auflöst, wurde hier nicht geprüft; betrachte einen 401 bei leerer URL als Grund, das Feld auszufüllen, nicht als Diagnose. LiteLLMs Seite zu kompatiblen Endpunkten enthält anschließend zwei Hinweise, die in entgegengesetzte Richtungen weisen: „Do NOT add anything additional to the base url e.g. /v1/embedding“ und „If you see Not Found Error when testing make sure your api_base has the /v1 postfix.“ Sie lassen sich als eine Regel zusammenfassen — bei /v1 enden und nichts danach hinzufügen.

Unter Docker stellt der Installationsleitfaden ausdrücklich fest, dass localhost und 127.0.0.1 in einer API-Basis-URL den Container meinen: Verwende http://host.docker.internal:<port> oder eine Gateway-Adresse wie http://172.17.0.1:<port> auf der standardmäßigen Linux-Bridge und verschiebe einen an die Host-Loopback-Adresse gebundenen Server auf etwas von Docker Erreichbares wie 0.0.0.0. Bestätige anschließend, dass die gelesene Konfiguration tatsächlich ausgeführt wurde: A0_SET_-Voreinstellungen sind nur anfängliche Standardwerte — „Once a value is saved in settings.json, it takes precedence over these environment variables“ — und ein Neustart ist erforderlich. Separat berichtet Issue #1769 (eröffnet am 15. Juli 2026, weiterhin offen), dass LiteLLM exit(-9) aufruft, wenn sich der registrierte Provider eines Modells von demjenigen unterscheidet, der es bereitstellt: die Analyse eines Meldenden, unbestätigt und hier nicht reproduziert.

Was der falsche Fix kostet

Der schnellste Weg, eine fehlschlagende Utility-Rolle ruhigzustellen, besteht darin, sie auf das Hauptmodell zu verweisen. Das funktioniert und wird zum Tarif des Hauptmodells für Datenverkehr abgerechnet, den der Installationsleitfaden als Zusammenfassung und Speicherextraktion beschreibt. Diese Zahlen sind veranschaulichende Token-Arithmetik, keine gemessenen Aufgabenkosten und keine Abrechnungshöchstgrenze: Angenommen werden für einen Tag Arbeit des Hauptmodells 1200k Eingabe- und 60k Ausgabetoken, für Utility-Datenverkehr 320k und 24k sowie die aktuellen Kunavo-Katalog-Tarife pro einer Million Token.

Die Hauptrolle selbst kostet für diesen Tag $3.150; wenn du die Utility-Rolle auf Claude Sonnet 4.6 zusammenlegst, kommen $0.924 hinzu, wobei Claude Haiku 4.5 für $0.308 modelliert. Beachte jedoch die Fähigkeitsuntergrenze: Der Installationsleitfaden warnt, dass Utility-Modelle „stark genug sein müssen, um Speicher zuverlässig zu extrahieren und zu konsolidieren“, und dass sehr kleine Modelle um 4B bei zuverlässiger Kontextextraktion normalerweise scheitern. Der Leitfaden beschreibt dies als Scheitern an der Aufgabe und nicht als Fehler; hier ist „das Modell hat einen Fehler ausgegeben“ die falsche Diagnose.

Agent Zero selbst kostet keine Lizenzgebühr — die LICENSE auf main enthält MIT-Text, Copyright „Agent Zero, s.r.o“ —; das Geld entfällt auf Modell-Token über die von dir konfigurierten Rollen. Der Katalogbetrag von Kunavo ist eine Abrechnungsuntergrenze, keine Obergrenze: Wenn der Upstream seine Kosten meldet, ist die Abrechnung der größere Wert aus den Katalogkosten und den Upstream-Kosten multipliziert mit dem anwendbaren Aufschlag. Die minimale Aufladung beträgt $10 an vorausbezahltem Guthaben. Siehe Abrechnungsdetails.

Welche Route du hinter die Rollen legen solltest

Für die Budgetierung je Rolle siehe Agent Zero API costs; für die dritte Position changing the embedding model; für Basis-URL- und Präfixkonventionen allgemein OpenAI-compatible API. Um einen Kunavo-Schlüssel mit other zu verbinden: Beginne mit der Fehlerreferenz und erstelle anschließend ein Konto. Agent Zero wurde nicht zur Laufzeit gegen Kunavos Endpunkt getestet; halte daher beim Ausprobieren eine funktionierende Route verfügbar.

Häufig gestellte Fragen

Das Verhalten von Agent Zero wurde am 21. September 2026 aus dem Quellcode des main-Branches von agent0ai/agent-zero — models.py und conf/model_providers.yaml — sowie aus dessen Dokumentation, Releases und Issues gelesen; LiteLLM-Ausnahmeklassen und Fehlermeldungen wurden im litellm-1.88.1-Wheel von PyPI gelesen, der von Agent Zero festgelegten Version. Nichts hier wurde zur Laufzeit getestet: Es wurde keine Installation ausgeführt und kein Fehler vollständig reproduziert. Kunavo-Tokenpreise stammen aus dem Live-Katalog; jeder Dollarbetrag ist veranschaulichende Token-Arithmetik.