Chatbox API-Key einrichten: Modelle, Sicherheit und Sync (2026)

Auch bei derselben Aufgabe – Chatbox an eine eigene API anbinden – ist bei manchen nach fünf Minuten alles erledigt, während andere wiederholt auf 401 stoßen. Der Unterschied liegt selten am Client, sondern an Erstellung, Ablage und Nutzungsgrenzen des Keys. Dieser Artikel behandelt vier Fragen rund um den API-Key: Wie wird er erstellt, wie werden mehrere Modelle konfiguriert, wo liegt er, und wie wird er rotiert und Fehlern zugeordnet?

Hinweis: Chatbox ist eine Marke ihres jeweiligen Inhabers. Dieser Artikel dient nur der technischen Einrichtung; es besteht keine Zugehörigkeit zum Chatbox-Team. Modelle und Preise entnehmen Sie den Modellpreisen, die Oberfläche richtet sich nach der aktuellen Version.

1. Zuerst zwei Arten von „Key-Quellen“ unterscheiden

In Chatbox können zwei Zugangsdaten parallel existieren: das Konto für den Chatbox-AI-Dienst und der API-Key, den Sie für einen benutzerdefinierten Anbieter eintragen. Die Abrechnung erfolgt über verschiedene Stellen, und auch die Fehlersuche unterscheidet sich grundlegend.

Quelle	Kostenstelle	Geeignet für	Beachten
Chatbox-AI-Konto	nach Client-Tarif	Nutzer, die keine Keys verwalten wollen	Hat nichts mit dem benutzerdefinierten Key zu tun
Eigener API-Key	Abrechnung beim API-Anbieter	Nutzer mit Gateway- oder Modellkonto	Muss selbst verwahrt und rotiert werden
Lokales Modell	lokale Hardware	Daten dürfen das Gerät nicht verlassen	Kein entfernter Key nötig

Wenn trotz erfolgreicher Anmeldung ein 401 erscheint, prüfen Sie zuerst, welcher Anbieter in der aktuellen Sitzung ausgewählt ist. Eine erfolgreiche Kontomeldung bedeutet nicht, dass der Key des benutzerdefinierten Anbieters korrekt eingetragen ist.

2. Key erstellen: Benennung, Zuordnung und Rechte

Registrieren Sie sich beim ZSQH AI Gateway und legen Sie den Key in der Konsole an. Drei Dinge sollten gleich beim ersten Versuch stimmen:

Nachvollziehbar benennen: Format „Gerät-Zweck-Nutzer“, etwa chatbox-mac-alice.
Ein Key, ein Zweck: Desktop, Mobilgerät und Automatisierungsskripte trennen, damit Fehler leichter zu lokalisieren sind.
Zuordnung dokumentieren: Erstellungsdatum, Verantwortlicher und Zweck im internen Verzeichnis festhalten.

Der Key wird üblicherweise nur bei der Erstellung einmal vollständig angezeigt und ist nach dem Schließen der Seite nicht mehr sichtbar. Speichern Sie ihn sofort im Passwortmanager und versenden Sie keinen Screenshot in Gruppenchats. Unterstützt die Konsole Limits, Modellbereiche oder IP-Beschränkungen, richten Sie diese nach dem Prinzip minimaler Rechte ein. Bei Unsicherheit gilt als Untergrenze: ein eigener Key pro Zweck.

3. Mehrere Anbieter und Modelle in Chatbox konfigurieren

Mehrere Modelle bedeuten nicht mehrere Keys. Üblicherweise hat ein Anbieter einen Key, unter dem mehrere Modell-IDs hängen:

Einstellungen öffnen und „Modellanbieter“ aufrufen.
Einen OpenAI-kompatiblen Anbieter hinzufügen; der Name sollte ein Umgebungspräfix enthalten.
Base URL eintragen, üblicherweise https://ai.zhongshangqihang.com/v1.
API-Key eintragen und prüfen, dass keine Leerzeichen davor oder dahinter stehen.
Modell-IDs manuell hinzufügen oder die Modellliste abrufen.
Für jedes Modell den Typ wählen: Chat, Vision, Reasoning oder Tool-Aufruf.
Auf „Prüfen“ klicken und anschließend im Chat die Modelle wechseln.

Die Modell-ID richtet sich nach den Modellpreisen. Den Anzeigenamen können Sie anpassen, die API-Kennung muss jedoch zeichengenau übereinstimmen. Benennen Sie Chat- und Vision-Modelle getrennt, etwa „Chat-Haupt“ und „Vision-Screenshot“, damit die Auswahl nicht verwechselt wird.

Wenn im Team auch Cherry Studio, LobeChat oder andere Clients verwendet werden, sollten Anbieternamen und Modell-Aliase einheitlich sein. So lässt sich vermeiden, dass dieselbe Person in verschiedenen Clients unterschiedliche Modelle nutzt.

4. Wo liegt der Key: lokal, Sync und Backup

Die Desktop-Version speichert die Konfiguration üblicherweise im lokalen Anwendungsdatenverzeichnis, die mobile Version im App-Sandbox. Der genaue Pfad hängt von Betriebssystem und Version ab; manuelles Bearbeiten der Konfigurationsdatei ist nicht empfehlenswert.

Beim Thema Synchronisierung sind drei Dinge zu trennen:

Chatverlauf-Sync: Ob und in welchem Umfang unterstützt, hängt von Clientversion und Kontotarif ab.
Einstellungs-Sync: Die Anbieterkonfiguration kann mit dem Konto synchronisiert werden oder nur lokal bleiben.
Key-Sync: „Konfiguration wird synchronisiert“ bedeutet nicht automatisch „der Key wird sicher synchronisiert“. Viele Clients schreiben den Key in Konfigurations- oder Backup-Dateien.

Behandeln Sie exportierte Backups, migrierte Konfigurationsverzeichnisse und geteilte Screenshots daher als sensibel. Beim Gerätewechsel ist es besser, den Key neu einzutragen, statt das gesamte Datenverzeichnis zu kopieren; widerrufen Sie den alten Key, sobald das bisherige Gerät nicht mehr genutzt wird.

5. Minimale Rechte: Der Key soll nur das Nötige können

Bei API-Keys gilt nicht „so wenige wie möglich“, sondern „so klar abgegrenzt wie möglich“. Praktikable Maßnahmen:

Jedes Teammitglied erhält einen eigenen Key, keine gemeinsame Nutzung.
Produktion und Test trennen; Test-Keys erhalten niedrigere Limits.
Keys nur auf den Geräten speichern, auf denen sie gebraucht werden; auf öffentlichen Rechnern nach der Nutzung löschen.
Budgets, Modell-Whitelists oder Verbrauchswarnungen in der Gateway-Konsole vollständig aktivieren, sofern verfügbar.
In Logs und Tickets nur die letzten Zeichen des Keys nennen, niemals den vollständigen Schlüssel.

Unterstützt der Client mehrere Anbieter, lässt sich zusätzlich nach „Arbeit/Privat“ trennen. Bei einer Offenlegung muss dann nur ein Key widerrufen werden, ohne andere Geräte zu beeinträchtigen.

6. Rotation und Widerruf im festen Rhythmus

Rotieren Sie mindestens alle 90 Tage und sofort bei Personaländerungen, Geräteverlust oder versehentlich weitergegebener Konfiguration. Die Reihenfolge darf nicht vertauscht werden:

In der Konsole einen neuen Key mit Datums-Suffix anlegen.
In Chatbox den Key des Anbieters durch den neuen Wert ersetzen.
Eine Testnachricht senden und prüfen, ob das Modell normal antwortet.
Erst nach erfolgreicher Funktion des neuen Keys den alten widerrufen.
Den Gateway-Verbrauch prüfen, um fremde Aufrufe auszuschließen.
Das interne Verzeichnis aktualisieren und das Rotationsdatum eintragen.

Zur Prüfung genügt zunächst ein Befehl, der nur den Statuscode liefert:

export ZSQH_API_KEY="sk-neuer-schluessel"

curl -sS -o /dev/null -w "%{http_code}\n" \
  "https://ai.zhongshangqihang.com/v1/models" \
  -H "Authorization: Bearer $ZSQH_API_KEY"

Ein 200 bestätigt die Authentifizierung; bei 401 prüfen Sie zuerst, ob der Key vollständig kopiert wurde. Bietet das Gateway keine Modelllisten-Schnittstelle, testen Sie stattdessen mit einer normalen Chat-Anfrage. Ändern Sie während der Rotation nicht gleichzeitig Base URL und Modell-ID, sonst lässt sich nicht feststellen, welcher Schritt das Problem verursacht hat.

7. Häufige Fehler: nach Statuscode aufteilen

Symptom	Häufige Ursache	Vorgehen
`401 Unauthorized`	Key falsch, abgelaufen, widerrufen oder mit Leerzeichen	Neu erstellen und vollständig einfügen
`403 Forbidden`	Keine Modellberechtigung, regionale oder richtlinienbedingte Sperre	Rechte und Modellbereich in der Konsole prüfen
`404 Not Found`	Pfad der Base URL falsch	Prüfen, ob `/v1` nötig ist
`429 Too Many Requests`	Parallelität oder Kontingent begrenzt	Parallelität senken, Verbrauch und Limit prüfen
`5xx`	Upstream-Dienst gestört	Später erneut versuchen, Anfragezeit festhalten

Ändern Sie bei der Fehlersuche jeweils nur eine Variable. Zuerst klären, ob „dieser Key“ oder „dieses Modell“ das Problem ist: Mit einem anderen Key oder einem anderen Modell lässt sich die Ursache schnell eingrenzen.

8. Übergabecheckliste für Teams

Wenn die folgenden Punkte in der Übergabedokumentation stehen, lassen sich die meisten „nach dem Wechsel funktioniert nichts mehr“-Fälle vermeiden:

Verantwortlicher, Zweck, Erstellungsdatum und nächstes Rotationsdatum des Keys.
Anbietername, Base URL und Liste der Modell-IDs.
Auf welchen Geräten Keys gespeichert sind und welche Geräte gemeinsam genutzt werden.
Ablauf zum Widerruf bei Ausscheiden, Wechsel oder Geräteverlust.
Zugang und Ansprechpartner für die Prüfung auffälligen Verbrauchs.

Häufige Fragen

Wird der Key mit dem Chatverlauf auf andere Geräte synchronisiert?

Nicht zwangsläufig. Chatverlauf-Sync und Konfigurations-Sync sind zwei verschiedene Dinge; ob der Key mit der Konfiguration übertragen wird, hängt von Clientversion und Anmeldeart ab. Betrachten Sie die Sync-Funktion nicht als Tresor für Schlüssel; beim Gerätewechsel ist erneutes Eintragen sicherer.

Kann ein Key gleichzeitig am Desktop und am Handy verwendet werden?

Technisch meist ja, dauerhaft empfehlenswert ist es aber nicht. Getrennte Keys pro Gerät lassen sich bei Verlust oder Offenlegung einzeln widerrufen, ohne die andere Seite zu beeinträchtigen.

„Prüfen“ im Client ist erfolgreich, der Chat meldet aber 401 – warum?

Prüfen Sie zuerst, ob im Chat der Anbieter und das Modell ausgewählt sind, die Sie gerade konfiguriert haben. Bei mehreren parallel vorhandenen Anbietern geht die Anfrage häufig an einen anderen Anbieter, in dem kein Key hinterlegt ist.

Müssen nach einer Key-Rotation die Modelle neu hinzugefügt werden?

Normalerweise nicht. Modell-IDs gehören zur Anbieterkonfiguration; ein Key-Wechsel ändert nur die Authentifizierung. Leert der Client nach dem Wechsel jedoch die Modellliste, fügen Sie die Modelle erneut hinzu; maßgeblich bleibt die Preisseite.

Darf der Key in Proxy-Software oder Browser-Erweiterungen eingetragen werden?

Davon ist abzuraten. Der Key sollte nur in vertrauenswürdigen Clients und der Gateway-Konsole erscheinen. Proxy-Software, Screenshot-Tools und Browser-Erweiterungen können Konfigurationen lesen oder weiterleiten; wo er nicht gebraucht wird, sollte er nicht hinterlegt werden.

Nächste Schritte

Die Key-Verwaltung in Chatbox lässt sich so zusammenfassen: ein Key pro Zweck, Konfiguration und Backups wie sensible Dateien behandeln, bei der Rotation zuerst den neuen Key anlegen und erst danach den alten widerrufen. Für einen einheitlichen Zugang sowie Verbrauchs- und Rechteverwaltung können Sie sich beim ZSQH AI Gateway registrieren; Modelle und Preise entnehmen Sie den Modellpreisen.