Cherry Studio ist ein verbreiteter Desktop-KI-Client für Windows, macOS und Linux. Das Programm stellt selbst keine Modelle bereit; sie kommen von den konfigurierten API-Anbietern. Neben eingebauten Anbietern lassen sich OpenAI-kompatible eigene Endpunkte hinzufügen – praktisch für Teams mit einem einheitlichen Gateway: eine Base URL, ein Key, und mehrere Modelle stehen zur Auswahl.

Dieser Beitrag beschreibt den üblichen Versionsstand von 2026 von der Installation über Anbieter, Modelle, Assistenten und Wissensbasis bis zur Nutzung im Team. Bezeichnungen in der Oberfläche ändern sich mit Versionen; maßgeblich ist die aktuelle Version.

Hinweis: Cherry Studio ist Produkt und Marke des jeweiligen Inhabers; OpenAI ist eine Marke von OpenAI, Inc. Dieser Beitrag dient der technischen Anbindung und steht in keiner Zugehörigkeits- oder Partnerschaftsbeziehung zu den genannten Unternehmen. Modelle, Schnittstellenumfang und Preise richten sich nach den Modellpreisen dieser Website.

1. Installation: offizielle Quellen bevorzugen

Cherry Studio bietet Desktop-Installationspakete; übliche Bezugsquellen sind die offizielle Website und die GitHub Releases des Projekts. Das passende Paket je System wählen:

  • Windows: Installationsprogramm herunterladen und den Hinweisen folgen.
  • macOS: DMG herunterladen und in den Programme-Ordner ziehen; blockiert das System den ersten Start, gemäß Systemhinweis freigeben.
  • Linux: AppImage oder das Paket der Distribution gemäß Projektangabe installieren.

Von „grünen“ Versionen unbekannter Herkunft oder modifizierten Paketen wird abgeraten. Der Desktop-Client speichert API-Keys und Chatverläufe; Installationspakete unklarer Herkunft bergen hohe Risiken. Nach der Installation unter „Einstellungen“ im Bereich „Über“ die Version prüfen und erst dann über ein Upgrade entscheiden; ältere Versionen können andere Schaltflächennamen und Feldpositionen haben.

2. Drei Parameter vorbereiten

Für einen eigenen Anbieter werden nur drei Dinge benötigt, doch jedes ist fehleranfällig:

Feld Empfohlene Eingabe Erläuterung
Anbietertyp OpenAI Verwendet das OpenAI-kompatible Protokoll
API-Adresse https://ai.zhongshangqihang.com/v1 Bis /v1 eintragen, nicht den vollständigen Schnittstellenpfad
API-Key sk-... In der Gateway-Konsole erstellen, nach Projekt benennen
Modell-ID API-Kennung von der Preisseite Nicht der Anzeigename auf der Website

Der Key wird nach der Registrierung im ZSQH AI Gateway in der Konsole erstellt. Empfohlen ist ein Key pro Projekt, um Verbrauch, Limit und Widerruf im Blick zu behalten. Die Modell-ID von der Seite Modellpreise kopieren und auf Groß-/Kleinschreibung, Bindestriche und Versions-Suffix achten.

3. Eigenen Anbieter hinzufügen

Am Beispiel der aktuellen üblichen Version:

  1. Cherry Studio öffnen und unten links auf das Zahnradsymbol klicken, um die Einstellungen zu öffnen.
  2. „Modellanbieter“ wählen.
  3. Unter der Anbieterliste auf „+ Anbieter hinzufügen“ klicken.
  4. Unter „Eigenen Anbieter hinzufügen“ den „Anbieternamen“ eintragen, etwa „ZSQH Gateway“.
  5. Den „API-Key“ eintragen.
  6. Unter „Endpunkteinstellungen“ OpenAI wählen; bietet das Gateway das Responses-Protokoll, kann unter „Weitere Einstellungen“ auch OpenAI Responses gewählt werden.
  7. Die API-Adresse eintragen, etwa https://ai.zhongshangqihang.com/v1.
  8. Auf „Hinzufügen“ klicken und speichern.

Fehlt „+ Anbieter hinzufügen“ in der Version, zuerst den Client aktualisieren. Die Bezeichnung des Endpunkttyps unterscheidet sich je nach Version, die Kernfelder bleiben jedoch gleich: Name, Key, Adresse. Bildgenerierung und Bildbearbeitung sind separate Base-URL-Optionen und dürfen nicht mit der Adresse der Dialogmodelle vermischt werden.

4. Modelle hinzufügen und Verbindung prüfen

Nach dem Speichern des Anbieters zur Modellliste des Anbieters zurückkehren; es gibt zwei Wege:

  • Modellliste abrufen: Der Client fragt die verfügbaren Modelle beim Gateway ab; nach Erfolg die benötigten Modelle auswählen.
  • Manuell hinzufügen: Auf „+“ klicken und die Modell-ID eingeben. Dieser Weg eignet sich, wenn das Gateway keine Listen-Schnittstelle anbietet oder der Abruf scheitert.

Die Modell-ID muss exakt mit der Preisseite übereinstimmen. Nach manuellem Hinzufügen außerdem prüfen, ob der Modelltyp „Dialog“ oder „Chat“ ist; bei falschem Typ erscheint das Modell nicht im Auswahlfeld der Dialogoberfläche. Embedding- und Bildmodelle werden je nach Zweck separat hinzugefügt.

Die Schaltfläche „Prüfen“ in der Oberfläche bestätigt vor allem, ob der API-Key verwendbar ist – nicht, ob jedes Modell für Sie freigeschaltet ist. Nach dem Speichern einen neuen Dialog anlegen, das eben hinzugefügte Modell wählen und „Antworte nur mit OK“ senden; erst das ist die vollständige Verifikation.

5. Zuerst mit curl prüfen, dann zurück zum Client

Wenn die Konfiguration hängt, mit einer minimalen Anfrage unterscheiden, ob das Problem am Gateway oder am Client liegt:

export ZSQH_API_KEY="sk-Ihr-Schluessel"

curl -sS "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"}]
  }'

Enthält die Antwort choices, sind Adresse, Key und Modell zumindest erreichbar; das Problem liegt dann meist in Client-Feldern oder einem Netzwerk-Proxy. Bei 401 zuerst Key und Leerzeichen prüfen, bei 404 /v1 und Modell-ID, bei 429 Verbrauch und Parallelität. Jeweils nur eine Variable ändern, nicht gleichzeitig Key, Adresse und Modell austauschen.

6. Assistenten: Modelle konkreten Aufgaben zuordnen

„Assistenten“ in Cherry Studio speichern Systemprompt, Modell und Parameter und eignen sich, wiederkehrende Arbeit zu fixieren. Eine praktische Aufteilung:

  • Für Alltagsfragen ein schnelles, kostenkontrolliertes Allroundmodell verwenden.
  • Für lange Zusammenfassungen einen eigenen Assistenten mit langem Kontext anlegen und die Ausgabestruktur im Prompt begrenzen.
  • Für Code-Aufgaben ein Modell mit stärkeren Coding-Fähigkeiten wählen und ausdrücklich verlangen, zuerst Dateien zu lesen und dann zu ändern.
  • Für Übersetzung und Glättung je einen Assistenten anlegen und Terminologie sowie Stilvorgaben in den Systemprompt schreiben.
  • Jeder Assistent löst nur eine Art von Aufgabe, damit der Prompt nicht immer länger wird.

In den Einstellungen lässt sich zudem ein Standardmodell festlegen, um die Auswahl bei jedem neuen Dialog zu sparen. Je mehr Modelle, desto wichtiger die Kontextkontrolle: Materialien, die in die Wissensbasis gehören, zuerst dort ablegen; was sich zusammenfassen lässt, nicht wiederholt als Ganzes einfügen.

7. Wissensbasis: ein Embedding-Modell ist optional

Der Einstieg zur Wissensbasis liegt links unter „Wissensbasis“; auf „Neu“ klicken, einen Namen vergeben, der die Grenzen des Materials beschreibt, und ein Embedding-Modell wählen. Die aktuelle Version bietet drei Wege:

  • Nicht verwenden: nur BM25-Schlüsselwortsuche, keine zusätzliche Konfiguration, geeignet zur ersten Validierung.
  • Cloud-Embedding-Modell: Der entsprechende Embedding-Dienst muss erreichbar sein; die Suche verbindet Schlüsselwörter und Vektoren.
  • Lokales Embedding-Modell: Zuerst unter „Einstellungen → Lokale Modelle“ ein Embedding-Modell herunterladen, dann in der Wissensbasis auswählen.

Läuft das Embedding über das Gateway, zuerst bestätigen, dass das Gateway eine Embedding-Schnittstelle und das passende Modell anbietet; sonst „Nicht verwenden“ oder ein lokales Embedding wählen. Nach dem Anlegen auf „Material hinzufügen“ klicken, zunächst ein bis zwei Dateien mit eindeutigen Antworten importieren und nach der Verarbeitung Testfragen stellen.

Ein Wechsel des Embedding-Modells kann einen „Neuaufbau der Wissensbasis“ auslösen. Vorher prüfen, ob das neue Modell verfügbar ist, und nicht gleichzeitig Modell und Chunk-Einstellungen ändern – sonst lässt sich nicht feststellen, wodurch sich das Ergebnis verändert hat.

8. Reihenfolge bei häufigen Störungen

Symptom Häufige Ursache Behandlung
401 – Authentifizierung fehlgeschlagen Key falsch, mit Leerzeichen oder nicht gespeichert Erneut einfügen und prüfen, ob der Key zum aktuellen Gateway gehört
404 Not Found API-Adresse mit /v1 zu viel oder zu wenig Nur bis /v1 eintragen, nicht den vollständigen Pfad
model not found Modell-ID falsch oder nicht freigeschaltet Exakte Kennung von der Preisseite kopieren
Modellliste lässt sich nicht abrufen Gateway bietet keine Listen-Schnittstelle Modell-ID manuell hinzufügen
Wissensbasis liefert schlechte Ergebnisse Chunking, Suchverfahren oder Materialqualität Zuerst mit kleinem Materialsatz testen, dann Chunking anpassen
Dialog bricht mittendrin ab Proxy, Firewall oder Netzwerkschwankung Streaming testweise abschalten, Proxy und Timeouts prüfen

Unternehmensnetze oder Proxy-Software können SSE-Streaming blockieren; typisch ist „Anfrage geht raus, Antwort kommt nicht zurück“. Streaming vorübergehend abschalten: Funktioniert die nicht gestreamte Variante, vor allem Proxy und Firewall prüfen statt wiederholt das Modell zu ändern.

9. Teamnutzung: geteilt werden Standards, nicht Keys

Cherry Studio ist ein Desktop-Client; die öffentliche Dokumentation führt Mehrbenutzer-Rechteverwaltung nicht als Kernfunktion. Teamnutzung ähnelt daher „einheitlicher Konfigurationsstandard plus lokale Clients“. Empfohlen:

  • Jede Person nutzt einen eigenen Gateway-Key mit Namenszuordnung; bei Austritt oder Offenlegung gezielt widerrufen.
  • Verbrauch und Limits im Gateway überwachen und Kosten nach Projekt aufteilen.
  • Systemprompts häufig genutzter Assistenten als Textvorlagen pflegen und einheitlich verteilen.
  • Material der Wissensbasis an einem teamkontrollierten gemeinsamen Ort halten, damit nicht verschiedene Versionen gepflegt werden.
  • Backups über WebDAV oder S3-kompatiblen Speicher anlegen, aber beachten, dass sie Provider-Konfiguration und API-Keys enthalten.
  • Backup-Dateien nicht in Gruppenchats senden und nicht auf nicht vertrauenswürdigen gemeinsamen Netzlaufwerken ablegen.
  • Auf gemeinsam genutzten Rechnern keine langlebigen Keys speichern und keine Kundenvertraulichkeiten oder unbereinigten Verträge in Dialoge einfügen.

Braucht das Team zentrale Audits, Limits und Rechte, liegt der Schwerpunkt auf der Gateway-Seite.

Häufige Fragen

Ist Cherry Studio kostenlos?

Der Client selbst ist kostenlos nutzbar; die Modellaufrufe werden vom konfigurierten API-Anbieter berechnet. Maßgeblich sind die aktuelle Client-Version und die Preisseite des Gateways.

Gehört /v1 in die Base URL?

Die meisten OpenAI-kompatiblen Konfigurationen benötigen /v1; https://ai.zhongshangqihang.com/v1 ist richtig. Nicht /v1/chat/completions eintragen – der Client ergänzt den Schnittstellenpfad selbst.

Was tun, wenn die Modellliste nicht abgerufen werden kann?

Zuerst prüfen, ob das Gateway eine Modelllisten-Schnittstelle anbietet. Ist sie nicht verfügbar oder schlägt der Abruf fehl, über „+“ die Modell-ID manuell eingeben; das Ergebnis ist gleichwertig. Maßgeblich ist die API-Kennung auf der Preisseite.

Muss für die Wissensbasis ein Embedding-Modell konfiguriert werden?

Nein. Die aktuelle Version erlaubt „Nicht verwenden“ und beantwortet grundlegende Fragen über BM25-Schlüsselwortsuche. Für Vektorsuche später ein Cloud- oder lokales Embedding-Modell konfigurieren und die Erreichbarkeit des Dienstes prüfen.

Kann das Team einen gemeinsamen Key verwenden?

Nicht empfehlenswert. Ein gemeinsamer Key erlaubt keine Zuordnung des Verbrauchs, und eine Offenlegung betrifft die ganze Gruppe. Keys pro Person, Projekt oder Umgebung mit Gateway-Limits und Nutzungsberichten sind kontrollierbarer.

Nächster Schritt

Die Anbindung von Cherry Studio ist nicht kompliziert; schwierig ist die Abstimmung von Base URL, Key und Modell-ID. Zuerst mit curl testen, dann in den Client gehen und bei Problemen in der Reihenfolge 401, 404, model not found suchen. Für einen einheitlichen Modelleingang und Verbrauchsverwaltung können Sie sich im ZSQH AI Gateway registrieren; Modelle und Preise entnehmen Sie den Modellpreisen.

Weiterführende Beiträge: