設定

Pi 使用 JSON 設定檔，其中專案設定覆蓋全域設定。

可以直接編輯檔案，也可以使用 /settings 修改常用選項。

在互動式啟動時，pi 在信任包含專案本機設定、資源或專案 .agents/skills 的專案資料夾之前會詢問，並且在 ~/.pi/agent/trust.json 中沒有儲存該資料夾或父資料夾的決定。信任專案允許 pi 載入 .pi/settings.json 和 .pi 資源、安裝缺少的專案套件以及執行專案擴充。

非互動模式（-p、--mode json 和 --mode rpc）不會顯示信任提示。如果沒有適用的已儲存信任決策，它們會使用全域設定中的 defaultProjectTrust：ask（預設）和 never 會忽略這些專案資源，always 會信任它們。透過 --approve/-a 或 --no-approve/-na 可以覆寫單次執行的專案信任。

如果沒有適用的擴充或已儲存決策，則由 defaultProjectTrust 控制後備行為。可在 ~/.pi/agent/settings.json 中將其設定為 "ask"、"always" 或 "never"，也可以透過 /settings 修改。

pi config 和 package 指令使用相同的專案信任流程，但 pi update 從不提示。傳遞 --approve 以信任某個指令的專案本機設定，或傳遞 --no-approve 以忽略它們。

在互動模式下使用 /trust 可以為後續工作階段儲存專案信任決策，包括對直接父資料夾的信任。該指令只寫入 ~/.pi/agent/trust.json；目前工作階段不會重新載入，因此需要重新啟動 pi 才會生效。

{
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "high": 32768
  }
}

對於 VS Code，請包含 --wait，以便 pi 在編輯器退出後恢復：

{
  "externalEditor": "code --wait"
}

enableInstallTelemetry 僅控制傳送到 https://pi.dev/api/report-install 的匿名安裝/更新 ping。選擇退出遙測不會停用更新檢查；Pi 仍然可以存取 https://pi.dev/api/latest-version 尋找最新版本。

設定 PI_SKIP_VERSION_CHECK=1 可停用 Pi 版本更新檢查。使用 --offline 或 PI_OFFLINE=1 可停用此處描述的所有啟動網路操作，包括更新檢查、package 更新檢查和安裝/更新遙測。

{
  "httpProxy": "http://127.0.0.1:7890"
}

{
  "warnings": {
    "anthropicExtraUsage": false
  }
}

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

當 Provider 請求重試延遲超過 retry.provider.maxRetryDelayMs 時，請求會立即失敗並給出說明性錯誤，而不是靜默等待。將其設定為 0 可停用限制。

除非明確需要 Provider 級重試，否則保持 retry.provider.maxRetries 為 0。將其設定為大於 0 後，SDK/Provider 重試可能會在 Pi 看到超出使用限制的錯誤之前自行處理這些錯誤，在某些情況下可能會阻塞 Agent，直到 Provider 配額重置。

{
  "retry": {
    "enabled": true,
    "maxRetries": 3,
    "baseDelayMs": 2000,
    "provider": {
      "timeoutMs": 3600000,
      "maxRetries": 0,
      "maxRetryDelayMs": 60000
    }
  }
}

{
  "npmCommand": ["mise", "exec", "node@20", "--", "npm"]
}

npmCommand 用於所有 npm package 管理操作，包括安裝、解除安裝以及 git package 內的相依套件安裝。使用者範圍的 npm package 安裝在 ~/.pi/agent/npm/ 下；專案範圍的 npm package 安裝在 .pi/npm/ 下。按實際需要啟動的程序填寫 argv 樣式條目。設定 npmCommand 後，git package 相依套件安裝會使用普通 install，以避免包裝器或備用 package manager 中不相容的 npm 專用標誌。

{ "sessionDir": ".pi/sessions" }

當多個源指定工作階段目錄時，settings.json 中的優先級為 --session-dir、PI_CODING_AGENT_SESSION_DIR，然後是 sessionDir。

{
  "enabledModels": ["claude-*", "gpt-4o", "gemini-2*"]
}

這些設定定義從何處載入擴充、技能、提示和主題。

~/.pi/agent/settings.json 中的路徑相對於 ~/.pi/agent 進行解析。 .pi/settings.json 中的路徑相對於 .pi 進行解析。支援絕對路徑和 ~。

陣列支援 glob 模式和排除。使用 !pattern 排除。使用 +path 強制包含精確路徑，使用 -path 強制排除精確路徑。

字串形式載入包中的所有資源：

{
  "packages": ["pi-skills", "@org/my-extension"]
}

物件形式過濾要載入的資源：

{
  "packages": [
    {
      "source": "pi-skills",
      "skills": ["brave-search", "transcribe"],
      "extensions": []
    }
  ]
}

有關包管理的詳細資訊，請參閱packages.md。

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "defaultThinkingLevel": "medium",
  "theme": "dark",
  "compaction": {
    "enabled": true,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  },
  "retry": {
    "enabled": true,
    "maxRetries": 3
  },
  "enabledModels": ["claude-*", "gpt-4o"],
  "warnings": {
    "anthropicExtraUsage": true
  },
  "packages": ["pi-skills"]
}

專案設定 (.pi/settings.json) 覆蓋全域設定。巢狀物件被合併：

// ~/.pi/agent/settings.json (global)
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 16384 }
}

// .pi/settings.json (project)
{
  "compaction": { "reserveTokens": 8192 }
}

// Result
{
  "theme": "dark",
  "compaction": { "enabled": true, "reserveTokens": 8192 }
}