LobeChat vereint mehrere Modellanbieter, Plugins und Wissensdatenbanken in einer Oberfläche. Die vielen Konfigurationsfelder führen leicht zu Fehlinterpretationen. Die meisten Probleme liegen nicht am Modell selbst, sondern in einer von vier Ebenen: Der Key greift nicht, Adresse oder Modellname stimmen nicht, Kontingent oder Parallelität sind erschöpft, oder Netzwerk und Cross-Origin-Zugriff sind blockiert. Erst einordnen, dann Ebene für Ebene prüfen – das ist wirksamer als wiederholtes Neuinstallieren des Clients.

Der Artikel behandelt 401, 404, 429 und Verbindungsfehler und ergänzt Streaming-, Plugin- und Wissensdatenbank-Probleme. Oberflächen und Umgebungsvariablen ändern sich mit der Version; maßgeblich ist die aktuelle Dokumentation. Modelle und Preise entnehmen Sie den Modellpreisen, Preise können sich ändern.

Hinweis: LobeChat und LobeHub sind Produkte und Marken der jeweiligen Rechteinhaber. Dieser Artikel dient ausschließlich der technischen Fehlersuche; es besteht keine Zugehörigkeit zu den genannten Anbietern.

1. Erst Belege erfassen, dann die Kategorie bestimmen

Symptom Häufiger Statuscode oder Hinweis Erste Einschätzung Zuerst prüfen
401 Unauthorized invalid_api_key, leere Antwort Key nicht erkannt Vollständigkeit, zugehörige Adresse, Einbringung
404 / model not found not_found_error, model_not_found Pfad oder Modellname falsch Base URL, /v1, Modell-ID
429 Too Many Requests rate_limit_error, insufficient_quota Rate-Limit oder Kontingent Parallelität, Verbrauch, Abrechnung
Failed to fetch Kein Statuscode, Browserfehler Anfrage erhielt keine Antwort DNS, Proxy, Firewall, CORS
5xx server_error, Gateway-Fehlerseite Upstream- oder Gateway-Störung Retry und Request-ID notieren
Plugin oder Wissensdatenbank fehlerhaft Tool-Aufruf-Fehler, Upload-Fehler Fähigkeit oder Abhängigkeit fehlt Funktionsaufruf, Speicher, Embedding

Vor der Fehlersuche mindestens festhalten: Zeitpunkt, Version, Deployment-Art (Desktop, Web oder Docker), Statuscode, Antwortbody und Request-ID. Ohne diese Angaben bleibt nur Raten.

2. 401: Der Key wird nicht erkannt

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

  • Beim Kopieren sind Leerzeichen, Zeilenumbrüche oder Vollbreitzeichen hineingeraten; optisch gleich, tatsächlich anders.
  • Oberflächenkonfiguration und Umgebungsvariablen werden gemischt; die Anfrage nutzt nicht den erwarteten Key.
  • Der Key wurde gelöscht oder rotiert, oder das zugehörige Projekt ist deaktiviert.
  • Der Key von Anbieter A wird gegen die Adresse von Anbieter B gesendet.
  • Ein Unternehmensproxy fängt die Anfrage ab und liefert eine HTML-Anmeldeseite statt JSON.

Zuerst den Client umgehen und mit demselben Key und derselben Adresse eine minimale Anfrage senden:

export ZSQH_API_KEY="sk-IhrSchluessel"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"IhreModellID","messages":[{"role":"user","content":"Antworte nur mit OK"}]}' \
  -w "\nHTTP %{http_code}\n"

Eine Antwort mit 200 und choices bestätigt Key und Adresse; bleibt es bei 401, liegt das Problem bei Kopie, Rechten oder Proxy. Bei Docker-Deployment prüfen, ob die Variablen im Container angekommen sind: docker exec lobe-chat env | grep -i openai, der Containername richtet sich nach docker ps. Oberflächenkonfiguration gilt für den aktuellen Nutzer und kann nach Gerätewechsel oder Cache-Löschung verschwinden; im Team sind Umgebungsvariablen vorzuziehen.

3. 404 und model not found: Adresse und Modell getrennt prüfen

404 hat zwei Formen: Der Pfad existiert nicht oder das Modell existiert nicht. Erstere betrifft die URL, letztere die Modell-ID.

Beim Proxy-Adressfeld von LobeChat genügt je nach Gateway die Domain, in anderen Fällen ist /v1 nötig – entscheidend ist, ob das Gateway /v1 selbst weiterleitet. Maßstab ist, dass /v1 in der endgültigen Anfrageadresse genau einmal vorkommt. Ein häufiger Fehler: Der Host endet bereits auf /v1, und der Pfad wird erneut angehängt, sodass /v1/v1/chat/completions entsteht. Die Proxy-Adresse zeigt auf den API-Wurzelpfad, nicht auf den vollständigen /chat/completions-Pfad.

model not found hat nichts mit dem Pfad zu tun. Modell-IDs unterscheiden Groß- und Kleinschreibung, Versionssuffixe und Anbieterpräfixe und sollten von der Preisseite oder aus der Konsole kopiert werden. Wird die Liste über CUSTOM_MODELS verwaltet, zuerst mit -all,+einBestätigtFunktionierendesModell einen Minimaltest durchführen und erst danach weitere Modelle ergänzen; Kommas in ASCII-Schreibweise, ohne Leerzeichen. Erscheint ein Modell in der Liste, müssen Typ und Fähigkeiten trotzdem der Realität entsprechen, sonst scheitert der erste Aufruf.

403 bedeutet meist, dass der Key erkannt wird, das Modell oder die Funktion aber nicht erlaubt ist. Nicht mit 401 verwechseln und deshalb den Key tauschen.

4. CORS, Proxy und TLS: Fallstricke beim Browser-Direktzugriff

Sendet die Weboberfläche von LobeChat Anfragen aus dem Browser, muss das Gateway Cross-Origin-Anfragen der zugehörigen Domain erlauben. CORS-Fehler zeigen sich typischerweise als Access to fetch ... has been blocked by CORS policy in der Konsole, während curl einwandfrei funktioniert. Zwei Lösungen: Das Gateway erlaubt die entsprechende Origin, oder ein serverseitiger Proxy übernimmt die Weiterleitung und umgeht die Browserprüfung.

Läuft LobeChat hinter Nginx, Caddy oder Cloudflare, muss die Proxy-Ebene das Gateway erreichen; API-Host und HTTP-Proxy nicht verwechseln. System-Proxy, VPN, HTTP_PROXY und HTTPS_PROXY im Container können sich überlagern; nur eine Ebene behalten und interne Adressen über NO_PROXY ausnehmen.

TLS-Probleme äußern sich oft als UNABLE_TO_VERIFY_LEAF_SIGNATURE, meist bei unternehmensseitigen Entschlüsselungsproxys. Richtig ist die Installation des Unternehmens-Root-Zertifikats; NODE_TLS_REJECT_UNAUTHORIZED auf 0 zu setzen taugt nur zur vorübergehenden Eingrenzung und senkt die Sicherheit.

Auch der Plugin-Dienst muss die Origin von LobeHub zulassen. Beim Selbstbetrieb außerdem prüfen, ob die Plugin-Funktion aktiviert ist und das Modell Funktionsaufrufe unterstützt; sonst scheitert das Plugin erst in der Ausführung.

5. 429: Rate-Limits, Parallelität und Kontingent

429 hat zwei häufige Bedeutungen: zu viele Anfragen oder unzureichendes Kontingent. Erstere geht oft mit rate_limit_error einher, letztere mit insufficient_quota; die Gegenmaßnahmen sind entgegengesetzt.

  • Zu viele Anfragen: Parallelität senken, weniger gleichzeitig geöffnete Sitzungen und Clients; lange Kontexte erhöhen den Token-Verbrauch.
  • Kontingent erschöpft: Verbrauch und Abrechnung im Gateway prüfen, aufladen oder Key wechseln; reines Wiederholen hilft nicht.
  • Enthält der Antwort-Header Retry-After, diesen Wert abwarten; sonst exponentielles Backoff mit Zufallsanteil und einer Obergrenze für Versuche verwenden.
  • Bei einem gemeinsamen Team-Key teilen sich mehrere Geräte und Fenster dasselbe Parallelitätskontingent.

Tritt 429 nur bei langen Dialogen auf, zuerst den Kontext komprimieren oder eine neue Sitzung beginnen und anschließend das Kontextfenster des Modells prüfen. Die maximale Zahl mitgeführter Nachrichten zu senken lindert den Kontextdruck, ersetzt aber kein Verbrauchsmanagement.

6. Streaming bricht ab: Die Antwort stoppt auf halbem Weg

LobeChat gibt standardmäßig gestreamt zurück. Ein Abbruch mitten in der Antwort bedeutet meist nicht, dass das Modell defekt ist, sondern dass SSE durch einen Proxy gepuffert wird, die Verbindung im Leerlauf timeoutet oder der Upstream die Generierung unterbricht. Typisch: Die erste Hälfte kommt normal, die zweite endet abrupt, oder die Anzeige bleibt bei „tippt“.

Zuerst – soweit die Version es erlaubt – Streaming deaktivieren und dieselbe Frage vergleichen. Kommt die nicht gestreamte Antwort vollständig, liegt es an der SSE-Kette. Reverse Proxys müssen Response-Buffering abschalten und das Lese-Timeout verlängern, etwa proxy_buffering off und proxy_read_timeout in Nginx; auch CDNs wie Cloudflare können Ereignisströme puffern. Reasoning-Modelle „denken“ vor der Antwort längere Zeit und wirken blockiert; mit einer nicht gestreamten Anfrage prüfen, ob tatsächlich keine Antwort kommt.

7. Spezifische Fehler bei Plugins und Wissensdatenbank

Plugin-Fehler in drei Ebenen trennen: Unterstützt das Modell Funktionsaufrufe, ist das Plugin-Gateway erreichbar, erlaubt der Plugin-Dienst Cross-Origin-Anfragen. Beim Selbstbetrieb zusätzlich prüfen, ob die Plugin-Funktion aktiviert ist. Ohne Tool-Unterstützung lässt sich ein Plugin in der Oberfläche oft öffnen, scheitert aber bei der Ausführung.

Die Wissensdatenbank hat eigene Abhängigkeiten: PostgreSQL mit PGVector für Vektoren, S3-kompatibler Speicher für Originaldateien und ein verfügbares Embedding-Modell. Das Standard-Embedding ist häufig ein bestimmtes OpenAI-Modell, das das eigene Gateway nicht zwingend anbietet; es muss separat konfiguriert werden. Variablennamen und Werteformat richten sich nach der aktuellen Dokumentation.

Bei Upload-Fehlern Bucket-Adresse, Schlüssel, Rechte und CORS prüfen; bei Retrieval-Fehlern, ob der Index aufgebaut ist und die Embedding-Dimensionen übereinstimmen. Nach einem Wechsel des Embedding-Modells muss der alte Index meist neu erstellt werden. Die Verarbeitung von PDF und Word kann zusätzliche Dienste benötigen; wenn reiner Text funktioniert, komplexe Formate aber scheitern, in diese Richtung suchen.

8. Logs und Beweissicherung

  1. In den Entwicklerwerkzeugen das Network-Panel öffnen, die fehlgeschlagene Anfrage suchen und URL, Statuscode, Antwortbody und Header notieren; vor dem Teilen den Key entfernen.
  2. Mit docker logs -f lobe-chat Startfehler, fehlgeschlagene Migrationen und Verbindungs-Timeouts prüfen.
  3. Mit docker exec lobe-chat env bestätigen, dass die Variablen vorhanden sind; auf Schreibweise und Anführungszeichen achten.
  4. Im Container curl oder nslookup ausführen, um Container-Netzwerk, DNS und externes Gateway zu unterscheiden.
  5. Für ausführliche Logs mit DEBUG=lobe:* und LOG_LEVEL=debug starten und die Ausgabe verfolgen.
  6. Bei einer Meldung Version, Deployment-Art, Zeitpunkt, Statuscode und Request-ID beilegen; „verbindet nicht“ allein reicht zur Eingrenzung nicht.

9. Eine feste Prüfreihenfolge

  1. Mit curl direkt das Gateway ansprechen und prüfen, ob Key, Host und Modell gültig sind.
  2. Scheitert curl: DNS, Proxy, TLS, Firewall und Gateway-Status prüfen.
  3. Gelingt curl, scheitert LobeChat: API-Typ, doppeltes /v1, Modell-ID, CORS und Client-Proxy prüfen.
  4. Nach Statuscode verzweigen: 401 Key, 404 Pfad und Modell, 429 Verbrauch und Parallelität, Verbindungsfehler Netzwerk und Zertifikate.
  5. Pro Durchgang nur eine Variable ändern, sofort erneut testen und das Ergebnis notieren.

Diese Reihenfolge trennt Client- und Serverprobleme. Die meisten vermeintlichen LobeChat-Fehler lassen sich am Ende einer Konfigurationszeile oder einer Netzwerkschicht zuordnen. Für zentrale Verwaltung von Keys, Verbrauch und Modelleinstieg können Sie sich im ZSQH AI Gateway registrieren; verfügbare Modelle und Abrechnung entnehmen Sie den Modellpreisen.

Häufige Fragen

Bedeutet „Failed to fetch“ in LobeChat einen falschen Key?

Nicht zwingend. Der Hinweis besagt nur, dass der Browser keine gültige Antwort erhalten hat. Zuerst mit curl dieselbe Adresse testen; scheitert curl, DNS, Proxy, Firewall und Zertifikate prüfen; gelingt curl, CORS, Pfadzusammensetzung und Client-Proxy kontrollieren.

Warum funktioniert curl, während LobeChat 401 meldet oder leer bleibt?

Häufig weichen Key in der Oberfläche und Umgebungsvariable voneinander ab, beim Kopieren sind Leerzeichen hineingeraten, die Proxy-Adresse enthält /v1 zu wenig oder zu viel, oder der Browser blockiert Cross-Origin. Die endgültige Anfrageadresse und die Header Punkt für Punkt vergleichen.

Ein Modell wurde in CUSTOM_MODELS ergänzt, erscheint aber nicht in der Liste?

Prüfen, ob der Variablenname zur aktuellen Version passt, das Komma ASCII ist und keine Leerzeichen enthält, und ob der Container neu erstellt statt nur neu gestartet wurde. Zuerst mit -all,+einBestätigtFunktionierendesModell einen Minimaltest durchführen, dann weitere Modelle ergänzen.

Erholt sich ein 429 durch wiederholtes Retry?

Rate-Limit-bedingte 429 können sich nach Backoff und reduzierter Parallelität erholen; bei unzureichendem Kontingent hilft Wiederholen nicht, hier sind Abrechnung, Verbrauch oder ein Key-Wechsel zu prüfen. Zuerst den Fehlertyp im Antwortbody bestimmen, dann über Retries entscheiden.

Ist ein fehlgeschlagener Wissensdatenbank-Upload dasselbe Problem wie ein Chat-API-Fehler?

Meist nicht. Der Chat nutzt die Chat-Schnittstelle; die Wissensdatenbank hängt zusätzlich von Datenbank, Vektor-Erweiterung, Objektspeicher und Embedding-Modell ab. Zuerst diese Konfiguration bestätigen, dann Dateiformat und Verarbeitungsdienst prüfen.

Weiterlesen: