Bài 2/20 trong bộ onboarding AgentKit v3. Đọc khoảng 12 phút, làm theo khoảng 10 phút.
Tui có một nguyên tắc khi làm tool cho dev: cái gì phá được thì phải có đường lui. Bài này đi đúng thứ tự tui khuyên anh em làm: chụp lại hiện trạng, update, kiểm tra, rồi mới tính chuyện bật auto-update. Lỡ có gì thì cuộn xuống phần rollback.
1/ Trước khi update: biết mình đang ở đâu ✅
ak --version
ak versions
ak doctor
ak versions cho bạn bảng phiên bản CLI, app desktop và từng kit. ak doctor kiểm tra môi trường: Node, Git, kết nối registry, thư mục ~/.agentkit, shim cũ của ClaudeKit...
Nếu bạn còn đang xài ClaudeKit (bản cài cũ, lệnh ck), chạy thêm:
ak migrate --dry-runak migrate chuyển bản cài ClaudeKit sang AgentKit. Luôn --dry-run trước, đọc kỹ nó định đụng vô đâu, rồi mới chạy thật.
2/ Chụp checkpoint trước khi lên v3 ✅
v3 tự snapshot những file nó sắp ghi (mỗi lần ak update đều có restore point trong ak backups list). Nhưng tui vẫn khuyên tạo một checkpoint có chủ đích trước khi nhảy version lớn:
ak backups checkpoint --pre-upgrade
ak backups listCheckpoint này chụp ~/.agentkit, thư mục home của các runtime và config agent của project. Nó chính là cái mà ak rollback --to v2 sẽ dùng để khôi phục.
Bài học xương máu: checkpoint phải chụp trước khi update. Ảnh dưới là ak rollback --to v2 --dry-run trên một máy đã ở v3 mà chưa từng có checkpoint v2. Nó nói thật là không có gì để khôi phục.
3/ Update theo 3 bước ✅
Thứ tự này lấy nguyên từ hướng dẫn migration chính thức của v3:
Bước 1: update CLI
ak self-update --channel stable --yesMuốn update luôn app desktop thì thêm --include-desktop:
ak self-update --channel stable --include-desktop --yesBước 2: refresh kit trong từng project
ak update /duong/dan/toi/project --yesNếu bạn có cài kit global (cho mọi project), refresh luôn:
ak update --global --yesLưu ý nhỏ: máy không có kit global thì lệnh này exit 2. Không phải lỗi, chỉ là "hổng có gì để update".
Bước 3: kiểm tra
ak versions
ak licenses
ak doctor --jsonXong. Mở Claude Code lên gõ /ak- là thấy danh sách skill theo tên mới ak-<slug> (thay cho ak:<slug> của v2). Codex thì gõ $ak-.
Khi update bị chặn vì license
Nếu bạn thấy lỗi renewal_required (exit 15), nghĩa là bản bạn xin vượt quá cửa sổ cập nhật của license. Kit hiện tại vẫn chạy bình thường, không có gì bị khoá. Chi tiết chính sách ở bài 3.
4/ Bật auto-update (tuỳ chọn) ✅ opt-in
Mặc định ak không tự update sau lưng bạn. Muốn bật thì phải đăng ký project trước, rồi đặt lịch:
ak projects add /duong/dan/toi/project
ak update --schedule daily --project /duong/dan/toi/projectCó daily, weekly và off. Xem trạng thái và đánh dấu đã đọc kết quả:
ak update --status
ak update --ack
Còn app desktop tự kiểm tra và tải bản mới thì bật riêng (ghi vào ~/.agentkit/config.yaml, tắt bằng --disable-auto-update):
ak self-update --enable-auto-updateKhi nào auto-update tự tắt?
Có biến môi trường
CI(chạy trong GitHub Actions, GitLab CI...) thì auto-update không chạy. Hợp lý, không ai muốn pipeline tự đổi version giữa chừng.Đặt
AK_NO_AUTO_UPDATE=1để tắt hẳn trên máy.Sau khi bạn
ak rollback --to v2, mọi đường update lên v3 bị đóng băng (--checkvà--dry-runsẽ báorollback-hold), cho tới khi bạn chủ động chạy lạiak update --ssot.
5/ Rollback về v2 ✅
Nếu v3 làm bạn khó chịu (tui mong là hổng có, nhưng phải tính), thì:
ak rollback --to v2 --dry-runĐọc kỹ kế hoạch, thấy ổn thì chạy thật:
ak rollback --to v2Mấy cờ hữu ích:
| Cờ | Tác dụng |
|---|---|
--dry-run |
Chỉ xem kế hoạch, không ghi gì |
--install-v2 |
Cài lại CLI v2 luôn |
--with-desktop |
Rollback cả app desktop |
--checkpoint <id> |
Chọn đúng checkpoint (xem ID bằng ak backups list) |
--skip-secrets |
Không đụng tới vault secret |
Rollback có journal ở ~/.agentkit/backups/rollback/journal.json, nên bị ngắt giữa chừng thì chạy lại là nó đi tiếp.
Trường hợp đặc biệt: nếu bạn đã chạy ak update --ssot hai lần ở hai scope khác nhau (ví dụ global trước, project sau), checkpoint lần thứ hai đã mang layout mới. Rollback sẽ từ chối checkpoint đó. Bạn phải chỉ đúng checkpoint đầu tiên:
ak backups list
ak rollback --to v2 --checkpoint <id-checkpoint-dau-tien>Cài thẳng v2 khi không còn gì để khôi phục:
curl -fsSL https://agentkit.best/install.sh | AK_VERSION=2.19.0 shWindows:
$env:AK_VERSION = "2.19.0"
irm https://agentkit.best/install.ps1 | iex(ak self-update chỉ đi tới, không đi lùi, nên muốn về v2 phải dùng installer pin version.)
6/ Gỡ rối: mấy lỗi tui gặp thật
"Error: Command failed." mà không nói gì thêm
Đây là điểm tui tự thấy kỳ nhất của bản 3.0.0. Gõ sai tên lệnh hoặc gọi lệnh cần đăng nhập khi chưa login, bạn có thể chỉ nhận được một dòng cụt lủn. Cách xem lý do thật:
ak <lenh-cua-ban> --verbose
Đã ghi vào báo cáo gap.
ak doctor báo "update state unknown" nhưng ak versions nói đã mới nhất
Hai lệnh đọc hai nguồn trạng thái khác nhau. Tin ak versions cho câu hỏi "tui có đang ở bản mới nhất không". Doctor sẽ hết "unknown" sau lần ak update đầu tiên ghi state.
Kiểm tra network "OK" nhưng thực ra là 404
Doctor hiện tính "server có trả lời" là OK, kể cả trả về 404. Nếu bạn nghi mạng có vấn đề, thử thẳng:
ak self-update --checkLệnh này phải gọi registry thật, nên lỗi mạng sẽ lộ ra rõ hơn.
Cảnh báo shim ck va chạm
Máy từng cài ClaudeKit có thể còn lệnh ck cũ trên PATH. Doctor sẽ cảnh báo. Không nguy hiểm, nhưng nên dọn bằng ak migrate để tránh gõ nhầm.
Chưa đăng nhập mà ak licenses vẫn "[OK]"
Bản 3.0.0 có thể in [OK] trống trơn khi bạn chưa login. Đừng tin dòng đó, kiểm tra bằng:
ak whoami
ak login --email ban@example.comVẫn kẹt?
Gửi report kèm chẩn đoán đã redact:
ak feedback --type bug --title "Mo ta ngan" --attach-diagnostics --export feedback.mdĐọc file feedback.md trước, thấy ổn thì gửi thật (bỏ --export).
Checklist 1 phút
ak versionsvàak doctorchạy đượcak update <project> --yescho từng projectak update --global --yesnếu có kit globalak versions,ak licenses,ak doctor --jsonkhông còn lỗi(Tuỳ chọn) bật
--schedule daily
Bài tiếp: License và chính sách cập nhật mới →
Nguồn
Hướng dẫn migration v2 → v3:
agentkit/docs/guides/v2-to-v3-migration.md(tagv3.0.0), mục "Upgrade steps", "SSOT upgrade", rollbackak update --help,ak self-update --help,ak rollback --help,ak backups --help,ak migrate --help(ak 3.0.0)Output thật:
ak doctor,ak versions,ak update --status,ak rollback --to v2 --dry-runchạy trong HOME tạm, 02/11/2026GitHub release
v3.0.0: https://github.com/bestagentkits/agentkit/releases/tag/v3.0.0