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 alte.

Vier Pfade enthalten alles, was Sie bearbeiten werden.

• ~/.dsh/settings.yaml enthält manuell und über die UI geschriebene Einstellungen, einschließlich Ihrer Provider- und Modellrouten.
• ~/.dsh/.credentials.yaml enthält die Secrets. Die Einstellungen enthalten nur eine Referenz auf ein Credential. Der eigentliche Schlüsselwert steht daher in einer einzelnen 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 gelegt.

DeepSeek kündigte das Harness am 17 August 2026 als Entwickler-Preview unter der MIT-Lizenz an. In der README wird darauf hingewiesen, dass es zu inkompatiblen Änderungen kommen wird. Die Feldnamen und Pfade in diesem Leitfaden entsprechen der Repository-Dokumentation vom August 2026. Vergleichen Sie sie mit der Dokumentation der von Ihnen installierten Version, bevor Sie Konfigurationen aus einem beliebigen Leitfaden kopieren, auch aus diesem. Bei einer Preview werden Bezeichnungen zwischen Releases geändert.

Das ehrliche Minimum bis zur ersten Ausgabe

dsh benötigt Node.js 22.19 oder höher innerhalb der 22er-Reihe oder Version 24 und höher. Node 23 liegt außerhalb dieses Bereichs. Prüfen Sie die Version zuerst, da ein Versionskonflikt beim Start fehlschlägt und die Fehlermeldung wie ein beschädigtes Paket aussieht.

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. Dadurch ist der Port von einem anderen Rechner aus nicht erreichbar, selbst wenn die Firewall den Zugriff erlaubt. Leiten Sie den Port auf einem VPS stattdessen über SSH weiter, anstatt 3080 im Internet zu öffnen. Falls die ausgegebene URL unklar ist, erklärt warum dsh auf dieser Adresse startet, welche Zugriffe die Loopback-Bindung verhindert und welche nicht.

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 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 verwendbar, ohne Neustart, da der laufende Server die Zugangsdaten speichert und die Referenz zur Laufzeit auflöst. Zugriff auf die dsh-Weboberfläche auf einem Remote-Server behandelt den Fall mit SSH-Tunnel und Reverse Proxy. DeepSeek Harness auf einem VPS installieren beschreibt die Servervorbereitung, die dieser Leitfaden voraussetzt.

Prüfen Sie nach dem Speichern, was die Anwendung erstellt 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 Gruppen oder alle Benutzer lesbare Zugangsdaten-Datei gibt Ihren Schlüssel an jedes andere Konto auf dem Server 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 endgültige Antwort aus.

Umgebungsvariablen oder Konfigurationsdatei

Es gibt zwei Möglichkeiten, dsh einen Schlüssel bereitzustellen. Diese Möglichkeiten 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. In Ihren Einstellungen wird nur eine Referenz darauf gespeichert. Nach dem Speichern zeigt die Web UI den Schlüssel nicht erneut an.

Ein benutzerdefinierter Anbieter kann stattdessen mit apiKeyEnv eine Umgebungsvariable angeben. Dies ist die Struktur, die die Dokumentation für ~/.dsh/settings.yaml vorgibt.

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 geschriebene Struktur. Während einer Entwickler-Vorschau ä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 für diese Datei die Berechtigungen auf 600. Sie muss dem Benutzer gehören, unter dem der Dienst ausgeführt wird.

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

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

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

Modelle unterstützen standardmäßig nur Text. Fügen Sie input: [text, image] zu einem Modelleitrag hinzu, um die Bildunterstützung zu deklarieren. Alternativ können Sie defaultInput auf Routenebene als Fallback für Modelle festlegen, deren Katalogeintrag diese Information nicht enthält. Die Chat-Completions-Route von DeepSeek unterstützt ausschließlich 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 verweisen, 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. Beide Komponenten lassen sich daher direkt verbinden. Richten Sie zuerst den Modellserver ein: ein LLM mit Ollama auf einem VPS selbst hosten beschreibt die Installation und das Abrufen 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 jetzt den Provider hinzu. Ollama verlangt ein Feld für den API-Schlüssel und ignoriert dessen Wert. Daher funktioniert 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 in der Umgebung, die der dsh-Prozess sieht.

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, 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, benötigen eine manuell eingetragene Modellliste.

Ein weiterer Fehler betrifft die Basis-URL. Lassen Sie /v1 weg, werden Anfragen an Pfade gesendet, die Ollama nicht bereitstellt. Der Aufruf schlägt dann mit 404 fehl, und das Modell wird nicht ausgeführt. Das Suffix gehört zur OpenAI-kompatiblen Schnittstelle. Es ist keine optionale Ergänzung.

Wenn Ollama auf einem anderen Rechner läuft, wird die Adresse dieses Rechners zur Basis-URL. Ihre Prompts werden dann unverschlüsselt über HTTP im Klartext über das Netzwerk übertragen. Betreiben Sie Ollama auf demselben Host oder stellen Sie es hinter TLS (Transport Layer Security) und eine Authentifizierung: einen öffentlich erreichbaren Ollama-Endpunkt absichern.

Was den Rechner in den einzelnen Modi verlässt

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 für die Antwort gelesen hat, die Ausgabe der ausgeführten Befehle und alle Tool-Ergebnisse, die er einbezieht. Wenn der Agent eine Datei geöffnet hat, befindet sich Ihr Quellcode in diesem Payload. 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 übertragen weiterhin Daten über das Netzwerk. npx lädt das Paket aus der npm-Registry herunter. Jedes Tool, das der Agent ausführt, kann unabhängig davon auf das Internet zugreifen. Dazu gehören auch verbundene MCP-Server (Model Context Protocol), die MCP-Server auf einem VPS ausführen ausführlich behandelt. Ein Plugin gehört ebenfalls in diese Kategorie. Bei seiner Installation wird der Code eines anderen Autors mit den Berechtigungen Ihres Agenten ausgeführt. Deshalb sollten Sie vor der Installation prüfen, worauf ein Plugin zugreifen kann. Außerdem kann Telemetrie Daten übertragen, wenn Sie sie aktivieren.

Telemetrie ist standardmäßig deaktiviert. DSH_TELEMETRY_MODE ist die Einwilligungseinstellung. Nicht gesetzte, leere oder nicht erkannte Werte werden zu DISABLED aufgelöst. In diesem Zustand erstellt dsh keinen OpenTelemetry-(OTel-)Provider, -Processor oder -Exporter. Ein neues Profil erzeugt daher überhaupt keine Telemetrie-Netzwerkanfrage. FEEDBACK_ONLY aktiviert die Freigabe von Sitzungsprotokollen nach einer Feedback-Aktion. FULL erlaubt zusätzlich die Berichterstattung des Launchers. Der Sitzungsfeed kann Sitzungsinhalte, Tool-Daten, Prompts und Workspace-Pfade exportieren. Behandeln Sie FULL daher als Übertragung Ihrer Arbeit an DeepSeek.

Für eine zuverlässige Deaktivierung, die nicht davon abhängt, dass der Modus-String korrekt gesetzt ist, setzen Sie DSH_TELEMETRY_DISABLED=1. Jeder nicht leere Wert ist eine verbindliche Abmeldung. 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. Diesen Namen sollten Sie kennen, wenn Sie Ihre eigenen Firewall-Logs prüfen.

Überprüfen Sie die Einstellung, statt ihr zu vertrauen. Wenn eine Aufgabe läuft, listen Sie die ausgehenden Verbindungen auf, die der Prozess hält.

sudo ss -tnp | grep -i node

Im Modus mit lokalem Modell sollten Sie die Loopback-Verbindung zu 11434 sehen, aber keine Verbindung zu einer öffentlichen Adresse. Jede andere Verbindung sollten Sie identifizieren, bevor Sie fortfahren. Was ein Coding-Agent an externe Dienste überträgt führt dieselbe Prüfung für andere Harnesses aus und erklärt, wie Sie das Ergebnis auswerten.

Wohin Secrets nicht gehören

• Shell-Historie. export DEEPSEEK_API_KEY=sk-... wird von ~/.bash_history im Klartext geschrieben und bleibt dort noch lange nach der Rotation des Keys erhalten. Setzen Sie der Eingabe ein Leerzeichen voran, 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 Key in ~/.bashrc oder ~/.zshrc ist nur ein git add von einem öffentlichen Repository entfernt, wenn Sie Dotfiles mit git versionieren. Führen Sie in diesem Repository vor dem Push git grep -I -n 'sk-' aus.
• settings.yaml. Verwenden Sie apiKeyEnv für benutzerdefinierte Provider, damit die Datei statt eines Secrets einen Variablennamen enthält. Config-Dateien werden in Issue-Reports und Support-Chats eingefügt. Credentials-Dateien nicht.
• Ausgabe von env und Screenshots des Terminals. Alles, was die vollständige Umgebung ausgibt, gibt auch den Key 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-Env-Dateien heraushalten behandelt dasselbe Problem auf der Container-Seite desselben Servers.

Arbeiten mit einer Entwicklervorschau

Fixieren Sie die getestete Version, weil eine Vorschau in einem Patch-Release einen Konfigurationsschlüssel ändern kann und Ihr Provider dann nicht geladen werden kann. Wenn die Installation mit der fixierten Version anschließend den Start verweigert oder npx weiterhin einen nicht angeforderten Build bereitstellt, beschreibt die Installations- und Versionsfehler einer Vorschau den npx-Cache und die npm-Version, die mit Node ausgeliefert wird. Halten Sie settings.yaml und cordis.patch.yml unter Versionsverwaltung. Schließen Sie die Datei mit den Zugangsdaten aus. So sehen Sie, was sich nach einem Upgrade geändert hat.

Zwei Flags helfen, wenn sich ein Profil nicht erwartungsgemäß 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 einzelnen Ebenen von Hand zu lesen.

dsh --profile web --dump-config

Führen Sie diesen Befehl zuerst aus, wenn nach einem Upgrade etwas nicht mehr 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, also in ~/.dsh/.credentials.yaml, sofern Sie DSH_HOME nicht selbst setzen. Die Seite „Models“ schreibt den Schlüssel dort hinein. Ihre Einstellungen enthalten nur eine Referenz darauf. Das Geheimnis befindet sich daher in einer einzigen Datei. Prüfen Sie die Berechtigungen mit stat -c '%a %n' ~/.dsh/.credentials.yaml und setzen Sie sie auf 600, falls sie weiter gefasst sind. Ein benutzerdefinierter Provider kann die Datei vollständig vermeiden, indem Sie mit apiKeyEnv eine Umgebungsvariable angeben.

Wie bringe ich dsh dazu, ein lokales Modell statt der DeepSeek-API zu verwenden?

Fügen Sie einen benutzerdefinierten Provider hinzu, dessen Basis-URL auf Ihren lokalen OpenAI-kompatiblen Endpunkt zeigt. Für Ollama lautet sie http://127.0.0.1:11434/v1. Verwenden Sie api: openai-completions und ein Modell id, das Sie exakt aus ollama list kopieren. Ollama erwartet einen API-Key-Wert und ignoriert ihn. Daher funktioniert jede nicht leere Zeichenfolge. 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 Fehlermeldungen.

Sendet dsh meinen Code standardmäßig irgendwohin?

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

Warum meldet dsh MISSING_CREDENTIAL, obwohl meine Variable gesetzt ist?

Weil dsh die von apiKeyEnv angegebene Variable aus seiner eigenen Prozessumgebung liest. Eine in Ihrer Shell exportierte Variable erreicht keinen systemd-Dienst, keine Sitzung eines anderen Benutzers und keinen Prozess, der vor dem Export gestartet wurde. Legen Sie den Wert in einer EnvironmentFile für die Unit ab und setzen Sie die Berechtigungen auf 600. Alternativ exportieren Sie ihn in derselben Shell, aus der Sie dsh starten. 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 aus der 22er-Reihe oder 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 Laufzeitumgebung sieht wie eine fehlerhafte Installation aus. Dadurch installieren viele Benutzer das Paket neu, statt die Laufzeitumgebung zu aktualisieren.