dsh konfigurieren: API-Keys, Modelle und Endpunkte

Wo dsh seine Konfiguration speichert

dsh (DeepSeek Harness) speichert seine Konfiguration in einem Verzeichnis: $DSH_HOME, standardmäßig ~/.dsh. Alles, was Sie in der Web-UI festlegen, wird dort als einfache Dateien gespeichert. Kopieren Sie dieses Verzeichnis auf einen anderen Server, verhält sich das neue System wie das bisherige.

Vier Pfade enthalten alles, womit Sie arbeiten werden.

• ~/.dsh/settings.yaml enthält manuell und über die UI erstellte Einstellungen, einschließlich Ihrer Provider- und Modellrouten.
• ~/.dsh/.credentials.yaml enthält die Geheimnisse. Einstellungen enthalten nur eine Referenz auf ein Zugangsdatenobjekt. Der eigentliche Schlüsselwert befindet sich daher in einer Datei.
• ~/.dsh/profiles/ enthält benannte Profile, und ~/.dsh/storages/ enthält gespeicherte Sitzungen.
• ~/.dsh/cordis.patch.yml ist Ihre eigene Patch-Ebene. Sie wird für jedes Profil über die integrierte Konfiguration angewendet.

DeepSeek hat das Harness am 17. August 2026 als MIT-lizenzierte Entwicklervorschau angekündigt. In der README wird auf Änderungen hingewiesen, die die Kompatibilität beeinträchtigen. Die Feldnamen und Pfade in diesem Leitfaden entsprechen der Repository-Dokumentation vom August 2026. Prüfen Sie sie vor dem Kopieren von Konfigurationsdaten aus einem Leitfaden, auch aus diesem, anhand der Dokumentation für die von Ihnen installierte Version. Eine Vorschauversion benennt Dinge zwischen Releases um.

Das ehrliche Minimum bis zur ersten Ausgabe

dsh benötigt Node.js 22.19 oder höher innerhalb der 22er-Reihe oder Node.js 24 und höher. Node 23 liegt außerhalb dieses Bereichs. Prüfen Sie zuerst die Version, weil eine nicht passende Version beim Start fehlschlägt und die Fehlermeldung wie ein defektes Paket wirkt.

node -v
npx @deepseek-ai/dsh web

npx lädt das Paket aus der npm-Registry und startet die Weboberfläche auf http://127.0.0.1:3080. Die Anwendung bindet an die Loopback-Adresse. Der Port ist dadurch von einem anderen Rechner aus nicht erreichbar, selbst wenn Ihre Firewall den Zugriff erlaubt. Leiten Sie den Port auf einem VPS stattdessen über SSH weiter, anstatt 3080 im Internet zu öffnen.

ssh -N -L 3080:127.0.0.1:3080 you@your-server

Öffnen Sie http://127.0.0.1:3080 auf Ihrem Laptop und wechseln Sie anschließend zu Settings und Models. Die DeepSeek-Karte enthält ein einziges Feld für den API-Schlüssel. Fügen Sie den Schlüssel von platform.deepseek.com ein und speichern Sie ihn. Die Modellroute ist sofort ohne Neustart verwendbar, weil der laufende Server die Zugangsdaten speichert und die Referenz dynamisch auflöst. Auf die dsh-Weboberfläche auf einem entfernten Server zugreifen behandelt den Tunnel und den Fall mit Reverse Proxy. DeepSeek Harness auf einem VPS installieren behandelt die Servervorbereitung, die diese Anleitung voraussetzt.

Sehen Sie nach dem Speichern nach, was die Anwendung angelegt hat.

ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yaml

Sie sollten settings.yaml, .credentials.yaml und profiles/ sehen. Wenn stat einen anderen Modus als 600 ausgibt, führen Sie chmod 600 ~/.dsh/.credentials.yaml aus. Eine für die Gruppe oder weltweit lesbare Zugangsdaten-Datei gibt Ihren Schlüssel an jedes andere Konto auf dem System weiter.

Für den ersten Lauf ohne Browser genügt ein Befehl.

npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"

Das Headless-Profil führt eine einzelne Sitzung aus und gibt die abschließende Antwort aus.

Umgebungsvariablen oder Konfigurationsdatei

Es gibt zwei Möglichkeiten, dsh einen Schlüssel bereitzustellen. Sie sind nicht austauschbar.

Ein Kataloganbieter (DeepSeek, Anthropic, OpenAI und die übrigen integrierten Anbieter) erhält seinen Schlüssel über die Seite Models. Der Wert wird in ~/.dsh/.credentials.yaml eingetragen. Ihre Einstellungen enthalten anschließend nur eine Referenz darauf. Die Web UI zeigt den Schlüssel nach dem Speichern nicht erneut an.

Ein benutzerdefinierter Anbieter kann stattdessen mit apiKeyEnv eine Umgebungsvariable angeben. So sieht die Dokumentation ~/.dsh/settings.yaml vor.

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]

Fügen Sie zunächst über die Web UI einen Anbieter hinzu. Öffnen Sie anschließend ~/.dsh/settings.yaml und kopieren Sie die dort erzeugte Struktur. Während einer Developer Preview ändert sich die Verschachtelung am wahrscheinlichsten. Die Datei, die die Anwendung gerade geschrieben hat, ist immer aktuell.

apiKeyEnv wird aus der Umgebung des dsh-Prozesses gelesen, nicht aus Ihrer Login-Shell. Ein in einer interaktiven Sitzung exportierter Schlüssel ist für eine systemd-Unit nicht sichtbar. Daher gibt dieselbe Konfiguration, die bei der manuellen Eingabe von dsh web funktioniert, unter einem Dienst MISSING_CREDENTIAL zurück. Geben Sie der Unit eine eigene Datei.

[Service]
EnvironmentFile=/etc/dsh/dsh.env

Setzen Sie die Berechtigungen dieser Datei auf 600. Der Benutzer, unter dem der Dienst läuft, muss Eigentümer der Datei sein.

Modelle auswählen und die ID, die Sie nicht umbenennen können

Jeder konfigurierte Provider wird in der Modellauswahl angezeigt. Wenn Sie ein Modell auswählen, wird es außerdem zum Standardmodell für neue Sitzungen. Bereits vorhandene Sitzungen behalten das darin gespeicherte Modell. Durch den Wechsel wird eine alte Unterhaltung daher nicht geändert.

Die Provider-ID ist dauerhaft. Anforderungen, gespeicherte Sitzungen, Modelldefaults und Verweise auf Zugangsdaten beziehen sich alle darauf. Deshalb gibt es keine Schaltfläche zum Umbenennen. Wenn Sie die ID ändern, müssen Sie einen neuen Provider anlegen und den alten löschen. Wählen Sie einen Namen, den Sie dauerhaft verwenden können: local-ollama statt test2.

Modelle sind standardmäßig auf Text beschränkt, sofern Sie nichts anderes angeben. Fügen Sie einem Modelleitrag input: [text, image] hinzu, um die Bildunterstützung zu deklarieren. Alternativ können Sie defaultInput auf Route-Ebene als Fallback für Modelle festlegen, die im Katalog nicht entsprechend beschrieben sind. Die Chat-Completions-Route von DeepSeek selbst unterstützt nur Text und kann nicht anders konfiguriert werden. Ein an diese Route angehängtes Bild wird daher abgelehnt, bevor Daten gesendet werden.

dsh auf einen lokalen Endpunkt richten, damit Ihr Code auf dem Rechner bleibt

Ollama stellt unter http://127.0.0.1:11434/v1 eine OpenAI-kompatible API bereit. dsh kann über einen benutzerdefinierten Provider jede OpenAI-kompatible Basis-URL verwenden. Dadurch lassen sich beide Komponenten ohne weitere Zwischenschicht verbinden. Richten Sie zuerst den Modellserver ein: ein LLM mit Ollama auf einem VPS selbst hosten beschreibt die Installation und den Abruf des Modells.

Prüfen Sie, ob der Endpunkt antwortet, bevor Sie dsh konfigurieren.

ollama list
curl -s http://127.0.0.1:11434/v1/models

ollama list gibt den exakten Tag jedes abgerufenen Modells aus. Kopieren Sie diese Zeichenfolge. curl gibt dieselben Modelle als JSON zurück. Eine leere Liste bedeutet, dass Ollama läuft, aber kein Modell abgerufen wurde. Connection refused bedeutet, dass Ollama nicht läuft oder nicht auf 11434 lauscht.

Fügen Sie nun den Provider hinzu. Ollama erfordert ein Feld für den API-Schlüssel und ignoriert dessen Wert. Daher genügt jede nicht leere Zeichenfolge.

llm-pi-ai:
  providers:
    local-ollama:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://127.0.0.1:11434/v1
      models:
        - id: <the exact tag printed by ollama list>

Exportieren Sie die Variable so, dass der dsh-Prozess sie sehen kann.

sudo install -d -m 700 /etc/dsh
printf 'OLLAMA_API_KEY=ollama\n' | sudo tee /etc/dsh/dsh.env
sudo chmod 600 /etc/dsh/dsh.env

Drei Fehler decken fast alle Versuche ab. MISSING_CREDENTIAL bedeutet, dass dsh die von apiKeyEnv benannte Variable nicht lesen konnte. Prüfen Sie daher die Umgebung des Prozesses und nicht die Umgebung Ihres Terminals. UNKNOWN_MODEL bedeutet, dass id nicht mit einem konfigurierten Modell übereinstimmt. Vergleichen Sie den Wert Zeichen für Zeichen mit ollama list, einschließlich des Tags nach dem Doppelpunkt. Ein 401-Fehler beim Abrufen der verfügbaren Modelle stammt aus der Modellerkennung. Dabei wird GET /models auf Ihrer Basis-URL aufgerufen. Endpunkte, die diesen Pfad nicht bereitstellen, erfordern eine manuelle Eingabe der Modelle.

Eine weitere Fehlerquelle ist die Basis-URL. Lassen Sie /v1 weg. Andernfalls werden die Anfragen an Pfade gesendet, die Ollama nicht bereitstellt. Der Aufruf endet dann mit einem 404-Fehler, und das Modell wird nicht ausgeführt. Das Suffix ist Bestandteil der OpenAI-kompatiblen Schnittstelle und keine bloße Dekoration.

Wenn Ollama auf einem anderen Rechner läuft, wird dessen Adresse zur Basis-URL. Ihre Prompts übertragen sich dann über unverschlüsseltes HTTP im Klartext über das Netzwerk. Lassen Sie Ollama auf demselben Host laufen oder sichern Sie den Endpunkt mit TLS (Transport Layer Security) und Authentifizierung ab: einen exponierten Ollama-Endpunkt absichern.

Was verlässt den Rechner in den einzelnen Modi

Mit einem DeepSeek-Schlüssel geht jede Anfrage an die API von DeepSeek. Diese Anfrage enthält Ihren Prompt, den Inhalt der Dateien, die der Agent zur Beantwortung gelesen hat, die Ausgabe der ausgeführten Befehle und alle Tool-Ergebnisse, die er einbezieht. Ihr Quellcode befindet sich in diesem Payload, sobald der Agent eine Datei geöffnet hat. So funktioniert ein gehostetes Modell. Deshalb sollten Sie berücksichtigen, in welchem Verzeichnis Sie den Agenten starten.

Bei einem anderen Kataloganbieter oder einem Unternehmens-Gateway geht derselbe Payload stattdessen an diesen Anbieter. Die Basis-URL zeigt genau, wohin.

Bei einem lokalen Endpunkt geht die Modellanfrage an 127.0.0.1:11434 und bleibt auf dem Rechner. Kein Teil Ihres Codes erreicht einen Modellanbieter. Drei Dinge verlassen den Rechner trotzdem. npx lädt das Paket aus der npm-Registry herunter. Jedes Tool, das der Agent ausführt, kann selbst auf das Internet zugreifen. Dazu gehören auch verbundene MCP-Server (Model Context Protocol), die unter MCP-Server auf einem VPS betreiben ausführlich behandelt werden. Außerdem kann Telemetrie übertragen werden, wenn Sie sie aktivieren.

Die Telemetrie ist deaktiviert, bis Sie zustimmen. DSH_TELEMETRY_MODE ist der Einwilligungsschalter. Nicht gesetzte, leere oder nicht erkannte Werte werden zu DISABLED aufgelöst. In diesem Zustand erstellt dsh weder einen OpenTelemetry-(OTel-)Provider noch einen Prozessor oder Exporter. Ein neues Profil erzeugt daher überhaupt keine Telemetrie-Netzwerkanfrage. FEEDBACK_ONLY aktiviert die Weitergabe von Sitzungslogs nach auslösendem Feedback. FULL erlaubt zusätzlich die Berichterstattung des Launchers. Der Sitzungs-Feed kann Sitzungsinhalte, Tool-Daten, Prompts und Workspace-Pfade exportieren. Behandeln Sie FULL daher so, als würden Sie Ihre Arbeit an DeepSeek senden.

Für eine harte Sperre, die nicht davon abhängt, dass Sie die Moduszeichenfolge korrekt setzen, verwenden Sie DSH_TELEMETRY_DISABLED=1. Jeder nicht leere Wert ist ein verbindlicher Opt-out. Die Einstellung wird vor dem Start des Laufs gelesen. Der Projektcode kann sie daher während der Sitzung nicht wieder aktivieren. Die Standardadresse des Collectors ist harness-telemetry.deepseeksvc.com. Dieser Name ist nützlich, wenn Sie Ihre eigenen Firewall-Logs prüfen.

Prüfen Sie die Einstellung, statt ihr zu vertrauen. Listen Sie bei laufender Aufgabe die ausgehenden Verbindungen auf, die der Prozess hält.

sudo ss -tnp | grep -i node

Im Modus mit lokalem Modell sollte die Loopback-Verbindung zu 11434 sichtbar sein. Eine Verbindung zu einer öffentlichen Adresse sollte nicht vorhanden sein. Jede andere Verbindung sollten Sie identifizieren, bevor Sie fortfahren. Was ein Coding-Agent nach außen sendet führt dieselbe Prüfung mit anderen Harnesses durch und erklärt, wie Sie das Ergebnis auswerten.

Wohin Secrets nicht gehören

• Shell-History. export DEEPSEEK_API_KEY=sk-... wird von ~/.bash_history im Klartext gespeichert und bleibt dort lange bestehen, nachdem Sie den Schlüssel rotiert haben. Setzen Sie ein Leerzeichen vor den Befehl, wenn HISTCONTROL=ignorespace gesetzt ist, oder umgehen Sie die Shell und schreiben Sie den Wert direkt in eine Datei mit dem Modus 600.
• Committete Dotfiles. Ein Schlüssel in ~/.bashrc oder ~/.zshrc ist nur git add von einem öffentlichen Repository entfernt, wenn Sie Dotfiles mit git verwalten. Führen Sie in diesem Repository git grep -I -n 'sk-' aus, bevor Sie pushen.
• settings.yaml. Verwenden Sie für eigene Provider apiKeyEnv, damit die Datei einen Variablennamen statt eines Secrets enthält. Konfigurationsdateien werden in Issue-Reports und Support-Chats eingefügt. Credential-Dateien nicht.
• Ausgabe von env und Screenshots des Terminals. Alles, was die gesamte Umgebung ausgibt, gibt auch den Schlüssel aus.
• Backups. ~/.dsh sollte gesichert werden, aber .credentials.yaml darin ist ein aktives Secret. Schließen Sie diese Datei aus oder verschlüsseln Sie das Archiv.

Diese Regeln gelten nicht nur für dsh. Secrets aus Compose-Umgebungsdateien heraushalten behandelt dasselbe Problem auf der Container-Seite desselben Servers.

Mit einer Developer Preview arbeiten

Fixieren Sie die getestete Version, weil eine Preview bereits in einem Patch-Release einen Konfigurationsschlüssel ändern kann und Ihr Provider dann das Laden abbricht. Halten Sie settings.yaml und cordis.patch.yml unter Versionsverwaltung. Schließen Sie die Anmeldedatendatei davon aus. So sehen Sie nach einem Upgrade, was sich geändert hat.

Zwei Flags helfen, wenn sich ein Profil nicht wie erwartet verhält. --dump-default-config gibt die zusammengesetzte Standardkonfiguration aus, ohne den Dienst zu starten. --dump-config gibt auf dieselbe Weise die zusammengesetzte Konfiguration für Ihr Profil aus. Ein Vergleich zeigt, was Ihre Patch-Ebene tatsächlich geändert hat. Das ist schneller, als die Ebenen manuell zu lesen.

dsh --profile web --dump-config

Führen Sie diesen Befehl zuerst aus, wenn nach einem Upgrade etwas nicht funktioniert. Ein Schlüssel, der zwischen Releases verschoben wurde, erscheint im Dump als fehlender Zweig. Die Korrektur besteht dann aus einer einzeiligen Änderung und nicht aus einer Neuinstallation.

FAQ

Wo speichert dsh meinen DeepSeek-API-Schlüssel?

In $DSH_HOME/.credentials.yaml. Das ist ~/.dsh/.credentials.yaml, sofern Sie DSH_HOME nicht selbst setzen. Die Seite „Models“ schreibt den Schlüssel dorthin. Ihre Einstellungen enthalten nur einen Verweis darauf. Das Geheimnis befindet sich daher in einer einzigen Datei. Prüfen Sie die Berechtigungen mit stat -c '%a %n' ~/.dsh/.credentials.yaml. Setzen Sie sie auf 600, falls sie weniger restriktiv sind. Bei einem benutzerdefinierten Provider lässt sich die Datei vollständig vermeiden, indem Sie mit apiKeyEnv eine Umgebungsvariable angeben.

Wie kann ich dsh anstelle der DeepSeek-API mit einem lokalen Modell verwenden?

Fügen Sie einen benutzerdefinierten Provider mit der Basis-URL Ihres lokalen OpenAI-kompatiblen Endpunkts hinzu. Für Ollama lautet diese http://127.0.0.1:11434/v1. Verwenden Sie api: openai-completions sowie ein Modell id, das Sie exakt aus ollama list übernehmen. Ollama erfordert einen API-Key-Wert und ignoriert ihn. Daher funktioniert jeder nicht leere String. Prüfen Sie mit curl -s http://127.0.0.1:11434/v1/models, ob der Endpunkt antwortet, bevor Sie eine dsh-Konfiguration ändern. Ein nicht erreichbarer Endpunkt und eine fehlerhafte Konfiguration führen zu ähnlichen Fehlern.

Sendet dsh meinen Code standardmäßig irgendwohin?

Bei einem gehosteten Modell: ja. Ihr Prompt und der Inhalt der Dateien, die der Agent gelesen hat, befinden sich in der API-Anfrage an diesen Anbieter. Bei einem lokalen Endpunkt geht die Anfrage an das Loopback-Interface und bleibt auf dem Rechner. Telemetrie wird separat übertragen und ist standardmäßig deaktiviert: DSH_TELEMETRY_MODE wird bei nicht gesetzter Variable zu DISABLED aufgelöst. In diesem Zustand wird kein Exporter erstellt. Setzen Sie DSH_TELEMETRY_DISABLED=1, um die Telemetrie vor dem Start des Laufs zu deaktivieren.

Warum meldet dsh MISSING_CREDENTIAL, obwohl meine Variable gesetzt ist?

Weil dsh die von apiKeyEnv angegebene Variable aus der Prozessumgebung des eigenen Prozesses liest. Eine in Ihrer Shell exportierte Variable steht einem systemd-Dienst, der Sitzung eines anderen Benutzers oder einem Prozess, der vor dem Export gestartet wurde, nicht zur Verfügung. Legen Sie den Wert für die Unit in einer EnvironmentFile mit den Berechtigungen 600 ab, oder exportieren Sie ihn in derselben Shell, die dsh startet. Prüfen Sie mit sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ, welche Werte der laufende Prozess tatsächlich enthält.

Welche Node.js-Version benötigt dsh?

Node.js 22.19 oder höher innerhalb der 22er-Linie oder Node.js 24 und höher. Node 23 liegt außerhalb des unterstützten Bereichs. Führen Sie zuerst node -v aus. Ein Startfehler aufgrund einer nicht unterstützten Runtime sieht wie eine fehlerhafte Installation aus. Dadurch installieren Benutzer häufig das Paket erneut, obwohl stattdessen die Runtime aktualisiert werden muss.