Jan Agent

執行一行 `jan config set --base-url https://api.kunavo.com/v1`，即可將 Kunavo 寫入 ~/.jan/config.toml；Jan Agent 預覽 CLI 本身不含推理引擎，會使用該金鑰執行。

# Jan Agent is a preview on a nightly channel — check your build first.
jan --version

jan config set \
  --provider kunavo \
  --api-key sk-kn-... \
  --base-url https://api.kunavo.com/v1 \
  --model claude-sonnet-5 \
  --model claude-haiku-4-5 \
  --api-type openai

jan config list   # configured providers as JSON, keys redacted

逐步操作

1. 在 /app/keys 建立金鑰並複製——金鑰只會顯示一次。
2. 確認你正在設定的是什麼：jan --version。Jan Desktop 也附有透過 jan 呼叫的 CLI，但指令集不同；因此請先確認 jan config set --help 列出 --base-url，再輸入其餘內容。
3. 執行上方的 jan config set 指令。--provider 是你自行選定的 ID，而非固定清單中的名稱 — 文件中的本機硬體範例使用 --provider local — 而且 --model 可以重複使用；每次都會取代現有清單，而不是新增項目。
4. 使用 jan config list（金鑰已遮蔽）或 jan config path 查看檔案本身，確認設定已寫入，再執行 jan cli models list 查看每個 provider 提供的內容。手動輸入的模型 ID 即使端點不再列出它，也會繼續保留；jan cli models refresh --provider kunavo 則會以端點清單為準。
5. 切換至專案目錄並執行 jan，然後用 /model 選取模型。第一次執行建議使用 jan --plan：此模式為唯讀，能在任何內容寫入磁碟前顯示協定不相容的問題。
6. 交給它一項會編輯檔案的任務。Jan Agent 是代理程式，因此第一次執行應測試工具呼叫和串流 — 若端點僅部分相容，這些功能會最先出問題；而打招呼兩者都測不到。

已於 2026年9月21日 根據 Jan Agent 的 Providers 頁面 進行確認。第三方設定會變動；如果這裡的欄位名稱不再與你看到的內容相符，應以該頁面為準，而不是本頁。

除錯用戶端前先驗證

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

# 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 權杖的美元價格，輸入／輸出。

有兩種不同的東西都叫作 Jan API 金鑰

兩者放在同一個檔案中，意義卻完全相反，因此 jan config list 可能會讓原本預期另一種金鑰的人覺得有問題。

Jan Desktop 兩者都不會發出：它沒有帳戶，因此無法在那裡產生金鑰。其本機 API 伺服器會使用你自行建立的金鑰，這又是第三種意義，適用於不同的主機。

Jan Desktop 會傳遞哪些設定，以及傳遞範圍到哪裡

Jan Agent 會從四個來源讀取 provider 設定，優先順序由上而下；第二個來源最容易讓人意外。

1. ~/.jan/config.toml — 基礎設定，也是 jan config set 唯一會寫入的檔案。
2. Jan Desktop 的 settings.json — 僅供繼承。它會新增你尚未在 Agent 中設定的 provider，不會覆寫既有設定，也不會寫回該檔案。
3. 專案 agent.toml 中的 [provider] 區塊 — 明確指定專案層級的選項，因此優先於前兩者。該檔案通常會提交至版本控制，因此請勿將 api_key 放入其中。
4. 命令列上的 --provider / --api-key，或 JAN_API_KEY / <PROVIDER>_API_KEY — 指定性最高，也最短暫。

除錯時，有兩個結果值得先了解，以免查錯方向。jan config list 可能顯示沒有任何 provider，但 jan cli models list 卻回傳多個項目 — 後者包含從 Desktop 繼承的項目，而這些項目並未儲存在 ~/.jan/config.toml。此外，繼承的 provider 永遠不會更新，因為此處沒有可供改寫的項目：若要讓 Kunavo 的模型清單保持最新，必須將它設為獨立的 jan config set 項目；上方的區塊正是如此設定。

當多個 provider 提供相同模型 ID 時

Kunavo 提供 claude-sonnet-5 這類 ID，直接連到模型供應商的 provider 項目也可能提供相同 ID。Jan Agent 必須擇一使用，文件記載的優先順序是：先比對 provider 的 models 清單中的完全相符項目，再比對以 <provider>/<model> 為前綴、名稱指向已設定 provider 的項目；若多個 provider 都提供相同 ID，則優先使用有憑證的 provider，而非沒有金鑰的同名項目。因此，kunavo/claude-sonnet-5 可用來指定你要使用哪一個。這個限定名稱僅供 Jan 使用 — 送出請求前會將它移除，因為上游服務不接受附有 provider 限定名稱的 ID。

從主控台內新增相同項目

如果你不想輸入旗標：/settings > providers 可管理相同的 ~/.jan/config.toml 項目，而 a 會開啟新增表單，欄位為 name、base url、api key 和以空格分隔的 models。此表單有兩項旗標操作不具備的功能：基礎 URL 必須是 https://（localhost 端點則可使用 http://），如此一來，金鑰就不會透過未加密的遠端連線送出 — Kunavo 使用 https://，因此不受此限制 — 而編輯時 API 金鑰欄位會顯示 (unchanged)，除非你輸入新內容，否則會保留已儲存的金鑰。清空此欄位會清除金鑰，而不是保留原值。