Cài đặt chi tiết
Trang này đi qua cách cài Phillip trên từng hệ điều hành, cách sửa PATH, nâng cấp, gỡ cài đặt và cài extension VS Code. Nếu cần đi từ đầu đến task đầu tiên thì xem Dev và Test.
Máy cần những gì
Bạn cần Node 22 trở lên kèm npm (kiểm tra bằng node --version), git, và một trong ba hệ điều hành macOS, Linux hoặc Windows. Bạn cũng cần quyền ghi vào thư mục cài toàn cục của npm, vì script cài không dùng sudo (xem Thư mục cài của npm). Cuối cùng là địa chỉ Tara của tổ chức, trong tài liệu này viết là https://tara.phillipcli.cloud. Bạn hỏi trưởng nhóm hoặc đội vận hành để biết địa chỉ thật.
Cài từ Tara
Tara phục vụ script cài và đã ghi sẵn địa chỉ của chính nó vào script. Script không đi qua dịch vụ gói bên ngoài nào.
curl -fsSL https://tara.phillipcli.cloud/install.sh | shKhi chạy, script lần lượt làm các việc sau.
- Kiểm tra Node 22 trở lên và
npm. Thiếu hoặc cũ thì dừng và chỉ cách cài. - Tải thông tin bản Phillip mới nhất (
latest.json) và gói.tgztừ Tara. - Đối chiếu sha256 của gói với giá trị Tara công bố. Không khớp thì không cài.
- Chạy
npm install -gvới gói đó. - Kiểm tra thư mục
bincủa npm đã nằm trongPATHchưa, và cảnh báo nếu lệnhphtrên máy đang trỏ tới chương trình khác. - Ghi địa chỉ Tara và khóa công khai của Tara vào cấu hình người dùng của Phillip, giữ nguyên các khóa khác trong cấu hình.
Cài xong, bạn kiểm tra và thiết lập như sau:
ph --version # phiên bản Phillip rồi phiên bản Claude Code đi kèm
ph setup # đăng nhập Tara, chọn harness, kết nối GitHub/GitLab, kiểm tra máy (chạy trong thư mục repo)
ph forge doctor # kiểm tra môi trườngNếu bạn thuộc nhiều tổ chức, ph setup (qua ph login) sẽ hỏi dùng tổ chức nào. Trong CI, hãy chỉ rõ bằng ph login --org acme hoặc đặt PHILLIP_ORG=acme. Muốn đổi sau này, dùng ph org switch <slug>. Người chưa có tổ chức nào thì tạo ở màn hình Get started trên Portal, hoặc bằng ph org create <slug>.
Lệnh cài theo hệ điều hành
| Hệ điều hành | Lệnh cài | Cấu hình người dùng lưu ở |
|---|---|---|
| macOS, Linux | curl -fsSL https://tara.phillipcli.cloud/install.sh | sh | ~/.config/phillip/config.json (hoặc theo XDG_CONFIG_HOME) |
| Windows (PowerShell) | irm https://tara.phillipcli.cloud/install.ps1 | iex | %APPDATA%\phillip\config.json |
Muốn đổi thư mục cấu hình thì đặt biến môi trường PHILLIP_HOME trước khi chạy script. Máy không có curl thì script tự dùng wget. Trên Windows, nếu chưa có Node, script gợi ý chạy winget install OpenJS.NodeJS.
Cài bằng npm
Nếu trưởng nhóm đưa bạn file gói .tgz, hoặc bạn không muốn dùng script, hãy cài thẳng:
npm install -g ./phillip-<phiên-bản>.tgzCách này chưa ghi địa chỉ Tara vào cấu hình. Vì vậy ở bước thiết lập, bạn chạy ph setup --tara https://tara.phillipcli.cloud để Phillip lấy địa chỉ và khóa công khai.
Thêm vào PATH
ph và phillip là hai tên của cùng một chương trình, nằm trong thư mục bin của npm. Nếu terminal báo ph: command not found thì thư mục đó chưa có trong PATH.
Mở một terminal mới, vì shell chỉ đọc lại cấu hình khi khởi động.
Xem thư mục cần thêm:
bashecho "$(npm prefix -g)/bin"Thêm thư mục đó vào
PATH. Ví dụ với zsh:bashecho 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrcBash thì dùng
~/.bashrctrên Linux hoặc~/.bash_profiletrên macOS. Trên Windows, bạn thêm thư mục mànpm prefix -gin ra vào biếnPathcủa người dùng rồi mở lại PowerShell.Chạy
ph --versionđể kiểm tra.
Nếu máy có chương trình khác cũng tên ph, script cài sẽ cảnh báo. Lúc đó bạn dùng phillip thay cho ph, hoặc đưa thư mục bin của npm lên trước trong PATH.
Thư mục cài của npm
Lỗi EACCES nghĩa là npm đang cài vào thư mục hệ thống mà bạn không có quyền ghi. Đừng dùng sudo npm, hãy cho npm cài vào thư mục của bạn:
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrcTrên Windows, bạn chạy npm config set prefix "$env:APPDATA\npm" rồi thêm thư mục đó vào Path. Sau đó chạy lại lệnh cài.
Nâng cấp và gỡ cài đặt
Muốn nâng cấp, bạn chạy lại đúng lệnh cài ở trên. Script lấy bản mới nhất của Tara, kiểm sha256 và cài đè, còn cấu hình và đăng nhập của bạn vẫn giữ nguyên. Bandum chạy trên máy thì nâng cấp riêng bằng ph bandum ui upgrade, và tài nguyên trong dự án thì dùng ph tara outdated rồi ph tara upgrade.
Muốn gỡ, bạn chạy:
npm uninstall -g @phillipcli/phillipNếu muốn xóa luôn cấu hình và dữ liệu, trước hết đăng xuất bằng ph tara logout để thu hồi phiên và xóa token khỏi máy, sau đó xóa thư mục cấu hình ở bảng trên. Máy có Guardrails do tổ chức cài bằng quyền quản trị thì gỡ theo hướng dẫn của đội vận hành, vì ph guardrails uninstall cần sudo.
Cài extension VS Code
Extension Phillip cho VS Code là một file .vsix mà Tara phát cạnh gói Phillip. Bạn tải về rồi cài bằng hai lệnh:
curl -fsSLo phillip-vscode.vsix https://tara.phillipcli.cloud/phillip/phillip-vscode-latest.vsix
code --install-extension phillip-vscode.vsixNếu Tara của bạn bắt đăng nhập mới được tải, bạn đăng nhập Tara trước rồi mở cùng địa chỉ trên trình duyệt để lưu file.
Hoặc trong VS Code, bạn mở Extensions, bấm menu ... rồi chọn Install from VSIX.... Extension không giữ token riêng mà chạy lệnh ph giúp bạn, nên bạn cần cài và đăng nhập Phillip trước. Xem thêm Extension VS Code.
Đọc kết quả ph forge doctor
ph forge doctor cho biết môi trường đã đủ chưa.
| Dòng | Ý nghĩa |
|---|---|
✗ Node, ✗ Claude Code, ✗ git, ✗ Tara | Bắt buộc, sửa rồi chạy lại |
⚠ Ryoma, ⚠ Collector, ⚠ Guardrails | Tùy chọn, có gợi ý cách sửa |
Môi trường đạt khi không còn dòng ✗, còn dòng ⚠ không chặn bạn. Gặp lỗi khác thì xem Xử lý sự cố.