
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.

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.

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.

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.

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.

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.

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.

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 |

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:

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
- Installation · Your First Company · Your First Agent
- Codex Adapter · Claude Code Adapter · Projects
- Execution Policy · Issues · Debug a Stuck Heartbeat
- OpenAI Codex Authentication · Claude plan với claude -p
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.
Vui lòng đăng nhập để bình luận.