Konfiguracja dsh: API keys, modele i endpointy

Gdzie dsh przechowuje swoją konfigurację

dsh (DeepSeek Harness) przechowuje konfigurację w jednym katalogu: $DSH_HOME, którego domyślna lokalizacja to ~/.dsh. Wszystkie ustawienia wprowadzone w interfejsie WWW są zapisywane w tym miejscu jako zwykłe pliki. Skopiowanie tego katalogu na inny serwer sprawi, że nowa maszyna przejmie zachowanie starej.

Wszystkie istotne elementy znajdują się w czterech ścieżkach.

• ~/.dsh/settings.yaml zawiera ustawienia wprowadzone ręcznie oraz przez interfejs, w tym trasy dostawców i modeli.
• ~/.dsh/.credentials.yaml przechowuje dane uwierzytelniające. Ustawienia zawierają jedynie odniesienie do poświadczeń, więc sama wartość klucza znajduje się w jednym pliku.
• ~/.dsh/profiles/ przechowuje nazwane profile, a ~/.dsh/storages/ zapisane sesje.
• ~/.dsh/cordis.patch.yml stanowi własną warstwę poprawek użytkownika. Jest ona nakładana na wbudowaną konfigurację dla każdego profilu.

DeepSeek ogłosił udostępnienie narzędzia jako developer preview na licencji MIT w dniu 17 sierpnia 2026 r., a plik README wskazuje na możliwość wystąpienia zmian niekompatybilnych wstecz. Nazwy pól oraz ścieżki w tym przewodniku są zgodne z dokumentacją repozytorium na sierpień 2026 r. Przed skopiowaniem konfiguracji z jakiegokolwiek poradnika, w tym niniejszego, należy zweryfikować je z dokumentacją zainstalowanej wersji, ponieważ w fazie preview nazwy elementów mogą ulegać zmianom pomiędzy wydaniami.

Uczciwe minimum na start

dsh wymaga Node.js w wersji 22.19 lub nowszej z linii 22, albo wersji 24 i wyższej. Node 23 znajduje się poza tym zakresem. Najpierw sprawdź wersję, ponieważ niedopasowanie wersji powoduje błąd przy starcie, a komunikat o błędzie sugeruje uszkodzenie pakietu.

node -v
npx @deepseek-ai/dsh web

npx pobiera pakiet z rejestru npm i uruchamia Web UI na http://127.0.0.1:3080. Usługa wiąże się z adresem loopback, co oznacza, że port nie jest dostępny z innej maszyny, nawet jeśli zapora sieciowa na to pozwala. Na serwerze VPS przekieruj port przez SSH zamiast otwierać 3080 na świat.

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

Otwórz http://127.0.0.1:3080 na swoim laptopie, a następnie przejdź do Settings i Models. Karta DeepSeek zawiera jedno pole na API key. Wklej klucz z platform.deepseek.com i zapisz zmiany. Ścieżka modelu staje się dostępna natychmiast, bez konieczności restartu, ponieważ działający serwer przechowuje poświadczenia i rozwiązuje odwołania w czasie rzeczywistym. Dostęp do dsh Web UI na zdalnym serwerze opisuje tunelowanie oraz przypadek reverse proxy, a instalacja DeepSeek Harness na VPS omawia przygotowanie serwera, które zakłada ten przewodnik.

Po zapisaniu sprawdź, co utworzyła aplikacja.

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

Powinieneś zobaczyć settings.yaml, .credentials.yaml oraz profiles/. Jeśli stat wyświetla tryb inny niż 600, wykonaj chmod 600 ~/.dsh/.credentials.yaml. Plik poświadczeń z uprawnieniami do odczytu dla grupy lub wszystkich użytkowników udostępnia Twój klucz każdemu innemu kontu na serwerze.

Do pierwszego uruchomienia bez przeglądarki wystarczy jedno polecenie.

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

Profil headless uruchamia pojedynczą sesję i wypisuje końcową odpowiedź.

Zmienne środowiskowe lub plik konfiguracyjny

Istnieją dwa sposoby przekazania klucza do dsh i nie są one wymienne.

Dostawca katalogowy (DeepSeek, Anthropic, OpenAI oraz reszta wbudowanej listy) przyjmuje klucz poprzez stronę Models. Wartość trafia do ~/.dsh/.credentials.yaml, a ustawienia przechowują jedynie odniesienie do niej. Interfejs WWW nigdy nie wyświetla klucza ponownie po jego zapisaniu.

Dostawca niestandardowy może wskazać zmienną środowiskową za pomocą apiKeyEnv. Jest to format opisany w dokumentacji dla ~/.dsh/settings.yaml.

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]

Najpierw dodaj jednego dostawcę przez interfejs WWW, a następnie otwórz ~/.dsh/settings.yaml i skopiuj strukturę, którą plik zapisał. W fazie developer preview zagnieżdżenie jest elementem, który najczęściej ulega zmianie, a plik zapisany przez aplikację jest zawsze aktualny.

apiKeyEnv jest odczytywane ze środowiska procesu dsh, a nie z powłoki logowania. Klucz wyeksportowany w sesji interaktywnej jest niewidoczny dla jednostki systemd, dlatego ta sama konfiguracja, która działa po ręcznym wpisaniu dsh web, zwraca MISSING_CREDENTIAL w ramach usługi. Należy dostarczyć jednostce własny plik.

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

Plik ten należy przechowywać z uprawnieniami 600, których właścicielem jest użytkownik, na koncie którego uruchomiona jest usługa.

Wybór modeli oraz identyfikator, którego nie można zmienić

Każdy skonfigurowany dostawca pojawia się w selektorze modeli. Wybór modelu ustawia go również jako domyślny dla nowych sesji. Istniejące sesje zachowują przypisany do nich model, więc przełączenie nie powoduje nadpisania starej konwersacji.

Identyfikator dostawcy (Provider ID) jest stały. Żądania, zapisane sesje, domyślne ustawienia modeli oraz odwołania do poświadczeń wskazują na ten identyfikator, dlatego nie istnieje przycisk zmiany nazwy. Zmiana identyfikatora wymaga utworzenia nowego dostawcy i usunięcia starego. Należy wybrać nazwę, która będzie odpowiednia w dłuższej perspektywie: local-ollama zamiast test2.

Modele obsługują wyłącznie tekst, chyba że zadeklarowano inaczej. Należy dodać input: [text, image] do wpisu modelu, aby zadeklarować obsługę obrazów, lub ustawić defaultInput na poziomie trasy jako ustawienie zapasowe dla modeli, których katalog nie opisuje. Trasa chat-completions dostawcy DeepSeek obsługuje wyłącznie tekst i nie można jej skonfigurować inaczej, dlatego obraz dołączony do tej trasy jest odrzucany przed wysłaniem jakichkolwiek danych.

Skierowanie dsh na lokalny punkt końcowy w celu utrzymania kodu na serwerze

Ollama udostępnia API zgodne z OpenAI pod adresem http://127.0.0.1:11434/v1. dsh komunikuje się z dowolnym bazowym adresem URL zgodnym z OpenAI za pośrednictwem niestandardowego dostawcy, dzięki czemu oba komponenty łączą się bezpośrednio. Najpierw skonfiguruj serwer modelu: samodzielne hostowanie LLM za pomocą Ollama na VPS zawiera informacje o instalacji i pobieraniu modelu.

Przed przystąpieniem do konfiguracji dsh upewnij się, że punkt końcowy odpowiada.

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

ollama list wyświetla dokładny tag każdego pobranego modelu. Skopiuj ten ciąg znaków. curl zwraca listę tych samych modeli w formacie JSON. Pusta lista oznacza, że Ollama działa, ale nie pobrano żadnych modeli. Connection refused oznacza, że Ollama nie działa lub nie nasłuchuje na porcie 11434.

Teraz dodaj dostawcę. Ollama wymaga pola klucza API i ignoruje jego wartość, więc dowolny niepusty ciąg znaków będzie poprawny.

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>

Wyeksportuj zmienną w miejscu, w którym proces dsh będzie mógł ją odczytać.

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

Trzy rodzaje błędów obejmują niemal wszystkie nieudane próby konfiguracji. MISSING_CREDENTIAL oznacza, że dsh nie mogło odczytać zmiennej o nazwie apiKeyEnv, więc sprawdź środowisko procesu, a nie środowisko terminala. UNKNOWN_MODEL oznacza, że id nie pasuje do skonfigurowanego modelu, więc porównaj je z ollama list znak po znaku, włącznie z tagiem po dwukropku. Błąd 401 podczas pobierania dostępnych modeli wynika z mechanizmu wykrywania modeli, który wywołuje GET /models na bazowym adresie URL; punkty końcowe, które nie obsługują tej ścieżki, wymagają ręcznego wpisania nazw modeli.

Kolejną pułapką jest bazowy adres URL. Pomiń /v1, a żądania trafią na ścieżki nieobsługiwane przez Ollama, co spowoduje błąd 404 i brak uruchomienia modelu. Ten przyrostek jest częścią interfejsu zgodnego z OpenAI, a nie elementem dekoracyjnym.

Jeśli Ollama działa na innej maszynie, adres tej maszyny staje się bazowym adresem URL, a Twoje zapytania przesyłane są przez sieć otwartym tekstem za pomocą zwykłego HTTP. Utrzymuj usługę na tym samym hoście lub umieść ją za TLS (transport layer security) i uwierzytelnianiem: zabezpieczanie wystawionego punktu końcowego Ollama.

Co opuszcza maszynę w poszczególnych trybach

W przypadku użycia klucza DeepSeek każde żądanie trafia do API DeepSeek. Żądanie to zawiera prompt, zawartość plików odczytanych przez agenta w celu udzielenia odpowiedzi, dane wyjściowe wykonanych poleceń oraz wszelkie wyniki narzędzi, które agent zdecydował się dołączyć. Kod źródłowy znajduje się wewnątrz tego ładunku danych za każdym razem, gdy agent otworzy plik. Tak działa model hostowany i dlatego należy rozważyć, w którym katalogu uruchamia się agenta.

W przypadku korzystania z innego dostawcy z katalogu lub bramy firmowej, ten sam ładunek danych trafia do danego dostawcy. Adres base URL wskazuje dokładnie, gdzie.

W przypadku lokalnego punktu końcowego żądanie do modelu trafia do 127.0.0.1:11434 i pozostaje na maszynie. Żadna część kodu nie dociera do dostawcy modelu. Trzy elementy nadal przekraczają sieć. npx pobiera pakiet z rejestru npm. Każde narzędzie uruchomione przez agenta może samodzielnie łączyć się z Internetem, w tym serwery MCP (model context protocol), z którymi nawiązano połączenie, co szczegółowo opisano w uruchamianie serwerów MCP na VPS. Oraz telemetria, jeśli zostanie włączona.

Telemetria jest wyłączona do momentu wyrażenia zgody. DSH_TELEMETRY_MODE to przełącznik zgody, a nieustawione, puste lub nierozpoznane wartości są interpretowane jako DISABLED. W tym stanie dsh nie tworzy dostawcy, procesora ani eksportera OpenTelemetry (OTel), więc nowy profil nie wysyła żadnych żądań sieciowych związanych z telemetrią. FEEDBACK_ONLY włącza udostępnianie dzienników sesji wyzwalanych przez opinie użytkownika. FULL zezwala również na raportowanie przez launcher. Kanał sesji może eksportować zawartość sesji, dane narzędzi, prompty oraz ścieżki obszaru roboczego, więc należy traktować FULL jako wysyłanie pracy do DeepSeek.

Aby wymusić całkowite zatrzymanie, które nie zależy od poprawnego ustawienia ciągu znaków trybu, należy ustawić DSH_TELEMETRY_DISABLED=1. Każda niepusta wartość jest wiążącym wyłączeniem zgody i jest odczytywana przed rozpoczęciem działania, więc kod projektu nie może włączyć jej ponownie w trakcie sesji. Domyślny adres kolektora to harness-telemetry.deepseeksvc.com; jest to przydatna nazwa, którą warto znać podczas analizy własnych logów firewalla.

Należy weryfikować ustawienia zamiast im ufać. Podczas wykonywania zadania należy wyświetlić listę połączeń wychodzących utrzymywanych przez proces.

sudo ss -tnp | grep -i node

W trybie modelu lokalnego powinno być widoczne połączenie zwrotne (loopback) do 11434 i brak połączeń z adresami publicznymi. Każde inne połączenie wymaga identyfikacji przed kontynuowaniem pracy. Co agent programistyczny wysyła do domu zawiera opis tej samej weryfikacji dla innych środowisk oraz wyjaśnienie, jak interpretować wyniki.

Gdzie nie należy przechowywać sekretów

• Historia powłoki. export DEEPSEEK_API_KEY=sk-... jest zapisywane w ~/.bash_history w postaci jawnej i pozostaje tam długo po rotacji klucza. Poprzedź polecenie spacją, gdy ustawiona jest zmienna HISTCONTROL=ignorespace, lub pomiń powłokę i zapisz wartość bezpośrednio do pliku z uprawnieniami 600.
• Zatwierdzone pliki konfiguracyjne (dotfiles). Klucz w ~/.bashrc lub ~/.zshrc znajduje się o jedno git add od publicznego repozytorium, jeśli przechowujesz pliki konfiguracyjne w git. Uruchom git grep -I -n 'sk-' w tym repozytorium przed wykonaniem push.
• settings.yaml. Używaj apiKeyEnv dla niestandardowych dostawców, aby plik zawierał nazwę zmiennej zamiast sekretu. Pliki konfiguracyjne są wklejane do zgłoszeń błędów i czatów wsparcia. Pliki z poświadczeniami nie powinny być.
• Dane wyjściowe env i zrzuty ekranu terminala. Wszystko, co wyświetla całe środowisko, wyświetla również klucz.
• Kopie zapasowe. ~/.dsh warto archiwizować, a .credentials.yaml wewnątrz niego jest aktywnym sekretem. Wyklucz ten plik lub zaszyfruj archiwum.

Te zasady nie dotyczą wyłącznie dsh, a utrzymywanie sekretów poza plikami env w Compose omawia ten sam problem po stronie kontenerów na tym samym serwerze.

Praca z wersją developer preview

Należy przypiąć przetestowaną wersję, ponieważ wersja preview może zmienić klucz konfiguracyjny w wydaniu poprawkowym, co spowoduje błąd ładowania u dostawcy. Pliki settings.yaml oraz cordis.patch.yml należy przechowywać w systemie kontroli wersji, wykluczając plik z poświadczeniami, aby móc śledzić zmiany po aktualizacji.

Dwie flagi pomagają w diagnostyce, gdy profil nie działa zgodnie z oczekiwaniami. Flaga --dump-default-config wyświetla złożoną konfigurację domyślną bez uruchamiania usługi, a --dump-config w ten sam sposób wyświetla konfigurację złożoną dla danego profilu. Porównanie obu wyników pozwala sprawdzić, co faktycznie zmieniła warstwa poprawek, co jest szybsze niż ręczna analiza warstw.

dsh --profile web --dump-config

W przypadku awarii po aktualizacji należy uruchomić to polecenie w pierwszej kolejności. Klucz, który został przeniesiony między wydaniami, będzie widoczny jako brakująca gałąź w zrzucie, a naprawa sprowadzi się do edycji jednej linii zamiast ponownej instalacji.

FAQ

Gdzie dsh przechowuje mój klucz API DeepSeek?

W $DSH_HOME/.credentials.yaml, który jest lokalizacją ~/.dsh/.credentials.yaml, chyba że samodzielnie ustawisz DSH_HOME. Strona Models zapisuje tam klucz, a ustawienia przechowują jedynie odwołanie do niego, dzięki czemu sekret znajduje się w jednym pliku. Sprawdź uprawnienia za pomocą stat -c '%a %n' ~/.dsh/.credentials.yaml i ustaw je na 600, jeśli są mniej restrykcyjne. Niestandardowy dostawca pozwala całkowicie uniknąć użycia pliku poprzez zdefiniowanie zmiennej środowiskowej za pomocą apiKeyEnv.

Jak sprawić, by dsh używał modelu lokalnego zamiast API DeepSeek?

Dodaj niestandardowego dostawcę, którego bazowy URL jest Twoim lokalnym endpointem zgodnym z OpenAI. W przypadku Ollama jest to http://127.0.0.1:11434/v1, z api: openai-completions oraz modelem id skopiowanym dokładnie z ollama list. Ollama wymaga wartości klucza API, ale ignoruje ją, więc dowolny niepusty ciąg znaków będzie działał. Potwierdź, że endpoint odpowiada za pomocą curl -s http://127.0.0.1:11434/v1/models, zanim zaczniesz edytować konfigurację dsh, ponieważ niedziałający endpoint i błędna konfiguracja generują podobne błędy.

Czy dsh domyślnie wysyła mój kod gdziekolwiek?

W przypadku modelu hostowanego – tak. Twój prompt oraz zawartość plików odczytanych przez agenta znajdują się w żądaniu API wysyłanym do dostawcy. W przypadku lokalnego endpointu żądanie trafia na interfejs loopback i pozostaje na maszynie. Telemetria to osobny strumień danych i jest domyślnie wyłączona: DSH_TELEMETRY_MODE przyjmuje wartość DISABLED, gdy nie jest ustawiona, i w tym stanie żaden eksporter nie jest tworzony. Ustaw DSH_TELEMETRY_DISABLED=1, aby zrezygnować z przesyłania danych, co jest sprawdzane przed uruchomieniem procesu.

Dlaczego dsh zgłasza MISSING_CREDENTIAL, mimo że moja zmienna jest ustawiona?

Ponieważ dsh odczytuje zmienną wskazaną przez apiKeyEnv ze środowiska własnego procesu. Zmienna wyeksportowana w powłoce nie dociera do usługi systemd, sesji innego użytkownika ani procesu uruchomionego przed wyeksportowaniem zmiennej. Umieść wartość w EnvironmentFile z uprawnieniami 600 dla jednostki lub wyeksportuj ją w tej samej powłoce, która uruchamia dsh. Sprawdź, co faktycznie zawiera uruchomiony proces za pomocą sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ.

Jakiej wersji Node.js wymaga dsh?

Node.js 22.19 lub nowszej z linii 22, albo 24 i wyższej. Node 23 znajduje się poza wspieranym zakresem. Uruchom node -v przed wykonaniem jakichkolwiek innych działań, ponieważ błąd uruchomienia wynikający z nieobsługiwanego środowiska wykonawczego wygląda jak uszkodzona instalacja i skłania użytkowników do ponownej instalacji pakietu zamiast środowiska wykonawczego.