Cherry Studio bringt mehrere Modellanbieter in einem Desktop-Client zusammen. Das ist bequem, doch die Key-Verwaltung wird leicht vernachlässigt: Wer hat ihn angelegt, welche Modelle sind damit erreichbar, wo liegt er, wandert er in ein Backup, und wird er nach dem Ausscheiden eines Mitarbeiters noch verwendet? Dieser Artikel gibt eine praktikable Reihenfolge für Erstellung, Konfiguration, Speicherung, Synchronisierung, Rotation, Berechtigungen und Fehlersuche.

Hinweis: Cherry Studio ist eine Marke von CherryHQ. Dieser Artikel dient nur der technischen Diskussion; es besteht keine Zugehörigkeits- oder Kooperationsbeziehung zu CherryHQ. Bezeichnungen, Speicherorte und Menüpunkte können sich je nach Version ändern; maßgeblich sind die aktuelle Client-Version und die offizielle Dokumentation. Modelle und Preise entnehmen Sie den Modellpreisen.

1. Zuerst drei Arten von „Cherry Studio Key“ unterscheiden

Der Begriff wird oft vermischt:

  • Client- oder Enterprise-Plattform-Zugangsdaten: für Anmeldung, Enterprise-Verwaltung oder herstellereigene Dienste; Rechte und Abrechnung legt der Hersteller fest.
  • Modellanbieter-Keys: werden von OpenAI, Anthropic, Google und anderen ausgestellt und in das jeweilige Anbieterfeld eingetragen.
  • Gateway-Keys: werden von OpenAI-kompatiblen Diensten wie dem ZSQH AI Gateway ausgestellt; ein Key kann mehrere Modelle erreichen.

Dieser Artikel behandelt die dritte Art. Sie dient nicht zur Anmeldung bei Cherry Studio und kann auch nicht die Schnittstellen des Client-Herstellers aufrufen. Wählen Sie bei der Konfiguration „Benutzerdefinierter Anbieter“ oder einen OpenAI-kompatiblen Zugang, statt den Gateway-Key in ein herstellerspezifisches Feld zu schreiben.

2. Key erstellen: zuerst Zweck und Obergrenze festlegen

Legen Sie nicht zuerst den Key an und überlegen dann, wofür er dienen soll – die umgekehrte Reihenfolge spart viel Arbeit:

  1. Öffnen Sie die Registrierungsseite des ZSQH AI Gateway, registrieren Sie sich und melden Sie sich in der Konsole an.
  2. Rufen Sie die Seite für API-Keys auf und legen Sie einen neuen Key an.
  3. Der Name sollte Nutzer, Gerät und Zweck erkennen lassen, etwa cherry-laptop-daily, nicht test.
  4. Legen Sie ein Ausgabenlimit und ein Ablaufdatum fest; unterstützt die Konsole Modellbereiche, begrenzen Sie die nutzbaren Modelle nach Projekt.
  5. Prüfen Sie das Kontoguthaben, damit die Konfiguration nicht erst bei der ersten Anfrage scheitert.
  6. Kopieren Sie den Key in einen Passwortmanager, nicht zuerst in Gruppenchats, Dokumente oder Tickets.

Bevor Sie in den Client wechseln, prüfen Sie per Kommandozeile, ob Key, Adresse und Modell zusammenpassen:

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

Enthält die Antwort das Feld choices, ist die Anfragekette in Ordnung. Bei 401 prüfen Sie zuerst den Key, bei 404 zuerst den Pfad /v1, bei „model not found“ zuerst die Modell-ID.

3. Anbieter und Modelle im Client konfigurieren

Der Einstieg in Cherry Studio ist üblicherweise „Einstellungen → Modellanbieter“. Die Schaltflächen heißen je nach Version etwas anders, die Felder sind aber weitgehend gleich:

Feld Empfohlene Eingabe Hinweis
Anbietertyp Benutzerdefiniert / OpenAI-kompatibel Kein herstellerspezifisches Protokoll wählen
API-Key sk-... In der Konsole erstellter Gateway-Key
API-Adresse https://ai.zhongshangqihang.com/v1 Kein Schrägstrich am Ende
Modell aus Liste laden oder manuell hinzufügen ID muss mit der Preisseite übereinstimmen

Nach dem Speichern können Sie „Modellliste abrufen“ verwenden oder Modell-IDs manuell eintragen. Modell-IDs unterscheiden zwischen Groß- und Kleinschreibung sowie Versionssuffixen; kennzeichnen Sie den Typ nach Zweck als Chat, Embedding, Vision und so weiter. Die konkreten Optionen richten sich nach der aktuellen Version. Prüfen Sie die Konfiguration anschließend mit „Testen“ oder einer Nachricht „Antworte nur mit OK“.

4. Mehrere Modelle sinnvoll aufteilen

Mehrere Modelle bedeuten nicht, die Liste vollzustellen, sondern jedem Assistenten genau eine Aufgabe zu geben:

  • Alltagsfragen: ein schnelles Allround-Modell mit kontrollierbaren Kosten.
  • Lange Texte und Verträge: ein Modell mit langem Kontext, in einem eigenen Assistenten, damit es nicht mit dem Alltagschat vermischt wird.
  • Code und strukturierte Ausgaben: ein Modell mit stabilen Coding-Fähigkeiten; prüfen Sie die benötigten Parameter.
  • Wissensdatenbank: ein separates Embedding-Modell konfigurieren; bei Bedarf zusätzlich ein Reranking-Modell.
  • Sensible Inhalte: vorzugsweise lokale Modelle oder vorher die Grenzen der Datenverarbeitung klären.

Formulieren Sie für jeden Assistenten einen klaren System-Prompt, um wiederholte Erklärungen zu sparen. Je mehr Modelle im Einsatz sind, desto wichtiger ist es, ganze Dokumente nicht immer wieder in den Chat zu kopieren, sondern zuerst in die Wissensdatenbank aufzunehmen.

5. Wo liegt der Key, und was ist bei Backup und Sync zu beachten?

Cherry Studio speichert Anbieterkonfiguration und Keys in den lokalen Anwendungsdaten. Die offizielle Dokumentation sagt nicht zu, dass der lokale Speicher verschlüsselt ist; behandeln Sie die Dateien daher als sensibel: Festplattenverschlüsselung aktivieren, Sperrbildschirm-Passwort setzen und das Anwendungsdatenverzeichnis nicht in öffentliche Cloud-Laufwerke oder Code-Repositories legen.

Für Backups nennt die offizielle Dokumentation WebDAV, S3-kompatiblen Speicher und lokale Verzeichnisse. Ein vollständiges Backup enthält Chats, Assistenten, Wissensdatenbank, Anhänge und Anbieterkonfiguration – inklusive der API-Keys. Ein reduziertes Backup ist kleiner, kann die Wissensdatenbank aber nicht vollständig wiederherstellen. Eine Echtzeit-Synchronisierung zwischen mehreren Geräten beschreibt die Dokumentation nicht; üblich ist, auf Rechner A zu sichern und auf Rechner B wiederherzustellen.

Deshalb gilt:

  • Backup-Dateien wie Schlüsseldateien behandeln, nicht teilen und nicht auf nicht vertrauenswürdigen Clouds ablegen.
  • Für jedes Gerät einen eigenen Key anlegen, nicht einen Key auf alle Rechner kopieren.
  • Vor einer Migration ein vollständiges Backup erstellen und nach der Wiederherstellung Anbieter, Modelle und Wissensdatenbank einzeln prüfen.
  • Auf gemeinsam genutzten Rechnern getrennte Systemkonten verwenden, damit sich Konfigurationen nicht überschreiben.

6. Rotation und Widerruf

Rotieren Sie mindestens alle 90 Tage oder sofort bei Ausscheiden eines Teammitglieds, Verlust eines Geräts oder Verdacht auf Offenlegung. Die Reihenfolge lautet: zuerst neu anlegen, dann umstellen, zuletzt deaktivieren – den alten Key nicht direkt löschen.

  1. Legen Sie einen neuen Key mit gleichen Rechten an, der Name erhält ein Datums-Suffix.
  2. Ersetzen Sie den API-Key in Cherry Studio und prüfen Sie jeden Anbietereintrag.
  3. Senden Sie eine Testanfrage und vergewissern Sie sich, dass im Gateway-Log Aufrufe des neuen Keys erscheinen.
  4. Beobachten Sie Fehlerquote und Verbrauch, um übersehene Skripte oder Geräte zu finden.
  5. Deaktivieren Sie den alten Key und löschen Sie ihn erst nach einer Weile.

Cherry Studio kann für einen Anbieter mehrere Keys hinterlegen und reihum verwenden, was Lastspitzen verteilt. Das bedeutet aber nicht, dass Keys geteilt werden dürfen; Abrechnung und Verantwortlichkeit bleiben getrennt.

7. Minimale Rechte und Teamregeln

  • Ein Key pro Person, ein Key pro Zweck; für Automatisierung eigene Keys anlegen.
  • Wenn Limits, Ablaufdatum und Modellbereich verfügbar sind, alle drei setzen, mindestens die ersten beiden.
  • Über ein einheitliches Gateway anbinden, damit Mitglieder-, Modell- und Verbrauchslogs für die Abrechnung vorliegen.
  • Ein Verzeichnis führen: nur Key-Name, Inhaber, Zweck, Erstellungs- und Ablaufdatum, niemals der vollständige Key.
  • Monatlich ungenutzte Keys, Keys über Limit und auffällige Authentifizierungsfehler prüfen.
  • Erstellung, Übergabe und Deaktivierung von Keys in Onboarding- und Offboarding-Prozesse aufnehmen.
  • Festlegen, welche Daten in Cloud-Modelle dürfen; sensible Projekte vorher bewerten.
  • Regelmäßig die Modellpreise prüfen, da sich Preise und verfügbare Modelle ändern.

8. Fehlersuche

  • 401 / Invalid API Key: Key falsch, deaktiviert oder beim Einfügen mit Leerzeichen oder Zeilenumbruch versehen.
  • 403: Limit ausgeschöpft, Rechte fehlen oder das Modell liegt außerhalb des erlaubten Bereichs.
  • 404: API-Pfad falsch; prüfen Sie, ob /v1 doppelt oder gar nicht vorhanden ist.
  • 429: Rate-Limit oder Ausgabenlimit erreicht; prüfen Sie den Verbrauch in der Konsole.
  • Timeout oder Abbruch: Proxy, Firewall und Streaming-Einstellungen prüfen.
  • Fehler in der Wissensdatenbank: Embedding-Modell nicht konfiguriert oder das Gateway bietet keine passende Embedding-Schnittstelle.
  • Nach Wiederherstellung eines Backups unbrauchbar: prüfen, ob die Anbieterkonfiguration wiederhergestellt wurde, und Key neu eintragen oder validieren.
  • Nach Key-Wechsel weiterhin Fehler: Speicherung bestätigen und im Gateway-Log prüfen, ob die Anfrage ankommt.

Häufige Fragen

Wo liegt der API-Key von Cherry Studio, und ist er sicher?

Er liegt in den lokalen Anwendungsdaten; der genaue Pfad hängt von System und Version ab. Die offizielle Dokumentation sagt keine Verschlüsselung zu, und ein vollständiges Backup enthält den Key. Behandeln Sie ihn als sensibel, aktivieren Sie Festplattenverschlüsselung und vermeiden Sie die Synchronisierung an öffentliche Orte.

Kann ein Key für mehrere Modelle verwendet werden?

In der Regel ja, solange das Gateway diesem Key die Modelle freigibt. Ob sich der Modellbereich einschränken lässt, hängt von der Konsole ab. Ohne diese Möglichkeit begrenzen Sie die Auswirkungen zumindest über Ausgabenlimit, Ablaufdatum und Logs.

Werden Keys beim WebDAV-Backup hochgeladen?

Laut offizieller Dokumentation enthält ein vollständiges Backup Anbieterkonfiguration und API-Keys. Wählen Sie einen vertrauenswürdigen Speicherort, aktivieren Sie Transportverschlüsselung und teilen Sie Backup-Dateien nicht. Bei besonders sensiblen Keys können Sie ein reduziertes Backup prüfen oder die Keys vor dem Backup entfernen.

Wie migriert man Konfiguration und Keys auf einen neuen Rechner?

Erstellen Sie zuerst ein vollständiges Backup, laden Sie es zu WebDAV oder S3 und stellen Sie es auf dem neuen Gerät wieder her; alternativ kann das lokale Backup-Verzeichnis übertragen werden. Prüfen Sie danach Anbieter, Modelle, Wissensdatenbank und Standardmodell und legen Sie für das neue Gerät einen eigenen Key an.

Was ist bei einer Key-Offenlegung zuerst zu tun?

Deaktivieren oder löschen Sie den Key, um den Schaden zu stoppen, und prüfen Sie anschließend auffälligen Verbrauch, Aufrufquellen und Zeiträume. Kontrollieren Sie danach Backups, Repositories, Chatverläufe und Screenshots und rotieren Sie bei Bedarf weitere Zugangsdaten derselben Umgebung.

Fazit

Die Key-Konfiguration in Cherry Studio ist nicht kompliziert; schwierig ist die langfristige Verwaltung: nachvollziehbare Namen, Obergrenzen, geschützte Speicherung, klare Backup-Grenzen und die Fähigkeit, bei einer Offenlegung schnell zu reagieren. Registrieren Sie sich zunächst beim ZSQH AI Gateway und legen Sie einen Key nur für den Client an; danach verschärfen Sie die Regeln nach Teamvorgaben und prüfen die Kosten regelmäßig anhand der Modellpreise.

Weitere Artikel: