DeepSeek Harness

Settings → Models → “Add model provider” → “Custom model API” 需要五個欄位 — Provider ID、display name、base URL、API protocol 與 API key — 讓 Claude 與 GPT 和內建 DeepSeek 卡片出現在同一個選擇器中。

# Settings → Models → Add model provider → Custom model API
#
#   Provider ID     kunavo          (lowercase, and permanent)
#   display name    Kunavo
#   base URL        https://api.kunavo.com/v1
#   API protocol    OpenAI Chat Completions   (openai-completions)
#   API key         sk-kn-...
#
# Then Model catalog → Fetch available models → Add selected,
# or type the ids by hand. The page writes the active profile's
# $DSH_HOME/profiles/<profile>/cordis.patch.yml — profile "web" under
# `dsh web`. The same provider there, plus an optional second one
# that sends Claude ids over Anthropic Messages, whose base URL has
# NO /v1. This entry replaces the whole llm-pi-ai config: keep any
# provider already in it.

- id: llm-pi-ai
  config:
    providers:
      kunavo:
        apiKeyEnv: KUNAVO_API_KEY
        api: openai-completions
        baseURL: https://api.kunavo.com/v1   # → /v1/chat/completions
        models:
          - id: claude-sonnet-5
          - id: claude-opus-5
          - id: claude-haiku-4-5
          - id: gpt-5-6-sol
      kunavo-claude:
        apiKeyEnv: KUNAVO_API_KEY
        api: anthropic-messages
        baseURL: https://api.kunavo.com      # → /v1/messages
        models:
          - id: claude-sonnet-5
          - id: claude-haiku-4-5

逐步操作

1. 在 /app/keys 建立金鑰並複製——金鑰只會顯示一次。
2. 啟動 Web UI（dsh web）並前往 Settings → Models。選擇 Add model provider。卡片會先顯示 Third-party model provider，其中只列出 dsh 隨附的供應商 — 請切換至 Custom model API。
3. 填寫 Provider ID（使用小寫，且永久固定 — 文件說明請求、已儲存的工作階段、模型預設值和憑證參照都會使用此 ID；若要更名，必須新增供應商並刪除舊供應商）、display name、base URL https://api.kunavo.com/v1、API protocol OpenAI Chat Completions，以及 API key。金鑰僅供寫入；dsh 會將它保存在 $DSH_HOME/.credentials.yaml，並只在設定檔中儲存金鑰參照。
4. 在 Model catalog 下選擇 Fetch available models — Kunavo 會回應 GET /v1/models，因此選擇器會自動填入模型。勾選所需項目，再選擇 Add selected。手動輸入 ID 的效果完全相同；文件建議只要探索結果為空，就改用手動輸入。
5. 選用：若要透過 Anthropic 自有通訊協定使用 Claude ID，請新增第二個自訂模型 API，設定專屬的 Provider ID、基底網址 https://api.kunavo.com（不含 /v1）、API protocol Anthropic Messages，並使用相同金鑰。此處的 Fetch 也會列出完整目錄；只新增 claude- ID（為什麼只新增這些）。
6. 在編輯器中選取模型，然後傳送一個會操作檔案的回合，而不是打招呼 — Harness 的大多數工作都依賴工具呼叫，因此第一次就讀取並編輯某個項目，能提供更多資訊。模型變更會在下一個請求生效；文件明確指出不需要重新啟動。

已於 2026年10月1日 根據 DeepSeek Harness 的「Configure models」頁面（與標籤 dsh-v0.2.0-rc.2 中的 docs/user/guide/providers.md 文字相同） 進行確認。第三方設定會變動；如果這裡的欄位名稱不再與你看到的內容相符，應以該頁面為準，而不是本頁。

除錯用戶端前先驗證

一個請求就能判斷失敗原因是端點、金鑰還是設定檔。如果這裡回傳 JSON，則相同的基礎 URL 與金鑰在 DeepSeek Harness 中也能運作。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

欄位中應填入哪個模型 ID

每個文字模型都能以模型 ID 存取——即時清單位於 GET /v1/models，帶有價格的目錄位於模型頁面。費率是每 1M 權杖的美元價格，輸入／輸出。

透過 Anthropic Messages 使用 Claude

Kunavo 也支援 Anthropic Messages API，而 anthropic-messages 是表單提供的三種通訊協定之一。harness 文件明確指出：「一個供應商使用一種通訊協定，因此同時支援兩種通訊協定的閘道需要設定兩個供應商」— 因此這是與第一個並列的第二個供應商，而非在第一個供應商上設定的選項。

• 基底網址 https://api.kunavo.com，即根網址。 在測試中，根網址會將請求傳送至 /v1/messages?beta=true — Claude Code 也使用這個路徑，且 Kunavo 支援此路徑。網址結尾若加上 /v1，請求就會傳送至 /v1/v1/messages。DeepSeek Harness 與 Claude Code 的比較並列顯示兩個用戶端的請求。
• 僅限 Claude ID。 Kunavo 的 /v1/messages 僅支援 claude- ID；在此使用 gpt- ID 會收到指出 /v1/chat/completions 的 404。GPT 請繼續使用 openai-completions 供應商。
• Fetch 會列出所有模型；只新增 Claude 模型。 dsh 的 llm-pi-ai README 說明，此通訊協定的探索請求會使用 Anthropic 的 x-api-key 標頭傳送 GET /v1/models；Kunavo 的模型清單也會如同 Authorization: Bearer 一樣，從該標頭取得金鑰 — 這些資訊來自 dsh 原始碼和 Kunavo 自行執行的測試，不是來自本次測試。Fetch available models取得的結果是完整目錄，包含 GPT 和圖像模型，因此只勾選 claude- ID；手動輸入也同樣可行。完整清單的證明力沒有看起來那麼高：同一份 README 指出，清單網址無論是否包含 /v1 都會接受，但模型請求會原樣使用基底網址 — 因此，Fetch 也可能從 https://api.kunavo.com/v1 填入清單，而使用該基底網址傳送的第一個回合會前往 /v1/v1/messages。
• 這種設定的作用。 請求會以 Anthropic 的格式送達 — 在測試中，系統提示會作為頂層 system 欄位傳送，因此不會用到 developer 角色 — Kunavo 會原樣轉送，不會從 OpenAI 格式轉換。透過轉換，openai-completions 供應商也能連線至相同的 Claude ID；這就是步驟中使用該供應商的原因。

表單背後的設定檔

Models 頁面會寫入 $DSH_HOME/profiles/<profile>/cordis.patch.yml — 若您以 dsh web 啟動，則會寫入 $DSH_HOME/profiles/web/cordis.patch.yml。較舊的 dsh 文件指向 $DSH_HOME/settings.yaml；0.2.0-rc.2 的文件則沒有。若瀏覽器與伺服器位於同一台機器，Settings 標題中的 Open configuration file 會開啟該檔案；適配器會在下一個請求時重新讀取設定。此端點有五項設定需要注意：

1. Context window 和 max output tokens — 在表單中，位於 Customized settings → Model options 下。手動輸入的 ID 不會帶有這兩項設定，因此路由會使用預設值：根據 llm-pi-ai README，context 為 262,144 個 token，output 為 32,768 個 token — 本次測試中，兩個自訂供應商都恰好要求 max_tokens: 32768。表格中的每個 ID 都支援更高的上限；請確認對應列的資訊，若要提高上限，請從模型的目錄項目調整。Kunavo 會依模型實際產生的 token 計費，不會依上限計費。
2. compat.supportsDeveloperRole — 不需要。Harness 建議在閘道拒絕 developer 角色時啟用此選項；Kunavo 在所有模型系列（包括 Claude）都會將該角色讀作 system turn。（直到 2026-09-30，Claude 路徑會丟棄該角色，這個選項當時建議您啟用；保留啟用狀態沒有影響。）
3. compat.maxTokensField — 保持原設定。Harness 通常會將此項與上方的切換選項搭配，作為第一個修正方式；但 Kunavo 自行處理請求的程式會讀取 max_completion_tokens，並回退至 max_tokens，因此預設值已可正常運作。
4. reasoningEfforts — 表單中沒有此欄位。手動輸入的模型不會宣告任何推理層級，因此不會顯示 Effort 選單；由端點自行決定預設推理行為。若要使用該選單，請自行宣告層級；在 openai-completions 中，每個金鑰都是一個層級，其值則是以 reasoning_effort 傳送的字串。這對 gpt- ID 有效；對 claude- ID 則無效，因為 Kunavo 的聊天介面不會將 reasoning_effort 轉送至 Anthropic（/docs/chat#reasoning）。
5. 輸入類型（檔案中的 input: [text, image]）— 文件明確指出，這項設定「宣告端點支援某項功能，但不會檢查端點」。在不支援圖像的 ID 上勾選 Image，harness 不會偵測到；請求會在後續階段遭到拒絕。勾選前，請先在 /models 確認該 ID。

工作階段傳送的其餘內容 — 每回合 24 個工具定義、每個新工作階段的一次簡短標題請求，以及 DeepSeek 自有路由上的額外欄位 — 請參閱DeepSeek Harness 定價。