Dokumentation

Crush

Crush ist Charms terminalbasierter Coding-Agent — nicht die gleichnamige Rust-Shell. Seine Konfiguration erfolgt über Bash. Um ihn auf einen anderen Endpoint auszurichten, muss daher nur ein Provider mit Typ, Basis-URL und Schlüssel hinzugefügt werden.

Crush wird per Bash konfiguriert — ein `provider add kunavo --type openai-compat --base-url "https://api.kunavo.com/v1"` in crushrc bringt Charms Terminal-Agenten zu Claude und GPT.

~/.config/crush/crushrc

# A crushrc is Bash, not a settings file. Everything here is executed.
provider add kunavo \
  --type openai-compat \
  --base-url "https://api.kunavo.com/v1" \
  --api-key "${KUNAVO_API_KEY:?set KUNAVO_API_KEY}"

model add kunavo/claude-sonnet-5 \
  --name "Claude Sonnet 5" \
  --context-window 1000000 \
  --default-max-tokens 32000 \
  --price-input 1.4 \
  --price-output 7

model add kunavo/claude-haiku-4-5 \
  --name "Claude Haiku 4.5" \
  --context-window 200000 \
  --default-max-tokens 16000 \
  --price-input 0.7 \
  --price-output 3.5

model large kunavo/claude-sonnet-5
model small kunavo/claude-haiku-4-5

Die Basis-URL behält das Suffix /v1. Das dokumentierte OpenAI-kompatible Beispiel von Crush lautet --base-url "https://api.deepseek.com/v1", und auch das Anthropic-kompatible Beispiel endet auf dieselbe Weise. Das Suffix gehört also zur Konvention des Clients und ist keine Vermutung. Lässt man es weg, schlägt die Anfrage mit 404 statt mit einem Authentifizierungsfehler fehl.

Verwenden Sie --type openai-compat, nicht openai. Die README grenzt die Optionen klar voneinander ab: openai dient dazu, Anfragen über OpenAI weiterzuleiten oder zu routen; openai-compat ist für Nicht-OpenAI-Provider mit OpenAI-kompatiblen APIs vorgesehen. Kunavo ist der zweite Fall.

Ein crushrc ist Bash mit den integrierten Crush-Befehlen. Crush weist ausdrücklich darauf hin, dass es sich um vertrauenswürdigen Code handelt — es läuft in einer vollständigen Shell. Genau darin liegt auch der Vorteil: --api-key "$(op read ...)" hält den Schlüssel aus der Datei heraus. Das ältere crush.json wird weiterhin geladen, aber die README bezeichnet es als veraltet. Verwenden Sie daher crushrc als Grundlage.

Kunavo hat Crush nicht zur Laufzeit getestet — weder diesen Client noch einen anderen auf diesen Seiten. Hier wurde Crushs dokumentierte Konfiguration mit dem von Kunavo veröffentlichten Endpoint abgeglichen. Eine Einrichtungsseite ist kein Testergebnis. Führen Sie eine klar begrenzte Aufgabe aus, bevor Sie damit täglich arbeiten.

Noch kein Schlüssel? Erstelle ein Kunavo-Konto, erstelle einen Schlüssel (er beginnt mit sk-kn-) und füge ab $10 Guthaben hinzu – Aufrufe werden aus diesem Guthaben bezahlt, fehlgeschlagene Aufrufe werden nicht berechnet. Das Dashboard öffnet anschließend die Crush-Einrichtung.

Schritt für Schritt

Erstellen Sie unter /app/keys einen Schlüssel und kopieren Sie ihn — er wird nur einmal angezeigt. Exportieren Sie ihn als KUNAVO_API_KEY oder lesen Sie ihn direkt in der Konfiguration aus einem Passwortmanager aus.
Legen Sie den obigen Block in ~/.config/crush/crushrc ab. Crush liest zuerst ./.crushrc, dann ./crushrc und anschließend die globale Datei. So kann ein Projekt die Einstellungen des Rechners überschreiben — und ein geklontes Repository kann eine eigene Konfiguration mitbringen.
Starten Sie crush und drücken Sie ctrl+l, um die Modellauswahl zu öffnen. Die obigen Einträge model large und model small legen bereits beide Slots fest. Die Auswahl dient daher zum Wechseln des Modells, nicht zur Einrichtung.
Wenn Sie IDs nicht manuell registrieren möchten: Die automatische Erkennung wird ausgeführt, wenn die Modellliste eines openai-compat-Providers leer ist oder wenn Sie --discover-models true übergeben. Kunavo antwortet mit GET /v1/models, sodass die Liste automatisch befüllt wird. Bei Konflikten haben Ihre eigenen model add-Felder Vorrang.
Führen Sie eine klar begrenzte Aufgabe aus und prüfen Sie anschließend die unter /app/billing für Ihr Konto erfasste Abrechnung. Der im Terminal angezeigte Betrag wird aus den von Ihnen eingegebenen Zahlen für --price-* berechnet; maßgeblich ist die Abrechnung.

Abgeglichen mit Der Abschnitt „Custom Providers“ in der Crush-Dokumentation am 21. September 2026. Einstellungen von Drittanbietern können sich ändern; wenn ein Feldname hier nicht mehr mit deiner Ansicht übereinstimmt, ist diese Seite maßgeblich, nicht diese hier.

Dies ist die Kurzfassung. Die vollständige Anleitung – Modellauswahl, Kosten einer tatsächlichen Sitzung und Fehlerszenarien – findest du in Crush und OpenCode.

Vor dem Debugging des Clients prüfen

Eine Anfrage klärt, ob der Fehler am Endpunkt, am Schlüssel oder an der Konfigurationsdatei liegt. Wenn diese Anfrage JSON zurückgibt, funktionieren dieselbe Basis-URL und derselbe Schlüssel in Crush.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

Welche Modell-ID in das Feld gehört

Jedes Textmodell ist über eine Modell-ID erreichbar – die aktuelle Liste findest du unter GET /v1/models, den Katalog mit Preisen auf der Modellseite. Die Tarife sind USD pro 1 Mio. Token, Eingabe / Ausgabe.

Modell-ID	Kunavo: Ein- und Ausgabe	Wo es in Crush hineinpasst
`claude-sonnet-5`	$1.40 / $7.00	der große Modell-Slot — das Alltagsmodell zum Programmieren und Bearbeiten
`claude-haiku-4-5`	$0.70 / $3.50	der kleine Modell-Slot, den Crush ständig für Titel und Zusammenfassungen verwendet
`claude-opus-5`	$3.50 / $17.50	für Refactorings, bei denen ein falscher Plan teuer wäre, zum großen Modell-Slot wechseln
`gpt-5-6-terra`	$0.70 / $4.20	eine zweite Modellfamilie mit demselben Schlüssel — nur noch ein model add entfernt

Die Abrechnung erfolgt pro Token aus einem vorausbezahlten Guthaben ohne Monatsgebühr – siehe Abrechnung. Bei wiederholtem Kontext – dem Großteil dessen, was ein Editor oder Chat-Client sendet – verändert Prompt-Caching die Rechnung stärker als die Modellwahl.

Häufig gestellte Fragen

Wie füge ich der Crush CLI einen benutzerdefinierten API-Provider hinzu?

Schreibe es in eine crushrc, die Bash mit Crush-Built-ins ist. Eine Zeile registriert den Endpunkt — provider add kunavo --type openai-compat --base-url "https://api.kunavo.com/v1" --api-key "$KUNAVO_API_KEY" — und ein model add pro ID registriert, was du aufrufen möchtest, mit Anzeigename, Kontextfenster und Preisen pro Million, die Crush für seine Schätzung auf dem Bildschirm verwendet. Crush liest ./.crushrc, dann ./crushrc, dann ~/.config/crush/crushrc, sodass derselbe Block pro Projekt oder pro Rechner funktioniert.

Muss die Crush-Basis-URL auf /v1 enden?

Ja. In Crushs eigenen Beispielen für benutzerdefinierte Anbieter steht das Suffix bei beiden Typen: https://api.deepseek.com/v1 für den OpenAI-kompatiblen Fall und https://api.anthropic.com/v1 für den Anthropic-kompatiblen Fall. Für einen Kunavo-Schlüssel lautet der Wert https://api.kunavo.com/v1. Bei Claude Code ist es genau umgekehrt: Dort benötigt ANTHROPIC_BASE_URL einen nackten Ursprung, weil der Client den Pfad selbst anhängt — dasselbe Gateway, zwei Schreibweisen, und ein fehlendes /v1 führt zu einem 404 statt zu einem 401.

Soll ich --type openai oder --type openai-compat verwenden?

openai-compat für jedes Gateway eines Drittanbieters. Crushs README reserviert openai für das Proxying oder Weiterleiten von Anfragen über OpenAI selbst und empfiehlt openai-compat für Anbieter außerhalb von OpenAI mit OpenAI-kompatiblen APIs. Der Typ legt auch das Verhalten jenseits des Übertragungsformats fest: Die automatische Modellerkennung wird bei einem openai-compat-Anbieter mit leerer Modellliste ausgeführt. Crush unterstützt außerdem --type anthropic für Anthropic-kompatible Endpunkte; dafür wird --extra-header anthropic-version 2023-06-01 verwendet.

Ist crush.json noch der richtige Ort für diese Konfiguration?

Nein. crush.json ist das ursprüngliche Format. Crushs eigene Dokumentation bezeichnet es inzwischen als veraltet und weist darauf hin, dass es keine neuen Funktionen mehr erhält; das aktuelle Format ist crushrc. Beachte, dass beide ausgeführt statt geparst werden — eine crushrc läuft in einer vollständigen Shell, und jedes $(...) in crush.json wird beim Laden ausgewertet. Deshalb warnt die Dokumentation davor, Crush in einem Verzeichnis zu starten, dessen Konfiguration du nicht gelesen hast, und deshalb funktioniert es überhaupt, einen Schlüssel innerhalb der Konfiguration aus einem Passwortmanager abzurufen.

Warum weichen die von Crush angezeigten Kosten von der Abbuchung ab?

Weil es sich um zwei verschiedene Zahlen aus zwei verschiedenen Quellen handelt. Die Schätzung auf dem Bildschirm für einen manuell registrierten Anbieter wird aus den Werten --price-input und --price-output berechnet, die du bei model add eingegeben hast. Bei integrierten Anbietern stammt sie aus Catwalk, Crushs externem Anbieterkatalog. Keine der beiden Quellen liest dein Konto aus. Ein Tippfehler in einem --price-* -Flag führt zu einer falschen Anzeige, nicht zu einer falschen Abbuchung. Vergleiche die Abrechnung stattdessen mit dem Transaktionsprotokoll unter /app/billing.

Kann Crush Claude- oder GPT-Modelle über einen benutzerdefinierten Anbieter verwenden?

Ja, und Crush schränkt das in keiner Weise ein. Charm Hyper ist der offizielle Anbieter, zu dem dich die Einführung leitet. Ein benutzerdefinierter Anbieter ist jedoch ein dokumentierter, uneingeschränkt verfügbarer Weg, und die Modell-ID wird am Endpunkt statt im Client aufgelöst. Eine Claude-ID bei einem openai-compat-Anbieter ist also die vorgesehene Kombination: Der Typ bezeichnet das Übertragungsprotokoll, nicht den Anbieter.