Làm quen

Chạy conductor lần đầu, cài Engineer Kit và xác minh runtime lập trình.

Bạn hoàn tất onboarding khi trợ lý lập trình đã chọn nhận diện được một Skill của Engineer Kit trong project do bạn kiểm soát.

Trước khi bắt đầu

Bạn cần:

ak có trong PATH — xem Cài đặt.
Một runtime lập trình được hỗ trợ đã được cài và đăng nhập với provider riêng.
Tài khoản AgentKit có quyền sử dụng Engineer Kit.
Một project thử nghiệm nơi bạn có thể thêm cấu hình runtime.

Xác thực AgentKit cấp quyền truy cập các Kit có license. Nó không đăng nhập Claude Code, Codex, Cursor, DeepSeek Harness, Grok, Pi hoặc Oh My Pi vào provider, và đăng nhập runtime không cấp quyền sử dụng Kit AgentKit.

Chạy onboarding

Chuyển vào project sẽ nhận Kit, rồi chạy conductor:

cd /path/to/project
ak onboard

ak onboard chạy một pipeline có kiểm tra trạng thái:

Stage	Behavior
1. Setup	Khi thiếu `adapters.enabled` hoặc `kit.default`, chạy wizard trên TTY hoặc ghi mặc định cho script.
2. Channel	Chỉ điền `updates.channel` khi giá trị này trống. `--channel` tường minh chỉ áp dụng cho lần chạy này và không được lưu; `kit.channel` không bao giờ được ghi.
3. Scope	Resolve scope project hoặc global trước khi hỏi login.
4. Login	Skip phiên CLI có thể gia hạn; nếu thiếu thì cho chọn email OTP hoặc user API key trên TTY.
5. Kit	Skip khi đã có install receipt; nếu thiếu thì xác nhận kit và runtime trên TTY rồi cài.

Bước đã hoàn tất được báo là skipped, nên bạn có thể chạy lại lệnh sau lần đầu bị gián đoạn hoặc mới hoàn thành một phần. --yes chấp nhận prompt xác nhận nhưng không bao giờ trở thành --force.

Hãy chỉ định rõ Kit, runtime và kênh phát hành khi cần kết quả lặp lại được:

ak onboard --kit engineer --target codex --channel <channel>

Thay <channel> bằng kênh đang chọn trong header tài liệu. Thứ tự ưu tiên là stable hoặc beta được truyền rõ ràng, CLI published -beta, kit.channel đã lưu, rồi suy ra từ version (beta cho Beta CLI; stable cho development và Stable build). Giá trị không được hỗ trợ như nightly thoát 2 mà không đổi config.

Kit được chọn theo --kit, rồi kit.default, cuối cùng là engineer; default đã cấu hình là none cũng resolve thành engineer. Target được chọn theo --target, rồi adapter đầu tiên đang bật. Trên TTY, onboard xác nhận cả hai giá trị trước khi cài trừ khi --kit hoặc --target đã khoá trục đó. Chế độ không tương tác giữ các mặc định đó và thoát 2 nếu không resolve được target.

Mọi thư mục trừ home của user đều là scope project hợp lệ, kể cả folder mới, trống và chưa có .git hay .agentkit/ownership.json. Chạy từ home không phải scope project. Onboard cảnh báo, bảo bạn chuyển vào một project, rồi thoát 2. Dùng --project-dir hoặc --global thay vì chờ TTY đề nghị cài global:

ak onboard --global --kit engineer --target codex --channel <channel>

Nơi chạy	Behavior
Mọi thư mục trừ home của user	Dùng thư mục đó làm scope project và cài Kit vào đó.
Home của user trên TTY	Cảnh báo home không phải project, in lệnh tiếp theo, rồi thoát `2`. Không ghi tệp Kit project vào home.
Home của user không có TTY	Thoát `2` trước login và yêu cầu chuyển thư mục hoặc dùng `--global`.
`--global`	Bỏ kiểm tra project và cài Kit user-wide, kể cả khi chạy từ home.
`--project-dir <path>`	Dùng path đó thay thư mục hiện tại; home vẫn yêu cầu `--global`.

Stage	User mới	User đã dùng AgentKit
Setup	Chạy setup	Skip khi config cơ bản đã có
Login	Cho chọn email OTP hoặc user API key	Skip khi session có thể gia hạn
Kit	Cài route đã chọn	Skip receipt đã có; nếu chỉ thiếu receipt thì chỉ cài Kit

Email OTP là phương thức login mặc định trên TTY. --email <address> bỏ qua bước chọn phương thức và đi thẳng tới OTP. Lỗi xác thực khi cài tương tác sẽ kích hoạt login và thử cài lại một lần.

Dùng onboarding trong automation

Onboard không tương tác không thể thu credential mới. Hãy tạo phiên CLI trước, sau đó truyền đầy đủ các lựa chọn mà job phụ thuộc:

ak login --api-key ak_live_... --no-interactive
ak onboard \
  --no-interactive \
  --yes \
  --project-dir /path/to/project \
  --kit engineer \
  --target codex \
  --channel <channel>

Nếu chưa có phiên dùng được, onboard không tương tác thoát 2 thay vì mở prompt đăng nhập. Khi thiếu setup cơ bản, đường script dùng --kit hoặc engineer, --target hoặc claude-code, và tắt telemetry. Không đưa API key, OTP, license key, tệp phiên hoặc credential provider thật vào source control, ảnh chụp, diagnostics hay lịch sử shell dùng chung.

Khi nào dùng từng lệnh riêng

Trong lần dùng đầu, bạn thường không cần tự chạy riêng setup, login rồi cài Kit. Hãy dùng từng lệnh khi cần thay đổi hoặc khôi phục một lớp mà không chạy lại toàn bộ conductor:

Lệnh	Dùng khi
`ak setup`	Đổi adapter, Kit mặc định, telemetry hoặc tuỳ chọn provider/model nâng cao sau onboarding
`ak login`	Đổi tài khoản AgentKit, rotate user API key, khôi phục xác thực hoặc tạo phiên trước automation
`ak kit init`	Cài một route Kit cụ thể khi cấu hình và xác thực đã ở trạng thái tốt
`ak init`	Yêu cầu AgentKit tiếp nhận và theo dõi toàn bộ project hiện có, gồm ownership manifest và đường dẫn docs/plan tuỳ chỉnh

Các lệnh này vẫn thuộc CLI contract, nhưng là đường hỗ trợ chứ không phải các bước onboarding bổ sung.

Xác minh kết quả

Xác nhận tài khoản AgentKit, quyền dùng Kit và tình trạng cài đặt cục bộ:

ak whoami
ak licenses
ak doctor --exit-on-fail

ak whoami thoát 0 ngay cả khi báo trạng thái chưa xác thực. Script phải kiểm tra kết quả thay vì xem exit code bằng không là bằng chứng đã đăng nhập. Chỉ tiếp tục khi ak licenses liệt kê Engineer Kit và doctor không báo lỗi chặn.

Khởi động lại trợ lý hoặc mở phiên mới để nạp nội dung đã cài, rồi gọi một Skill:

/ak:cook Add a health-check endpoint

$ak:cook Add a health-check endpoint

Với Cursor, Grok Build và Pi, dùng surface discovery và invocation hiện tại của runtime đó. Với DeepSeek Harness, dùng discovery surface hiện tại hoặc tuyến dispatch cục bộ one-shot ak run engineer/scout --target dsh; không đưa secret vào prompt dispatch này vì nó đi qua process argument. Onboarding hoàn tất khi trợ lý nhận diện Skill, đọc yêu cầu và bắt đầu workflow trong project hiện tại.

Khôi phục và lỗi thường gặp

Chưa có phiên AgentKit: chạy lại ak onboard trên TTY, hoặc dùng một phương thức ak login rõ ràng.
Engineer Kit không có trong ak licenses: đăng nhập bằng tài khoản sở hữu Kit. Cài lại không thể tạo quyền còn thiếu.
Runtime chưa có hoặc đã logout: cài hoặc đăng nhập runtime đó bằng tài khoản provider, rồi chạy lại onboard.
Skill không được nhận diện: xác nhận install summary ghi đúng target, khởi động lại trợ lý và chạy ak doctor --exit-on-fail trước khi cài lại.
Cảnh báo channel_drift: đặt giá trị updates.channel và kit.channel đã lưu về cùng một kênh. ak onboard --channel chỉ áp dụng cho một lần chạy và không thay đổi giá trị nào.
Runtime đã có tệp: trên TTY, onboard có thể hỏi ghi đè các đường dẫn collision của AgentKit và thử lại một lần với --force. Tệp tuỳ chỉnh không thuộc AgentKit được giữ. --yes và chế độ không tương tác không tự bật force; huỷ thoát 3.

Để xem chi tiết scope Kit, tương thích target, refresh, uninstall và khôi phục, đọc Cài đặt Kit. Nếu không, hãy tiếp tục với Khởi động nhanh.