# DeepSeek Harness (dsh) mit QCode einrichten

> **Zuletzt überprüft**: 2026-11-09 · 📄 Laut offizieller Dokumentation (DeepSeek Harness 0.2.2-rc.1, am 2026-11-04 auf npm und GitHub veröffentlicht; die Repository-Dokumentation wurde am 2026-11-09 gelesen)

## Auf einen Blick

| Punkt | Details |
|---|---|
| Was es ist | DeepSeek Harness (`dsh`) ist ein Open-Source-Agent-Harness von DeepSeek AI; die Web-Oberfläche startet mit `dsh web` |
| Nutzbare Modelle | Claude ✅ (Anthropic-Messages-Provider) · GPT ✅ · GLM / Kimi / DeepSeek / Qwen ✅ (OpenAI-Chat-Completions-Provider) · Gemini ❌ (QCode bietet derzeit keine Gemini-Modelle an) |
| Protokoll & Base-URL | OpenAI Chat Completions: `https://api.qcode.cc/openai/v1` · Anthropic Messages: `https://api.qcode.cc/api` |
| Wo konfigurieren | **Settings → Models** → **Add model provider** → **Custom model API** |
| Wohin geschrieben | `$DSH_HOME/profiles/<profile>/cordis.patch.yml`; der Key liegt in `$DSH_HOME/.credentials.yaml` |
| Offizielle Dokumentation | [Modelle konfigurieren](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/user/guide/providers.md) · [Repository](https://github.com/deepseek-ai/deepseek-harness) |

DeepSeek Harness befindet sich in der Entwicklervorschau. Die offizielle README sagt: "THERE WILL BE COMPATIBILITY-BREAKING CHANGES." Gleichen Sie die von Ihnen eingesetzte Version mit dieser Seite ab.

## Welches Protokoll

Das **API protocol** eines eigenen Providers muss mit dem Protokoll des Gateways übereinstimmen. Die Auswahl bietet drei Optionen: OpenAI Chat Completions, OpenAI Responses und Anthropic Messages, gespeichert als `openai-completions`, `openai-responses` und `anthropic-messages`. Ein Provider spricht ein Protokoll, daher braucht ein Gateway mit zwei Protokollen zwei Provider.

QCode bietet Claude nur über das Anthropic-Protokoll und GPT nur über die OpenAI-Protokolle; die vier chinesischen Modellfamilien funktionieren über beide. Siehe [Endpunkte und API-Pfade](/docs/getting-started/endpoints-and-api-paths). Daraus ergeben sich zwei Provider:

| Provider | API protocol | Base-URL | Modell-IDs (Beispiele) |
|---|---|---|---|
| `qcode` | OpenAI Chat Completions (`openai-completions`) | `https://api.qcode.cc/openai/v1` | `gpt-6-sol`, `deepseek-v4-pro`, `glm-5.3`, `kimi-k3`, `qwen3.8-max` |
| `qcode-claude` | Anthropic Messages (`anthropic-messages`) | `https://api.qcode.cc/api` | `claude-sonnet-5`, `claude-opus-5` |

Die Provider-IDs sind frei gewählte Namen. Verwenden Sie die Modell-IDs von [qcode.cc/models](https://qcode.cc/models) Zeichen für Zeichen; die chinesischen IDs stehen auch unter [Chinesische Modelle](/docs/usage/cn-models). Hängen Sie kein `/` an eine Base-URL und setzen Sie keine `claude-…`-IDs hinter die OpenAI-Base-URL.

## Installation

DeepSeek Harness benötigt Node.js 24.9 oder neuer (das npm-Paket deklariert `node >=24.9.0`, und die Versionshinweise zu v0.2.2-rc.1 sagen: "Raise the minimum supported Node.js version to 24.9."). Installieren Sie Node.js und führen Sie aus:

```sh
npx @deepseek-ai/dsh web
```

Der Befehl startet die Web-Oberfläche standardmäßig auf `http://127.0.0.1:3080` und öffnet sie bei lokalem Start im Standardbrowser. Ein SSH-Start gibt nur die Host-URL aus. Mit `--no-open` läuft der Server ohne Browserfenster.

Für den Start aus einem Repository-Checkout:

```sh
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web
```

`$DSH_HOME` ist das Datenverzeichnis des Harness; standardmäßig `~/.dsh`, sofern Sie nicht die Umgebungsvariable `DSH_HOME` setzen. Lesen Sie vor dem Start den offiziellen [Sicherheitshinweis](https://github.com/deepseek-ai/deepseek-harness/blob/master/SAFETY.md).

## Konfiguration

Modelländerungen wirken ab der nächsten Anfrage, ohne den Server neu zu starten.

Die Web-Oberfläche folgt der Sprache des Browsers. Die Schritte unten nennen die englischen Bezeichnungen; in der deutschen Oberfläche heißen sie:

| Englische Oberfläche | Deutsche Oberfläche |
|---|---|
| Settings → Models | Einstellungen → Modelle |
| Add model provider · Custom model API | Modellanbieter hinzufügen · Kundenspezifisches Modell API |
| Provider ID · Display name · Base URL | Anbieter-ID · Anzeigename · Basis-URL |
| API protocol · API key | API-Protokoll · API-Schlüssel |
| Models · Add model · Fetch available models | Modelle · Modell hinzufügen · Verfügbare Modelle abrufen |
| Create provider | Anbieter erstellen |
| Model options · Reasoning levels · Image | Modelloptionen · Argumentationsebenen · Bild |

1. Öffnen Sie die Web-Oberfläche, dann **Settings → Models**, und wählen Sie **Add model provider**.
2. Wechseln Sie die Karte zu **Custom model API**. Sie ist für ein Relay, ein Firmen-Gateway, einen selbst betriebenen Server oder jeden Provider gedacht, der im installierten Katalog fehlt.
3. Füllen Sie das Formular für den ersten Provider:
   - **Provider ID**: `qcode` (kleingeschrieben; die ID ist dauerhaft, wählen Sie sie bewusst)
   - **Display name**: `QCode` (optional)
   - **Base URL**: `https://api.qcode.cc/openai/v1`
   - **API protocol**: OpenAI Chat Completions
   - **API key**: Ihr QCode-Key (beginnt mit `cr_`)
4. Wählen Sie in der Liste **Models** des Formulars (die offizielle Anleitung nennt sie Modellkatalog) **Add model** und tragen Sie die Modell-IDs ein, etwa `deepseek-v4-pro` und `gpt-6-sol`. **Fetch available models** fragt den Endpunkt nach seinen Modellen; das ist nur eine Erleichterung, und laut offizieller Anleitung funktionieren von Hand eingetragene IDs genauso, wenn der Abruf fehlschlägt oder nichts listet. Auf QCode listet der OpenAI-Endpunkt die GPT-Modelle, daher tragen Sie die chinesischen IDs von Hand ein.
5. Wählen Sie **Create provider**. Wiederholen Sie den Vorgang dann mit Provider ID `qcode-claude`, Display name `QCode Claude`, Base-URL `https://api.qcode.cc/api`, **API protocol** = Anthropic Messages, demselben Key und dem Modell `claude-sonnet-5` und wählen Sie erneut **Create provider**.
6. Öffnen Sie die Modellauswahl und wählen Sie ein Modell. Die Auswahl macht das Modell zugleich zum Standard für neue Sitzungen.

Keys sind nur beschreibbar: Nach dem Speichern erhält die Seite nur eine maskierte Beschreibung, niemals den Klartext. Der Key liegt in `$DSH_HOME/.credentials.yaml`, in den Einstellungen bleibt nur sein Verweis.

### Was die Seite schreibt

Zur Orientierung: Dieselben Provider sehen in `$DSH_HOME/profiles/<profile>/cordis.patch.yml` so aus. Beim Standardstart mit `dsh web` ist `<profile>` gleich `web`, der Pfad also `$DSH_HOME/profiles/web/cordis.patch.yml`. Dieses Dokument schreibt die Seite für Sie; bearbeiten Sie es von Hand nur, wenn Sie eine Einstellung brauchen, die das Formular nicht anbietet.

```yaml
- id: llm-pi-ai
  config:
    providers:
      qcode:
        displayName: QCode
        apiKeyEnv: QCODE_API_KEY
        api: openai-completions
        baseURL: https://api.qcode.cc/openai/v1
        models:
          - id: deepseek-v4-pro
          - id: gpt-6-sol
      qcode-claude:
        displayName: QCode Claude
        apiKeyEnv: QCODE_CLAUDE_API_KEY
        api: anthropic-messages
        baseURL: https://api.qcode.cc/api
        models:
          - id: claude-sonnet-5
```

`apiKeyEnv` ist ein Verweis auf die Anmeldedaten: Die Seite leitet ihn aus der Provider ID ab (`qcode` → `QCODE_API_KEY`, `qcode-claude` → `QCODE_CLAUDE_API_KEY`) und speichert den eingegebenen Key unter diesem Namen. Der offizielle Eintrag zu `MISSING_CREDENTIAL` sagt: speichern Sie den Provider-Key über die Models-Seite oder setzen Sie die referenzierte Umgebungsvariable. Eine Cordis-Konfigurationsüberschreibung ersetzt die gesamte Konfiguration des Eintrags, behalten Sie beim Bearbeiten einer bestehenden Überschreibung also Ihre anderen Provider.

## Verbindung überprüfen

1. Wählen Sie ein hinzugefügtes Modell in der Modellauswahl und senden Sie eine kurze Nachricht wie `ping`.
2. Öffnen Sie [probe.qcode.cc](https://probe.qcode.cc), geben Sie Ihren QCode-Key ein und prüfen Sie, dass die Anfrage mit diesem Modell erscheint.
3. Um Key und Pfad ohne dsh zu prüfen:

```bash
KEY="cr_your_key"

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

# Anthropic Messages provider
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-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

## Fehlerbehebung

| Symptom | Ursache | Lösung |
|---|---|---|
| `MISSING_CREDENTIAL` | Kein Key gespeichert oder die referenzierte Umgebungsvariable ist leer | Speichern Sie den Key über **Settings → Models** oder setzen Sie die in `apiKeyEnv` genannte Variable vor dem Start von `dsh` |
| `UNKNOWN_MODEL` | Das gewählte Modell ist nicht in der Liste des Providers | Wählen Sie ein konfiguriertes Modell oder fügen Sie die Modell-ID zum Provider hinzu |
| Fetch available models liefert 401 | Falscher Key | Prüfen Sie den Key; die Modellerkennung ruft den OpenAI-kompatiblen Endpunkt `GET /models` auf |
| Die Liste ist leer oder der Abruf schlägt fehl | Das Format der Endpunktliste wird von der Erkennung nicht gelesen | Tragen Sie die Modell-IDs von Hand ein |
| `model_not_available_on_endpoint` | Eine `claude-…`-ID wurde dem OpenAI-Chat-Completions-Provider hinzugefügt | Setzen Sie Claude-IDs in den Anthropic-Messages-Provider mit Base-URL `https://api.qcode.cc/api` |
| 404 | Abschließender Schrägstrich oder falscher Pfadpräfix in einer Base-URL | Vergleich mit [Endpunkte und API-Pfade](/docs/getting-started/endpoints-and-api-paths) |
| Das Gateway lehnt alle Anfragen ab, obwohl Key und URL stimmen | Sein Anfrageformat weicht von OpenAI ab | Offizieller Rat: setzen Sie auf der Route `compat.supportsDeveloperRole: false` und `compat.maxTokensField: max_tokens` |
| Nur Modelle mit Reasoning schlagen fehl | pi-ai sendet deren System-Prompt mit der Rolle `developer` | Setzen Sie `compat.supportsDeveloperRole: false` |
| Für ein von Hand eingetragenes Modell erscheint kein Effort-Menü | Das Modell deklariert keine Reasoning-Stufen | Schalten Sie **Reasoning levels** in den **Model options** des Modells ein |

## Bekannte Einschränkungen

- Entwicklervorschau: Konfigurationsfelder und Verhalten können sich zwischen Versionen ändern; diese Seite wurde gegen 0.2.2-rc.1 geprüft, die Version, die npm am 2026-11-09 als `latest` führt.
- Das Formular hat kein Feld für die `compat`-Schalter; setzen Sie sie auf der Route in `cordis.patch.yml`, wie in der offiziellen Anleitung beschrieben.
- Ein von Hand eingetragenes Modell deklariert keine Reasoning-Stufen, bis Sie sie ergänzen, und bleibt rein textbasiert, bis Sie in seinen **Model options** **Image** wählen (siehe die Abschnitte der offiziellen Anleitung zu Bildeingabe und Reasoning-Aufwand).

## Weiterführende Dokumentation

- [Endpunkte und API-Pfade](/docs/getting-started/endpoints-and-api-paths) — Tabelle „Protokoll × Modellfamilie"
- [Chinesische Modelle](/docs/usage/cn-models) — GLM / Kimi / DeepSeek / Qwen: IDs und Pfade
- [CodeWhale (DeepSeek-TUI)](/docs/ide/deepseek-tui) — ein weiterer Terminal-Agent mit beiden Protokollen
- [Übersicht der Tool-Kompatibilität](/docs/ide/tool-compatibility) — welches Tool welches Protokoll spricht
- [T3 Code](/docs/ide/t3code) — eine Oberfläche, die Claude Code und Codex steuert
- [DeepSeek-Harness-Leitfaden auf qcode.cc](https://qcode.cc/de/deepseek-harness-guide) — Hintergrund und Anwendungsfälle