pi 編碼代理 API 設定

pi的官方Custom Models機制從~/.pi/agent/models.json載入網關和自訂模型。 TokenHub 使用 openai-completions API 類型。這裡沒有通用的「新增提供者」表單；此設定檔是受支援的入口點。

第 1 步：為 models.json 準備憑證

在啟動 pi 的同一終端機中，設定：

export TOKENHUB_API_KEY="sk-..."

在models.json中，讀取環境變數的值必須是"$TOKENHUB_API_KEY"。 pi 的文檔指出，沒有 在models.json中，讀取環境變數的值必須是"$TOKENHUB_API_KEY"`。 pi 的文檔指出，沒有 的大寫字串被視為文字鍵，而不是環境變數名稱。

步驟2：編輯~/.pi/agent/models.json

{
  "providers": {
    "tokenhub": {
      "baseUrl": "__API_BASE_URL__/v1",
      "api": "openai-completions",
      "apiKey": "$TOKENHUB_API_KEY",
      "models": [
        {
          "id": "YOUR_TOKENHUB_MODEL_ID",
          "name": "TokenHub / YOUR_TOKENHUB_MODEL_ID",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 8192
        }
      ]
    }
  }
}

更正 TokenHub 模型頁面中的每個欄位：

• id 是發送到 API 的型號 ID，並且是必需的。
• 僅對於支援擴展推理的模型，將 reasoning 設定為 true。
• input 預設為文字。僅對具有影像輸入的型號使用 ["text", "image"]。
• 雖然contextWindow有預設值，但聲明模型的真實上下文視窗。
• maxTokens 是最大輸出，而不是上下文視窗。

TokenHub 使用不記名令牌。如果您的 pi 版本未自動新增授權標頭，請在提供者層級新增 "authHeader": true。

步驟3：開啟/model重新載入文件

在 pi 會話中執行 /model。每次/model開啟時，pi都會重新載入models.json，因此不需要重新啟動。選擇tokenhub/YOUR_TOKENHUB_MODEL_ID，要求其解釋一個文件，成功後才測試工具呼叫。

如果提供者和模型已顯示但不可選擇，則檔案已載入但憑證未解析。檢查環境變量，或使用 /login / auth.json 儲存提供者金鑰。

僅在需要時應用特定於 pi 的兼容性覆蓋

某些 OpenAI-compatible 服務拒絕 developer 角色或 reasoning_effort。僅在相應的 400 錯誤發生後添加這些標誌：

"compat": {
  "supportsDeveloperRole": false,
  "supportsReasoningEffort": false
}

不要搶先禁用功能。基本請求成功後，僅針對確切型號配置 thinkingLevelMap、影像輸入、取樣參數或定價。

根據pi的負載行為進行故障排除

• /model 中完全不存在提供者：檢查檔案路徑、JSON 語法、baseUrl 和 api。
• 提供者存在，但無法選擇模型：$TOKENHUB_API_KEY 未解析，或提供者缺少已儲存的憑證。
• 401：确认pi进程继承了该变量，并根据需要设置authHeader: true。
• 400或提前截斷：正確的contextWindow、maxTokens或compat；不要簡單地增加數字。
• 變更未出現：重新開啟 /model，而不是依賴目前會話中顯示的舊選擇。

官方參考資料

• pi：定制型号
• pi：自定义提供商扩展 API