Pi

在 ~/.pi/agent/models.json 中設定自訂供應商區塊 — baseUrl、api 與模型 ID — 讓 Earendil 的 Pi 終端程式設計代理透過一組金鑰使用 Claude 與 GPT。

{
  "providers": {
    "kunavo": {
      "baseUrl": "https://api.kunavo.com/v1",
      "api": "openai-completions",
      "apiKey": "$KUNAVO_API_KEY",
      "models": [
        {
          "id": "claude-sonnet-5",
          "name": "Claude Sonnet 5",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1000000,
          "maxTokens": 128000
        },
        {
          "id": "claude-haiku-4-5",
          "name": "Claude Haiku 4.5",
          "input": ["text", "image"],
          "contextWindow": 200000,
          "maxTokens": 64000
        }
      ]
    }
  }
}

逐步操作

1. 在 /app/keys 建立金鑰並複製——金鑰只會顯示一次。
2. 將金鑰設為環境變數 KUNAVO_API_KEY。Pi 會在 apiKey 欄位中解析 "$NAME" 或 "${NAME}"，也接受直接輸入值或以 !command 開頭的寫法。若變數名稱後面還有一般文字，請使用大括號格式。
3. 建立或編輯 ~/.pi/agent/models.json，並貼上上方區塊。非內建供應商必須提供 baseUrl，且供應商或模型層級至少有一個 api 值——Pi 原始碼會在缺少這些值時拒絕載入模型——其他設定則皆為選填。開啟 /model 即可重新載入檔案。
4. 啟動 pi、執行 /model，並選擇你宣告的其中一個 ID。如果清單中沒有它們，請檢查 JSON 前面的金鑰——請參閱上方的解析順序說明。
5. 給它一項會讀取並編輯實際檔案的任務。Pi 幾乎所有操作都仰賴工具呼叫，因此第一次執行若能存取檔案系統，會比打招呼讓你了解更多——而且這正是能揭露串流或工具結構描述不相符的測試；Kunavo 尚未替你測試這類問題。

已於 2026年10月1日 根據 Pi 的「選擇模型」文件 進行確認。第三方設定會變動；如果這裡的欄位名稱不再與你看到的內容相符，應以該頁面為準，而不是本頁。

除錯用戶端前先驗證

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

# 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

在 2026 年 9 月 22 日文件更新之前，Pi 為自訂提供者的 api 記載了四種值——openai-completions、openai-responses、anthropic-messages 和 google-generative-ai。更新後的模型頁面沒有列出任何值：範例中顯示 openai-completions，並將情況描述為「OpenAI、Anthropic 或 Google 相容的端點」。Pi v0.99.2 的原始碼將此欄位型別定義為自由字串，並將其派送至十種內建實作中相符的一種——上述四種加上 openai-codex-responses、azure-openai-responses、google-vertex、mistral-conversations、bedrock-converse-stream 和 pi-messages。自訂提供者過去只有上述四種值有文件記載；其餘六種都未在此測試。本頁並未表示其中任何一種可搭配第三方端點使用。

anthropic-messages 是文件記載的四種值之一，而 Kunavo 除了支援 OpenAI 相容介面，也支援 Anthropic Messages 介面。因此，這條路由在設定上是可行的。本頁不會提供可直接貼上的設定區塊，並在其中替它填入 base URL：Pi 的文件從未明確說明這個 api 欄位應填什麼。直到 9 月 22 日之前，文件以兩種方式呈現這個欄位——一個範例使用 https://proxy.example.com/v1，另一個使用不帶其他內容的 https://proxy.example.com；當天的文件更新刪除了兩種寫法，卻沒有擇一。如果你選用這條路由，請先試一種寫法；若第一次呼叫回傳的是 404 而非 401，就要修改那一行。

在 Pi 的此 api compat 結構描述中，有三個欄位值得你事先了解（原始碼版本 v0.99.2）；文件中對這些欄位的唯一規則，也值得先引用：「相容性設定應描述端點請求或回應行為經驗證的差異。不要只因端點宣稱相容於 OpenAI 或 Anthropic，就啟用這些設定。」

1. compat.supportsEagerToolInputStreaming — 適用於會拒絕逐工具預先輸入串流的後端。
2. compat.supportsStrictTools — endpoint 是否接受嚴格的 JSON-schema 工具定義；自訂模型不會沿用內建 Anthropic 模型宣告的設定。
3. compat.supportsMidConvoEffort — 在對話進行中變更推理強度。此 endpoint 是否符合條件，要在執行時確認；Kunavo 尚未透過實際執行來判定。

本頁頂端的 openai-completions 區塊避開了這三個設定；這就是建議從那裡開始的實際原因，而非宣稱它的效能較佳。