Cherry Studio ist ein verbreiteter Desktop-Client für KI mit Unterstützung für mehrere Anbieter, Modellwechsel, Assistenten und Wissensdatenbanken. Der Client stellt selbst keine Modelle bereit; die Modelle kommen aus der konfigurierten API. Viele Nutzer bleiben an derselben Stelle hängen: Welche Base URL wird eingetragen, wohin gehört der Key, und wie fügt man eine Modell-ID hinzu? Dieser Artikel führt den vollständigen Ablauf anhand der verbreiteten aktuellen Version durch.

Hinweis: Cherry Studio ist ein Produkt seines jeweiligen Inhabers; dieser Artikel dient ausschließlich der technischen Anleitung. Oberflächennamen und Einstiegspunkte können sich mit Versionen ändern; maßgeblich ist die aktuelle Version. Modelle und Preise entnehmen Sie den Modellpreisen.

1. Drei Dinge vor der Anbindung vorbereiten

Unabhängig vom Gateway benötigt ein eigener Anbieter nur drei Parameter:

  1. API Key: Nach der Registrierung im ZSQH AI Gateway in der Konsole anlegen und nach Projekt oder Umgebung benennen.
  2. Base URL: Die OpenAI-kompatible Adresse des Gateways, üblicherweise https://ai.zhongshangqihang.com/v1.
  3. Modell-ID: Von der Seite Modellpreise kopieren; entscheidend ist die API-Kennung, nicht der Anzeigename.

Prüfen Sie Key und Modell zuerst mit einem Befehl, bevor Sie den Client konfigurieren. Das erspart viele Umwege:

export ZSQH_API_KEY="sk-ihr-schluessel"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ihre-modell-id",
    "messages": [{"role": "user", "content": "Antworte nur mit OK"}]
  }'

Wenn die Antwort choices enthält, sind Key, Adresse und Modell zumindest grundsätzlich in Ordnung; ein verbleibendes Problem liegt dann in der Client-Konfiguration.

2. Wie die Base URL eingetragen wird

Die Feldbezeichnung in Cherry Studio kann je nach Version variieren, verbreitet sind „API-Adresse“ oder „API Host“. Empfohlen ist folgende Belegung:

Konfiguration Empfohlene Eingabe Hinweis
Anbietertyp OpenAI Verwendet das OpenAI-kompatible Protokoll
API-Adresse https://ai.zhongshangqihang.com/v1 Kein abschließender Schrägstrich
API-Schlüssel sk-... In der Konsole erzeugter Key
Modell-ID Laut Preisseite Beim manuellen Hinzufügen besonders prüfen

Versionen behandeln /v1 unterschiedlich: Manche ergänzen es automatisch, andere verlangen die vollständige Angabe. Die Zuordnung ist einfach: 401 deutet meist auf den Key, 404 meist auf den Pfad. Meldet die vollständige Adresse 404, versuchen Sie es ohne /v1; meldet nur die Domain 404, ergänzen Sie /v1. Ändern Sie immer nur eine Variable, nicht gleichzeitig Key, Adresse und Modell.

3. Eigenen Anbieter hinzufügen

Der Ablauf in der verbreiteten aktuellen Version (Schaltflächennamen richten sich nach Ihrer Version):

  1. Cherry Studio öffnen und unten links die Einstellungen aufrufen (Zahnradsymbol).
  2. „Modellservices“ oder „Modellanbieter“ öffnen.
  3. Auf „+ Anbieter hinzufügen“ klicken.
  4. Als Anbietertyp OpenAI oder die OpenAI-kompatible Option wählen.
  5. Anbietername, API-Schlüssel und API-Adresse eintragen.
  6. Speichern, zur Modellliste zurückkehren und Modell-IDs hinzufügen.

Fehlt „Anbieter hinzufügen“ in Ihrer Version, aktualisieren Sie zuerst den Client. Ältere Versionen haben andere Einstiegspunkte und Felder; das ungeprüfte Übernehmen alter Anleitungen führt leicht zu falschen Eingaben.

4. Modell-ID hinzufügen

Nach dem Speichern des Anbieters gibt es zwei Wege:

  • Modellliste abrufen: Der Client fragt die verfügbaren Modelle beim Gateway ab; anschließend die gewünschten Modelle auswählen.
  • Manuell hinzufügen: Auf „+“ klicken und die Modell-ID direkt eingeben. Dieser Weg eignet sich, wenn das Gateway keine Modellliste bereitstellt oder der Abruf fehlschlägt.

Die Modell-ID muss exakt mit der Preisseite übereinstimmen, einschließlich Groß-/Kleinschreibung, Versions-Suffix und Bindestrichen. Beim manuellen Hinzufügen muss außerdem der Modelltyp „Dialog“ oder „Chat“ lauten; bei falschem Typ erscheint das Modell nicht im Auswahlmenü des Dialogs.

Modelltyp Typischer Zweck Hinweis
Dialogmodell Alltägliche Fragen, Texte, Code Am häufigsten, zuerst konfigurieren
Reasoning-Modell Komplexe Analyse, Mathematik, Planung Latenz und Kosten meist höher
Bildmodell Bildverständnis, Fragen zu Screenshots Prüfen, ob das Gateway Bildeingaben unterstützt
Embedding-Modell Wissensdatenbank, Vektorsuche Schnittstelle und Modell separat prüfen

Für eine Wissensdatenbank muss auch das Embedding-Modell gatewayseitig verfügbar sein. Ist nur ein Dialogmodell konfiguriert, schlägt der Upload von Dokumenten weiterhin fehl. Klären Sie in diesem Fall, ob das Gateway eine Embedding-Schnittstelle anbietet, und entscheiden Sie dann über einen separaten Embedding-Anbieter.

5. Prüfung und Fehlersuche in Reihenfolge

Legen Sie nach der Konfiguration einen neuen Dialog an, wählen Sie das gerade hinzugefügte Modell und senden Sie „Antworte nur mit OK“. Bei einem Fehler gehen Sie in dieser Reihenfolge vor und installieren nicht sofort den Client neu:

Symptom Häufige Ursache Behandlung
401 Unauthorized Key falsch, abgelaufen oder nicht gespeichert Key neu einfügen, auf Leerzeichen achten
404 Not Found /v1 in der Base URL passt nicht /v1 wie oben beschrieben ergänzen oder entfernen
model not found Modell-ID falsch oder nicht freigeschaltet Genaue Kennung von der Preisseite kopieren
Modellliste lässt sich nicht abrufen Gateway bietet keine Listen-Schnittstelle Modell-ID manuell hinzufügen
Dialog bricht ab Netzwerkschwankung oder Timeout Proxy prüfen, Parallelität senken, erneut versuchen
Wissensdatenbank meldet Fehler Embedding-Modell nicht konfiguriert Ein verfügbares Embedding-Modell separat einrichten

Ein oft übersehener Punkt: Firmennetzwerke oder Proxy-Software können SSE-Streaming blockieren; dann lässt sich eine Anfrage senden, aber keine Antwort empfangen. Deaktivieren Sie testweise die Streaming-Ausgabe. Funktioniert die nicht-gestreamte Antwort, prüfen Sie gezielt Proxy und Firewall.

6. Mehrere Modelle und Alltagsnutzung

Der Wert von Cherry Studio liegt darin, unterschiedliche Aufgaben zu trennen. Praktisch bewährt hat sich:

  1. Ein allgemeines Modell für alltägliche Fragen, schnell und kostenkontrolliert.
  2. Ein Modell mit langem Kontext für Zusammenfassungen langer Texte, in einem eigenen Assistenten.
  3. Ein codefähigeres Modell für Programmieraufgaben.
  4. Ein separates Embedding-Modell für die Wissensdatenbank.
  5. Für jeden Assistenten einen klaren System-Prompt, damit Anweisungen nicht jedes Mal wiederholt werden.

Je mehr Modelle, desto wichtiger ist die Kontextkontrolle. Ein vollständiges Dokument in jeden Dialog zu kopieren, verteuert jede Anfrage. Was in die Wissensdatenbank gehört, sollte zuerst dort abgelegt werden; wo eine Zusammenfassung genügt, sollte mit ihr gearbeitet werden.

7. Sicherheit und Team-Nutzung

  • Der Key liegt lokal auf dem Client; bei gemeinsam genutzten Rechnern sollten Systemkonten getrennt sein.
  • Speichern Sie keine langlebigen Keys auf gemeinsam genutzten Firmengeräten.
  • Vergeben Sie Keys pro Projekt, damit Verbrauch und Widerruf gatewayseitig nachvollziehbar bleiben.
  • Fügen Sie keine Kundenprivatsphäre, Vertragstexte oder unmaskierte Daten in den Client ein.
  • Prüfen Sie regelmäßig den Gateway-Verbrauch. Bei ungewöhnlichem Wachstum zuerst den Key sperren und dann die Ursache untersuchen.

Häufige Fragen

Ist Cherry Studio kostenlos?

Der Client selbst kann kostenlos verwendet werden. Die Kosten für Modellaufrufe erhebt der konfigurierte API-Anbieter. Maßgeblich sind die aktuelle Client-Version und die Preisseite des Gateways.

Warum meldet der Client trotz eingetragenem Key 401?

Prüfen Sie zuerst, ob der Key überflüssige Leerzeichen enthält, und dann, ob er zu der Plattform der aktuellen Base URL gehört. Keys verschiedener Gateways sind nicht austauschbar; außerdem kann der Key gelöscht oder das Kontingent aufgebraucht sein.

Gehört /v1 in die Base URL?

Richten Sie sich nach dem Hinweis der aktuellen Version. Die meisten OpenAI-kompatiblen Konfigurationen benötigen /v1, manche Clients ergänzen es automatisch. Entscheidend ist, ob die Anfrage /v1/chat/completions erreicht; bei 404 passen Sie das Ende der Adresse an.

Lassen sich Claude- oder Gemini-Modelle verwenden?

Ja, sofern das Gateway die Modelle im OpenAI-kompatiblen Format bereitstellt und Sie die exakte Modell-ID eintragen. Bei Modellen mit abweichendem nativem Protokoll sind einzelne Parameter möglicherweise nicht kompatibel; maßgeblich ist die Dokumentation des Gateways.

Funktioniert Cherry Studio offline?

Nein. Der Client ist nur die Oberfläche; die Inferenz findet in der entfernten API statt. Ohne Netzwerk oder bei nicht erreichbarem Gateway kann ein Dialog nicht abgeschlossen werden.

Nächste Schritte

Die Konfiguration von Cherry Studio ist nicht kompliziert; schwierig ist die Abstimmung von Base URL, Key und Modell-ID. Prüfen Sie zuerst per curl, bevor Sie den Client öffnen, und suchen Sie Fehler in der Reihenfolge 401, 404, model not found. Für einen einheitlichen Modelleinstieg und Verbrauchsverwaltung können Sie sich im ZSQH AI Gateway registrieren; Modelle und Preise stehen auf der Seite Modellpreise.

Weiterlesen: