Cài đặt

Sau trang này, lệnh ak sẽ hoạt động trong terminal và sẵn sàng cho bước thiết lập đầu tiên.

Môi trường được hỗ trợ

AgentKit phát hành bản 64-bit cho:

Hook của Kit chạy trên Node.js, nên ak cần Node.js 20.11 trở lên trên máy. ak tìm Node từ PATH trước, sau đó tới các vị trí cài đặt tiêu chuẩn của nền tảng, nên bản Node có sẵn thường không cần cấu hình gì. Khi không tìm được bản Node.js phù hợp, ak báo rõ và đề nghị cài Node.js LTS qua package manager mà nó phát hiện — winget, choco hoặc scoop trên Windows, brew trên macOS, và apt, dnf, pacman hoặc snap trên Linux.

Việc cài đó không bao giờ tự chạy: nó luôn cần bạn đồng ý tường minh, kể cả trong CI — nơi bạn cấp quyền bằng AK_AUTO_INSTALL_NODE=1. Không có consent, ak báo lỗi kèm lệnh cài thủ công cho package manager của bạn thay vì tiếp tục. Sau khi cài, ak kiểm tra lại version vừa resolve so với mức tối thiểu 20.11 chứ không tin rằng package manager đã cung cấp bản đủ mới.

Bạn cũng cần cài và đăng nhập một runtime lập trình được hỗ trợ trước khi chạy Skill của Kit trong runtime đó. Các target registry đã phát hành gồm Claude Code, Codex, Cursor, DeepSeek Harness (dsh), Grok, Pi (pi) và Oh My Pi (omp). Pi, DeepSeek Harness, Grok và Oh My Pi là target projection Kit có thể cài; DeepSeek Harness, Grok và Oh My Pi còn hỗ trợ dispatch Skill trực tiếp qua ak run --target dsh, ak run --target grok và ak run --target omp. Registry cũng phát hành package cloud-harness chỉ dùng để phân phối cho Cloud Harness MCP harness; đó không phải target cài đặt cục bộ. Xác thực tài khoản AgentKit là một bước riêng.

Cài CLI

curl -fsSL https://agentkit.best/install.sh | sh

irm https://agentkit.best/install.ps1 | iex

Cả hai lệnh đều cài từ kênh stable trừ khi bạn đặt AK_CHANNEL. Từ Windows cmd.exe, gọi cùng trình cài đặt PowerShell bằng:

powershell -NoProfile -Command "irm https://agentkit.best/install.ps1 | iex"

Trình cài đặt xác minh bản phát hành như thế nào

Trình cài đặt chính thức từ chối tải xuống chưa được xác minh. Với kênh đã được ghim trong trình cài đặt, nó đối chiếu kích thước byte và SHA-256 của archive với giá trị bất biến đi kèm trình cài đặt. Với một phiên bản cụ thể, release base tùy chỉnh hoặc lựa chọn chưa được ghim khác, nó dùng verifier đã ghim hash để xác thực metadata kênh và bản phát hành đã ký, rồi kiểm tra archive đã chọn trước khi trả về dữ liệu.

Nếu chỉ domain chính bị lọc, hãy thử lại entry point chính thức có nội dung giống hệt mà không thay đổi chuỗi xác minh:

curl -fsSL https://releases.agentkit.best/install.sh | sh

irm https://releases.agentkit.best/install.ps1 | iex

Nếu cùng object vẫn bị chặn, hãy giữ endpoint protection hoạt động và nhờ quản trị viên xem xét việc từ chối.

Xác minh cài đặt

Mở terminal mới nếu trình cài đặt đã đổi PATH, rồi chạy:

ak --version
ak doctor --json

Bạn sẽ thấy phiên bản đã cài. Trong kết quả doctor, hãy kiểm tra data.healthy; một lần chạy hoàn tất của ak doctor --json thường trả exit code 0 ngay cả khi một health check thất bại. Dùng ak doctor --exit-on-fail khi exit code của process phải làm gate cho script. Nếu không tìm thấy ak, hãy thêm thư mục cài đặt được báo vào PATH và khởi động lại terminal.

Chọn kênh phát hành khác

Kênh mặc định là stable. Để chọn bản beta được ghim sẵn trong trình cài đặt qua cùng quy trình đã xác minh:

curl -fsSL https://agentkit.best/install.sh | AK_CHANNEL=beta sh

$env:AK_CHANNEL = 'beta'; irm https://agentkit.best/install.ps1 | iex

Pin Beta được nhúng vào installer khi installer được phát hành, nên có thể chậm hơn bản Beta mới nhất. Để xem pin hiện tại trước khi chạy installer, hãy đọc nó từ script đang được phục vụ:

curl -fsSL https://agentkit.best/install.sh | grep -A4 'channel_pin_version()'

(irm https://agentkit.best/install.ps1) -split "`n" | Select-String -Context 0,5 'function Get-ChannelPinVersion'

Mục beta là phiên bản installer sẽ chọn. AK_VERSION ghim một phiên bản semantic, còn AK_INSTALL_DIR đổi thư mục đích. Hãy để cả hai chưa đặt nếu bạn không cần quyền kiểm soát này.

Chạy thiết lập lần đầu

ak onboard

ak onboard chạy setup nếu cần, đăng nhập trên TTY, xác nhận kit và runtime trừ khi bạn đã truyền --kit hoặc --target, rồi cài một kit. Lệnh này không thay ak setup cho các lần sửa tuỳ chọn sau. Tiếp tục với Làm quen để xem phương thức đăng nhập, target kit và khôi phục.

ak setup

Setup phát hiện trạng thái đăng nhập của các runtime hiện có và cập nhật ~/.agentkit/config.yaml theo cách nguyên tử. Thiết lập cơ bản cấu hình adapter đang bật và kit mặc định mà không sao chép credential của runtime. Lệnh này không đăng nhập tài khoản AgentKit, không cài nội dung kit và giữ nguyên lựa chọn telemetry đã lưu. Telemetry tắt mặc định; hãy bật bằng ak setup --step telemetry.

Cập nhật hoặc gỡ AgentKit an toàn

Dùng ak self-update --check để kiểm tra CLI mới hơn mà chưa áp dụng. Xem Cập nhật ak trước khi đổi kênh hoặc cập nhật bản cài hiện có.

Trước khi gỡ bất cứ thứ gì, hãy xem trước thao tác dọn dẹp được quản lý tương ứng với nội dung bạn đã cài:

ak kit uninstall engineer --dry-run
ak uninstall --dry-run

Lệnh đầu xem trước việc gỡ Engineer Kit. Lệnh thứ hai xem trước việc gỡ project được AgentKit quản lý ở thư mục hiện tại; đây không phải lệnh gỡ CLI. Chỉ chạy lại lệnh phù hợp với --yes sau khi đã xem kế hoạch. Mặc định, cả hai đều giữ tệp không rõ nguồn gốc hoặc đã sửa và tạo snapshot cho các thay đổi được hỗ trợ trước khi xóa. Một lần xem trước hoàn tất sẽ trả exit code 3 theo thiết kế; thao tác gỡ được áp dụng thành công trả exit code 0.

Cuối cùng, chạy ak logout để xóa phiên CLI cục bộ trước. Thu hồi từ xa cho một phiên email có thể làm mới là best-effort, nên registry ngừng hoạt động không thể khiến máy vẫn đăng nhập cục bộ. Sau đó, chỉ xóa binary đã cài (~/.local/bin/ak hoặc %USERPROFILE%\bin\ak.exe). Đừng xóa toàn bộ ~/.agentkit hoặc %USERPROFILE%\.agentkit trừ khi bạn đã kiểm tra và không còn cần registry project, phiên thiết bị của ứng dụng, cache hay snapshot khôi phục bên trong.