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

dsh 儲存設定的位置

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

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

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

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

首次輸出所需的最低設定

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

node -v
npx @deepseek-ai/dsh web

npx 會從 npm registry 下載套件，並在 http://127.0.0.1:3080 啟動 Web UI。它會繫結 loopback 位址，因此即使防火牆允許該連接埠，其他機器仍無法連線。在 VPS 上，請改用 SSH 轉送，不要將 3080 開放到網際網路。如果列出的 URL 令人困惑，dsh 為何會在該位址啟動說明 loopback 繫結能保護什麼，以及無法保護什麼。

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涵蓋 SSH tunnel 和 reverse proxy 的情境，在 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，並複製其中寫入的結構。在 developer preview 階段，最可能變動的是巢狀結構；應用程式剛寫入的檔案始終是目前版本。

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

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

將該檔案的權限設為 mode 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 (transport layer security) 與驗證機制後方：保護公開的 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) servers；在 VPS 上執行 MCP servers 會詳細說明這一點。plugin 也屬於同一類，因為安裝 plugin 會以 agent 的權限執行其他作者的程式碼。因此，安裝前值得先檢查 plugin 可以連線到哪些位置。另一類是 telemetry，但前提是你已將它開啟。

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

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

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

sudo ss -tnp | grep -i node

在 local-model mode 中，你應該看到連往 11434 的 loopback 連線，且不應看到連往公開位址的連線。其他任何連線都值得先確認，再繼續操作。Coding agent 會傳送哪些內容 會針對其他 harnesses 執行相同檢查，並說明如何解讀結果。

不要放置密密的地方

• Shell 歷程記錄。export DEEPSEEK_API_KEY=sk-... 會以明文寫入 ~/.bash_history，而且金鑰輪替後很久仍會留在其中。設定 HISTCONTROL=ignorespace 時，請在命令前加上空格；或略過 shell，直接將值寫入權限模式為 600 的檔案。
• 已提交的點檔案。如果將點檔案存放在 git 中，~/.bashrc 或 ~/.zshrc 中的金鑰只要 git add 就可能進入公開儲存庫。推送前，請在該儲存庫中執行 git grep -I -n 'sk-'。
• settings.yaml。自訂 provider 請使用 apiKeyEnv，讓檔案只保存變數名稱，而不是 secret。設定檔常會被貼到 issue 報告和支援對話中，但 credentials 檔案不會。
• env 的輸出和終端機畫面截圖。任何會列出完整環境的命令，也會一併列出金鑰。
• 備份。~/.dsh 值得備份，但其中的 .credentials.yaml 是有效的 secret。請排除該檔案，或加密封存檔。

這些規則不只適用於 dsh；避免將 secret 放入 Compose env 檔案也涵蓋同一台伺服器在容器端的相同問題。

管理 developer preview

請固定已測試的版本，因為 preview 可能在修補程式版本中變更設定鍵，導致 provider 無法載入。若固定版本的安裝仍拒絕啟動，或 npx 持續提供你未要求的 build，preview 產生的安裝與版本錯誤涵蓋 npx 快取，以及 Node 隨附的 npm。將 settings.yaml 與 cordis.patch.yml 納入版本控制，但排除 credentials 檔案，以便在升級後查看變更內容。

當 profile 的行為不如預期時，兩個旗標可協助診斷。--dump-default-config 會在不啟動服務的情況下輸出組合後的預設設定，而 --dump-config 會以相同方式輸出 profile 的組合設定。比較兩者即可看出 patch layer 實際變更的內容，比手動逐層閱讀更快。

dsh --profile web --dump-config

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

FAQ

dsh 將 DeepSeek API 金鑰儲存在哪裡？

在 $DSH_HOME/.credentials.yaml 中；如果未自行設定 DSH_HOME，其值就是 ~/.dsh/.credentials.yaml。Models 頁面會將金鑰寫入該檔案，而設定中只保留指向它的參照，因此 secret 只會存在於一個檔案中。使用 stat -c '%a %n' ~/.dsh/.credentials.yaml 檢查檔案模式；如果權限比 600 寬鬆，請將其設為 600。自訂 provider 可透過 apiKeyEnv 指定環境變數，完全避免使用該檔案。

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

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

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

使用代管模型時，會。提示內容以及 agent 讀取的檔案內容，都會包含在傳送給該供應商的 API 請求中。使用本機端點時，請求會傳送至 loopback，並留在本機。Telemetry 是獨立的資料流，預設為關閉：未設定時，DSH_TELEMETRY_MODE 會解析為 DISABLED，在此狀態下不會建立 exporter。設定 DSH_TELEMETRY_DISABLED=1 可選擇退出，且該設定會在執行開始前讀取。

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

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

dsh 需要哪個 Node.js 版本？

Node.js 22.19 或 22 系列的更新版本，或 Node.js 24 以上。Node 23 不在支援範圍內。先執行 node -v，因為不受支援的 runtime 所造成的啟動失敗，看起來會像安裝損壞，容易讓人重新安裝套件，而不是更新 runtime。