Ảnh bìa phần 2

Hình 1. Một đội AI nhỏ: phân tích, sửa lỗi và kiểm tra kết quả.

Ở Phần 1, ta đã có một bug rõ ràng (bộ lọc “Đang xử lý” bị mất khi chuyển trang) và một cách phân vai CEO – Developer – QA. Bài này biến nó thành quy trình chạy thật trong khoảng 60–90 phút: cài Paperclip, kết nối CLI, tạo đội, giao ticket và nghiệm thu.

Bạn sẽ có sau bài này: một company trong Paperclip với 3 agent, một task đi qua đủ các bước sửa → review → phê duyệt, và bằng chứng (commit, kết quả test) để kiểm tra.

Trước khi bắt đầu

Cần có Ghi chú
Node.js 24.11.0 trở lên Kiểm tra bằng node –version
pnpm Bật qua Corepack (lệnh ở Bước 1)
Git + repo thử nghiệm Repo có README hướng dẫn chạy app và chạy test
Codex CLI hoặc Claude Code CLI Đã cài, chạy được từ terminal
Máy/VM riêng cho thử nghiệm Agent sẽ chạy lệnh trực tiếp trên máy này — xem cảnh báo ở Bước 4

⚠️ Không dùng repo production và không để credential production (SSH key deploy, token cloud…) trên máy chạy agent trong lần thử đầu.

Sáu bước kết nối CLI và giao ticket

Hình 2. Tổng quan sáu chặng của bài: cài môi trường và repo (Bước 1, 4) → đăng nhập CLI (Bước 2) → chọn adapter (Bước 3) → kiểm tra (Bước 5) → giao ticket (Bước 6–7) → nghiệm thu (Bước 8).

Bước 1. Cài và khởi động Paperclip

Chạy bằng tài khoản người dùng thường — không dùng sudo hay terminal Administrator, vì PostgreSQL nhúng sẽ từ chối chạy dưới quyền quản trị.

node –version # phải >= v24.11.0
corepack enable
corepack prepare pnpm@latest –activate
npx paperclipai onboard –yes

–yes nhận toàn bộ cấu hình mặc định (CSDL PostgreSQL nhúng, lưu trữ trên đĩa). Bỏ –yes nếu muốn tự chọn chế độ triển khai, CSDL và lưu trữ. Những lần sau, khởi động lại bằng npx paperclipai run.

✅ Kết quả mong đợi: terminal in địa chỉ giao diện, mặc định http://localhost:3100, và trình duyệt mở được trang Paperclip.

Dữ liệu nằm ở ~/.paperclip/instances/default/. Hãy sao lưu ngay file secrets/master.key trong thư mục đó — nó mã hóa mọi API key bạn lưu trong Paperclip; mất file là mất các secret.

Nếu onboarding lỗi ở bước CSDL, sửa lỗi đó trước (xem mục Xử lý sự cố của trang Installation, ví dụ máy Mac Apple Silicon có thể cần tạo symlink thư viện libzstd/liblz4). Đừng sang bước sau khi Paperclip chưa chạy ổn.

Bước 2. Đăng nhập CLI

Đăng nhập trên chính máy sẽ chạy agent (máy cài Paperclip), không phải máy bạn mở trình duyệt.

Codex CLI

codex login # đăng nhập bằng ChatGPT qua trình duyệt
codex login status # xem đang dùng ChatGPT hay API key

Adapter codex_local mặc định kế thừa phiên đăng nhập Codex của máy host. Nếu agent có cấu hình API key riêng (ví dụ biến OPENAI_API_KEY), API key sẽ được ưu tiên và bạn bị tính phí theo token. Kiểm tra mục xác thực của agent để biết chắc mình đang chạy bằng gì.

Claude Code CLI

claude # mở Claude Code
/login # đăng nhập bằng tài khoản Claude

Adapter claude_local nhận xác thực qua đăng nhập subscription, ANTHROPIC_API_KEY hoặc Bedrock. Khi đăng nhập bằng gói Claude, các lượt chạy headless (claude -p) dùng hạn mức của gói.

⚠️ Nhắc lại từ Phần 1: dùng subscription phù hợp cho thử nghiệm cá nhân trên tài khoản của bạn. Khi chạy cho nhóm hoặc chạy liên tục, chuyển sang API key / gói doanh nghiệp theo khuyến nghị và điều khoản của nhà cung cấp.

Bước 3. Tạo company, mục tiêu và đội agent

1. Tạo company (giao diện gọi là organization) tên Ticket Maintenance Lab.

Màn hình tạo organization

Hình 3. Màn hình đầu tiên khi tạo company — giao diện gọi là organization. (Ảnh: tài liệu chính thức Paperclip)

2. Vào Goals, thêm mục tiêu: “Sửa lỗi mất bộ lọc khi phân trang, có test hồi quy và được người phụ trách nghiệm thu”. (Phiên bản hiện tại không hỏi goal khi tạo company; bạn thêm sau.)

3. Tạo agent đầu tiên — Paperclip tự đặt agent này là CEO. Chọn adapter claude_local hoặc codex_local.

Chọn adapter cho agent

Hình 4. Bước chọn adapter khi tạo agent: Claude Code, Codex, Cursor, Gemini CLI… (Ảnh: tài liệu chính thức Paperclip)

4. Sau heartbeat đầu tiên, CEO sẽ đề xuất chiến lược và chờ bạn (với vai trò board) duyệt trong mục Approvals. Việc tuyển thêm agent cũng có thể cần duyệt. Nếu thấy agent “đứng im”, hãy kiểm tra Approvals trước.

Trang Approvals

Hình 5. Trang Approvals: yêu cầu tuyển agent và chiến lược của CEO chờ bạn bấm Approve hoặc Reject. (Ảnh: tài liệu chính thức Paperclip)

5. Tạo thêm hai agent Developer và QA, báo cáo cho CEO.

Chọn runner. Trên macOS và Linux (glibc 2.39+), agent mới có thể mặc định dùng Paperclip Runner — tính năng còn thử nghiệm. Bài này dùng đường CLI cổ điển: vào Advanced → Runner → Legacy runner; với Codex, đặt thêm engine = cli (mặc định auto sẽ chạy qua ACP).

Dán hướng dẫn (instructions) cho từng agent. Ba mẫu dưới đây đã thử viết cho ngắn, rõ, có quy tắc bàn giao:

[CEO – điều phối kỹ thuật]
Khi nhận báo lỗi: tái hiện, tìm file liên quan, nêu giả thuyết nguyên nhân
và hướng sửa. KHÔNG sửa code. Nếu không tái hiện được, ghi rõ đã thử gì
và cần thêm thông tin gì từ người phụ trách.

[Developer]
Chỉ sửa trong phạm vi task. Đọc quy ước của repo trước khi sửa.
Luôn bổ sung test hồi quy. Khi bàn giao, comment gồm: nhánh/commit,
file đã sửa, lệnh test đã chạy, kết quả thật (pass/fail), điểm chưa
xác minh được. Không merge, không deploy.

[QA]
Đối chiếu TỪNG tiêu chí nghiệm thu với đúng commit được bàn giao.
Chạy lại test. Ghi Đạt/Không đạt cho từng tiêu chí. Nếu không đạt:
nêu dữ liệu, các bước tái hiện, kết quả mong đợi và kết quả thực tế.
Thay đổi yêu cầu -> chuyển cho người phụ trách quyết định.

Bước 4. Gắn repo và khóa phạm vi làm việc

1. Tạo project Ticket App.

2. Trong tab Configuration → Codebase, bấm Set local folder và chọn thư mục repo trên máy chạy agent. Hoặc dùng Source repos → Add GitHub repo rồi Save changes.

Cấu hình project

Hình 6. Tab Configuration của project: thêm GitHub repo ở mục Source repos rồi Save changes. (Ảnh: tài liệu chính thức Paperclip)

3. Tạo một nhánh thử nghiệm sạch, chạy thử app và test bằng tay để chắc chắn chúng chạy được.

4. Lần đầu, cho các agent làm tuần tự trên một thư mục. Tính năng isolated workspace (mỗi task một checkout riêng) còn là thử nghiệm — để dành cho Phần 3.

⚠️ Quan trọng về quyền. Với claude_local, tùy chọn dangerouslySkipPermissions mặc định bật, vì Paperclip chạy Claude ở chế độ headless không có ai bấm xác nhận. Nghĩa là agent có thể chạy mọi lệnh mà tài khoản của bạn chạy được trên máy đó. Nếu tắt, các thao tác cần xin quyền sẽ đơn giản là không chạy. Trong giao diện, đây là mục Permission mode: Full auto (approve all) ở tab Harness / Runtime. Lựa chọn an toàn cho lần thử: để bật nhưng chạy trên máy/VM/container riêng, repo thử nghiệm, và bật branch protection để agent không thể push lên nhánh chính.

Cấu hình Harness / Runtime

Hình 7. Tab Harness / Runtime của agent Claude Code: Permission mode mặc định “Full auto (approve all)”. Ảnh mẫu đang dùng đường chạy ACP; với Legacy runner, một số trường có thể khác. (Ảnh: tài liệu chính thức Paperclip)

Bước 5. Chạy thử một task chỉ đọc

Trước khi cho sửa code, kiểm tra kết nối:

1. Mở từng agent, bấm Test Environment (hoặc Run test). Mục này kiểm tra lệnh CLI, xác thực và model. Chạy lại mỗi khi đổi model, adapter hay môi trường.

Test agent thành công

Hình 8. Kết quả kiểm tra kết nối thành công: “Connection successful”. (Ảnh: tài liệu chính thức Paperclip)

2. Giao CEO một task chỉ đọc:

Đọc README của repo. Báo lại: lệnh chạy app, lệnh chạy test, và đường dẫn
thư mục chứa màn hình danh sách ticket. Không thay đổi bất kỳ file nào.

✅ Kết quả mong đợi: agent comment đúng các lệnh có trong README và git status trên repo vẫn sạch. Nếu agent đọc sai repo hoặc bịa lệnh, sửa cấu hình project trước khi đi tiếp.

Bước 6. Phân tích, chốt phạm vi rồi giao sửa

1. Giao CEO task “Phân tích lỗi mất bộ lọc khi phân trang”. Đầu ra cần có: cách tái hiện, file xử lý phân trang/bộ lọc (agent tự tìm trong repo thật), hướng sửa.

2. Bạn đọc kết quả và chốt phạm vi. Ví dụ: “Chỉ sửa phía frontend, không đổi API”.

3. Tạo task triển khai, dán mẫu task từ Phần 1, đính kèm kết quả phân tích và giao cho Developer.

Bước 7. Bật review và phê duyệt trên task

Trong hộp tạo task (hoặc panel Properties của task có sẵn), bên cạnh ô Assignee có hai nút Reviewer và Approver:

Trường Chọn Tác dụng
Assignee Developer Người thực hiện
Reviewer QA Developer báo xong → task sang in_review và chờ QA, không đóng ngay
Approver Bạn Sau khi QA đạt, task chờ bạn duyệt

Reviewers và Approvers

Hình 9. Đặt Reviewers và Approvers trong nhóm EXECUTION của panel Properties. (Ảnh: tài liệu chính thức Paperclip)

Khi QA yêu cầu sửa, task tự quay về in_progress và giao lại cho Developer. Giới hạn số vòng bằng maxReviewRounds trong execution policy (mặc định 3, đặt 1–50). Hết số vòng, task được chuyển cho người phụ trách (người được gán chịu trách nhiệm, nếu không có thì người tạo task).

Một phản hồi QA tốt trông như sau: “Tiêu chí 1 KHÔNG ĐẠT: chọn ‘Đang xử lý’ → trang 2 → bấm Trang trước: bộ lọc mất. Mong đợi: vẫn giữ bộ lọc.” — cụ thể đến mức Developer sửa được ngay.

Bước 8. Nghiệm thu

Mở task để xem ai đang giữ việc, trạng thái và lịch sử trao đổi; mở Run history để xem từng lượt chạy đã làm gì. Trước khi bấm duyệt, tự kiểm tra checklist:

Run history

Hình 10. Danh sách lượt chạy (Runs): agent, trạng thái, loại kích hoạt và thời lượng — mở từng lượt để xem transcript. (Ảnh: tài liệu chính thức Paperclip)

  • Commit được QA kiểm tra trùng với commit Developer bàn giao.
  • Mỗi tiêu chí nghiệm thu đều có kết luận kèm bằng chứng.
  • Lệnh test và kết quả là đầu ra thật, không phải câu “test đã pass”.
  • Bạn tự chạy lại test ít nhất một lần.

Duyệt task xong, bạn mới merge và deploy theo quy trình của repo. Đóng task và đưa lên production là hai quyết định riêng.

Xử lý sự cố thường gặp

Nguyên tắc: đọc Run history trước, sửa cấu hình sau.

Dấu hiệu Nguyên nhân thường gặp Cách xử lý
Không tìm thấy CLI PATH của tiến trình Paperclip khác terminal của bạn Trỏ đúng đường dẫn CLI, chạy lại Test Environment
Lỗi xác thực / model bị từ chối Hết phiên đăng nhập, sai chế độ auth, model không có trong gói codex login status hoặc /login lại; chọn model gói hỗ trợ
Checkout trả về 409 Conflict Task đang bị agent khác giữ Kiểm tra ai đang giữ task; tách việc thay vì cho hai agent cùng làm
Lượt chạy thoát với mã 143 Timeout hoặc hết bộ nhớ Chia nhỏ task, giảm ngữ cảnh trước khi tăng timeout
Task chuyển retry_exhausted Agent chạy mà không để lại comment Thêm yêu cầu “luôn comment kết quả” vào instructions
Agent đứng im sau khi tạo Đang chờ Approval, hoặc timer heartbeat tắt và chưa được giao việc Duyệt trong Approvals; giao task hoặc bấm Run now
Agent đọc sai code Project trỏ sai thư mục Sửa Codebase rồi chạy lại task chỉ đọc

Kiểm tra cuối bài

Thử nghiệm đạt khi bạn trả lời được trọn vẹn: task giao cho ai; CLI dùng tài khoản/model nào; bản sửa ở commit nào; test nào đã chạy; ai duyệt kết quả. Nếu dùng subscription, ghi lại mức sử dụng trước và sau đợt thử — đây là dữ liệu đầu vào cho Phần 3.

Nếu chưa trả lời được một câu nào đó, hãy làm rõ quy trình trước khi thêm agent. Phần 3 bàn về vận hành nhiều ticket: theo dõi gì, tối ưu hạn mức ra sao và khi nào nên mở rộng.

Tài liệu tham khảo

Hướng dẫn đối chiếu với tài liệu chính thức ngày 13/11/2026; tên nút và mặc định có thể đổi theo phiên bản. Lỗi bộ lọc là tình huống thực hành; Ảnh chụp giao diện lấy từ tài liệu chính thức docs.paperclip.ing (dữ liệu mẫu); sơ đồ và ảnh bìa là minh họa tạo bằng AI.

 

Guest