Wie man beliebige KI-Modelle in DeepSeek Harness ausführt?

DeepSeek Harness (dsh) wird mit den eingebundenen eigenen Modellen von DeepSeek ausgeliefert, aber Sie sind nicht an diese gebunden. Der Harness behandelt Modellanbieter als Konfiguration: Sie verweisen einen Anbieterblock auf einen beliebigen OpenAI-kompatiblen Endpunkt, übergeben ihm eine Referenz auf Zugangsdaten, und Ihre Agenten-Sitzungen laufen auf dem Modell, das sich hinter dieser URL befindet. Eine lokale Ollama-Instanz, ein Unternehmens-Gateway, Qwen über DashScopes kompatiblen Modus oder die großen Kataloganbieter wie Anthropic und OpenAI lassen sich alle in denselben Block einbinden.

Dieser Leitfaden geht diesen Block Schlüssel für Schlüssel durch und erstellt dann drei funktionierende Anleitungen: ein lokales Modell, einen gehosteten OpenAI-kompatiblen Endpunkt und die eingebauten Kataloganbieter. Alles, was hier zitiert wird, stammt aus dem offiziellen Anbieter-Leitfaden auf dem Master-Branch, abgerufen am 20. August 2026. Eine Einschränkung vorab: dsh ist eine Entwickler-Vorschau, und die README warnt in Großbuchstaben, dass es zu abwärtsinkompatiblen Änderungen kommen wird. Überprüfen Sie die Dokumentation mit Ihrer installierten Version, bevor Sie etwas in die Produktion übernehmen.

Wenn Sie neu beim Harness selbst sind, beginnen Sie mit was DeepSeek Harness ist und wie es funktioniert, und kommen Sie dann hierher zurück für die Anbieter-Infrastruktur.

Warum Modelle in einem Agenten-Harness überhaupt wechseln?

Ein Agenten-Harness ist eine Schleife: Das Modell plant, ruft Tools auf, liest Ergebnisse und wiederholt den Vorgang. Der Harness besitzt die Schleife; das Modell ist eine Zutat. Drei Gründe, warum Sie die Zutat ändern würden:

Kosten. Agenten-Sitzungen verbrauchen Token schnell, da jedes Tool-Ergebnis wieder in den Kontext zurückgespeist wird. Routinemäßige Sitzungen auf ein günstigeres Modell oder auf DeepSeek V4-Flash statt V4-Pro umzuleiten, ändert Ihre Rechnung, ohne Ihren Workflow zu ändern. Sie können ein teures Spitzenmodell für die Sitzungen konfiguriert lassen, die es benötigen.

Datenlokalität. Einige Codebasen dürfen das Gebäude nicht verlassen. Ein Anbieterblock, der auf ein Modell verweist, das auf Ihrer eigenen Hardware läuft, bedeutet, dass Prompts, Dateiinhalte und Tool-Ausgaben niemals das Netzwerk überqueren. Derselbe Harness, dieselbe Benutzeroberfläche, keine Datenabflüsse.

Lokale Entwicklung. Wenn Sie Plugins erstellen oder das Agentenverhalten testen, möchten Sie nicht, dass jede Iteration API-Gutschriften kostet oder von Ihrem Netzwerk abhängt. Ein kleines lokales Modell antwortet schnell genug, um die Schleife zu testen, und Sie tauschen das echte Modell wieder ein, wenn das Verhalten wichtig ist.

Das Design folgt der Architektur von dsh: Alles im Harness ist ein Plugin, und der Modelladapter ist eines der austauschbaren Teile. Anbieterrouten werden vom Plugin dsh-llm-pi-ai verwaltet, das im Plugin-Konfigurationskatalog des Repos als die "Anbieterrouten, die diese Instanz besitzt" dokumentiert ist. Das ist die Maschinerie. Die benutzerspezifische Oberfläche ist ein YAML-Block.

Der Anbieterblock, Schlüssel für Schlüssel

Benutzerdefinierte Anbieter befinden sich in $DSH_HOME/settings.yaml, und Sie können sie auch über die Web-Benutzeroberfläche unter Einstellungen → Modelle erstellen. Hier ist das Beispiel direkt aus der offiziellen Dokumentation:

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

Was jeder Schlüssel bewirkt:

• my-gateway ist die Anbieter-ID. Es ist ein permanenter Bezeichner, wählen Sie also einen Namen, mit dem Sie leben können; der in der Benutzeroberfläche angezeigte Name wird separat festgelegt.
• apiKeyEnv benennt die Umgebungsvariable, die Ihren API-Schlüssel enthält. Die Einstellungsdatei enthält niemals das Geheimnis selbst, sondern nur diese Referenz. Mehr darüber, wo der tatsächliche Schlüssel gespeichert ist, finden Sie weiter unten.
• api deklariert das Verbindungsprotokoll. openai-completions ist der dokumentierte Wert für OpenAI-kompatible Endpunkte, was das Versprechen „jedes Modell“ ermöglicht: Die meisten Gateways, lokalen Laufzeitumgebungen und gehosteten Anbieter sprechen dieses Protokoll.
• baseURL ist das Stammverzeichnis des Endpunkts, an das der Harness Anfragen sendet.
• models listet die über diesen Anbieter verfügbaren Modell-IDs auf. Jeder Eintrag benötigt mindestens eine id, die mit dem übereinstimmen muss, was der Endpunkt im Anfragetext erwartet.
• input deklariert Modalitäten pro Modell. Benutzerdefinierte Modelle sind standardmäßig nur Text, daher muss ein Vision-Modell explizit input: [text, image] deklarieren, sonst werden Bildanhänge es nicht erreichen. Es gibt auch ein route-spezifisches defaultInput, das einen Fallback für jedes Modell des Anbieters festlegt; ein input auf Modellebene überschreibt dies.
• compat enthält Kompatibilitätsschalter für Endpunkte, die vom Standard-OpenAI-Verhalten abweichen. Die Dokumentation nennt zwei: supportsDeveloperRole: false für Backends, die die developer-Rolle ablehnen, und maxTokensField: max_tokens für Backends, die den älteren Feldnamen für die Ausgabebegrenzung wünschen. Compat kann auf Routenebene oder pro Modell eingestellt werden.

Eine nützliche Funktion, die es wert ist, bemerkt zu werden: Wenn Sie einen benutzerdefinierten Anbieter über die Web-Benutzeroberfläche hinzufügen, fragt eine Option „Verfügbare Modelle abrufen“ die OpenAI-kompatible GET /models-Route des Endpunkts ab und füllt die Modellliste für Sie aus. Wenn Ihr Endpunkt diese Route implementiert, ersparen Sie sich die manuelle Eingabe.

Wo der eigentliche API-Schlüssel gespeichert ist

Geheimnisse werden nur schreibend in $DSH_HOME/.credentials.yaml gespeichert. Nachdem Sie einen Schlüssel über die Benutzeroberfläche gespeichert haben, gibt dsh nur einen redigierten Deskriptor zurück; der wörtliche Wert wird nie wieder angezeigt. settings.yaml enthält Referenzen (apiKeyEnv-Namen, Zugangsdaten-Deskriptoren), niemals die Schlüssel selbst. Diese Trennung bedeutet, dass Sie eine Einstellungsdatei committen oder teilen können, ohne etwas preiszugeben, und einen Schlüssel rotieren können, ohne die Anbieterkonfiguration zu ändern.

Anleitung 1: Ein lokales Modell über Ollama ausführen

Ollama stellt eine OpenAI-kompatible API unter http://localhost:11434/v1 bereit, die Ollama in seinem eigenen OpenAI-Kompatibilitätshandbuch dokumentiert. Da dsh openai-completions an jede Basis-URL spricht, ist die Kopplung unkompliziert.

[ÜBERPRÜFUNG: Die dsh-Dokumentation zeigt kein Ollama-spezifisches Beispiel; diese Anleitung wendet das dokumentierte Schema für benutzerdefinierte Anbieter auf Ollamas dokumentierten OpenAI-kompatiblen Endpunkt an. Testen Sie es auf Ihrer Installation, bevor Sie es intern veröffentlichen.]

llm-pi-ai:
  providers:
    ollama-local:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://localhost:11434/v1
      models:
        - id: gpt-oss:20b
        - id: qwen3

Hinweise dazu:

• Ollama benötigt lokal keinen API-Schlüssel, aber das Schema erwartet eine Referenz auf Zugangsdaten, setzen Sie also einen Dummy-Wert: export OLLAMA_API_KEY=ollama. Ollama ignoriert, was immer Sie senden.
• Die Modell-id muss mit dem von Ollama bereitgestellten Tag übereinstimmen. Führen Sie ollama list aus und kopieren Sie die Namen exakt, einschließlich Tag.
• Ziehen Sie das Modell zuerst (ollama pull gpt-oss:20b) und bestätigen Sie, dass der Server antwortet, bevor Sie es in dsh einbinden. Die vollständige lokale Einrichtung haben wir in wie man GPT-OSS mit Ollama ausführt behandelt, und dasselbe Muster funktioniert auch für andere Open-Weight-Modelle wie Kimi K3, wenn Ihre Hardware dafür ausreicht.

Ein schneller Funktionstest erspart Ihnen eine verwirrende Agenten-Sitzung: Rufen Sie http://localhost:11434/v1/models in Apidog auf, bevor Sie die dsh-Konfiguration anfassen. Wenn diese Anfrage Ihre Modellliste zurückgibt, ist die Basis-URL korrekt, der Server läuft, und „Verfügbare Modelle abrufen“ in der dsh-Benutzeroberfläche wird ebenfalls funktionieren. Wenn nicht, wird keine noch so umfangreiche Harness-Konfiguration es beheben.

Erwartungsmanagement: Agenten-Harnesses verlassen sich stark auf Tool-Aufrufe und langen Kontext. Kleine lokale Modelle bewältigen die Schleife für Tests, aber sie planen schlechter und brechen Tool-Aufrufe häufiger ab als die Spitzenmodelle, um die der Harness entwickelt wurde. Das ist für die Plugin-Entwicklung in Ordnung; für die echte Arbeit ist es frustrierend.

Anleitung 2: Ein gehosteter OpenAI-kompatibler Endpunkt (Qwen über DashScope)

Für ein gehostetes Beispiel wählen Sie einen Anbieter, der seine OpenAI-Kompatibilität dokumentiert, anstatt einen, von dem Sie annehmen, dass er sie hat. Alibaba Cloud Model Studio (DashScope) tut dies: Seine OpenAI-Kompatibilitätsseite dokumentiert einen /compatible-mode/v1-Endpunkt für Qwen-Modelle, mit regionalen, arbeitsbereichsspezifischen Domänen (für Singapur: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1) und Authentifizierung über die Umgebungsvariable DASHSCOPE_API_KEY.

Auf das dsh-Schema abgebildet:

llm-pi-ai:
  providers:
    qwen-dashscope:
      apiKeyEnv: DASHSCOPE_API_KEY
      api: openai-completions
      baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: qwen3-max

Ersetzen Sie {WorkspaceId} durch Ihre tatsächliche Workspace-Domain aus der Model Studio-Konsole und überprüfen Sie die Modellliste des Anbieters auf aktuelle IDs; wir haben eine Zusammenfassung der Premium-Stufe in unserem Qwen 3.8 API-Leitfaden. Dasselbe Muster erstreckt sich auf jeden Anbieter mit dokumentierter OpenAI-Kompatibilität: Moonshots Kimi API, OpenRouter, eine vLLM-Bereitstellung oder das interne Gateway Ihres Unternehmens. Die einzigen Teile, die sich ändern, sind baseURL, der Name der Umgebungsvariablen und die Modell-IDs. Wenn Sie Open-Source-Modelle in Codex konfiguriert haben, wird Ihnen dies vertraut vorkommen; dshs YAML-Block spielt dieselbe Rolle wie die model_providers-Konfiguration von Codex.

Zwei Besonderheiten für gehostete Endpunkte:

• Wenn der Endpunkt des Anbieters Anfragen mit seltsamen Fehlern bezüglich Rollen oder Token-Feldern ablehnt, dafür gibt es die compat-Schalter. Versuchen Sie zuerst supportsDeveloperRole: false; ältere OpenAI-kompatible Implementierungen datieren vor der developer-Rolle.
• Vision-Modelle müssen input: [text, image] explizit deklarieren, selbst wenn das gehostete Modell Bilder unterstützt. dsh geht bei benutzerdefinierten Modellen von reinem Text aus, sofern nicht anders angegeben.

Anleitung 3: Die eingebauten Kataloganbieter

Für die Mainstream-Clouds benötigen Sie keinen benutzerdefinierten Block. dsh liefert Kataloganbieter für DeepSeek, Anthropic und OpenAI, bei denen die Einrichtung hauptsächlich darin besteht, einen API-Schlüssel einzufügen. Spezielle Katalogeinträge verfügen über eigene native Authentifizierungsabläufe: Bedrock verwendet AWS-Zugangsdaten, Vertex benötigt ein ADC-Projekt, Azure benötigt seine API-Version, und Codex authentifiziert über OAuth.

Kataloganbieter sind der reibungsarme Weg, wenn Sie einfach Claude oder GPT hinter dem Harness haben möchten, und so werden die meisten Leute DeepSeek V4-Pro ausführen, dessen API-Start im August 2026 gleichzeitig mit dem Harness selbst erfolgte (Details unter api-docs.deepseek.com). Benutzerdefinierte Anbieter sind für alles, was der Katalog nicht abdeckt: lokale Laufzeitumgebungen, Gateways, regionale Anbieter und OpenAI-kompatible Aggregatoren.

Modellauswahl und was Sitzungen speichern

Das Hinzufügen eines Anbieters macht seine Modelle verfügbar; die Auswahl eines Modells in Einstellungen → Modelle macht es zur Standardeinstellung für neue Sitzungen. Zwei Verhaltensweisen aus der Dokumentation, die es wert sind, verinnerlicht zu werden:

1. Bestehende Sitzungen behalten das Modell bei, mit dem sie gestartet wurden. Sitzungen protokollieren ihr ursprüngliches Modell, sodass eine Änderung der Standardeinstellung mitten im Projekt die Historie nicht stillschweigend umschreibt oder ändert, was eine laufende Sitzung verwendet.
2. Wenn Sie den Anbieter löschen, der die aktuelle Standardeinstellung besitzt, blockiert der Komponist die Eingabe, bis Sie ein neues Modell auswählen. Der Harness scheitert laut, anstatt zu raten.

Diese Sitzungsbindung ist wichtig für die Reproduzierbarkeit: Wenn Sie dsh mit anderen Harnesses vergleichen (wir haben genau das in DeepSeek Harness vs. Claude Code getan), können Sie darauf vertrauen, dass das Transkript einer Sitzung ein Modell widerspiegelt und nicht einen Austausch mitten im Lauf.

Fehlerbehebung bei den üblichen Problemen

Falsche oder unerreichbare baseURL. Der häufigste Fehler ist der am wenigsten exotische. Bestätigen Sie, dass die URL dort endet, wo das Protokoll es erwartet (normalerweise /v1 für OpenAI-kompatible Endpunkte, /compatible-mode/v1 für DashScope) und dass ein einfacher GET {baseURL}/models außerhalb des Harness erfolgreich ist. Dies ist der Kontrollpunkt, an dem sich Apidog in fünf Minuten bezahlt macht: Senden Sie die Anfrage mit demselben Header (Authorization: Bearer $KEY), den der Harness senden wird, und lesen Sie den tatsächlichen Statuscode und den Antwortkörper anstatt eines gekapselten Harness-Fehlers. Wenn Sie offline entwickeln oder der Anbieter instabil ist, simulieren Sie die /models- und /chat/completions-Antworten des Anbieters in Apidog und weisen Sie baseURL während der Entwicklung auf den Mock.

Fehlende oder leere Umgebungsvariable. apiKeyEnv benennt eine Variable; sie erstellt keine. Wenn die Variable nicht in der Umgebung gesetzt ist, in der dsh tatsächlich läuft, gehen Anfragen unauthentifiziert raus und kommen mit 401 zurück. Denken Sie daran, dass ein über eine GUI oder einen Dienstmanager gestarteter Prozess Ihr Shell-Profil möglicherweise nicht erbt. echo $GATEWAY_API_KEY im selben Kontext, der dsh web startet, nicht nur in einem beliebigen Terminal.

Diskrepanz bei der Eingabemodalität. Sie hängen ein Bild an, und das Modell sieht es nie, oder die Anfrage schlägt fehl. Benutzerdefinierte Modelle sind standardmäßig nur Text. Fügen Sie input: [text, image] beim Modelleintrag hinzu oder setzen Sie defaultInput auf Routenebene, wenn jedes Modell des Anbieters Bilder verarbeitet.

Protokoll-Eigenheiten. Fehler, die eine nicht unterstützte Rolle oder einen abgelehnten Token-Parameter erwähnen, weisen auf Kompatibilitätsschalter hin: supportsDeveloperRole: false und maxTokensField: max_tokens sind die beiden dokumentierten.

Gestern hat noch alles funktioniert. Entwickler-Vorschau. Pinnen Sie die Version fest, die Sie deployen, lesen Sie die Release Notes vor dem Upgrade und erwarten Sie, dass sich das Einstellungsschema ändert. Das deepseek-harness Repo ist die Wahrheitsquelle, nicht irgendein Blogbeitrag, dieser eingeschlossen.

Ein weiterer Integrationshinweis: Modellanbieter sind nur die halbe Anpassungsgeschichte. Die andere Hälfte ist, welche Tools der Agent aufrufen kann, und Sie können Ihre API-Workflows direkt einbinden; das behandeln wir in Verwendung des Apidog CLI in DeepSeek Harness.

Häufig gestellte Fragen (FAQ)

Unterstützt DeepSeek Harness Ollama offiziell?

Die offizielle Anbieter-Dokumentation erwähnt Ollama nicht namentlich. Was sie unterstützt, ist jeder Endpunkt, der das openai-completions-Protokoll spricht, und Ollama dokumentiert eine OpenAI-kompatible API unter http://localhost:11434/v1. Die obige Anleitung kombiniert die beiden dokumentierten Hälften; testen Sie sie auf Ihrer Installation, da dsh eine Entwickler-Vorschau ist und sich Schemata zwischen Releases ändern können.

Wo speichert dsh meine API-Schlüssel?

In $DSH_HOME/.credentials.yaml, nur schreibend. Die Benutzeroberfläche zeigt nach dem Speichern einen redigierten Deskriptor an, und settings.yaml enthält nur Referenzen wie apiKeyEnv-Namen. Sie erhalten niemals einen Klartext-Schlüssel in Ihrer Anbieterkonfiguration.

Kann ich verschiedene Modelle für verschiedene Sitzungen verwenden?

Ja. Die Auswahl eines Modells legt die Standardeinstellung nur für neue Sitzungen fest; jede bestehende Sitzung behält das Modell bei, mit dem sie gestartet wurde. So können Sie ein günstiges Modell wie DeepSeek V4-Flash für routinemäßige Sitzungen verwenden, die Standardeinstellung für ein schwieriges Problem auf ein leistungsstärkeres Modell umstellen, und Ihre früheren Sitzungen bleiben unberührt.

Mein benutzerdefinierter Endpunkt gibt Fehler zurück, die dieselbe Anfrage in Curl nicht erzeugt. Was nun?

Vergleichen Sie die genauen Nutzlasten. Der Harness sendet möglicherweise eine developer-Rolle oder ein neueres Token-Cap-Feld, das Ihr Backend nicht akzeptiert; die dokumentierten Korrekturen sind supportsDeveloperRole: false und maxTokensField: max_tokens unter compat. Das Wiedergeben der Harness-formatierten Anfrage in einem API-Client zeigt Ihnen, an welchem Feld das Backend scheitert.