Konfiguracja dsh: API keys, modele i endpointy

Lokalizacja konfiguracji dsh

dsh (DeepSeek Harness) przechowuje konfigurację w jednym katalogu: $DSH_HOME, którego domyślną ścieżką jest ~/.dsh. Wszystkie ustawienia wprowadzone w interfejsie WWW są zapisywane w tym miejscu jako zwykłe pliki. Skopiowanie tego katalogu na inny serwer sprawia, że nowa maszyna przejmuje zachowanie poprzedniej.

Cztery ścieżki zawierają wszystkie istotne elementy konfiguracji.

• ~/.dsh/settings.yaml przechowuje ustawienia wprowadzone ręcznie oraz przez interfejs, w tym trasy dostawców i modeli.
• ~/.dsh/.credentials.yaml przechowuje dane uwierzytelniające. Ustawienia zawierają jedynie odwołanie 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 warstwę własnych poprawek. Jest ona nakładana na wbudowaną konfigurację dla każdego profilu.

Firma DeepSeek ogłosiła udostępnienie narzędzia harness jako wersji poglądowej dla programistów 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 przewodnika, w tym niniejszego, należy zweryfikować je z dokumentacją zainstalowanej wersji, ponieważ wersje poglądowe wprowadzają zmiany w nazewnictwie 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ższych. Node 23 znajduje się poza tym zakresem. Najpierw sprawdź wersję, ponieważ niedopasowanie wersji powoduje błąd przy uruchomieniu, a komunikat o błędzie sugeruje uszkodzenie pakietu.

node -v
npx @deepseek-ai/dsh web

npx pobiera pakiet z rejestru npm i uruchamia interfejs Web UI na http://127.0.0.1:3080. Powiązuje on adres pętli zwrotnej (loopback), co oznacza, że port nie jest dostępny z innej maszyny, nawet jeśli zapora sieciowa na to pozwala. Na serwerze VPS przekieruj go przez SSH zamiast otwierać port 3080 na świat. Jeśli wyświetlony adres URL jest niejasny, dlaczego dsh uruchamia się pod tym adresem wyjaśnia, co chroni powiązanie z adresem pętli zwrotnej, a czego nie.

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 klucz API. Wklej klucz z platform.deepseek.com i zapisz go. Ścieżka modelu staje się użyteczna natychmiast, bez restartu, ponieważ działający serwer przechowuje poświadczenia i rozwiązuje odwołanie w czasie rzeczywistym. Dostęp do dsh Web UI na zdalnym serwerze omawia tunelowanie oraz przypadek użycia reverse proxy, a instalacja DeepSeek Harness na VPS opisuje 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, uruchom 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 wyświetla 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 pozostałe z wbudowanej listy) przyjmuje klucz poprzez stronę Models. Wartość trafia do ~/.dsh/.credentials.yaml, a ustawienia przechowują jedynie odwołanie 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 zalecany 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 zapisaną przez niego strukturę. W fazie developer preview zagnieżdżenie jest elementem, który najczęściej ulega zmianom, a plik wygenerowany 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. Przypisz jednostce jej własny plik.

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

Utrzymuj ten plik z uprawnieniami 600, którego 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. Wybranie 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 rozwiązanie zastępcze dla modeli, których katalog nie opisuje. Własna trasa chat-completions dostawcy DeepSeek obsługuje tylko tekst i nie można jej skonfigurować inaczej, dlatego obraz dołączony do tej trasy zostanie odrzucony 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. Narzędzie 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, ale ignoruje jego wartość, więc dowolny niepusty ciąg znaków będzie odpowiedni.

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, wliczając w to tag po dwukropku. Błąd 401 podczas pobierania dostępnych modeli wynika z procesu wykrywania modelu, który wywołuje GET /models na bazowym adresie URL; w przypadku punktów końcowych, które nie obsługują tej ścieżki, modele należy wpisać ręcznie.

Kolejną pułapką jest bazowy adres URL. Jeśli pominiesz /v1, żądania trafią na ścieżki nieobsługiwane przez Ollama, co spowoduje błąd 404 i uniemożliwi uruchomienie modelu. Sufiks 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 będą przesyłane 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, wyniki wykonanych poleceń oraz wszelkie dane narzędzi, które agent zdecydował się dołączyć. Kod źródłowy znajduje się wewnątrz tego ładunku za każdym razem, gdy agent otwiera plik. Tak działa model hostowany i dlatego należy przemyśleć, w którym katalogu uruchamia się agenta.

W przypadku innego dostawcy z katalogu lub bramy firmowej, ten sam ładunek trafia do wybranego 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 korzystają z sieci. 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 uruchamianiu serwerów MCP na VPS. Wtyczki należą do tej samej kategorii, ponieważ instalacja wtyczki uruchamia kod innego autora z uprawnieniami agenta, dlatego warto sprawdzić, do czego wtyczka ma dostęp przed jej instalacją. Dotyczy to również telemetrii, jeśli zostanie włączona.

Telemetria jest wyłączona do momentu wyrażenia zgody. DSH_TELEMETRY_MODE to przełącznik zgody, a wartości nieustawione, puste lub nierozpoznane są interpretowane jako DISABLED. W tym stanie dsh nie tworzy dostawcy, procesora ani eksportera OpenTelemetry (OTel), więc nowy profil nie generuje ż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 trybu, należy ustawić DSH_TELEMETRY_DISABLED=1. Każda niepusta wartość oznacza autorytatywną rezygnację i jest odczytywana przed rozpoczęciem pracy, więc kod projektu nie może jej zmienić w trakcie sesji. Domyślny adres kolektora to harness-telemetry.deepseeksvc.com; warto znać tę nazwę 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 oraz brak połączeń z adresami publicznymi. Każde inne połączenie należy zidentyfikować 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 dotfiles 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 technicznego. Pliki z poświadczeniami nie powinny być w ten sposób udostępniane.
• Dane wyjściowe env i zrzuty ekranu terminala. Każde polecenie wyświetlające całe środowisko ujawnia również klucz.
• Kopie zapasowe. ~/.dsh warto archiwizować, jednak .credentials.yaml wewnątrz niego to aktywny sekret. Wyklucz ten plik z kopii lub zaszyfruj archiwum.

Powyższe zasady nie dotyczą wyłącznie dsh, a artykuł utrzymywanie sekretów poza plikami env w Compose omawia ten sam problem w kontekście 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. Jeśli przypięta instalacja odmawia uruchomienia lub npx ciągle dostarcza kompilację, o którą nie wnioskowano, błędy instalacji i wersji generowane przez wersję preview wyjaśniają kwestie pamięci podręcznej npx oraz npm dostarczanego z Node. Należy przechowywać settings.yaml oraz cordis.patch.yml w systemie kontroli wersji, wykluczając plik z danymi uwierzytelniającymi, aby móc śledzić zmiany po aktualizacji.

Dwie flagi pomagają w sytuacjach, gdy profil nie działa zgodnie z oczekiwaniami. --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 złożoną konfigurację dla danego profilu. Porównanie obu wyników pozwala sprawdzić, co faktycznie zmieniła warstwa poprawki, co jest szybsze niż ręczna analiza warstw.

dsh --profile web --dump-config

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

FAQ

Gdzie dsh przechowuje mój klucz API DeepSeek?

W $DSH_HOME/.credentials.yaml, co domyślnie oznacza ~/.dsh/.credentials.yaml, chyba że samodzielnie zdefiniowano DSH_HOME. Strona Models zapisuje tam klucz, a ustawienia przechowują jedynie odwołanie do niego, dzięki czemu sekret znajduje się w jednym pliku. Należy sprawdzić uprawnienia za pomocą stat -c '%a %n' ~/.dsh/.credentials.yaml i ustawić je na 600, jeśli są mniej restrykcyjne. Własny dostawca pozwala całkowicie uniknąć użycia pliku poprzez wskazanie zmiennej środowiskowej w apiKeyEnv.

Jak skonfigurować dsh, aby korzystało z modelu lokalnego zamiast API DeepSeek?

Należy dodać własnego dostawcę, którego base URL wskazuje na lokalny endpoint zgodny 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 podania klucza API, ale ignoruje jego wartość, więc dowolny niepusty ciąg znaków jest poprawny. Przed edycją konfiguracji dsh należy potwierdzić działanie endpointu za pomocą curl -s http://127.0.0.1:11434/v1/models, ponieważ nieaktywny endpoint i błędna konfiguracja generują podobne komunikaty o błędach.

Czy dsh domyślnie wysyła mój kod na zewnątrz?

W przypadku modelu hostowanego – tak. Prompt oraz zawartość plików odczytanych przez agenta są przesyłane w żądaniu API do dostawcy. Przy użyciu lokalnego endpointu żądanie trafia na adres loopback i pozostaje na maszynie. Telemetria stanowi osobny strumień i jest domyślnie wyłączona: DSH_TELEMETRY_MODE przyjmuje wartość DISABLED, gdy nie jest ustawione, a w tym stanie żaden eksporter nie jest tworzony. Należy ustawić DSH_TELEMETRY_DISABLED=1, aby zrezygnować z przesyłania danych przed uruchomieniem procesu.

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

Ponieważ dsh odczytuje zmienną wskazaną przez apiKeyEnv ze środowiska własnego procesu. Zmienna wyeksportowana w powłoce nie jest widoczna dla usługi systemd, sesji innego użytkownika ani procesu uruchomionego przed wykonaniem eksportu. Należy umieścić wartość w pliku EnvironmentFile z uprawnieniami 600 dla danej jednostki lub wyeksportować ją w tej samej powłoce, z której uruchamiane jest dsh. Wartość faktycznie dostępną dla uruchomionego procesu można sprawdzić 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 wersji 24 i wyższych. Node 23 znajduje się poza zakresem wsparcia. Przed wykonaniem jakichkolwiek innych czynności należy uruchomić node -v, ponieważ błąd uruchomienia wynikający z nieobsługiwanego środowiska wykonawczego przypomina uszkodzoną instalację i skłania użytkowników do reinstalacji pakietu zamiast aktualizacji środowiska wykonawczego.