dsh 設定教學：API 金鑰、模型與端點

dsh 儲存設定的位置

dsh (DeepSeek Harness) 會將設定儲存在一個目錄中：$DSH_HOME，預設值為 ~/.dsh。您在 Web UI 中設定的任何內容，都會以純文字檔案寫入該目錄。將此目錄複製到另一台伺服器後，新伺服器的行為就會與原本的伺服器相同。

以下 4 個路徑包含您會操作的所有內容。

• ~/.dsh/settings.yaml 儲存手動建立及由 UI 寫入的設定，包括 provider 與 model 路由。
• ~/.dsh/.credentials.yaml 儲存 secrets。設定只保留 credential 的參照，因此金鑰值本身會存放在其中一個檔案中。
• ~/.dsh/profiles/ 儲存具名 profiles，~/.dsh/storages/ 儲存已保存的 sessions。
• ~/.dsh/cordis.patch.yml 是您自己的修補層。對每個 profile 套用內建設定後，也會再套用此修補層。

DeepSeek 在 17 August 2026 將此 harness 宣布為採用 MIT 授權的 developer preview，README 也指出未來會有造成相容性中斷的變更。本指南中的欄位名稱與路徑，符合截至 August 2026 的 repository 文件。請先對照您所安裝版本的文件，再從任何指南（包括本指南）複製設定，因為 preview 版本可能會在不同 releases 之間重新命名項目。

首次輸出所需的最低設定

dsh 需要 22 系列的 Node.js 22.19 或更新版本，或 Node.js 24 以上版本。Node.js 23 不在支援範圍內。請先檢查版本，因為版本不相容會在啟動時失敗，而錯誤訊息看起來像是套件損壞。

node -v
npx @deepseek-ai/dsh web

npx 會從 npm registry 下載套件，並在 http://127.0.0.1:3080 啟動 Web UI。它會繫結至 loopback 位址，因此即使防火牆允許，其他機器仍無法連線到該連接埠。在 VPS 上，請改用 SSH 轉送，不要將 3080 開放至網際網路。

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

在筆記型電腦上開啟 http://127.0.0.1:3080，然後前往 Settings 和 Models。DeepSeek 卡片只有一個 API key 欄位。貼上從 platform.deepseek.com 取得的金鑰並儲存。模型路由會立即可用，無須重新啟動，因為執行中的伺服器會儲存認證資訊，並即時解析該參照。從遠端伺服器連線至 dsh Web UI 說明 tunnel 和反向代理的情境；在 VPS 上安裝 DeepSeek Harness 說明本指南假設的伺服器準備工作。

儲存後，查看應用程式建立了哪些內容。

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

您應該會看到 settings.yaml、.credentials.yaml 和 profiles/。如果 stat 顯示的模式不是 600，請執行 chmod 600 ~/.dsh/.credentials.yaml。群組可讀取或所有使用者可讀取的認證檔案，會讓伺服器上的其他帳號取得您的金鑰。

首次執行且不使用瀏覽器時，只需一個命令。

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

無頭模式檔案會執行單一工作階段，並輸出最終答案。

環境變數或設定檔

提供 dsh 金鑰有兩種方式，兩者不能互換。

目錄中的 provider（DeepSeek、Anthropic、OpenAI，以及內建清單中的其他 provider）會透過 Models 頁面取得金鑰。值會寫入 ~/.dsh/.credentials.yaml，而設定只保留對該值的參照。儲存後，Web UI 不會再次顯示金鑰。

自訂 provider 則可使用 apiKeyEnv 指定環境變數。文件對 ~/.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]

先透過 Web UI 新增一個 provider，再開啟 ~/.dsh/settings.yaml，並複製其中寫入的結構。開發人員預覽期間，最可能變更的是巢狀結構；應用程式剛寫入的檔案一定是目前的格式。

apiKeyEnv 會從 dsh 程序的環境讀取，不會從你的登入 shell 讀取。互動工作階段中 export 的金鑰對 systemd unit 不可見。因此，手動輸入 dsh web 時可正常運作的相同設定，在服務中會回傳 MISSING_CREDENTIAL。請為該 unit 指定專用檔案。

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

將該檔案的模式設為 600，並由服務執行時使用的使用者擁有。

選擇模型，以及無法重新命名的 ID

所有已設定的 provider 都會出現在模型選擇器中。選取模型後，該模型也會成為新工作階段的預設模型。已存在的工作階段會保留其中記錄的模型，因此切換模型不會改寫舊對話。

Provider ID 是永久的。請求、已儲存的工作階段、模型預設值和認證參照都會指向該 ID，因此沒有重新命名按鈕。變更 ID 代表必須建立新的 provider，並刪除舊的 provider。請選擇可長期使用的名稱：local-ollama，而不是 test2。

除非另行宣告，否則模型僅支援文字。在模型項目中加入 input: [text, image]，即可宣告支援影像；也可以在路由層級設定 defaultInput，作為目錄未描述之模型的後援設定。DeepSeek 自有的 chat-completions 路由僅支援文字，無法改成其他設定，因此附加至該路由的影像會在任何內容送出前遭到拒絕。

將 dsh 指向本機端點，讓程式碼留在主機上

Ollama 在 http://127.0.0.1:11434/v1 提供相容 OpenAI 的 API。dsh 可透過自訂 provider 連線到任何相容 OpenAI 的 base URL，因此兩者之間不需要其他元件。先設定模型伺服器：在 VPS 上使用 Ollama 自行代管 LLM 說明安裝與提取模型的步驟。

在修改 dsh 前，先確認端點能正常回應。

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

ollama list 會列出每個已提取模型的確切 tag。複製該字串。curl 會以 JSON 回傳相同的模型清單。空清單表示 Ollama 正在執行，但尚未提取任何模型。Connection refused 表示 Ollama 未執行，或未在 11434 上監聽。

現在新增 provider。Ollama 要求提供 API key 欄位，但會忽略其值，因此任何非空字串都可以。

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>

在 dsh 程序可取得該變數的環境中匯出它。

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

幾乎所有嘗試都可歸結為 3 種失敗情況。MISSING_CREDENTIAL 表示 dsh 無法讀取 apiKeyEnv 所指定名稱的變數，因此應檢查程序的環境，而不是終端機的環境。UNKNOWN_MODEL 表示 id 與已設定的模型不符，因此請逐字比對 ollama list，包括冒號後的 tag。擷取可用模型時若收到 401，原因是模型探索功能會在 base URL 上呼叫 GET /models；未提供該路徑的端點必須手動輸入模型。

base URL 也是常見陷阱。不要省略其中的 /v1，否則請求會送到 Ollama 未提供的路徑，呼叫會回傳 404，模型也不會執行。這個後綴是相容 OpenAI 介面的必要部分，不是裝飾。

如果 Ollama 在其他機器上執行，該機器的位址會成為 base URL，之後提示會透過未加密的純 HTTP 在網路上傳送。請讓它與 dsh 位於同一台主機，或將它放在 TLS（傳輸層安全性）與驗證機制後方：強化暴露在網路上的 Ollama 端點安全性。

各模式會讓哪些資料離開主機

使用 DeepSeek key 時，每個請求都會傳送至 DeepSeek 的 API。請求會包含你的提示、agent 為了回答而讀取的檔案內容、執行命令的輸出，以及它選擇納入的工具結果。只要 agent 開啟過某個檔案，你的原始碼就會出現在該 payload 中。這是託管模型的運作方式，也是你需要考慮從哪個目錄啟動 agent 的原因。

使用其他 catalog provider 或公司 gateway 時，相同的 payload 會改送至該供應商。base URL 會明確告訴你資料的目的地。

使用 local endpoint 時，模型請求會傳送至 127.0.0.1:11434，並留在本機。你的程式碼不會傳給任何模型供應商。但仍有 3 類資料會跨越網路。npx 會從 npm registry 下載套件。agent 執行的任何工具都可能自行連上網際網路，包括你連接的 MCP（model context protocol）伺服器；在 VPS 上執行 MCP 伺服器會詳細說明這一點。此外，如果你啟用 telemetry，telemetry 也會傳送資料。

在你選擇加入前，telemetry 預設為關閉。DSH_TELEMETRY_MODE 是同意開關；未設定、空值或無法辨識的值都會解析為 DISABLED。在此狀態下，dsh 不會建立 OpenTelemetry（OTel）provider、processor 或 exporter，因此全新的 profile 完全不會發出 telemetry 網路請求。FEEDBACK_ONLY 會選擇加入由回饋觸發的工作階段日誌分享。FULL 也會允許 launcher 回報。工作階段資料流可能匯出工作階段內容、工具資料、提示與 workspace 路徑，因此請將 FULL 視為會把你的工作傳送至 DeepSeek。

若要採取不依賴正確設定 mode 字串的強制停用措施，請設定 DSH_TELEMETRY_DISABLED=1。任何非空值都會被視為明確停用，而且該值會在執行開始前讀取，因此專案程式碼無法在工作階段中途重新啟用它。預設 collector 位址是 harness-telemetry.deepseeksvc.com；查看自己的防火牆日誌時，記住這個名稱會很有用。

請進行驗證，不要只信任設定值。執行工作時，列出該程序目前持有的對外連線。

sudo ss -tnp | grep -i node

在 local-model mode 中，你應該會看到連至 11434 的 loopback 連線，而不會看到連至公開位址的連線。其他任何連線都值得先確認，再繼續操作。Coding agent 會將哪些資料傳回外部會對其他 harness 執行相同檢查，並說明如何解讀結果。

不得存放秘密資訊的位置

• Shell 歷史記錄。export DEEPSEEK_API_KEY=sk-... 會以明文寫入 ~/.bash_history，即使輪替金鑰後仍會長時間留在其中。設定 HISTCONTROL=ignorespace 時，請在命令前加上空格；或略過 Shell，直接以 mode 600 將值寫入檔案。
• 已提交的 dotfile。若使用 git 管理 dotfile，~/.bashrc 或 ~/.zshrc 中的金鑰距離進入公開 repository 只有 git add。推送前，請在該 repository 中執行 git grep -I -n 'sk-'。
• settings.yaml。自訂 provider 請使用 apiKeyEnv，讓檔案儲存變數名稱，而不是秘密資訊。設定檔常會被貼到 issue 報告與支援對話中，但 credentials 檔案不會。
• env 的輸出與終端機螢幕截圖。任何會列出完整環境的命令，也會一併列出金鑰。
• 備份。~/.dsh 值得備份，但其中的 .credentials.yaml 是有效的秘密資訊。請排除該檔案，或加密封存檔。

這些規則不僅適用於 dsh；避免將秘密資訊放在 Compose env 檔案中也涵蓋同一台伺服器容器端的相同問題。

與開發者預覽版共存

請固定已測試的版本，因為預覽版可能在修補版本中變更設定金鑰，導致提供者無法載入。如果固定版本的安裝仍拒絕啟動，或 npx 持續提供你未要求的組建，預覽版產生的安裝與版本錯誤會說明 npx 快取，以及 Node 隨附的 npm。請將 settings.yaml 與 cordis.patch.yml 納入版本控制，但排除認證檔案，這樣升級後即可查看變更內容。

設定檔未依預期運作時，兩個旗標很有幫助。--dump-default-config 會在不啟動服務的情況下輸出組合後的預設設定，--dump-config 則以相同方式輸出個人設定檔的組合後設定。比較兩者即可看出修補層實際變更的內容，比手動逐層閱讀更快。

dsh --profile web --dump-config

升級後發生問題時，先執行這個指令。版本之間移動的金鑰會在輸出內容中顯示為缺少的分支；修正只需編輯一行，不必重新安裝。

FAQ

dsh 將我的 DeepSeek API key 儲存在哪裡？

在 $DSH_HOME/.credentials.yaml 中；除非自行設定 DSH_HOME，否則該路徑就是 ~/.dsh/.credentials.yaml。Models 頁面會將 key 寫入該檔案，而設定中只保留該 key 的參照，因此 secret 只會存放在一個檔案中。使用 stat -c '%a %n' ~/.dsh/.credentials.yaml 檢查檔案模式；若權限比 600 寬鬆，請將其設定為 600。自訂 provider 可透過 apiKeyEnv 指定環境變數，完全不使用該檔案。

如何讓 dsh 使用本機模型，而不是 DeepSeek API？

新增自訂 provider，並將 base URL 設為本機的 OpenAI-compatible endpoint。以 Ollama 為例，該 URL 是 http://127.0.0.1:11434/v1；api: openai-completions 和模型 id 必須從 ollama list 完整複製。Ollama 要求 API key 值，但會忽略該值，因此任何非空字串都可使用。在修改任何 dsh 設定前，先使用 curl -s http://127.0.0.1:11434/v1/models 確認 endpoint 有回應，因為 endpoint 無法連線與設定錯誤會產生相似的錯誤。

dsh 預設會將我的程式碼傳送到其他地方嗎？

使用 hosted model 時，會。你的 prompt 以及 agent 讀取之檔案的內容，都會包含在傳送至該 vendor 的 API request 中。使用本機 endpoint 時，request 會傳送至 loopback，並留在該機器上。Telemetry 是獨立的資料流，預設為關閉：未設定時，DSH_TELEMETRY_MODE 會解析為 DISABLED，此狀態下不會建立 exporter。設定 DSH_TELEMETRY_DISABLED=1，即可在執行開始前停用 telemetry。

為什麼已設定變數，dsh 仍回報 MISSING_CREDENTIAL？

因為 dsh 會從自身的 process environment 讀取 apiKeyEnv 所指定名稱的變數。在 shell 中 export 的變數不會傳給 systemd service、其他使用者的 session，或在 export 前已啟動的 process。請將值放入 EnvironmentFile，並為該 unit 設定 600 權限；或者在啟動 dsh 的同一個 shell 中 export 該變數。使用 sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ 確認執行中的 process 實際持有的內容。

dsh 需要哪個 Node.js 版本？

22 系列需要 Node.js 22.19 或更新版本，或使用 24 以上版本。Node 23 不在支援範圍內。先執行 node -v，因為不受支援的 runtime 會造成啟動失敗，看起來像安裝損壞，導致使用者重新安裝 package，而不是更新 runtime。