設定

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"設定為"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 停用此處所述的所有啟動網路操作，包括更新檢查、套件更新檢查和安裝/更新遙測。

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

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

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

當提供者請求重試延遲超過 retry.provider.maxRetryDelayMs 時，請求會立即失敗並出現資訊性錯誤，而不是靜默等待。將其設為 0 以停用限制。

将 retry.provider.maxRetries 保持在 0 除非明确需要提供者级别的重试。將其設為高於 0 可以使 SDK/provider 重試在 Pi 看到超出使用限制的錯誤之前處理這些錯誤，這可能會阻止代理，直到在某些情況下提供程序配額重置。

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

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

npmCommand 用於所有 npm 套件管理器操作，包括安裝、卸載以及 git 套件內的依賴項安裝。使用者範圍的 npm 軟體包安裝在 ~/.pi/agent/npm/ 下；專案範圍的 npm 軟體包安裝在 .pi/npm/ 下。完全按照應啟動的流程使用 argv 樣式條目。配置 npmCommand 時，git 套件依賴項安裝使用普通 install 以避免包裝器或備用套件管理器中特定於 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 }
}