
Hình 1. Paperclip lo phần giao việc, theo dõi và nghiệm thu giữa các vai trò AI.
Tóm tắt nhanh. Paperclip là phần mềm mã nguồn mở (MIT) để quản lý nhiều AI agent như quản lý một nhóm: ai làm việc gì, đang ở trạng thái nào, ai review, ai duyệt, tốn bao nhiêu. Nó không phải là AI — việc viết code vẫn do Claude Code, Codex CLI… đảm nhận. Bài này giúp bạn quyết định có nên thử Paperclip không, và nếu thử thì bắt đầu từ đâu.
Vấn đề Paperclip giải quyết
Hôm nay trong nhóm bạn: một developer nhờ AI tìm nguyên nhân bug, một người khác nhờ AI viết test, tech lead nhờ AI review trước khi merge. Mỗi việc đều nhanh hơn — nhưng người vẫn phải chép ngữ cảnh từ cửa sổ chat này sang cửa sổ khác, nhắc lại yêu cầu và tự nhớ việc nào đã xong.
Khi số agent tăng, câu hỏi khó nhất không còn là “viết prompt thế nào” mà là “tổ chức công việc ra sao”:
- Kết quả phân tích của agent A nằm ở đâu để agent B dùng tiếp?
- Ai chịu trách nhiệm sửa, ai xác nhận test đã chạy thật?
- Hai agent trả việc qua lại mãi thì lúc nào con người phải vào cuộc?
- Cả đội AI đã tiêu bao nhiêu tiền / bao nhiêu hạn mức?
Paperclip trả lời đúng nhóm câu hỏi này. Nếu nhóm bạn chưa gặp chúng — ví dụ chỉ một người dùng một agent và tự kiểm tra kết quả — thì chưa cần Paperclip. Chính trang giới thiệu sản phẩm cũng nói giá trị của lớp điều phối tăng lên khi nhiều agent chia sẻ công việc, ngân sách hoặc người review.
Paperclip đứng ở đâu
Hãy hình dung hai tầng:
| Tầng | Ai đảm nhận | Ví dụ |
|---|---|---|
| Điều phối | Paperclip | Tạo task, giao cho agent, chuyển sang review, chờ duyệt, ghi chi phí |
| Thực thi | Runtime của agent (Claude Code, Codex CLI…) | Đọc repo, sửa code, chạy test, tạo commit |
Paperclip nối với runtime qua adapter — ví dụ claude_local chạy Claude Code CLI, codex_local chạy Codex CLI ngay trên máy cài Paperclip. Hệ quả quan trọng: muốn agent đọc repo hay chạy test, máy đó phải có sẵn repo, công cụ và quyền tương ứng. Paperclip không tự cấp những thứ này.

Hình 2. Con người đặt mục tiêu, Paperclip điều phối, CLI thực thi và trả lại trạng thái cùng bằng chứng.
Bảy khái niệm cần nắm
Tài liệu Key Concepts của Paperclip xoay quanh bảy khái niệm. Nắm được chúng là đọc được mọi màn hình trong ứng dụng:
| Khái niệm | Hiểu đơn giản |
|---|---|
| Company | “Công ty ảo” chứa mục tiêu, agent, công việc và ngân sách. Có thể chạy nhiều company song song. |
| Agent | Một “nhân viên AI”: có vai trò, hướng dẫn, adapter và cấp trên. Agent đầu tiên luôn là CEO. |
| Task (Issue) | Đơn vị công việc có người phụ trách và trạng thái: backlog → todo → in_progress → in_review → done (ngoài ra có blocked, cancelled). |
| Heartbeat | Một lượt agent được “đánh thức” để làm việc. |
| Adapter | Cầu nối tới runtime thực thi (Claude Code, Codex…). |
| Budget | Giới hạn chi tiêu theo tháng cho company, agent; project cũng có thể có ngân sách. |
| Approval | Những quyết định cần con người duyệt: chiến lược của CEO, tuyển agent mới, vượt ngân sách. |
Ngoài ra còn Goal (mục tiêu của company) và Project (nhóm task gắn với một repo/thư mục) — bạn sẽ dùng chúng ở Phần 2.

Hình 3. Inbox gom task của bạn và các quyết định chờ duyệt (Hire Agent, CEO Strategy, Budget Override) với nút Approve/Reject. (Ảnh: tài liệu chính thức Paperclip)
Về heartbeat, agent được đánh thức khi: có lịch hẹn (timer — mặc định tắt với agent mới), được giao task, có comment mới trên task, bấm Run now, hoặc một approval được xử lý. Mỗi lượt chạy trên task phải để lại comment; tiến độ được lưu trên task chứ không nằm trong một cuộc chat.
⚠️ Đặt tên agent là “Developer” mới chỉ là cái nhãn. Để nó làm được việc, bạn còn phải cấu hình hướng dẫn (instructions), adapter, quyền và mẫu báo cáo đầu ra.
Thử trên một bug có phạm vi rõ
Cách tốt nhất để đánh giá Paperclip là chạy một luồng nhỏ, đo được. Xuyên suốt loạt bài, ta dùng một bug giả định trong ứng dụng quản lý ticket:
Chọn bộ lọc trạng thái “Đang xử lý” thì trang 1 hiển thị đúng. Sang trang 2, bộ lọc biến mất và danh sách quay về toàn bộ ticket.
Bug này phù hợp vì tái hiện được, phạm vi nhỏ và có tiêu chí đúng/sai rõ ràng. Lưu ý: đây là tình huống minh họa, không phải số liệu từ một dự án đã triển khai.
Phân vai theo đầu ra
Nguyên tắc: mỗi vai trò phải giao lại một thứ người khác kiểm tra được, không phải câu “đã xong”.
| Vai trò | Việc chính | Đầu ra bàn giao |
|---|---|---|
| CEO agent (đóng vai Tech Lead) | Đọc báo lỗi, khoanh vùng, đề xuất hướng sửa | Cách tái hiện, file liên quan, giả thuyết nguyên nhân |
| Developer agent | Sửa trong phạm vi đã chốt, viết test hồi quy | Commit/nhánh, lệnh test và kết quả thật |
| QA agent | Đối chiếu từng tiêu chí nghiệm thu với bản sửa | Đạt/không đạt theo từng tiêu chí, bước tái hiện nếu lỗi |
| Người phụ trách | Chốt phạm vi, duyệt cuối, merge/deploy | Quyết định chấp nhận hoặc yêu cầu sửa |
Vì sao CEO lại làm Tech Lead? Paperclip bắt buộc agent đầu tiên của company là CEO. Trong thử nghiệm nhỏ, giao luôn việc phân tích kỹ thuật cho CEO là cách gọn nhất, không cần thêm một agent.

Hình 4. Sơ đồ tổ chức trong Paperclip: CEO ở trên cùng, các agent (kỹ sư, QA…) báo cáo theo cấp; mỗi thẻ ghi vai trò và adapter. (Ảnh: tài liệu chính thức Paperclip)
Luồng bàn giao

Hình 5. Luồng xử lý bug đề xuất. Bước “Phân tích” do CEO agent đảm nhận vai Tech Lead; QA có thể trả việc về Developer trước khi con người phê duyệt.
1. Người phụ trách tạo task kèm báo lỗi và tiêu chí nghiệm thu.
2. CEO agent phân tích, người phụ trách chốt phạm vi.
3. Developer agent sửa và báo “xong” → task chuyển sang in_review thay vì đóng ngay.
4. QA agent kiểm tra. Không đạt → task tự quay về Developer kèm nhận xét. Đạt → chuyển sang bước duyệt.
5. Người phụ trách xem bằng chứng và phê duyệt.
Bước 3–4 không tự xảy ra chỉ vì bạn có một agent tên “QA”. Nó đến từ tính năng Execution Policy: trên mỗi task, bạn gán Reviewer và Approver. Execution Policy còn có maxReviewRounds (mặc định 3): sau số vòng agent trả việc qua lại liên tiếp, task được chuyển cho người phụ trách thay vì lặp mãi.

Hình 6. Panel Properties của task: nhóm EXECUTION có Reviewers và Approvers — nơi bật luồng review và phê duyệt. (Ảnh: tài liệu chính thức Paperclip)

Hình 7. Một task có thể cần nhiều heartbeat; review và phê duyệt là các giai đoạn riêng theo policy.
Mẫu task dùng được ngay
Sao chép mẫu dưới, thay nội dung của bạn, rồi dán vào mô tả task trong Paperclip:
Tiêu đề: Giữ bộ lọc trạng thái khi chuyển trang trong danh sách ticket
Bối cảnh: Chọn trạng thái “Đang xử lý” rồi sang trang 2 thì bộ lọc mất.
Đầu vào: repo thử nghiệm, README (cách chạy app + test), dữ liệu tái hiện.
Phạm vi: luồng phân trang và bộ lọc ở màn danh sách.
Cần đổi API/cấu trúc dữ liệu -> hỏi người phụ trách trước.
Tiêu chí nghiệm thu:
[ ] Giữ bộ lọc khi sang trang sau hoặc quay lại trang trước
[ ] Đổi bộ lọc -> quay về trang 1 của kết quả mới
[ ] Xóa bộ lọc -> danh sách về mặc định
[ ] Có test hồi quy theo quy ước của repo
Bàn giao bắt buộc: commit/nhánh, lệnh test đã chạy + kết quả thật,
điểm chưa xác minh được.
Giới hạn: chỉ làm trên nhánh thử nghiệm; merge/deploy do người phụ trách.
Phần đáng giá nhất của mẫu là tiêu chí nghiệm thu và bàn giao bắt buộc: chúng biến “AI bảo xong” thành “có bằng chứng để kiểm tra”.
Ba quyết định trước lần chạy đầu tiên
1. Quyền truy cập: cấp đúng, không cấp thừa
Developer cần đọc/sửa code trên môi trường thử nghiệm; QA cần chạy test trên đúng bản sửa. Quyền thực sự nằm ở runtime và máy chạy agent. Lưu ý: kiểm soát kiểu “hỏi trước khi dùng tool” của Paperclip chỉ áp dụng cho lệnh đi qua tool gateway của nó — lệnh shell, git, gh mà agent chạy trực tiếp thì không bị chặn. Vì vậy, chặn merge/deploy bằng branch protection ở repository và quyền ở hệ thống triển khai, đừng chỉ dựa vào lời dặn trong prompt.
2. Chi phí: subscription hay API key?
Hai adapter đều chạy được bằng tài khoản subscription (ChatGPT cho Codex, gói Claude cho Claude Code) hoặc bằng API key tính tiền theo token.
| Cách | Ưu điểm | Cần lưu ý |
|---|---|---|
| Subscription | Tận dụng gói sẵn có, không phát sinh hóa đơn theo token | Có hạn mức theo gói; Paperclip ghi chi phí lượt chạy là $0 nên ngân sách hard-stop không chặn được; nhà cung cấp khuyến nghị API key cho tự động hóa |
| API key | Phù hợp tự động hóa, ngân sách Paperclip đo được theo USD | Tốn tiền theo token; cần đặt ngân sách và kiểm tra hard-stop |
⚠️ Về điều khoản sử dụng. Tài liệu Codex của OpenAI ghi rõ API key là lựa chọn được khuyến nghị cho các luồng tự động như CI/CD. Anthropic cho biết claude -p đăng nhập bằng gói Claude sẽ dùng hạn mức của gói. Vì vậy subscription hợp lý cho thử nghiệm cá nhân, trên tài khoản của chính bạn. Khi đưa vào dùng chung cho nhóm hoặc chạy liên tục, hãy chuyển sang API key hoặc gói doanh nghiệp và đọc điều khoản của nhà cung cấp — đừng dùng chung một tài khoản cá nhân cho cả nhóm.
Để đọc chi phí đúng, tính: phí thuê bao phân bổ + phí API phát sinh + hạ tầng, rồi chia cho số ticket được nghiệm thu (không phải số ticket đã chạy). Với subscription, theo dõi thêm hạn mức ở trang usage của nhà cung cấp, vì Paperclip sẽ hiển thị $0.
Bốn thói quen giúp tiết kiệm hạn mức ngay từ đầu:
1. Một CLI trước. Chỉ thêm nhà cung cấp thứ hai khi có lý do so sánh rõ ràng.
2. Đánh thức theo sự kiện. Giữ timer heartbeat tắt (mặc định); chỉ dùng lịch cho việc thật sự định kỳ.
3. Ngữ cảnh gọn. Chỉ ra file liên quan và tiêu chí rõ thay vì để agent đọc cả repo.
4. Giới hạn vòng lặp. Giữ maxReviewRounds thấp (2–3); hết hạn mức thì dừng, không tự động chuyển sang API.
3. Khi nào con người phải quyết định
Yêu cầu agent dừng và hỏi khi: không tái hiện được lỗi, thiếu dữ liệu, hoặc yêu cầu mâu thuẫn với hành vi hiện tại. Một báo cáo vướng mắc tốt nói rõ thiếu gì và ai giải quyết được. Nếu Developer và QA bất đồng nhiều vòng, vấn đề thường nằm ở tiêu chí nghiệm thu chưa rõ — sửa tiêu chí, đừng chạy lại thêm.
Đánh giá thử nghiệm bằng số liệu
Sau 3–5 ticket tương tự, ghi lại bốn chỉ số và so với các ticket cùng độ khó làm theo cách cũ:
| Chỉ số | Câu hỏi |
|---|---|
| Chất lượng | Bản sửa có đạt tiêu chí và qua test hồi quy không? Có bị mở lại không? |
| Công sức con người | Mất bao nhiêu phút chuẩn bị đầu vào, gỡ vướng và review? |
| Thời gian hoàn thành | Từ lúc giao đến lúc được chấp nhận mất bao lâu (tính cả thời gian chờ)? |
| Chi phí | Tiền + hạn mức đã dùng cho mỗi ticket được chấp nhận? |
Nếu quy trình tạo ra nhiều báo cáo nhưng người review mất thêm thời gian, đó là tín hiệu chưa có lợi — hãy thu hẹp phạm vi hoặc cải thiện mẫu bàn giao trước khi mở rộng.
Việc cần làm sau bài này
- Chọn một ticket thật, phạm vi nhỏ, tái hiện được.
- Viết tiêu chí nghiệm thu và danh sách bằng chứng cần nhận lại theo mẫu ở trên.
- Quyết định: CLI nào, subscription hay API key, ai là người duyệt cuối.
Phần 2 sẽ đi từng bước: cài Paperclip, kết nối CLI, tạo đội CEO–Developer–QA và chạy ticket này từ đầu đến khi được nghiệm thu.
Tài liệu tham khảo
- What is Paperclip · Product Overview · Key Concepts
- Execution Policy · Routines & Heartbeats · Connector Access
- Codex Adapter · Claude Code Adapter · Budgets
- OpenAI Codex Authentication · Claude plan với Agent SDK / claude -p
Thông tin tính năng đối chiếu với tài liệu chính thức ngày 13/11/2026; Paperclip cập nhật nhanh, hãy kiểm tra lại phiên bản bạn dùng. Ả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.