Die Fehlermeldungen von Cherry Studio wirken vielfältig, lassen sich aber in Ebenen zerlegen: Wurde die Identität akzeptiert? Stimmen Adresse und Modell? Wurde die Anfrage überhaupt gesendet? Hat der Upstream gedrosselt? Wurde die Antwort unterwegs abgeschnitten? Wer Ebene für Ebene prüft, kommt schneller ans Ziel als durch wiederholtes Neuinstallieren des Clients.

Dieser Artikel ordnet 401, 404, 429, Verbindungsfehler, Streaming-Abbrüche und Fehler der Wissensdatenbank, nennt die Prüfreihenfolge, Diagnosebefehle und Methoden zur Beweissicherung. Menünamen und Log-Zugänge können sich je nach Version ändern; maßgeblich ist die aktuelle Version.

Hinweis: Cherry Studio ist ein Produkt seines jeweiligen Inhabers, OpenAI ist eine Marke seines jeweiligen Inhabers. Dieser Artikel dient nur der technischen Fehlersuche; es besteht keine Zugehörigkeit zu den genannten Herstellern. Modelle und Preise entnehmen Sie den Modellpreisen.

1. Zuerst die Prüfreihenfolge festlegen

Halten Sie bei einem Fehler vier Dinge fest: HTTP-Statuscode, Fehlermeldung im Antwortkörper, Zeitpunkt der Anfrage und die vom Gateway zurückgegebene Request-ID. Ohne diese Angaben bleibt nur „es ist irgendwann einmal fehlgeschlagen“; mit ihnen lässt sich die konkrete Anfrage und der Upstream nachverfolgen.

Gehen Sie dann in dieser Reihenfolge vor und ändern Sie jeweils nur eine Variable:

  1. Fragen Sie das Gateway direkt mit curl ab und prüfen Sie, ob Adresse, Key und Modell gültig sind.
  2. Klappt curl, der Client aber nicht, prüfen Sie Clientkonfiguration, Proxy und Protokolltyp.
  3. Klappen weder Client noch curl, prüfen Sie Key, Guthaben, Modell-ID und Gateway-Status.
  4. Scheitern nur lange Antworten oder die Wissensdatenbank, prüfen Sie Streaming, Timeouts und Embedding-Modell.
Symptom Häufige Ursache Zuerst prüfen
401 Unauthorized Key falsch, abgelaufen, mit Leerzeichen oder von einer anderen Plattform Passen Key und Base URL zusammen?
404 Not Found Pfad enthält /v1 zu viel oder zu wenig Ende der API-Adresse
model not found Modell-ID falsch geschrieben, Groß-/Kleinschreibung oder nicht freigeschaltet Modell-ID und Preisseite
429 Too Many Requests Parallelität, Frequenz oder Guthaben am Limit Antwort-Header und Gateway-Verbrauch
Verbindungs-Timeout Proxy, DNS, Firewall oder Zertifikat Systemproxy und Netzwerk
Antwort bricht mittendrin ab Streaming-Verbindung durch Proxy oder Timeout getrennt Streaming abschalten und vergleichen

2. 401: Key und Authentifizierung

401 bedeutet, dass der Server den Key nicht akzeptiert. Häufige Ursachen:

  • Beim Kopieren sind Leerzeichen, Zeilenumbrüche oder Anführungszeichen mitgekommen; die tatsächlich gesendete Zeichenkette ist unvollständig.
  • Der Key gehört zu einer anderen Plattform, wurde aber unter der aktuellen Base URL eingetragen.
  • Der Key wurde gelöscht oder rotiert, das zugehörige Projekt ist deaktiviert, oder das Guthaben ist aufgebraucht.
  • Der Client hat den Key nicht gespeichert; im Eingabefeld steht scheinbar ein Wert, die Anfrage enthält aber nichts.
  • Es wird das Anthropic- oder Gemini-Protokoll gegen einen OpenAI-kompatiblen Endpunkt verwendet, sodass das Authentifizierungsformat nicht passt.

Kopieren Sie den Key neu und prüfen Sie, dass davor und dahinter keine Leerzeichen stehen. Vergewissern Sie sich außerdem, dass Base URL und Key von derselben Plattform stammen. Unterstützt der Client „Prüfen“ oder „Verbindung testen“, nutzen Sie das zuerst und bestätigen Sie anschließend mit curl. Wenn curl funktioniert, der Client aber 401 meldet, prüfen Sie vor allem, ob der Key wirklich gespeichert wurde und ob der Protokolltyp stimmt.

3. 404 und model not found

Ein 404 bedeutet nicht zwingend, dass die Schnittstelle abgeschaltet wurde; meist ist der Pfad falsch zusammengesetzt. Typische Fälle:

  • In der Base URL steht die vollständige Endpunktadresse, und der Client hängt /chat/completions erneut an, sodass der Pfad doppelt erscheint.
  • /v1 fehlt, wo es nötig wäre, oder steht dort, wo es nicht hingehört.
  • Der Anbietertyp ist falsch gewählt, etwa ein OpenAI-kompatibler Endpunkt als Anthropic oder Gemini konfiguriert.
  • Modell-ID, Groß-/Kleinschreibung, Datums-Suffix und Bindestriche weichen von der Preisseite ab.
  • Das Modell existiert, ist für den aktuellen Key aber nicht freigeschaltet.

model not found und 404 sind getrennt zu betrachten: Ersteres bedeutet, die Adresse ist erreichbar, das Modell aber falsch; Letzteres kann schon am Routing scheitern. Fragen Sie zuerst /v1/models ab, um zu sehen, welche Modelle das Gateway meldet. Ist die Listen-Schnittstelle nicht verfügbar, kopieren Sie die genaue ID aus den Modellpreisen, tragen sie manuell ein und versuchen es erneut.

4. 429: Rate-Limit, Parallelität oder Guthaben

429 hat mindestens zwei Bedeutungen, die unterschiedliche Reaktionen erfordern:

  • Frequenz- oder Parallelitätslimit: zu viele Anfragen in kurzer Zeit oder mehrere gleichzeitig geöffnete Sitzungen und Agenten.
  • Guthaben oder Kontingent erschöpft: Das Projekt des Keys hat kein verfügbares Budget oder die Obergrenze erreicht.

Sehen Sie zuerst in Antwortkörper und -Header. retry-after nennt eine empfohlene Wartezeit. Nennt die Fehlermeldung ausdrücklich Quota oder Balance, wiederholen Sie nicht weiter mit Backoff, sondern prüfen Sie das Guthaben in der Konsole. Nur bei reinem Rate-Limit ist exponentielles Backoff sinnvoll, ergänzt um zufälliges Jitter, damit nicht alle Clients in derselben Sekunde erneut anfragen.

In Cherry Studio lassen sich leicht mehrere Assistenten gleichzeitig öffnen und Modelle im Batch vergleichen, wodurch die Parallelität unbemerkt steigt. Prüfen Sie zunächst mit einer Sitzung und einem Modell und stellen Sie den Rest schrittweise wieder her.

5. Verbindungsfehler, SSL und Proxy

Verbindungsfehler äußern sich häufig als endloses Laden mit Timeout, „keine Verbindung“ oder Zertifikatsfehler. Cherry Studio kennt üblicherweise drei Proxy-Modi: Systemproxy, benutzerdefinierter Proxy und kein Proxy. Sie liegen in den System- oder allgemeinen Einstellungen; die genaue Bezeichnung richtet sich nach der Version.

Prüfreihenfolge:

  1. Vergewissern Sie sich, dass Systemproxy oder VPN laufen und der Client auf „Systemproxy“ steht.
  2. Bei einem benutzerdefinierten Proxy: Adresse und Port prüfen, zum Beispiel http://127.0.0.1:7890.
  3. Die Bypass-Liste prüfen; die Zieldomain darf nicht fälschlich ausgeschlossen oder erzwungen über den Proxy geleitet werden.
  4. Testweise auf „Kein Proxy“ wechseln, um zu erkennen, ob die Proxy-Kette die Ursache ist.
  5. Bei TLS-Interception im Firmennetz prüfen, ob Systemzertifikat und Vertrauenskette vollständig sind.
  6. Die Systemzeit prüfen; eine große Abweichung lässt die Zertifikatsprüfung scheitern.

Ein häufiger Fehler ist, die Proxy-Adresse in das API-Adressfeld zu schreiben. Die API-Adresse ist die HTTPS-Adresse des Modell-Gateways; der Proxy gehört in die Proxy-Einstellungen. Beides nicht vermischen.

6. Unterbrochene Streaming-Ausgaben

Streaming-Antworten hängen an langlebigen Verbindungen. Häufig erscheint das erste Zeichen, dann stockt die Ausgabe nach Sekunden oder Minuten, oder nur ein Teil des Inhalts wird angezeigt. Ursachen sind Proxy-Pufferung, Idle-Timeouts, Gateway-Timeouts und Netzwerkwechsel.

Schalten Sie zuerst das Streaming ab und wiederholen Sie dieselbe Frage. Funktioniert die nicht gestreamte Antwort, liegt das Problem meist in der Übertragungskette; prüfen Sie Proxy-Software, Firewall und Timeouts des Reverse Proxy. Ein Reverse Proxy muss die Antwortpufferung abschalten und das Lese-Timeout verlängern, sonst wird SSE gesammelt am Stück zurückgegeben oder mittendrin gekappt.

Unterscheiden Sie außerdem „das Modell hat wirklich gestoppt“ von „die Verbindung wurde getrennt“. Ersteres endet meist mit einem Abschlussmarker, Letzteres hinterlässt oft ohne Fehlercode nur einen halben Text. Halten Sie beide Fälle getrennt fest, um später Client, Gateway und Netzwerk auseinanderzuhalten.

7. Fehler in Wissensdatenbank und Embedding

Fehler der Wissensdatenbank treten meist nicht an der Chat-Schnittstelle auf, sondern beim Einbetten oder Abrufen:

  • Es ist nur ein Chat-Modell konfiguriert, aber kein nutzbares Embedding-Modell.
  • Das Embedding-Modell unterstützt die aktuelle Embedding-Schnittstelle nicht, oder die Vektordimension passt nicht zum Index.
  • Eine hochgeladene Datei lässt sich nicht parsen, etwa ein gescanntes PDF ohne extrahierbaren Text.
  • Das Embedding-Modell wurde gewechselt, der Index aber nicht neu aufgebaut; alte Vektoren und neue Abfragen passen nicht zusammen.
  • Reranking- oder Retrieval-Dienst ist nicht erreichbar, was sich als leere Trefferliste oder Timeout zeigt.

Die Wissensdatenbank von Cherry Studio kann mit Stichwortsuche oder mit Embedding-Modellen als hybride Suche arbeiten; beim Modellwechsel löst die Oberfläche einen Neuaufbau aus. Prüfen Sie vor dem Neuaufbau, ob das neue Modell aufrufbar ist, und ändern Sie nicht gleichzeitig die Zerlegungsparameter, sonst lässt sich die Ursache der Qualitätsänderung nicht bestimmen. Die konkreten Menüpunkte richten sich nach der aktuellen Dokumentation.

8. Logs, Diagnosebefehle und Beweissicherung

Cherry Studio bietet einen Entwicklermodus, in dem sich die Aufrufkette im Request anzeigen lässt, um Modell- und Tool-Fehler zu lokalisieren; der Zugang richtet sich nach der Version. Auf Gateway-Seite sollten Request-ID, Modellname, Dauer und Token-Verbrauch vorliegen. Nur wenn die Zeitstempel beider Seiten zusammenpassen, lässt sich bestimmen, in welchem Abschnitt das Problem lag.

Erzeugen Sie zuerst eine minimale Reproduktion mit curl:

export ZSQH_API_KEY="sk-Ihr-Schluessel"

# 1. Adresse und Key pruefen
curl -sS "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -w "\nHTTP %{http_code}\n"

# 2. Modellaufruf pruefen
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"}]}' \
  -w "\nHTTP %{http_code}\n"

# 3. TLS-Handshake und Zertifikatskette separat pruefen
openssl s_client -connect ai.zhongshangqihang.com:443 -servername ai.zhongshangqihang.com </dev/null

Die drei Befehle entsprechen drei Fragen: Key und Adresse, Modell und Parameter, TLS und Zertifikat. Wo ein Schritt scheitert, prüfen Sie auf dieser Ebene weiter; ändern Sie nicht gleichzeitig Key, Adresse und Modell.

Häufige Fragen

Hilft bei 401 immer ein neuer Key?

Nicht unbedingt. Ein neuer Key schließt Probleme des Keys selbst aus. Wenn aber Base URL und Key-Plattform nicht zusammenpassen, das Protokoll falsch gewählt ist oder der Client den Key nicht wirklich speichert, hilft auch der zehnte Key nicht. Prüfen Sie zuerst, wohin die Anfrage tatsächlich geht.

Bedeutet 404, dass das Modell abgeschaltet wurde?

Meist ist der Pfad der Base URL falsch oder die Modell-ID fehlerhaft. Fragen Sie zuerst /v1/models per curl ab und vergleichen Sie die Kennung mit den Modellpreisen. Erst wenn beides stimmt, kommt eine Abschaltung des Modells in Betracht.

Muss bei 429 immer die Parallelität gesenkt werden?

Nein. Lesen Sie zuerst die Fehlermeldung: Nur bei reinem Rate-Limit sind weniger parallele Anfragen und Backoff sinnvoll. Bei fehlendem Guthaben bringt langsameres Senden nichts; prüfen Sie Balance oder Budget in der Konsole. Der Header retry-after hilft bei der Einschätzung der Wartezeit.

Warum bricht nur die Streaming-Antwort ab?

Streaming nutzt langlebige Verbindungen und wird leichter durch Proxy-Pufferung, Idle-Timeouts der Firewall oder Timeouts des Reverse Proxy gekappt. Schalten Sie Streaming zum Vergleich ab; funktioniert die normale Antwort, prüfen Sie Proxy und Timeouts, statt den Client wiederholt neu zu installieren.

Muss man Wissensdatenbank- und Chat-Fehler getrennt untersuchen?

Ja. Der Chat nutzt die Chat-Schnittstelle; die Wissensdatenbank umfasst zusätzlich Datei-Parsing, Embedding-Modell, Vektorindex und Retrieval-Dienst. Prüfen Sie zuerst den Chat, dann separat, ob das Embedding-Modell aufrufbar ist, die Dimensionen passen und der Index neu aufgebaut werden muss.

Nächste Schritte

Die Prüfreihenfolge lässt sich in einem Satz merken: erst curl, dann Client; erst Statuscode, dann Logs; jeweils nur eine Variable ändern. Wer einen einheitlichen OpenAI-kompatiblen Zugang, Request-Logs und Verbrauchsverwaltung benötigt, kann sich beim ZSQH AI Gateway registrieren; Modelle und Preise entnehmen Sie den Modellpreisen.

Weitere Artikel: