Pi coding agent 的模型設定分三層：內建的 provider 用 /login 登入（訂閱或 API 金鑰）或設環境變數；Pi 沒內建、但相容於 OpenAI／Anthropic／Google API 的端點，寫進 ~/.pi/agent/models.json；需要特殊認證或協定的服務才要寫擴充功能。選好之後用 /model 切換。這篇依照 Pi 在 2026 年 9 月 22 日改版後的文件，以及 2026 年 9 月 30 日發佈的 v0.99.2 原始碼，說明每一層怎麼設、金鑰的讀取順序（改版後變了）、自訂模型三個會默默出錯的預設值，以及接 OpenAI 相容端點的完整範例。
先確認是哪個 Pi。本頁講的是 Earendil 公司在 pi.dev 發佈的終端機程式碼代理，程式庫是 earendil-works/pi（原 badlogic/pi-mono），MIT 授權。它不是 Inflection 的聊天機器人 Pi(pi.ai)、不是 Pi Network 幣、不是 Raspberry Pi，也不是另一位作者的 Oh My Pi。
先選連線方式
Pi 的模型文件開頭就是這張對照：
| 你手上有的 | 建議做法 |
|---|---|
| 支援的訂閱方案 | 用 /login 登入 |
| 某個 provider 的 API 金鑰 | 用 /login 存起來，或設該 provider 的環境變數 |
| 本機的 GGUF 模型 | 接 llama.cpp router（用 /llama 管理） |
| OpenAI、Anthropic 或 Google 相容的端點 | 寫進 models.json |
| 自訂協定或認證流程的 provider | 寫或安裝 provider extension |
Pi 內建一份模型目錄，並可從 pi.dev 疊加較新的目錄資料；離線時沿用快取，要強制更新可以跑 pi update --models。只有在 Pi 沒有你要的 provider 或端點時，才需要自訂模型設定。
在 Pi 裡選模型
/model：搜尋並選擇模型。只會列出 provider 已經有可用認證的模型。- 在模型上按 Ctrl+S：存成新工作階段的預設模型。
/thinking：選目前模型的思考等級，Pi 只會列出該模型支援的等級；同樣按 Ctrl+S 存成啟動預設。- Ctrl+P：在可用模型之間輪換；
/scoped-models控制輪換清單並存檔。
工作階段會記錄換模型和思考等級的變化，恢復工作階段時會照著還原，但不會改動新工作階段的預設。
金鑰的讀取順序（改版後變了）
同時設定了好幾個金鑰來源時，Pi 文件寫的順序是：執行時的 --api-key → auth.json 裡存的憑證 → models.json 的 apiKey → provider 的環境變數（或雲端平台的環境憑證）。所以用 /login 存過的舊金鑰會蓋過你剛寫進檔案的那一把，這是「改了設定卻還是用舊帳號」最常見的原因；/logout 可以移除存起來的憑證。注意 9 月 22 日改版前，文件寫的是環境變數排在 models.json 前面，網路上的舊教學可能還是舊順序。
另一個常見誤會：模型不出現在 /model 裡，多半是認證問題而不是 JSON 寫錯。文件說自訂模型可以從 models.json 載入，但在 Pi 解析得到憑證之前，會一直「不可用」。
models.json：接 OpenAI 相容端點的完整範例
Pi 自己的範例是本機 Ollama —— dummy 金鑰只是讓模型變成可用，Ollama 本身不看它：
{
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434/v1",
"api": "openai-completions",
"apiKey": "ollama",
"models": [{ "id": "qwen2.5-coder:7b" }]
}
}
}接需要認證的端點，例如 Kunavo，就像這樣：
{
"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
}
]
}
}
}baseUrl和api必填。可以寫在 provider 層或模型層；依 v0.99.2 原始碼，兩者缺一，Pi 就不載入該模型。api不是四選一。9 月 22 日改版前，Pi 的文件為自訂 provider 列出四個值：openai-completions、openai-responses、anthropic-messages、google-generative-ai。改版後的文件不再列清單，只在上面那張對照表寫「OpenAI、Anthropic 或 Google 相容的端點」，範例也只用到openai-completions。v0.99.2 原始碼把api定義成任意字串，交給十種內建實作中對應的那一種處理 —— 上述四個，加上openai-codex-responses、azure-openai-responses、google-vertex、mistral-conversations、bedrock-converse-stream、pi-messages。只有前四個曾被文件寫成自訂 provider 的用法；另外六個這裡沒有測試過，本頁也不主張它們能接第三方端點。openai-completions的baseUrl要帶/v1。文件沒有用一句話規定，但相容端點範例全都帶版本路徑。少了/v1會得到 404，而不是認證錯誤。- 金鑰不要寫死。
apiKey和 header 值可以寫$NAME或${NAME}引用環境變數、直接寫值，或用!指令取得；文件說models.json裡的指令會在每次請求時執行、不會快取。auth.json和任何取金鑰的指令都請保密。 - 改完不用重開。打開
/model時會重新讀檔。models裡同 ID 的項目會新增或取代該 provider 的模型；想改內建模型的中繼資料而不取代整份清單，用modelOverrides。
三個會默默出錯的預設值
9 月 22 日的文件改版把欄位表拿掉了，但預設值還在原始碼裡（v0.99.2 的 provider-composer.ts）。自訂模型只要沒填，就會套用：
| 欄位 | 沒填時的預設 | 會造成什麼 |
|---|---|---|
cost | input、output、cacheRead、cacheWrite 全部 0 | 底部和 /session 的花費一直顯示 $0，不代表免費，只是沒有價格來源 |
contextWindow | 128000 | 上下文更大的模型會太早被壓縮 |
maxTokens | 16384 | 長回覆被截短 |
另外 reasoning 預設 false、input 預設只有文字。上面的 Kunavo 範例已依價目表填好上下文和輸出上限，沒有放 cost，因為價格寫死在檔案裡很快就會過期 —— 想讓底部顯示花費，就自己照 價目表填入每百萬 token 的價格。Pi 還支援 promptCache（以秒為單位宣告供應商快取的存活時間，用於快取暖機），文件建議取公開範圍中保守的那一端。
anthropic-messages：可以接，但 baseUrl 沒有定論
anthropic-messages 是改版前文件為自訂 provider 列出的四個值之一，Kunavo 也提供 Anthropic Messages 介面，所以 api: "anthropic-messages" 這條路是存在的。但 Pi 的文件從來沒有說清楚這種類型的 baseUrl 該不該帶 /v1：改版前一個範例寫 https://proxy.example.com/v1、另一個寫不帶路徑的 https://proxy.example.com，改版後兩個範例都刪了，還是沒有定論。走這條路的話先試一種，第一次請求回 404（而不是 401）就改這一行。compat 裡也有幾個專為非原廠端點設計的開關（例如 supportsEagerToolInputStreaming、supportsStrictTools），但文件提醒：相容設定應該描述「已驗證的行為差異」，不要只因為端點宣稱相容 OpenAI 或 Anthropic 就打開。上面的 openai-completions 範例避開了這些問題，這才是建議從它開始的真正原因，不是因為它比較快。
老實說明與付款
以上是讀 Pi 的文件和原始碼整理出來的設定參考，Kunavo 沒有實際用 Pi 跑過自家端點 —— 沒有跑過工作階段、串流、工具往返，也沒確認請求最後落在哪個模型。請保留你現在能用的路線，給 Pi 一個會讀寫真實檔案的任務試試；Pi 幾乎每一步都靠工具呼叫，這樣的第一次執行最能暴露串流或工具格式不合的問題。英文的完整設定頁在 Pi integration guide，各種付費路線（包括 Earendil 自己的 Radius 閘道）比較見 Pi coding agent pricing。
Kunavo 是預付儲值、按 token 扣款，沒有月費。最低儲值 $10，結帳走 Stripe，台灣可用信用卡（Visa、Mastercard、American Express、JCB、銀聯）、Apple Pay 和 Link；街口、LINE Pay 不在可用清單上。詳見計費說明，準備好之後可以建立帳號並產生金鑰。
FAQ
Pi coding agent 要怎麼換模型？
在 Pi 裡輸入 /model 搜尋可用的模型並選擇；在某個模型上按 Ctrl+S 可以存成新工作階段的預設，/thinking 選思考等級（同樣用 Ctrl+S 存成啟動預設），Ctrl+P 在可用模型之間輪換，/scoped-models 控制輪換的範圍。選單只會列出已經有可用認證的 provider 的模型；工作階段會記錄換模型的紀錄，恢復工作階段時會一併恢復，但不會改動新工作階段的預設。
Pi 要怎麼接自訂的 API 端點？
內建 provider 用 /login 或環境變數就好；Pi 沒有內建、但講的是它支援的 API（OpenAI、Anthropic 或 Google 相容）的端點，就在 ~/.pi/agent/models.json 加一個 provider 區塊：baseUrl、api、apiKey，以及 models 清單。baseUrl 和 api 缺一個，Pi 的原始碼就不會載入那個模型。api 不是固定的幾選一：2026 年 9 月 22 日文件改版前，Pi 為自訂 provider 文件化的值有四個（openai-completions、openai-responses、anthropic-messages、google-generative-ai），改版後的文件不再列清單；v0.99.2 原始碼把 api 定義成任意字串，交給十種內建實作中對應的那一種處理，另外六種從未被文件寫成自訂 provider 的用法，這裡也沒有測試過。接 OpenAI 相容端點，填改版後文件範例仍在用的 openai-completions。需要自訂串流、模型探索或特殊認證流程的服務，才要寫 provider extension。
Pi 的 API 金鑰從哪裡讀？順序是什麼？
Pi 的模型文件（2026 年 10 月 1 日）寫的順序是：執行時的 --api-key 最優先，其次是 auth.json 裡存的憑證（/login 存的就是這個），再來是 models.json 的 apiKey，最後才是 provider 的環境變數。所以之前用 /login 存過的舊金鑰，會蓋過你剛寫進 models.json 的那一把。apiKey 欄位可以寫 $NAME 或 ${NAME} 引用環境變數、直接寫值，或用 ! 開頭執行指令取得。注意：這個順序在 2026 年 9 月 22 日文件改版前是不同的（環境變數排在 models.json 前面），舊教學可能還寫著舊順序。
為什麼我自己加的模型在 Pi 底部顯示 $0？
因為自訂模型的 cost 預設全部是 0（依 v0.99.2 原始碼），底部和 /session 顯示的是設定檔裡的價格，不是端點實際收的錢。東西不是免費的，只是沒有價格來源；請照供應商的價目表填入每百萬 token 的 input、output、cacheRead、cacheWrite。順便把 contextWindow 和 maxTokens 也填上：沒填時分別預設 128000 和 16384，大上下文的模型會太早被壓縮、回覆被截短。
Pi 的 baseUrl 要不要加 /v1？
openai-completions 類型要加。Pi 的文件沒有用一句話寫明規則，但它的相容端點範例是 Ollama 的 http://localhost:11434/v1，改版前的 OpenRouter、Vercel AI Gateway、llama.cpp 範例也都帶著版本路徑。所以 OpenAI 相容端點填 /v1 根，例如 https://api.kunavo.com/v1。anthropic-messages 類型則沒有定論：改版前的文件一處寫 /v1、一處不寫，改版後兩個範例都拿掉了，仍沒有說明哪個對。
2026 年 10 月 1 日查證：pi.dev/docs/latest/models(Choose a Model)與 providers 頁、earendil-works/pi 標籤 v0.99.2 的 src/core/model-config.ts 與 provider-composer.ts，以及 GitHub API 的版本資訊。同日為 api 欄位另外查證：models 頁現在列出哪些值（只有 Ollama 範例裡的 openai-completions）、v0.99.2 的 model-config.ts 裡 api 的型別（任意字串，第 191、233 行）、provider-composer.ts 對自訂模型的分派（第 579 行），以及 packages/ai/src/compat.ts 的 BUILTIN_APIS（第 180 行，共十種）。Kunavo 沒有用 Pi 實際跑過自家端點。