Chuyển đến nội dung chính
Hướng dẫn AI

Hướng dẫn cài đặt, cấu hình và cuộc trò chuyện đầu tiên với Pi Agent

Cài pi không phức tạp, chỉ cần một lệnh. Điều duy nhất cần quyết định trước là phương thức xác thực: dùng gói đăng ký hiện có hay API Key. Dưới đây là toàn bộ quy trình cài đặt, xác thực và bắt đầu cuộc trò chuyện đầu tiên. Khái niệm cốt lõi: hai phương thức xác thựcPi cần thông tin xác thực của một nhà cung cấp LLM để hoạt động sau khi cài đặt. Có hai cách xác thực, và đây là điểm khác biệt duy nhất cần hiểu trong bài viết này: đăng nhập gói đăng ký (/login)｜API KeyDùng gì｜Các gói đăng ký như Claude Pro/Max, ChatGPT Plus/Pro｜API Key do nhà cung cấp cấpPhí｜Phức tạp (hạn mức gói đăng ký + có thể phát sinh mức sử dụng bổ sung)｜Tính theo

彡 GiaThời gian đọc khoảng 14 phút
Hướng dẫn cài đặt, cấu hình và cuộc trò chuyện đầu tiên với Pi Agent

Cài pi không phức tạp, chỉ cần một lệnh. Điều duy nhất cần quyết định trước là phương thức xác thực: dùng gói đăng ký hiện có hay API Key. Dưới đây là toàn bộ quy trình cài đặt, xác thực và bắt đầu cuộc trò chuyện đầu tiên.

Khái niệm cốt lõi: hai phương thức xác thực

Sau khi cài đặt, pi cần thông tin xác thực của một nhà cung cấp LLM để hoạt động. Có hai cách xác thực, và đây là điểm khác biệt duy nhất cần hiểu trong bài viết này:

  • Đăng nhập gói đăng ký (/login)｜API Key

  • Dùng gì｜Các gói đăng ký như Claude Pro/Max, ChatGPT Plus/Pro｜API Key do nhà cung cấp cấp

  • Phí｜Phức tạp (hạn mức gói đăng ký + có thể phát sinh mức sử dụng bổ sung)｜Tính theo token, dùng bao nhiêu trả bấy nhiêu

  • Lưu thông tin xác thực ở đâu｜~/.pi/agent/auth.json (OAuth token, tự động làm mới)｜Biến môi trường hoặc auth.json

  • Phù hợp với ai｜Đã có gói đăng ký, không muốn quản lý Key riêng｜Muốn kiểm soát chi phí chính xác

Lưu ý: đăng nhập gói đăng ký Anthropic (Claude Pro/Max) sử dụng kênh harness bên thứ ba và tính phí theo token, không tiêu hao hạn mức gói đăng ký. pi hiển thị cảnh báo, đây là hiện tượng bình thường. Nếu muốn kiểm soát hoàn toàn và luôn biết mình đã chi bao nhiêu, API Key sẽ thuận tiện hơn.

Thực hành

1. Cài pi

pi chạy trên Node.js, yêu cầu phiên bản 22.19.0 trở lên, trước tiên hãy kiểm tra bằng node --version. Chọn một trong hai cách cài đặt:

# Cài đặt toàn cục bằng npm (--ignore-scripts bỏ qua các script phụ thuộc, an toàn hơn)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# Hoặc dùng trình cài đặt curl (sẽ cài Node nếu máy chưa có)
curl -fsSL https://pi.dev/install.sh | sh

Sau khi cài xong, xác minh bằng pi --version. Gỡ cài đặt bằng npm uninstall -g @earendil-works/pi-coding-agent.

2. Cấu hình xác thực

Cách một: API Key (khuyến nghị), đặt Key thành biến môi trường:

export ANTHROPIC_API_KEY=sk-ant-...
pi

Hoặc trong pi, dùng /login để chọn một API Key provider và lưu Key vào ~/.pi/agent/auth.json (quyền 0600, chỉ bạn có thể đọc và ghi). Các biến môi trường của những nhà cung cấp phổ biến:

  • Nhà cung cấp｜Biến môi trường

  • Anthropic｜ANTHROPIC_API_KEY

  • OpenAI｜OPENAI_API_KEY

  • DeepSeek｜DEEPSEEK_API_KEY

  • Google Gemini｜GEMINI_API_KEY

  • Groq｜GROQ_API_KEY

  • xAI｜XAI_API_KEY

  • OpenRouter｜OPENROUTER_API_KEY

Xem danh sách đầy đủ gồm hàng chục nhà cung cấp trong tài liệu Providers chính thức[1].

Cách hai: Đăng nhập gói đăng ký, nếu đã có gói đăng ký như Claude Pro hoặc ChatGPT Plus, hãy dùng /login trong pi, chọn provider tương ứng và hoàn tất OAuth. Khi token hết hạn, pi sẽ tự động làm mới. Các lựa chọn: Claude Pro/Max, ChatGPT Plus/Pro(Codex), GitHub Copilot, xAI, OpenRouter. Đăng xuất bằng /logout.

Cộng đồng Pi rất sôi động, Pi Agent mới nhất đã hỗ trợ token plan của Qwen.

Sau khi cấu hình mô hình, bạn có thể dùng /model để chọn mô hình muốn sử dụng.

Pi Agent còn có khái niệm scoped models.

Mục đích của scoped models là cho phép người dùng chuyển nhanh giữa một số mô hình bằng ctrl + p. Bạn cũng có thể dùng ctrl + l để chọn. Cấu hình tương ứng nằm trong trường enabledModels của tệp ~/.pi/agent/settings.json.

3. Khởi động lần đầu

Đi tới thư mục dự án và khởi động:

cd /path/to/your/project
pi

Lần đầu truy cập một dự án có cấu hình .pi/, pi sẽ hỏi bạn có tin cậy hay không. Tài nguyên cấp dự án có thể chứa các extension có khả năng thực thi mã tùy ý, vì vậy pi không cho phép tải chúng mà bạn không biết. Quyết định tin cậy được lưu trong ~/.pi/agent/trust.json, lần sau sẽ không hỏi lại.

Giao diện gồm bốn phần từ trên xuống dưới: Header (phím tắt/tài nguyên đã tải), Messages, Editor (nơi nhập liệu, màu viền = cấp độ suy nghĩ), Footer (thư mục/phiên sử dụng/token/chi phí/mô hình hiện tại). Nhập trực tiếp rồi nhấn Enter, ví dụ:

Hãy xem cấu trúc kho lưu trữ này và cho tôi biết cách chạy các bước kiểm tra.

Theo mặc định, pi cung cấp cho mô hình bốn công cụ: read, write, edit, bash. Ba công cụ chỉ đọc khác là grep/find/ls được tắt theo mặc định; khi cần, hãy bật bằng --tools, chẳng hạn để pi chỉ đọc và không ghi khi thực hiện đánh giá mã:

pi --tools read,grep,find,ls -p "Đánh giá chất lượng mã của kho lưu trữ này"

Chuyển mô hình bằng Ctrl+L hoặc /model; thoát bằng cách nhấn Ctrl+C hai lần hoặc dùng /quit; tiếp tục cuộc trò chuyện trước đó bằng pi -c.

Hiểu nguyên lý

Thứ tự phân giải xác thực: khi đồng thời cấu hình biến môi trường, auth.json và tham số dòng lệnh, pi sẽ lấy theo thứ tự dòng lệnh --api-key > auth.json > biến môi trường > models.json. Để tạm thời đổi Key kiểm thử, dùng trực tiếp pi --api-key xxx, không cần thay đổi tệp cấu hình.

Quyền tin cậy dự án là lớp bảo vệ đầu vào, không phải sandbox: nó chỉ hiển thị hộp thoại khi khởi động tương tác. Ở chế độ không tương tác (pi -p), mặc định dùng ask, có thể ghi đè bằng -a/-na. pi không có sandbox theo mặc định; khi mô hình được cấp bash, nó có thể thực thi mọi lệnh. Với kho lưu trữ không đáng tin cậy, cần dùng container để cô lập; nội dung này sẽ được đề cập trong phần bảo mật sau.

Câu hỏi thường gặp

H: pi --version báo command not found nhưng npm cho biết đã cài thành công.
Phần lớn nguyên nhân là thư mục bin toàn cục của npm không nằm trong PATH. Dùng npm prefix -g để xem đường dẫn và thêm vào PATH; người dùng nvm nhớ chạy nvm use.

H: Khởi động báo phiên bản Node quá thấp.
pi yêu cầu Node 22.19.0+. Hãy nâng cấp bằng trình quản lý phiên bản (fnm/mise/nvm), hoặc dùng trình cài đặt curl.

H: Sau khi đăng nhập Claude Pro, lần nào cũng xuất hiện cảnh báo mức sử dụng bổ sung.
Gói đăng ký Anthropic sử dụng kênh bên thứ ba và tính phí theo token. Để tắt, thêm nội dung sau vào ~/.pi/agent/settings.json:

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

H: Shift+Enter không xuống dòng được.
pi dùng giao thức bàn phím Kitty để nhận diện phím bổ trợ. iTerm2, Kitty và Ghostty có thể sử dụng mà không cần cấu hình; VS Code 1.109.5+ hỗ trợ mặc định. Windows Terminal, WezTerm và Alacritty cần thêm một dòng cấu hình để chuyển tiếp phím; xem tài liệu cấu hình terminal[2].

H: Muốn hoàn toàn ngoại tuyến, không kết nối pi.dev để kiểm tra cập nhật.
PI_OFFLINE=1 tắt mọi thao tác mạng khi khởi động. Nếu chỉ muốn tắt kiểm tra phiên bản, dùng PI_SKIP_VERSION_CHECK=1.

Tài liệu tham khảo

  • • Tài liệu bắt đầu nhanh với Pi[3]

  • • Tài liệu Pi Providers[1] - Tất cả Provider, biến môi trường và cấu hình nhà cung cấp đám mây

  • • Tài liệu Pi Custom Models[4] - Tùy chỉnh Provider bằng models.json

  • • Tài liệu Pi Settings[5]

  • • Pi Terminal Setup[2] - Cấu hình phím cho từng terminal

  • • Kho lưu trữ Pi trên GitHub[6]

Liên kết trích dẫn

[1] Tài liệu Providers chính thức: https://pi.dev/docs/latest/providers
[2] Tài liệu cấu hình terminal: https://pi.dev/docs/latest/terminal-setup
[3] Tài liệu bắt đầu nhanh với Pi: https://pi.dev/docs/latest/quickstart
[4] Tài liệu Pi Custom Models: https://pi.dev/docs/latest/models
[5] Tài liệu Pi Settings: https://pi.dev/docs/latest/settings
[6] Kho lưu trữ Pi trên GitHub: https://github.com/earendil-works/pi

#Lập trình AI#Mã nguồn mở#Mô hình ngôn ngữ lớn#Nền tảng phát triển#Phân tích dữ liệu#Thiết kế AI#Tác nhân thông minh#Văn phòng AI