Xử lý sự cố
Bạn tìm lỗi của mình theo thông báo hoặc triệu chứng bên dưới. Trước khi nhờ giúp ở Liên hệ, hãy chạy ph forge doctor và gửi kèm kết quả.
Chưa đăng nhập Tara
Bạn gặp lỗi này khi thấy "not signed in to Tara", "Tara refused the request (401)", hoặc dòng ✗ Tara trong ph forge doctor. Nguyên nhân là chưa đăng nhập, hoặc phiên đã hết hạn. Phiên đăng nhập bằng trình duyệt sống khá ngắn, khoảng 12 giờ, để bảo vệ các việc cần quyền cao. Bạn đăng nhập lại như sau:
ph login # mở trình duyệt, click Allow
ph tara whoami # in tài khoản, tổ chức và hạn phiênMột lần đăng nhập thuộc về một tổ chức. Nếu bạn thuộc nhiều tổ chức, ph login hỏi bạn chọn từ danh sách đánh số, hoặc bạn gõ ph login --org <slug> (bắt buộc khi không có terminal, như trong CI). Nếu bạn chưa thuộc tổ chức nào, lệnh in địa chỉ Portal <tara>/get-started để bạn tạo tổ chức hoặc nhận lời mời. Muốn đổi tổ chức sau này, bạn dùng ph org switch <slug>.
Nếu máy không có trình duyệt, như qua SSH hay trong CI, bạn tạo token cá nhân trên Portal Tara (menu tài khoản, Access tokens (token truy cập)), chạy ph tara login --token-stdin rồi dán token vào.
Nếu không kết nối được tới Tara, bạn kiểm tra địa chỉ có https:// không, rồi kiểm tra mạng hoặc VPN.
Chưa thuộc tổ chức nào (no_org)
Bạn thấy thông báo "you do not belong to any organization yet", hoặc mã no_org (HTTP 409), khi chạy ph login hay tạo token. Nguyên nhân là tài khoản đã đăng nhập nhưng chưa là thành viên của tổ chức nào. Đăng nhập chỉ cho biết bạn là ai. Bạn không mất gì: mã đăng nhập chưa bị dùng hết, nên làm xong bước dưới bạn chạy lại lệnh là được.
Trên Portal: bạn mở <tara>/get-started. Bạn có thể tạo tổ chức (nhập tên và slug như acme, bạn thành Owner), hoặc mở đường dẫn lời mời mà Owner hay Admin đã gửi.
Bằng Phillip: bạn tạo tổ chức bằng ph org create acme (cần đăng nhập bằng trình duyệt), hoặc nhận lời mời trên Portal trước. Rồi đăng nhập lại:
ph org create acme --name "Acme Inc."
ph loginCần chọn tổ chức (org_required)
Bạn thấy "Choose an organization first", hoặc mã org_required (HTTP 409). Nguyên nhân là bạn thuộc nhiều tổ chức mà lúc đăng nhập chưa nói là tổ chức nào. Trong terminal, ph login hiện danh sách đánh số cho bạn chọn. Không có terminal, như trong CI hay qua SSH, lệnh in danh sách rồi dừng vì không hỏi bạn được.
Bằng Phillip: bạn nêu tên tổ chức.
ph org list # các tổ chức bạn thuộc về
ph login --org acmeTrong CI, bạn đặt PHILLIP_ORG=acme cạnh PHILLIP_TARA_TOKEN. Trên Portal: bạn chọn tổ chức ở bộ chuyển đầu trang.
Hết seat (seat_limit)
Bạn thấy seat_limit (HTTP 409) khi mời người, nhận lời mời hoặc đổi vai trò. Nguyên nhân là tổ chức đã dùng hết seat. Owner, Admin và Member mỗi người dùng một seat, và gói Free có 7 seat. Viewer không dùng seat. Gói Team không giới hạn seat: Owner có thể nâng gói.
Owner hoặc Admin xử lý theo một trong các cách sau:
- Trên Portal: mở trang thành viên của tổ chức. Bạn xóa người đã rời đi, hoặc đổi người chỉ cần dùng trình duyệt (BA, PO, PM) sang Viewer. BA, PO, PM mới thì mời với vai trò Viewer.
- Bằng Phillip:
ph org current # gói và số seat đã dùng
ph org members # ai đang trong tổ chức
ph org members set-role <login> viewer # nhả một seat
ph org members remove <login>
ph org invite <email> --role viewerNếu bạn không phải Owner hay Admin, hãy nhờ một trong hai người làm giúp.
Tên chỉ có ở tổ chức khác
Bạn thấy "did you mean beta/skill-foo?", hoặc mã not_found_hint (HTTP 404), khi cài hay khóa một tài nguyên bằng tên trần. Nguyên nhân là không có tài nguyên tên skill-foo ở kho chính thức hay trong tổ chức của bạn, nhưng một tổ chức khác có tài nguyên cộng đồng công khai cùng tên. Tên trần cố ý không bao giờ khớp với tài nguyên của tổ chức khác, để không ai chiếm được tên. Thông báo liệt kê tối đa năm tên đầy đủ.
Bạn dùng tên đầy đủ <org>/<tên>. Trên Portal: kho cộng đồng hiện tên đầy đủ của từng tài nguyên. Bằng Phillip:
ph tara search skill-foo --channel community
ph tara add beta/skill-fooNếu lỗi đến từ một phụ thuộc trong manifest, bạn ghi tên đầy đủ vào dependencies. Tài nguyên cộng đồng sẽ hỏi xác nhận trước khi thêm.
Mở tổ chức bị 404
Bạn mở <tara>/acme/... hoặc chạy lệnh cho một tổ chức rồi nhận 404 Not found. Nguyên nhân là bạn chưa là thành viên của tổ chức đó, hoặc gõ sai slug. Tara trả cùng một 404 cho cả hai trường hợp, để người ngoài không biết tổ chức có tồn tại hay không.
- Chạy
ph org listhoặc xem bộ chuyển tổ chức để biết các slug bạn thuộc về. - Nếu đáng ra bạn phải là thành viên, bạn nhờ Owner hoặc Admin mời, rồi nhận lời mời.
- Nếu bạn đã là thành viên, chuyển sang bằng
ph org switch <slug>, vì đăng nhập và token của bạn có thể đang thuộc tổ chức khác.
Không thấy lệnh ph (PATH)
Lỗi này hiện ra dưới dạng ph: command not found, hoặc terminal tích hợp của VS Code báo không tìm thấy ph, hoặc extension VS Code báo chưa cài Phillip dù bạn đã cài. Lý do là npm install -g đặt ph vào thư mục bin của npm, mà thư mục đó chưa nằm trong PATH. VS Code mở từ Dock hoặc menu Start cũng thường có PATH tối giản hơn terminal của bạn.
Mở một terminal mới, vì shell chỉ đọc lại cấu hình khi khởi động.
Tìm thư mục cần thêm:
bashecho "$(npm prefix -g)/bin"Thêm thư mục đó vào
PATHtrong file cấu hình shell. Ví dụ với zsh:bashecho 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrcRiêng VS Code thì bạn thoát hẳn rồi mở lại từ terminal bằng
code ., hoặc chạyph setupđể extension nhận đường dẫn.
Trên Windows, bạn thêm thư mục mà npm prefix -g in ra vào biến Path của người dùng rồi mở lại PowerShell.
Nếu khi cài gặp 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. Script cài không tự dùng sudo, nên bạn cho npm cài vào thư mục của mình:
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrcSau đó bạn chạy lại lệnh cài.
Node cũ hơn 22
Khi thấy "Node v… is too old. Phillip needs Node 22 or later", hoặc dòng ✗ Node trong ph forge doctor, bạn nâng Node lên 22 trở lên rồi chạy lại lệnh cài.
node --version # cần v22 trở lên
nvm install 22 && nvm use 22 # nếu dùng nvm; hoặc fnm, brew install node, trình cài từ nodejs.orgNếu máy có nhiều phiên bản Node, hãy chắc rằng terminal và VS Code cùng dùng bản 22.
Bị Guardrails chặn
Khi một thao tác của agent bị từ chối hoặc bị hỏi lại, thông báo sẽ kèm tên luật và lý do. Bị chặn chưa chắc là bạn làm sai, vì có khi luật chặn nhầm. Bạn đọc thông báo để biết luật nào và vì sao, rồi thử nhờ agent làm theo một hướng an toàn khác cho cùng mục đích.
Nếu tin luật chặn nhầm, bạn gửi phản hồi kèm lý do để đội phụ trách xem. Phillip che bí mật trong ghi chú trước khi gửi.
ph guardrails feedback <id luật> --note "Why I think this is a false positive"Muốn xem tình trạng Guardrails trên máy, bạn chạy ph guardrails status. Đừng tìm cách tắt Guardrails, nếu cần ngoại lệ thì nhờ Owner hoặc Admin của tổ chức, hoặc project admin, để policy được cập nhật đúng quy trình. Xem thêm Khi bị Guardrails chặn.
Plugin sai chữ ký hoặc bị thu hồi
Có ba dấu hiệu. Thứ nhất là thông báo "the signature of … is invalid" hoặc "… has no signature" khi cài tài nguyên hoặc khi chạy ph bandum ui. Thứ hai là cảnh báo "no Tara signing key is configured, so only sha256 is checked". Thứ ba là ph tara list hay ph forge doctor báo một tài nguyên bị thu hồi hoặc ngừng hỗ trợ.
| Triệu chứng | Làm gì |
|---|---|
| Chữ ký sai hoặc thiếu | Không chạy gói này và báo Owner hoặc Admin. Kiểm khóa tin cậy bằng ph tara keys |
| Cảnh báo chưa kiểm chữ ký | Máy chưa có khóa công khai. Lấy khóa từ Owner hoặc Admin rồi chạy ph tara keys trust ed25519:<khóa> |
| Tài nguyên bị thu hồi | Gói này có vấn đề an toàn. Chạy ph tara outdated rồi ph tara upgrade để lên bản không bị thu hồi, sau đó commit phillip.lock |
Plugin scm báo no connector plugin for <host> | Chạy ph connect để chọn nhà cung cấp cho máy chủ đó |
Cơ chế này được giải thích ở Ký số và thu hồi.
Lỗi khi kết nối GitHub hoặc GitLab
| Thấy | Cách xử lý |
|---|---|
| 401 hoặc 403 khi kiểm token | Token sai, hết hạn hoặc thiếu quyền, hoặc bạn chưa phải Developer của repo. Tạo lại bằng ph connect |
| 404 | Không vào được máy chủ hoặc project. Kiểm tra --host và xem token đã được cấp vào project chưa |
| Token mới không có tác dụng | Biến môi trường GITHUB_TOKEN hoặc GITLAB_TOKEN đang đè token đã lưu, bạn bỏ chúng khỏi shell |
Lỗi khi chạy Bandum trên máy
| Thấy | Cách xử lý |
|---|---|
| "port … is busy" | Bỏ --port để Phillip tự chọn cổng trống |
"--docker needs Docker installed and running" | Bật Docker Desktop rồi chạy lại, hoặc bỏ --docker để dùng SQLite |
| "Bandum exited early" | Đọc 20 dòng log mà Phillip in kèm, và chạy ph bandum ui logs |
| Bandum báo 401 từ GitHub hoặc GitLab | Chạy ph connect, rồi ph bandum ui stop và chạy lại ph bandum ui |
Lỗi hằng ngày với task
| Thấy | Cách xử lý |
|---|---|
no open PR for GH-12 | Bạn chưa mở PR, hoặc nhánh không mang mã GH-12 |
branch ... does not have the latest commit pushed | Chạy git push -u origin HEAD rồi chạy lại lệnh |
ph bandum check thoát với mã 2 | Sửa theo từng dòng báo lỗi, còn cảnh báo thì không chặn |
The repo has no .bandum.json | Dự án chưa khai cách chạy ứng dụng, bạn dùng --cli hoặc hỏi Dev |
Dòng cảnh báo trong ph forge doctor
Dòng ⚠ là tùy chọn, không làm thiết lập thất bại.
ph forge doctorNode v24.22.0Claude Code 2.1.308 (Claude Code)git git version 2.50.1 (Apple Git-155)Tara maya.chen @ https://tara.phillipcli.cloudphillip.lock 17 resources locked (lock ba8972f416dd)Ryoma https://ryoma.phillipcli.cloud: metrics receivedCollector data received through RyomaGuardrails not installed on this machine (the Guardrails dashboard will be empty). Install: sudo "$(command -v ph)" guardrails install --tara https://tara.phillipcli.cloud --ryoma https://ryoma.phillipcli.cloud --keys ed25519:<public key>| Thấy | Ý nghĩa |
|---|---|
⚠ Ryoma | Phiên chưa gửi số liệu, hoặc chưa đăng nhập Tara. Đăng nhập lại, nếu còn báo thì hỏi đội vận hành |
⚠ Guardrails | Máy chưa cài Guardrails. Chạy đúng lệnh sudo … mà doctor in ra, hoặc hỏi xem bạn có bắt buộc cài không |
⚠ Collector | Collector không nhận dữ liệu nên dashboard trống, nhờ đội vận hành kiểm tra |