Cài đặt

Pi sử dụng tệp cài đặt JSON với cài đặt dự án ghi đè cài đặt chung.

Chỉnh sửa trực tiếp hoặc sử dụng /settings cho các tùy chọn phổ biến.

Khi khởi động tương tác, pi hỏi trước khi tin cậy một thư mục dự án có chứa các cài đặt, tài nguyên hoặc dự án cục bộ của dự án .agents/skills và không có quyết định nào được lưu cho thư mục hoặc thư mục mẹ trong ~/.pi/agent/trust.json. Tin tưởng vào một dự án cho phép pi tải tài nguyên .pi/settings.json và .pi, cài đặt các gói dự án bị thiếu và thực hiện các phần mở rộng dự án.

Các chế độ không tương tác (-p, --mode json và --mode rpc) không hiển thị lời nhắc tin cậy. Nếu không có quyết định tin cậy đã lưu hiện hành, họ sẽ sử dụng defaultProjectTrust từ cài đặt chung: ask (mặc định) và never bỏ qua các tài nguyên dự án đó, trong khi always tin cậy chúng. Vượt qua --approve/-a hoặc --no-approve/-na để ghi đè độ tin cậy của dự án trong một lần chạy.

Nếu không áp dụng tiện ích mở rộng hoặc quyết định đã lưu, defaultProjectTrust sẽ kiểm soát hành vi dự phòng. Đặt thành "ask", "always" hoặc "never" trong ~/.pi/agent/settings.json hoặc thay đổi bằng /settings.

pi config và các lệnh gói sử dụng cùng một luồng tin cậy của dự án, ngoại trừ pi update không bao giờ nhắc. Chuyển --approve để tin cậy cài đặt dự án cục bộ cho một lệnh hoặc --no-approve để bỏ qua chúng.

Sử dụng /trust trong chế độ tương tác để lưu quyết định tin cậy dự án cho các phiên trong tương lai, bao gồm cả tin cậy cho thư mục mẹ trực tiếp. Nó chỉ viết ~/.pi/agent/trust.json; phiên hiện tại không được tải lại, vì vậy hãy khởi động lại pi để các thay đổi có hiệu lực.

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

Đối với VS Code, hãy bao gồm --wait để pi tiếp tục hoạt động sau khi trình chỉnh sửa thoát:

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

enableInstallTelemetry chỉ kiểm soát ping cài đặt/cập nhật ẩn danh thành https://pi.dev/api/report-install. Việc chọn không tham gia đo từ xa sẽ không vô hiệu hóa việc kiểm tra cập nhật; Pi vẫn có thể tìm nạp https://pi.dev/api/latest-version để tìm phiên bản mới nhất.

Đặt PI_SKIP_VERSION_CHECK=1 để tắt kiểm tra cập nhật phiên bản Pi. Sử dụng --offline hoặc PI_OFFLINE=1 để tắt tất cả các hoạt động mạng khởi động được mô tả ở đây, bao gồm kiểm tra cập nhật, kiểm tra cập nhật gói và đo từ xa cài đặt/cập nhật.

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

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

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

Khi nhà cung cấp yêu cầu độ trễ thử lại lâu hơn retry.provider.maxRetryDelayMs, yêu cầu sẽ không thành công ngay lập tức kèm theo lỗi thông tin thay vì im lặng chờ đợi. Đặt thành 0 để tắt giới hạn.

Giữ retry.provider.maxRetries ở 0 trừ khi rõ ràng cần phải thử lại ở cấp độ nhà cung cấp. Việc đặt nó ở trên 0 có thể khiến SDK/nhà cung cấp thử lại xử lý các lỗi hết giới hạn sử dụng trước khi Pi nhìn thấy chúng, điều này có thể chặn tác nhân cho đến khi hạn mức của nhà cung cấp được đặt lại trong một số trường hợp.

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

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

npmCommand được sử dụng cho tất cả các hoạt động của trình quản lý gói npm, bao gồm cài đặt, gỡ cài đặt và cài đặt phụ thuộc bên trong các gói git. Các gói npm trong phạm vi người dùng được cài đặt trong ~/.pi/agent/npm/; cài đặt các gói npm trong phạm vi dự án trong .pi/npm/. Sử dụng các mục nhập kiểu argv chính xác như quy trình sẽ được khởi chạy. Khi npmCommand được định cấu hình, các bản cài đặt phụ thuộc gói git sử dụng install đơn giản để tránh các cờ dành riêng cho npm trong trình bao bọc hoặc trình quản lý gói thay thế.

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

Khi nhiều nguồn chỉ định một thư mục phiên, mức độ ưu tiên là --session-dir, PI_CODING_AGENT_SESSION_DIR, sau đó là sessionDir trong settings.json.

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

Các cài đặt này xác định nơi tải tiện ích mở rộng, kỹ năng, lời nhắc và chủ đề.

Các đường dẫn trong ~/.pi/agent/settings.json phân giải tương ứng với ~/.pi/agent. Các đường dẫn trong .pi/settings.json phân giải tương ứng với .pi. Đường dẫn tuyệt đối và ~ được hỗ trợ.

Mảng hỗ trợ các mô hình và loại trừ toàn cầu. Sử dụng !pattern để loại trừ. Sử dụng +path để buộc bao gồm một đường dẫn chính xác và -path để buộc loại trừ một đường dẫn chính xác.

Dạng chuỗi tải tất cả tài nguyên từ một gói:

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

Biểu mẫu đối tượng lọc những tài nguyên nào sẽ tải:

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

Xem packages.md để biết chi tiết quản lý gói.

{
  "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"]
}

Cài đặt dự án (.pi/settings.json) ghi đè cài đặt chung. Các đối tượng lồng nhau được hợp nhất:

// ~/.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 }
}