Pi

在 models.json 中設定自訂 Provider，將終端程式設計 Agent Pi 接入 CoffeeRouter。

接入前準備

  • 安裝支援目前 Pi 版本的 Node.js。
  • 在 CoffeeRouter 建立獨立 API Key，並確認目標模型 ID。
  • 準備 https://www.coffeerouter.ai/v1 作為 OpenAI Compatible Base URL。

設定步驟

1. 安裝 Pi

目前官方 npm 套件：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
pi --version

也可以使用官方安裝指令碼：

curl -fsSL https://pi.dev/install.sh | sh

2. 設定 API Key

Linux / macOS：

export COFFEEROUTER_API_KEY="sk-your-api-key"

Windows PowerShell：

$env:COFFEEROUTER_API_KEY="sk-your-api-key"

3. 建立模型設定

在 ~/.pi/agent/models.json 中新增 CoffeeRouter：

{
    "providers": {
        "coffeerouter": {
            "baseUrl": "https://www.coffeerouter.ai/v1",
            "api": "openai-completions",
            "apiKey": "$COFFEEROUTER_API_KEY",
            "models": [
                {
                    "id": "your-model-id",
                    "name": "CoffeeRouter Model",
                    "reasoning": false,
                    "input": ["text"],
                    "contextWindow": 128000,
                    "maxTokens": 8192
                }
            ]
        }
    }
}

模型能力欄位必須依 CoffeeRouter 中的實際模型調整。不要為所有模型統一加入推理相容參數。

4. 選擇模型

啟動 Pi，輸入 /model 或按下 Ctrl+L，選擇 coffeerouter 與目標模型。models.json 會在開啟模型選擇器時重新載入。

驗證接入

選擇模型後傳送一個簡單的程式設計任務。如果 Pi 能正常串流輸出並執行基本工具呼叫，即表示設定成功。

推理模型設定

使用目前的 thinkingLevelMap

目前 Pi 已將舊的 compat.reasoningEffortMap 遷移為模型層級的 thinkingLevelMap。只有在確認目標模型接受相應推理等級時才新增，例如：

{
    "id": "your-reasoning-model-id",
    "reasoning": true,
    "thinkingLevelMap": {
        "minimal": "low",
        "low": "low",
        "medium": "medium",
        "high": "high",
        "xhigh": null
    }
}

不要沿用舊範例中的 thinkingFormat: "anthropic"；它不在目前 Pi 文件列出的 OpenAI Compatibility 格式中。

常見問題

Provider 或模型沒有顯示

確認檔案路徑為 ~/.pi/agent/models.json、JSON 格式正確，且已設定 COFFEEROUTER_API_KEY。沒有可用驗證資訊時，模型可能已載入但不會在選擇器中啟用。

回傳 401

重新設定 API Key，並從同一個 shell 啟動 Pi。確認令牌沒有過期、停用或超出限制。

推理模型行為異常

先移除自訂 compat 與 thinkingLevelMap，確認一般呼叫正常，再依具體模型協定逐項新增相容參數。

舊的 Pi 設定還能使用嗎

舊倉庫名稱、舊 npm 套件與 reasoningEffortMap 已過時。新文件應使用 earendil-works/pi、@earendil-works/pi-coding-agent 與模型層級的 thinkingLevelMap。

安全提示

  • 不要把真實 Key 寫入文件、截圖、工作階段記錄或版本庫。
  • Pi 的擴充與技能可以執行程式碼，安裝第三方套件前請審查來源與權限。
  • 建議為 Pi 使用獨立 CoffeeRouter 令牌，並依需求限制模型與額度。
  • Pi 會把提示詞、必要程式碼上下文與工具呼叫資料傳送到 CoffeeRouter。

官方資料