Chatbox ist ein plattformübergreifender KI-Client für Desktop und Mobilgeräte. Er kann den integrierten Chatbox-AI-Dienst nutzen oder mit eigenem API-Key an einen selbst gewählten Modelldienst angebunden werden. Dieser Artikel behandelt den zweiten Fall: von der Installation über die Einrichtung eines OpenAI-kompatiblen Anbieters bis zu Prüfung, Synchronisierung und Teamkonfiguration.

Hinweis: Chatbox ist eine Marke ihres jeweiligen Inhabers. Dieser Artikel dient nur der technischen Einrichtung; es besteht keine Zugehörigkeit zum Chatbox-Team. Menünamen und Funktionszugänge richten sich nach der aktuellen Version, Modelle und Preise nach den Modellpreisen.

1. Installation: Plattform und Version zuerst klären

Die Desktop-Version eignet sich für lange Gespräche, große Dokumente und Screenshots; die mobile Version für kurze Fragen zwischendurch. Beide lassen sich kombinieren, die Konfigurationswege unterscheiden sich jedoch.

Drei Punkte bei der Installation:

  1. Aus einer vertrauenswürdigen Quelle herunterladen und vor der Installation App-Name und Entwicklerangaben prüfen.
  2. Auf Firmenrechnern zuerst die Software-Whitelist klären, damit die App nach der Installation nicht blockiert wird.
  3. Nach der Installation auf die aktuelle stabile Version aktualisieren, bevor Sie konfigurieren.

Ältere Versionen kennen unter Umständen keinen „benutzerdefinierten Modellanbieter“, oder die Feldnamen weichen ab. Wer eine alte Anleitung stur befolgt, trägt den Key häufig in das falsche Feld ein. Erst aktualisieren, dann anhand der Oberfläche vorgehen.

2. Drei Parameter vor dem Anschluss vorbereiten

Unabhängig vom Gateway braucht ein benutzerdefinierter Anbieter nur drei Angaben:

Parameter Beispiel Häufiger Fehler
API-Key sk-... Beim Kopieren Leerzeichen oder Zeilenumbruch mitgenommen
Base URL https://ai.zhongshangqihang.com/v1 Vollständige Endpunktadresse eingetragen
Modell-ID laut Preisseite Anzeigename statt API-Kennung verwendet

Den Key erstellen Sie nach der Registrierung beim ZSQH AI Gateway; benennen Sie ihn nach Gerät und Zweck, etwa chatbox-mac-work. Die Base URL ist die OpenAI-kompatible Adresse des Gateways. Die Modell-ID kopieren Sie aus den Modellpreisen und achten auf Groß-/Kleinschreibung, Versionssuffixe und Bindestriche.

Notieren Sie die drei Parameter zunächst an einem temporären Ort und entscheiden Sie nach der Konfiguration, ob sie gespeichert werden. Schreiben Sie den Key nicht in öffentliche Dokumente oder Chatverläufe.

3. OpenAI-kompatiblen Anbieter hinzufügen

Die Schaltflächen heißen je nach Version anders, die Reihenfolge ist jedoch ähnlich:

  1. Chatbox öffnen und „Einstellungen“ aufrufen.
  2. „Modellanbieter“ oder „Modelldienst“ finden.
  3. Auf „Hinzufügen“ oder „+“ klicken und einen neuen Anbieter anlegen.
  4. Als Namen etwas Erkennbares wie „ZSQH“ eintragen.
  5. Als API-Modus „OpenAI-kompatibel“ wählen, nicht Anthropic oder Gemini.
  6. API-Key und Base URL eintragen.
  7. Auf „Abrufen“ klicken, um die Modellliste zu laden; bei Fehlschlag die Modell-ID manuell hinzufügen.
  8. Auf „Prüfen“ klicken, um die Verbindung zu testen, und das neue Modell auswählen.

Unter einem Anbieter können mehrere Modelle liegen. Chat-, Vision- und Reasoning-Modelle gehören am besten in denselben Anbieter, damit die Auswahl übersichtlich bleibt. Wer Test- und Produktionsumgebung trennt, legt zwei Anbieter mit unterschiedlichen Präfixen an.

4. Base URL und Modell-ID richtig eintragen

Die Base URL ist die fehleranfälligste Angabe. Sie sollte bis /v1 reichen; den weiteren Pfad ergänzt der Client selbst. Wer zusätzlich /chat/completions einträgt, riskiert einen doppelten Pfad und damit 404.

Zwei Merksätze für die Diagnose:

  • Bei 401 zuerst den Key prüfen: abgelaufen, gelöscht oder von Leerzeichen umgeben?
  • Bei 404 zuerst den Pfad prüfen: testweise /v1 am Ende ergänzen oder entfernen, jeweils nur eine Änderung.

Die Modell-ID muss der API-Kennung auf der Preisseite entsprechen. Der Anzeigename ist meist schöner, aber für Anfragen ungeeignet. Besonders bei Modellen mit Datum, Versionsnummer oder Suffixen wie -mini zeichengenau prüfen.

5. Prüfen: erst curl, dann zurück zum Client

Prüfen Sie im Terminal zuerst, ob die Gateway-Seite funktioniert; damit schließen Sie die Hälfte der Fehlerquellen aus:

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 JSON-Antwort choices, sind Key, Adresse und Modell gültig. Prüfen Sie danach drei Dinge im Client:

  1. Eine kurze Frage senden und kontrollieren, ob das erste Zeichen ankommt.
  2. Zwei Rückfragen stellen und prüfen, ob der Kontext erhalten bleibt.
  3. Eine lange Antwort erzeugen lassen und prüfen, ob sie nicht mittendrin abbricht.

Bricht nur die lange Antwort ab, prüfen Sie zuerst Netzwerk und Streaming; scheitern alle Anfragen, kehren Sie zu Key und Base URL zurück. Ein erfolgreicher „Prüfen“-Test belegt nur die Basiskonnektivität, nicht alle Fähigkeiten.

6. Einstellungen und Sync: Desktop und Mobil abstimmen

Zu den Einstellungen von Chatbox gehören üblicherweise Standardmodell, Temperatur, Kontextlänge, Proxy und Datenverzeichnis. Ändern Sie zunächst drei Punkte: Standardmodell, Streaming ja/nein und Speicherort der Daten. Die übrigen Werte bleiben auf Standard, bis alles läuft.

Szenario Empfohlenes Vorgehen Beachten
Tägliche Nutzung am Desktop Anbieterkonfiguration speichern, Standardmodell festlegen Sitzungen regelmäßig exportieren
Kurze Fragen am Handy Eigenen Anbieter mit wenigen Modellen einrichten Auf gemeinsam genutzten Handys keinen Key dauerhaft speichern
Rechnerwechsel Key und Modell-ID neu eintragen Nicht das gesamte Konfigurationsverzeichnis kopieren
Gemeinsam genutztes Gerät Getrennte Systemkonten verwenden Sitzungen und Keys dürfen nicht gegenseitig sichtbar sein

Ob Konten-Cloud-Sync unterstützt wird und welche Inhalte er umfasst, hängt von Version und Anmeldeart ab; maßgeblich ist die Dateneinstellungsseite der App. Gehen Sie nicht davon aus, „Chatverläufe werden synchronisiert, also auch der Key“. Meist ist der Key lokale Konfiguration und muss auf einem neuen Gerät neu eingetragen werden; exportierte Backups können sensible Daten enthalten und sind wie Schlüsseldateien zu behandeln.

7. Teamnutzung: Konfiguration als Infrastruktur behandeln

Was kleine Teams am häufigsten vernachlässigen, ist nicht der Anschluss, sondern die Übergabe. Mindestens gilt:

  • Keys pro Person vergeben, nicht einen Key für alle.
  • Einheitliche Anbieternamen verwenden, etwa mit Präfix ZSQH-.
  • Im Gateway Budgets oder Verbrauchswarnungen einrichten, um Dauerlast zu vermeiden.
  • Bei Ausscheiden oder Geräteverlust zuerst den Key widerrufen und dann die übrigen Konten bearbeiten.
  • Base URL, Modell-IDs und Clientversion in der internen Dokumentation festhalten.

Der Nutzen liegt nicht in „ordentlicherer Verwaltung“, sondern in schnellerer Fehlersuche: Ist der Key einer Person ungültig, wurde ein Modell abgeschaltet, oder weicht die Clientversion ab?

8. Häufige Fragen

Funktioniert Chatbox ohne API-Key?

Der integrierte Chatbox-AI-Dienst lässt sich ohne eigenen Key nutzen; Kontingent und Abrechnung richten sich nach der aktuellen Version. Der BYOK-Modus verwendet den von Ihnen konfigurierten API-Anbieter, dessen Kosten nach Verbrauch berechnet werden. Beides nicht vermischen.

Gehört /v1 an das Ende der Base URL?

Bei den meisten OpenAI-kompatiblen Konfigurationen ja. Wenn es mit und ohne /v1 Fehler gibt, ermitteln Sie per curl die vollständige Adresse, die eine Antwort liefert, und tragen Sie diese im Client ein, statt zu raten.

Ist der Key defekt, wenn „Modellliste abrufen“ scheitert?

Nicht zwingend. Möglicherweise bietet das Gateway keine Modelllisten-Schnittstelle, oder der Pfad stimmt nicht. Fügen Sie zuerst manuell eine Modell-ID hinzu und prüfen Sie mit „Prüfen“ oder einer echten Unterhaltung. Funktioniert das, fehlt nur die Listen-Schnittstelle.

Desktop funktioniert, Mobil nicht – warum?

Prüfen Sie zuerst, ob auf beiden Geräten dieselbe Base URL und Modell-ID eingetragen sind, und dann, ob das Mobilnetz die Anfragen blockiert. Zugang und verfügbare Funktionen können sich zwischen Mobil und Desktop unterscheiden; maßgeblich ist die aktuelle Version. Speichern Sie keine Keys mit hohen Rechten dauerhaft auf dem Handy.

Bleibt die Konfiguration nach einem Rechnerwechsel erhalten?

Ob Chatverläufe und Konfiguration erhalten bleiben, hängt von Kontologin, Sync-Funktion und exportierten Backups ab. Tragen Sie den Key besser neu ein und widerrufen Sie den alten Key auf dem bisherigen Gerät, sobald es nicht mehr genutzt wird.

Nächste Schritte

Beim Anschluss einer eigenen API an Chatbox zählen drei Schritte: richtige Version installieren, richtige Base URL eintragen, richtige Modell-ID wählen. Erst mit curl prüfen, dann in den Client gehen; bei Fehlern zuerst 401 über den Key, 404 über den Pfad und „Modell nicht gefunden“ über die ID behandeln. Für einen einheitlichen Zugang und Verbrauchsverwaltung können Sie sich beim ZSQH AI Gateway registrieren; Modelle und Preise entnehmen Sie den Modellpreisen.

Weitere Artikel: