Cài đặt Pi và cấu hình OmniProxy

Pi là một trợ lý terminal nhỏ gọn, tức là một chương trình cho phép bạn trò chuyện trực tiếp trong dòng lệnh, đọc tệp và hoàn thành tác vụ. System prompt của Pi khá ngắn và số lượng công cụ mặc định cũng không nhiều; khi cần thêm lệnh, quy trình hoặc giao diện khác, bạn có thể bổ sung thông qua extension. Có thể hiểu extension là thành phần bổ sung khả năng cho Pi, và sau khi hoàn thiện, bạn cũng có thể chia sẻ extension đó với người khác.

Sub-agent là cách giao một phần tác vụ cho một trợ lý khác xử lý, còn chế độ lập kế hoạch là sắp xếp các bước trước rồi mới bắt đầu thực hiện. Hai tính năng này không có sẵn theo mặc định; bạn có thể yêu cầu Pi tự tạo hoặc cài đặt gói do người khác chia sẻ.

Chuẩn bị trước khi cài đặt

macOS và Linux sử dụng tập lệnh cài đặt, tức là một lệnh tự động hoàn tất việc tải xuống và cài đặt. Windows sử dụng lệnh PowerShell được cung cấp trên trang chủ Pi; PowerShell là môi trường dòng lệnh tích hợp sẵn trong Windows. Bạn cũng có thể cài Pi trong WSL, tức là môi trường Linux chạy trong Windows.

Nếu chọn cài đặt bằng npm, trước tiên bạn cần chuẩn bị Node.js 22.19 trở lên. npm là trình quản lý gói được sử dụng cùng Node.js và có thể cài Pi từ dòng lệnh.

macOS Linux

install.sh

curl tập lệnh chính thức
Các phần phụ thuộc được trình cài đặt cố định
Dùng pi update để cập nhật

Windows

install.ps1

Lệnh PowerShell từ trang web chính thức
Git for Windows cung cấp Bash
Cũng có thể dùng WSL

Đã có Node

npm

Yêu cầu Node 22.19+
Tên gói là pi-coding-agent
Thêm --ignore-scripts

Tập lệnh cài đặt sẽ cố định các dependency. Cài đặt bằng npm không cố định dependency gián tiếp và cần thêm --ignore-scripts.

Cài đặt và khởi chạy lần đầu

Trên macOS hoặc Linux, mở terminal rồi chạy:

curl -fsSL https://pi.dev/install.sh | sh

Trên Windows, mở PowerShell rồi chạy:

powershell -c "irm https://pi.dev/install.ps1 | iex"

Nếu đã cài Node.js 22.19 trở lên, bạn cũng có thể sử dụng lệnh thay thế trong Quickstart:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Trong terminal tương tác, tập lệnh cài đặt có thể tạm dừng để đặt câu hỏi; bạn cần tiếp tục thao tác theo nội dung hiển thị trên màn hình. Nếu đã có phiên bản Node đáp ứng yêu cầu, lệnh npm này sẽ không đặt câu hỏi. Nếu muốn cài vào thư mục khác, hãy thêm --prefix /thư-mục-của-bạn. Ngày 2026-10-09, cách này đã cài đặt Pi 1.1.0.

Quá trình cài đặt npm thông thường không cần các lifecycle script của dependency, tức là những tập lệnh được gói phần mềm tự động chạy trong quá trình cài đặt. Tập lệnh cài đặt sẽ cố định các dependency; sau đó dùng pi update để cập nhật. Với bản cài đặt bằng npm, phương thức cập nhật phụ thuộc vào trình quản lý gói bạn sử dụng. Người dùng Nix cài đặt từ flake của Pi; flake là cấu hình mà Nix dùng để mô tả phần mềm và dependency, và pi update không thể cập nhật bản cài đặt Nix.

Sau khi cài đặt xong, trước tiên hãy xác nhận terminal có thể tìm thấy Pi:

pi --version

Trên Windows, nếu muốn cho phép mô hình thực thi lệnh Bash, phần lớn người dùng chạy trực tiếp trên máy nên cài Git for Windows. Bash là môi trường lệnh mà Pi dùng để chạy một số lệnh. Pi sẽ lần lượt tìm shellPath trong ~/.pi/agent/settings.json, Git Bash trong Program Files, rồi bash.exe trên PATH. shellPath dùng để chỉ định vị trí của Bash, còn PATH là danh sách thư mục mà hệ thống sử dụng khi tìm lệnh.

Sau khi khởi chạy, bạn có thể nhập !printf 'Bash is working\n' để kiểm tra. Nếu các tệp và công cụ đã nằm trong WSL, hãy cài đặt theo Quickstart ngay trong môi trường Linux đó.

Tiếp theo, chuyển đến thư mục chứa các tệp mà bạn muốn Pi xem hoặc xử lý, rồi khởi chạy:

cd /path/to/folder
pi

Thư mục này sẽ được dùng làm phạm vi làm việc hiện tại của Pi để phát hiện tệp và cấu hình, đồng thời dùng để nhóm các phiên làm việc.

Lấy thông số kết nối từ OmniProxy

Trước tiên, hãy chuẩn bị ba mục sau từ OmniProxy:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Sao chép từ danh sách mô hình hiện tại của OmniProxy

baseUrl là địa chỉ API mà Pi gửi yêu cầu đến và phải bao gồm /v1. apiKey là khóa dùng để truy cập API. Model ID là tên của mô hình cần gọi và phải được sao chép đầy đủ từ danh sách mô hình hiện tại của OmniProxy.

Đối với trường api, hãy điền openai-completions như trong ví dụ API tương thích. Trường này cho Pi biết cần gửi yêu cầu theo định dạng API nào.

Phải sao chép toàn bộ ID mô hình, bao gồm cả dấu gạch chéo trong tên. Vào ngày 2026-10-09, hai ID đối chiếu trong tài liệu của nhà cung cấp là gemini-3.8-flash và grok-4.7. Không sao chép tên không có trong danh sách.

Điền cấu hình công cụ

Cấu hình mô hình tùy chỉnh ở cấp người dùng của Pi được lưu trong models.json. Tệp này nằm trong thư mục agent, mặc định là ~/.pi/agent, vì vậy đường dẫn đầy đủ là ~/.pi/agent/models.json. Nếu đã đặt biến môi trường PI_CODING_AGENT_DIR, Pi sẽ sử dụng thư mục được biến này chỉ định; có thể hiểu biến môi trường là một giá trị cấu hình do hệ thống cung cấp để chương trình đọc.

Điền theo ví dụ API tương thích:

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

providers dùng để liệt kê các dịch vụ được kết nối, còn models dùng để liệt kê các mô hình có thể chọn. id của mỗi mô hình phải khớp với Model ID đầy đủ trong danh sách mô hình hiện tại của OmniProxy; input cho biết cấu hình ở đây sử dụng dữ liệu đầu vào dạng văn bản.

Bạn có thể ghi trực tiếp giá trị của apiKey, hoặc dùng $NAME hay ${NAME} để Pi đọc từ biến môi trường. Giá trị bắt đầu bằng ! sẽ được xem là một lệnh và được thực thi trong mỗi yêu cầu. Không đưa khóa thật vào repository. Nếu gateway không xác minh khóa, bạn có thể điền một chuỗi giữ chỗ chỉ dùng trên máy cục bộ. Ngày 2026-10-09, Pi đã đọc được tệp theo cách này.

Mở /model sẽ tải lại tệp này. /model là nơi xem và chọn mô hình trong Pi. Mô hình tùy chỉnh sẽ không xuất hiện trong /model cho đến khi Pi có thể phân tích được thông tin xác thực. Sau khi chọn mô hình, nhấn Ctrl+S để lưu mô hình đó làm mặc định cho các phiên mới.

Tệp

models.json

Thư mục mặc định là ~/.pi/agent
Thêm một mục trong providers
api dùng completions

Địa chỉ

baseUrl

Kết thúc bằng /v1
apiKey có thể dùng biến
id mô hình phải chính xác

Chọn dùng

/model

Tệp sẽ được tải lại sau khi mở
Chọn mô hình vừa thêm
Ctrl+S có thể lưu làm mặc định

Sau khi sửa tệp, hãy mở /model trong Pi và xác nhận mô hình đã xuất hiện.

Kiểm tra bằng một tác vụ thực tế

Sau khi hoàn tất cấu hình, bạn có thể thực hiện một lần kiểm tra không tương tác trong thư mục có tệp. Không tương tác nghĩa là không mở cuộc hội thoại liên tục; Pi sẽ kết thúc sau khi hoàn thành tác vụ này. Thay nội dung sau --model bằng ID đầy đủ trong danh sách hiện tại của OmniProxy:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Đọc dòng đầu tiên của tệp tôi chỉ định và không sửa đổi tệp."

Ở đây, --tools read chỉ cho phép công cụ đọc, đồng thời nội dung tác vụ cũng yêu cầu rõ ràng rằng không được sửa đổi tệp. Ngày 2026-10-09, Pi 1.1.0 đã đọc được nội dung tệp. Phản hồi đầu tiên mất khoảng hai phút.

Bạn cũng có thể sử dụng chế độ tương tác: chuyển đến thư mục, chạy pi, rồi dùng /model để chọn mô hình. Một tác vụ ví dụ trong Quickstart là yêu cầu Pi giải thích cách repository này được tổ chức và cách chạy các bước kiểm tra. Hãy quan sát xem Pi có đọc tệp và đưa ra phần giải thích hay không, sau đó kiểm tra nguồn và ID mô hình trong nhật ký gọi của OmniProxy.

Khởi động

pi khởi chạy được

Trước tiên cd đến thư mục
pi --version có đầu ra
Tên mô hình hiển thị ở cuối giao diện

Tác vụ

Nó đã đọc thư mục

Hỏi cách tổ chức kho mã
Xem các tệp mà nó liệt kê
Đừng chỉ kiểm tra thông báo lưu cấu hình

Nhật ký

Có thể thấy trên gateway

Nguồn là Pi
ID mô hình khớp
Giữ khóa trên máy cục bộ

Sau khi tên mô hình xuất hiện ở cuối giao diện, bạn vẫn cần hoàn thành một tác vụ thực tế.

Lỗi thường gặp

Không tìm thấy pi: mở lại terminal rồi thử pi --version. Nếu cài bằng npm, hãy xác nhận thư mục bin toàn cục nằm trong PATH.
Không có mô hình tùy chỉnh trong /model: xác nhận models.json nằm trong ~/.pi/agent/, apiKey có thể được phân tích, rồi mở lại /model.
Windows báo không tìm thấy Bash: cài Git for Windows hoặc đặt shellPath trong ~/.pi/agent/settings.json. Dấu gạch chéo ngược trong JSON phải được viết thành hai dấu.
Yêu cầu bị từ chối: kiểm tra api có phải là openai-completions và baseUrl có kết thúc bằng /v1 hay không. Không bật thêm tùy chọn tương thích chỉ vì phía bên kia tự nhận là tương thích.
ID mô hình không hợp lệ: sao chép lại từ danh sách hiện tại của OmniProxy.

Tài liệu tham khảo chính thức

Các lệnh cài đặt có tại trang chủ Pi và Quickstart. Thông tin về tệp mô hình có tại Choose a Model và Configuration. Thông tin về môi trường lệnh trên Windows có tại Run Pi on Windows. Các ID mô hình dùng trong ví dụ có tại danh sách mô hình Gemini và trang mô hình xAI.

Thay thế mọi chỗ giữ chỗ bằng giá trị từ cấu hình OmniProxy của riêng bạn. Không bao giờ công bố khóa thật.

Kết quả được lưu hoặc mã HTTP 200 đơn lẻ không chứng minh khả năng tương thích đầy đủ của Agent. Hãy kiểm tra nguồn và mô hình trong bản ghi lệnh gọi của OmniProxy.

Nguồn chính thức · Pi ↗