Wenn Ihre Apps heute einen LiteLLM-Proxy aufrufen, sprechen sie bereits die API von OpenAI oder von Anthropic. Kaeso spricht beide. Eine App umzuziehen ist deshalb vor allem ein Adresswechsel: eine neue Basis-URL und ein neuer Schlüssel. Ihr Code, Ihr SDK und die Art, wie Sie Antworten streamen, bleiben, wie sie sind.
Die fünf Minuten gelten für diesen Wechsel: Kaeso starten, einen Anbieter verbinden und eine App darauf zeigen lassen. Eine lange config.yaml zu übertragen dauert länger, deshalb geht die zweite Hälfte dieser Anleitung sie Stück für Stück durch: Modelle, Fallbacks, Schlüssel, Budgets, Caching und Protokolle, auch das, was anders funktioniert, und das Wenige, was Kaeso nicht kann.
Lassen Sie LiteLLM laufen, während Sie umziehen. Nichts hier verändert es, und jede App kehrt zurück, indem Sie ihre Basis-URL zurückstellen.
Bevor Sie beginnen
- Ein Server. Linux mit Docker Engine und Docker Compose 2.24 oder neuer, 2 vCPUs, 4 GB Arbeitsspeicher und 20 GB Festplatte. Um Kaeso zuerst auf Ihrem eigenen Rechner auszuprobieren, verwenden Sie
localhostals Domain. - Eine Domain, deren DNS-Eintrag auf den Server zeigt, mit offenen Ports 80 und 443, damit das mitgelieferte Caddy ein Zertifikat erhält.
- Ihre Anbieter-Schlüssel. Die, die LiteLLM heute nutzt; Ihre
config.yamlnennt sie alsos.environ/OPENAI_API_KEYund ähnlich. - Ein SMTP-Server für Anmeldelinks und Einladungen. Zum Ausprobieren können Sie ihn weglassen.
Der Wechsel
Kaeso starten
Jedes Release veröffentlicht eine compose.yaml, die das Gateway, die Konsole, PostgreSQL, ClickHouse für die Anfrageprotokolle, Valkey und Caddy startet. Laden Sie sie herunter, schreiben Sie die Einstellungen und starten Sie alles:
Der erste Start dauert ein bis zwei Minuten, während die Images geladen werden. Unter Docker Desktop oder Colima führen Sie statt der chown-Zeile nur chmod 0400 master-keys aus.
KAESO_MAIL_TRANSPORT=log schreibt E-Mails ins Protokoll des Gateways, statt sie zu senden. Zum Ausprobieren allein genügt das. Bevor Sie jemanden einladen, ersetzen Sie es durch Ihren SMTP-Server (E-Mail-Einstellungen (öffnet in einem neuen Tab)).
Ein Name bedeutet hier zweierlei. Der Hauptschlüssel von Kaeso verschlüsselt die Anbieter-Schlüssel, die es speichert; er ist nicht LiteLLMs master_key, und nichts ruft damit Modelle auf. Bewahren Sie eine Kopie von master-keys sicher auf, getrennt von Ihren Datenbank-Backups.
Der letzte Befehl gibt einen Einrichtungslink aus. Öffnen Sie ihn, geben Sie Ihren Namen, Ihre E-Mail-Adresse, ein Passwort und einen Namen für Ihre Organisation ein, und wählen Sie Kaeso einrichten. Sie sind jetzt Admin der Instanz und Inhaber der Organisation.
Einen Anbieter verbinden
Öffnen Sie Anbieter, wählen Sie Anbieter-Schlüssel hinzufügen, wählen Sie den Anbieter und fügen Sie seinen Schlüssel ein. Der erste Schlüssel eines Anbieters wird sein Standard, den jedes Projekt nutzt.
Kaeso speichert den Schlüssel verschlüsselt und zeigt ihn nie wieder. Apps sehen ihn nie: Sie rufen Kaeso mit eigenen Schlüsseln auf.
Ihre Modelle hinzufügen
Anfragen können nur Modelle aus dem Katalog eines Projekts nennen, so wie LiteLLM im Wesentlichen nur bedient, was model_list nennt. Wählen Sie unter Projekte die Option Projekt erstellen und benennen Sie es nach Ihrer App. Öffnen Sie dann Modelle, wählen Sie Modelle hinzufügen, suchen Sie die Modelle, die Ihre App aufruft, etwa claude-sonnet-5-5 oder gpt-6-sol, und fügen Sie sie hinzu.
Preise und Kontextfenster geben Sie nicht ein. Sie kommen aus KPMR (öffnet in einem neuen Tab), der Kaeso Provider & Model Registry, und die Installation hält sie selbst aktuell.
Einen Schlüssel erstellen
Wählen Sie im Projekt API-Schlüssel, dann Schlüssel erstellen. Benennen Sie ihn nach der App, behalten Sie den Zugriff Inferenz und wählen Sie ein Ablaufdatum. Kopieren Sie den Schlüssel, sk-kso-…, bevor Sie den Dialog schließen: Kaeso behält nur einen Hash davon.
Die App auf Kaeso zeigen lassen
Ändern Sie die Basis-URL und den Schlüssel. Sonst nichts:
Liest die App ihre Einstellungen aus der Umgebung, ändern Sie stattdessen diese:
Achten Sie auf das /v1. LiteLLM antwortet auf /chat/completions ebenso wie auf /v1/chat/completions, deshalb zeigen viele Apps mit dem OpenAI-SDK auf den bloßen Host. Kaeso bedient seine Modell-API nur unter /v1, der Rest der Domain ist die Konsole. Beim Anthropic-SDK ist es umgekehrt: Es hängt /v1 selbst an, seine Basis-URL ist also die bloße Domain.
Senden Sie eine Anfrage. Jede Antwort trägt einen Header kaeso-request-id, und die Anfrageprotokolle des Projekts zeigen die Anfrage wenige Sekunden später mit Status, Token, Kosten und Zeiten. Das ist der Wechsel.
Wie bei LiteLLM erreicht jedes SDK jedes Chatmodell, das OpenAI-SDK kann also Claude aufrufen. Sendet die App ein Feld, das der Anbieter des Modells nicht annimmt, lässt Kaeso es nicht stillschweigend fallen: Es lehnt die Anfrage mit einem Fehler ab, der das Feld nennt, damit keine Einstellung unbemerkt verloren geht.
Claude Code und Codex
Coding-Tools sind Apps wie alle anderen. Für Claude Code ändern Sie zwei Werte in ~/.claude/settings.json:
Claude Code ruft ein Opus-, ein Sonnet- und ein Haiku-Modell auf, das letzte für Hintergrundaufgaben, also müssen alle drei im Katalog des Projekts stehen. ANTHROPIC_DEFAULT_OPUS_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL und ANTHROPIC_DEFAULT_HAIKU_MODEL legen fest, welche, und können auch einen Alias nennen. Für Codex fügen Sie Kaeso als Modellanbieter hinzu, mit base_url = "https://kaeso.example.com/v1" und wire_api = "responses". Coding-Tools (öffnet in einem neuen Tab) zeigt beide Dateien vollständig.
Ihre config.yaml, Zeile für Zeile
Hier eine LiteLLM-Konfiguration, wie viele Teams sie betreiben: drei Modelle, eines davon unter eigenem Namen, Fallbacks, Wiederholungen, ein Redis-Cache und eine Datenbank für Schlüssel und Ausgaben.
In Kaeso steht nichts davon in einer Datei. Sie stellen es in der Konsole ein oder per Skript über die Platform API, und das Audit-Log hält jede Änderung fest.
Die folgenden Abschnitte nehmen sich diese Punkte einzeln vor.
Modelle und Anbieter
Namen, die Ihre Apps schon senden
Ein model_name, der die eigene Modell-ID des Anbieters ist, etwa claude-sonnet-5-5, braucht nur das Modell im Katalog. Apps senden ihn weiter.
Ein eigener Name, etwa fast, wird ein Alias. Öffnen Sie unter Modelle den Tab Aliasse, wählen Sie Alias erstellen, nennen Sie ihn fast und wählen Sie gpt-5.4-mini. Apps senden fast, und Sie können ihn später auf ein anderes Modell legen, ohne die Apps anzufassen.
Kaeso liest auch die Form provider/model, ein Name wie anthropic/claude-sonnet-5-5 funktioniert also unverändert. Ein Alias darf allerdings kein / enthalten, ein LiteLLM-Name wie prod/claude muss sich also in der App ändern.
Anbieter-Präfixe
LiteLLMs Präfix in litellm_params.model sagt Ihnen, welchen Anbieter-Schlüssel Sie hinzufügen. Die meisten heißen in Kaeso gleich, einige werden anders geschrieben:
Zwei Abkürzungen helfen bei großen Konfigurationen. Alle aktuellen OpenAI-Modelle hinzufügen, und derselbe Button für jeden anderen Anbieter, ersetzt einen Platzhalter wie openai/*; er fügt die Modelle hinzu, die der Anbieter heute hat, keine, die später erscheinen. Und wenn zwei Anbieter dieselbe Modell-ID bedienen, nennen Sie den, den Sie meinen, etwa groq/openai/gpt-oss-120b.
Preise, die Sie selbst festlegen
LiteLLM nimmt input_cost_per_token und output_cost_per_token in US-Dollar pro Token. Kaesos Preise sind in US-Dollar pro Million Token, multiplizieren Sie also mit einer Million: Aus 0.000003 wird 3. Öffnen Sie das Sheet des Modells, wählen Sie Werte anpassen und tragen Sie den Preis ein. Er gilt nur für dieses Projekt, und Auf KPMR zurücksetzen macht ihn rückgängig.
Selbst betriebene Server
Ein Eintrag mit api_base, etwa ein vLLM-, Ollama- oder LM-Studio-Server, wird ein eigener Anbieter. Öffnen Sie unter Anbieter den Bereich Eigene Anbieter, wählen Sie Eigenen Anbieter hinzufügen, geben Sie Basis-URL und Schlüssel ein und wählen Sie Einstellungen erkennen. Kaeso fragt den Server, wie es ihn aufruft, und listet seine Modelle, wenn Sie sie einem Projekt hinzufügen.
Was Ihr Server kostet, kann Kaeso nicht wissen, deshalb tragen Sie die Preise jedes Modells ein; 0 ist richtig für Hardware, die Sie nicht pro Token bezahlen. Steht der Server unter einer privaten Adresse, erlauben Sie sein Netz in compose.override.yaml neben der compose.yaml und übernehmen es mit docker compose up -d --wait:
Anbieter, die Kaeso nicht hat
Kaeso hat vierzehn Anbieter eingebaut: Anthropic, Cerebras, Cohere, DeepSeek, Groq, Mistral, Moonshot, Ollama Cloud, OpenAI, OpenRouter, QwenCloud, SpaceX, Together AI und Vercel AI Gateway. Azure OpenAI, Amazon Bedrock, Google Vertex AI und die Gemini API gehören nicht dazu. Nutzt Ihre Konfiguration azure/, bedrock/, vertex_ai/ oder gemini/, haben Sie zwei Wege. Gemini-Modelle bedienen auch OpenRouter und Vercel AI Gateway, etwa openrouter/google/gemini-2.5-pro. Für den Rest behalten Sie LiteLLM hinter Kaeso, wie das Ende dieser Anleitung zeigt.
Fallbacks, Wiederholungen und Lastverteilung
Fallbacks
In LiteLLM sind Fallbacks eine Liste nach Modellnamen. In Kaeso gehören sie zu einem Alias: Seine Route versucht ein Modell, dann das nächste. Routen kommen mit Kaeso 0.6.0, das beim Schreiben dieses Artikels als Release Candidate vorliegt; unter 0.5.6 zeigt ein Alias auf ein einzelnes Modell.
Damit Ihre Apps ihren Namen behalten, geben Sie dem Alias diesen Namen. Ein Alias hat Vorrang vor einem gleichnamigen Modell, und die Liste markiert ihn mit Verdeckt ein Modell. Für die Konfiguration oben:
- Erstellen Sie einen Alias namens
claude-sonnet-5-5. - Wählen Sie unter Beginnen mit die Vorlage Eine Fallback-Kette.
- Machen Sie
claude-sonnet-5-5zum ersten Schritt undgpt-6-solzu seinem Fallback, und wählen Sie dann Speichern.
Ein Schritt weicht aus, wenn sein Modell nicht verfügbar ist, ein Ratenlimit erreicht oder etwas in der Anfrage nicht annehmen kann, etwa Bilder. Das sind unavailable, limited und unsupported, die Standardgründe. Ein vierter Grund, rejected, deckt ab, was context_window_fallbacks und content_policy_fallbacks taten: Der Anbieter lehnt die Anfrage selbst ab, wegen eines zu langen Kontexts oder ihres Inhalts. Nehmen Sie ihn nur für einen Fallback auf, der annehmen kann, was das erste Modell ablehnte.
Für lange Prompts gibt es einen besseren Weg, als auf einen Fehler zu warten. Beginnen mit bietet auch Lange Prompts woanders hin: eine Bedingung auf die Eingabe-Tokens der Anfrage, damit ein langer Prompt direkt an das Modell mit dem größeren Kontext geht.
Jede Antwort auf einen Alias trägt einen Header kaeso-route, der jeden versuchten Schritt mit seinem Status auflistet. Das Anfrageprotokoll hält dieselben Schritte unter Zuerst versucht fest, und der Tab Testen zeigt vor dem Speichern, wohin eine Anfrage ginge.
Wiederholungen
Kaeso sendet jede Anfrage einmal. Die SDKs von OpenAI und Anthropic wiederholen von sich aus, standardmäßig zweimal, wenn ein Fehler es zulässt. Haben Sie sich auf num_retries verlassen, um am Proxy zu wiederholen, erhöhen Sie stattdessen max_retries im Client (maxRetries in TypeScript).
Lastverteilung
Mehrere Einträge unter einem model_name, etwa dasselbe Modell mit zwei Schlüsseln, haben keine direkte Entsprechung. Ein Projekt nutzt einen Schlüssel pro Anbieter, und Kaeso bündelt keine Schlüssel und wählt kein Deployment nach Latenz oder Auslastung. Um Arbeit auf mehrere Anbieterkonten zu verteilen, weisen Sie einen Anbieter-Schlüssel mit Projekten zuweisen einzelnen Projekten zu. Um Verkehr zwischen Modellen aufzuteilen, nutzen Sie eine Aufteilung in einer Route: Sie schickt jede Anfrage nach Gewicht einen ihrer Zweige hinunter, pro Anfrage, pro Aufrufer oder pro Wert eines Headers.
Schlüssel, Teams und Budgets
Neue Schlüssel für jede App
LiteLLMs virtuelle Schlüssel kommen nicht mit: Kaeso stellt eigene aus und behält davon nur Hashes. Jede App bekommt einen neuen Schlüssel, und das ist ohnehin die eine Änderung, die Sie an ihr vornehmen.
Teams werden Projekte. Jedes Projekt hat seinen eigenen Katalog, eigene Schlüssel, Limits und Protokolle, und Menschen treten ihm mit einer Rolle bei: Admin, Entwickler oder Betrachter. Geben Sie Software ein Dienstkonto statt des Schlüssels einer Person, damit ihre Schlüssel weiter funktionieren, wenn diese Person geht.
Was aus den Einstellungen eines virtuellen Schlüssels wird
Tage und Monate sind in Kaeso Kalendertage und -monate in UTC, eine budget_duration von 30d wird also ein Monatsbudget und 1d ein Tagesbudget. Ein Budget ist standardmäßig hart und lehnt Anfragen ab, sobald es aufgebraucht ist; schalten Sie das ab, sendet es nur Warnungen, standardmäßig bei 50, 80 und 100 Prozent. Kaeso hat kein Limit für parallele Anfragen, max_parallel_requests hat also keine Entsprechung, ebenso wenig die metadata eines Schlüssels: Sein Name ist das, was Anfrageprotokolle und Nutzung zeigen.
Limits sind verschachtelt. Das Budget eines Schlüssels kann nicht höher sein als das seines Inhabers, und das eines Inhabers nicht höher als das des Projekts. Ein Team-Budget aus LiteLLM wird also ein Limit für das Projekt.
Viele Schlüssel auf einmal
Bei Dutzenden Schlüsseln nutzen Sie die Platform API. Erstellen Sie unter Organisationseinstellungen › Plattform-Schlüssel einen Plattform-Schlüssel, und legen Sie dann für jede App ein Dienstkonto und einen Schlüssel mit seinen Limits an:
Der letzte Befehl gibt den neuen Schlüssel einmal aus. Speichern Sie ihn dort, wo die App ihn liest. Mit der Platform API automatisieren (öffnet in einem neuen Tab) deckt den Rest ab, vom Hinzufügen von Modellen bis zum Rotieren von Schlüsseln.
Caching
Aus cache: true wird ein Schalter pro Projekt. Öffnen Sie die Einstellungen des Projekts, schalten Sie unter Antwort-Cache die Option Antworten cachen ein und wählen Sie, wie lange Antworten bleiben, von 5 Minuten bis 7 Tagen.
Der Cache beantwortet eine Anfrage nur, wenn sie mit einer früheren übereinstimmt, verglichen nach der Übersetzung, sodass sich eine OpenAI-App und eine Anthropic-App einen Eintrag teilen können. Er speichert nicht gestreamte Antworten und wird nur innerhalb des Projekts geteilt. Einen semantischen Cache gibt es nicht. Apps steuern ihn pro Anfrage mit dem üblichen Header Cache-Control: no-cache fragt den Anbieter erneut, no-store umgeht den Cache. Jede Antwort sagt in kaeso-cache, was geschah, und ein Treffer kostet die Budgets nichts.
Protokolle und Ausgaben
Kaeso hält jede Anfrage selbst fest: Modell, Anbieter, Status, Token, Kosten, Zeiten, Schlüssel und Absender, und standardmäßig auch, was gesendet und zurückgegeben wurde. Die Organisation wählt, wie lange: 90 Tage Metadaten und 30 Tage Inhalte, wenn Sie nichts ändern. Um gar keine Prompts aufzubewahren, wie mit turn_off_message_logging, schalten Sie Anfrageinhalte protokollieren unter Organisationseinstellungen › Protokollierung ab, oder nur für ein einzelnes Projekt.
Die Nutzung lässt sich nach Tag, Modell, Schlüssel oder Mitglied lesen, in der Konsole oder über die Platform API, und die Anfrageprotokolle lassen sich als CSV oder JSON Lines exportieren. Das Gateway stellt Prometheus-Metriken auf einem eigenen Port für Ihre Dashboards bereit.
Kaeso leitet seine Protokolle nicht an fremde Werkzeuge weiter, Callbacks wie Langfuse oder Datadog haben also keine Entsprechung; lesen Sie stattdessen die Protokolle der Platform API oder den Export. Auch die bisherigen Ausgaben ziehen nicht mit um. Kaeso zählt ab der ersten Anfrage, die es bedient. Behalten Sie also einen Dump der LiteLLM-Datenbank, wenn Sie die Historie brauchen.
LiteLLM für das behalten, was Kaeso nicht kann
Kaesos Modell-API umfasst Chat Completions, Responses, Messages, Embeddings, Token-Zählungen und die Liste der Modelle. Sie hat keine Endpunkte für Bilder, Audio, Rerank, Moderation, Dateien oder Batches, keine Durchreich-Routen und keine Guardrails, und sie leitet keine MCP-Server für Ihre Apps weiter. Außerdem lehnt sie Responses-Anfragen ab, die den Anbieter bitten, eine Antwort zu speichern oder fortzusetzen, etwa mit previous_response_id; senden Sie jedes Mal die ganze Unterhaltung.
Für diese Endpunkte rufen Sie LiteLLM weiter direkt auf; nichts hindert eine App daran, beide zu nutzen. Für einen Anbieter, den Kaeso nicht hat, können Sie einen Schritt weitergehen und LiteLLM als eigenen Anbieter hinter Kaeso stellen:
- Erstellen Sie in LiteLLM einen virtuellen Schlüssel, beschränkt auf die Modelle, die Kaeso erreichen soll, etwa Ihre Bedrock- und Azure-Einträge.
- Steht LiteLLM unter einer privaten Adresse, erlauben Sie sein Netz in
compose.override.yaml, wie für einen selbst betriebenen Server. - Wählen Sie in Kaeso Eigenen Anbieter hinzufügen mit der Adresse von LiteLLM, etwa
http://10.0.0.12:4000/v1, und diesem Schlüssel. Einstellungen erkennen findet Chat Completions. Setzen Sie die ID auflitellm. - Fügen Sie seine Modelle einem Projekt hinzu und tragen Sie ihre Preise ein. Kaeso rechnet sie zu diesen Preisen ab und hält die Budgets daran.
Apps rufen dann LiteLLMs model_name mit der ID davor auf, etwa litellm/bedrock-claude, oder einen Alias, den Sie danach benennen, über denselben Schlüssel und dieselbe Basis-URL wie jedes andere Modell. Kaesos Schlüssel, Limits und Protokolle gelten für sie wie für jede andere Anfrage.
Zurückwechseln und abschalten
Bis Sie LiteLLM stoppen, ist der Rückweg dieselbe Änderung andersherum: die alte Basis-URL und der alte Schlüssel. Ziehen Sie eine App nach der anderen um und sehen Sie zu, wie ihre Anfragen in Kaesos Anfrageprotokollen erscheinen.
Sobald der Verkehr jeder App in Kaeso ankommt und die Protokolle von LiteLLM still werden, ziehen Sie einen letzten Dump seiner Datenbank und stoppen es. Hat ein Teil Ihres Setups in keinen der Abschnitte oben gepasst, schreiben Sie uns (öffnet in einem neuen Tab). Das hilft zu entscheiden, was Kaeso als Nächstes kann.