ZCode: eigener Anbieter (Desktop und CLI)

ZCode als eigenen Anbieter mit QCode.cc verbinden: Desktop laut offizieller Doku, ZCode CLI 0.17.1 mit Anthropic, OpenAI Chat und Responses getestet.

Brauchen Sie einen API-Key? Registrieren →·Endpunkte & Base-URLs →

Zuletzt überprüft: 2026-11-10 · 📄 Laut offizieller Dokumentation (ZCode-Desktop v3.17.2, im README und Changelog vom 2026-11-03) · ✅ QCode-Anbindung mit ZCode CLI 0.17.1 getestet (2026-11-10)

Ja, ZCode kann Ihren eigenen API-Schlüssel und Endpunkt nutzen. In der Desktop-App fügen Sie ihn über Add Provider hinzu; die quelloffene ZCode CLI liest ihn aus ~/.zcode/v2/provider_config.json. Stand 2026-11-10, getestet mit ZCode CLI 0.17.1: QCode funktioniert über alle drei Protokolle (Anthropic Messages, OpenAI Chat Completions, OpenAI Responses), und eine Anmeldung bei Z.ai oder BigModel ist nicht nötig. Die Desktop-Schritte folgen der offiziellen Dokumentation.

Auf einen Blick¶

Welches Protokoll¶

ZCode bietet drei Wege zu einem Modell, die sich darin unterscheiden, wo das Kontingent herkommt:

Diese Seite behandelt den dritten Weg. QCode bietet Claude nur über das Anthropic-Protokoll und GPT nur über die OpenAI-Protokolle an; GLM, Kimi, DeepSeek und Qwen funktionieren über Anthropic und OpenAI Chat (siehe Endpunkte & API-Pfade):

Den API-Pfad ergänzt ZCode selbst. Im CLI-Quellcode (normalizeAnthropicBaseURL) erhält eine Anthropic-Base-URL, die nicht auf /v1 endet, ein /v1, und das SDK hängt danach /messages an; https://api.qcode.cc/api landet also bei /api/v1/messages. Bei den beiden OpenAI-Typen wird /chat/completions bzw. /responses direkt an die Base URL gehängt, daher enden beide Werte auf /openai/v1. Hängen Sie kein / an. Derselbe Schlüssel funktioniert auch auf us.qcode.cc und asia.qcode.cc; tauschen Sie nur den Host und behalten Sie den Pfad.

Desktop-App (📄 laut offizieller Dokumentation)¶

Die folgenden Schritte folgen der offiziellen Dokumentation zu v3.17.2. Dieselben QCode-Adressen haben den Test mit der ZCode CLI bestanden; in der Desktop-App bestätigt Ihre erste Testnachricht die Verbindung.

Installation¶

Laut offizieller Installationsseite „Supports macOS (Apple Silicon / Intel), Windows (x64 / ARM64), and Linux (x64, ARM64, AppImage, DEB, RPM).“; v3.17.2 ist als neueste Version markiert.

• macOS: Öffnen Sie die heruntergeladene ZCode.dmg und ziehen Sie ZCode.app in den Ordner „Programme“. Meldet macOS, die App sei beschädigt, lautet die offizielle Lösung xattr -dr com.apple.quarantine /Applications/ZCode.app.
• Windows: Laden Sie das Installationsprogramm herunter, doppelklicken Sie es und folgen Sie dem Assistenten.
• Linux: Laden Sie .AppImage, .deb oder .rpm herunter; für ein AppImage führen Sie chmod +x ZCode-*.AppImage aus.

Die Installationsprogramme finden Sie auf zcode.z.ai.

QCode als Anbieter hinzufügen¶

Die Dokumentation zeigt Anbieter mit einem Endpunkt und ein DeepSeek-Beispiel mit beiden, sagt aber nicht, wie ZCode zwischen zwei Endpunkten eines Anbieters wählt. Diese Seite legt deshalb einen Anbieter pro Protokoll an:

1. Öffnen Sie ZCode, klicken Sie im Chatfeld auf den Modellnamen und dann unten in der Liste auf Manage Models. Damit öffnet sich Settings -> Model Settings. Beim ersten Start ohne nutzbares Modell führt auch Use API Key auf dem Startbildschirm zu den Anbietereinstellungen.
2. Klicken Sie unten in der Anbieterliste links auf Add Provider.

3. Für den ersten Anbieter:

4. Name: QCode Claude (den Namen wählen Sie selbst; die offizielle Seite nennt Beispiele wie claude oder deepseek)

5. Anthropic endpoint: https://api.qcode.cc/api (offiziell heißt es „Choose the vendor Base URL from the dropdown, or enter the API base URL manually“; geben Sie die Adresse manuell ein)
6. API Key: Ihr QCode-Schlüssel (beginnt mit cr_)
7. Klicken Sie auf Add Model und tragen Sie jede Modell-ID ein, zum Beispiel claude-sonnet-5-5. Der offizielle Text: „click Add Model and enter the model IDs supported by that service“.
8. Schalten Sie den Aktivierungsschalter ein („Turn on the enable switch to start using it“) und speichern Sie.
9. Wiederholen Sie das mit dem Namen QCode OpenAI, OpenAI endpoint https://api.qcode.cc/openai/v1, demselben Schlüssel und Modellen wie gpt-6.1-sol und deepseek-v4-flash.

Verwenden Sie die Modell-IDs von qcode.cc/models Zeichen für Zeichen; dort stehen auch die Preise pro Modell. Die chinesischen Modelle funktionieren auch über den Anthropic-Endpunkt, Sie können sie also in QCode Claude führen. Die Desktop-Dokumentation nennt die Endpunkte Anthropic und OpenAI und führt keine eigene Responses-Option auf; für Responses nutzen Sie die CLI unten.

Die Desktop-Konfigurationsdatei¶

Das offizielle FAQ nennt ~/.zcode/v2/config.json als die Datei für „Model provider setup (API keys, base URLs, model lists)“; behandeln Sie sie daher als Geheimnis und committen Sie sie nicht. Die Seite nennt eine Regel dazu: „a provider's options only recognizes connection settings such as apiKey, baseURL, apiKeyRequired, and headers; any other keys added by hand (e.g. reasoning_effort, vl_high_resolution_images) are silently ignored and never written into the request body.“ Richten Sie Anbieter in der Oberfläche ein, statt die Datei von Hand zu bearbeiten. Laut FAQ sind Umgebungsvariablen im Terminal und die Modelleinrichtung der Desktop-App getrennte Einstiegspunkte, die nicht automatisch synchronisiert werden.

ZCode CLI (✅ getestet 2026-11-10)¶

Stand 2026-11-10, getestet mit ZCode CLI 0.17.1: Alle drei QCode-Protokolle funktionieren über ~/.zcode/v2/provider_config.json, ohne zcode login.

Aus dem Quellcode bauen¶

Die CLI wird als Quellcode verteilt: Der Schnellstart baut sie aus dem Repository. Benötigt werden Git, Node.js 24.14.0 und pnpm 10.33.2 (maßgeblich ist die mise.toml im Repository). Führen Sie die Befehle im Wurzelverzeichnis des Repositorys aus:

git clone https://github.com/zai-org/ZCode.git
cd ZCode
pnpm install --frozen-lockfile
pnpm --filter @zcode/cli... build
node apps/zcode-cli/packages/cli/dist/zcode.cjs --version
node apps/zcode-cli/packages/cli/dist/zcode.cjs doctor --json

In den folgenden Befehlen steht zcode für node /absolute/path/to/zcode.cjs; lassen Sie die Dateien, die der Build daneben ablegt, an ihrem Platz.

provider_config.json anlegen¶

Speichern Sie Folgendes als ~/.zcode/v2/provider_config.json und ersetzen Sie cr_xxx durch Ihren QCode-Schlüssel. Es ist die Anthropic-Konfiguration aus dem Test:

{
  "schemaVersion": 1,
  "config": {
    "providerConfigRules": {
      "providerRules": [
        {
          "providerId": "qcode",
          "providerName": "QCode",
          "config": {
            "group": "standard-personal",
            "access": { "type": "api-key", "apiKey": "cr_xxx" },
            "api": {
              "type": "anthropic-messages",
              "baseUrl": "https://api.qcode.cc/api"
            },
            "personalModelIds": ["claude-haiku-5-5"]
          }
        }
      ]
    },
    "modelConfigRules": {
      "providerModelRules": [],
      "manualProviderModelRules": []
    },
    "defaultModelSelection": {
      "providerId": "qcode",
      "modelId": "claude-haiku-5-5"
    }
  }
}

Für ein anderes Protokoll ändern Sie api.type, api.baseUrl und die Modell-ID (in personalModelIds und in defaultModelSelection.modelId):

Zwei Punkte aus der offiziellen CLI-Anleitung:

• Das Feld heißt api.baseUrl und wird anders geschrieben als options.baseURL in der Desktop-Datei; die CLI liest provider_config.json, nicht ~/.zcode/v2/config.json.
• Die Anleitung sichert keine ${ENV}-Ersetzung in apiKey zu; der Schlüssel steht daher im Klartext in der Datei. Schränken Sie die Rechte ein und nehmen Sie die Datei nicht in Git auf:

chmod 600 ~/.zcode/v2/provider_config.json

Nicht interaktiv prüfen¶

zcode --prompt "Reply with one word: ready. Do not call tools." \
  --cwd /path/to/project --mode plan --json --no-color

--json liefert sessionId, response und Laufdaten; eine response mit ready bedeutet, dass der Anbieter funktioniert. Geben Sie immer --mode an: Ohne diese Option läuft --prompt im Modus yolo, der Befehle ausführt und Dateien ändert. zcode ohne Argumente startet die interaktive TUI.

Prüfen¶

1. Desktop: Wählen Sie im Modellwähler des Chatfelds ein Modell des neuen Anbieters und senden Sie eine kurze Testanweisung, wie die offizielle Seite empfiehlt („send a short test instruction“).
2. CLI: Führen Sie die Prüfung mit --prompt oben aus.
3. Öffnen Sie probe.qcode.cc, geben Sie Ihren QCode-Schlüssel ein und prüfen Sie, ob die Anfrage mit diesem Modell erscheint.
4. Schlüssel und Pfad ohne ZCode testen:

KEY="cr_your_key"

# Anthropic Messages
curl -sS https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-5-5","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'

# OpenAI Chat Completions
curl -sS https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"model":"deepseek-v4-flash","max_tokens":32,
       "messages":[{"role":"user","content":"ping"}]}'

Fehlerbehebung¶

ZCode wandelt die gewählte Denkstufe für den Endpunkt um: „OpenAI-compatible endpoints use the top-level reasoning_effort field, while Anthropic-compatible endpoints use thinking / effort.“

Bekannte Einschränkungen¶

• Der Desktop-Teil folgt der offiziellen Dokumentation zu v3.17.2; Menünamen können sich zwischen Versionen ändern. Der CLI-Teil wurde mit 0.17.1 und einem Modell pro Protokoll getestet.
• Laut offizieller Seite lassen sich für Drittanbietermodelle noch keine eigenen Anfrageparameter ergänzen.
• Die Desktop-Dokumentation nennt die Endpunkte Anthropic und OpenAI; Responses steht über openai-responses in der CLI zur Verfügung. QCode bietet derzeit keine Gemini-Modelle an.
• CLI: Der Schlüssel liegt im Klartext in provider_config.json, und --prompt ohne --mode läuft im Modus yolo.

Verwandte Seiten¶

• Endpunkte & API-Pfade — Tabelle Protokoll × Modellfamilie
• Übersicht der Tool-Kompatibilität — welches Tool welches Protokoll spricht
• Kimi Code CLI einrichten — ein weiterer Terminal-Agent mit Anthropic-, OpenAI-Chat- und Responses-Anbietern
• MiniMax Code einrichten — Desktop-App und mcode-CLI mit denselben drei API-Formaten
• DeepSeek Harness (dsh) — ein weiteres Agent-Harness mit Formular für eigene Modelle
• Chinesische Modelle — IDs und Pfade für GLM / Kimi / DeepSeek / Qwen

Enterprise →