Paperclip: điều phối một team AI agent nhỏ (Claude Code + Codex) mà không rối

1. Một agent thì dễ, một nhóm agent thì phải có người điều phối

AICodeKing bắt đầu bằng một quan sát quen thuộc: chạy một coding agent thì khá đơn giản. Bạn giao cho nó một task, kiểm tra xem nó làm gì, rồi bảo nó sửa những chỗ còn thiếu. Nhưng khi bạn có Claude Code đang build một thứ, Codex đang review nó, và thêm một agent khác lo phần research, thì bạn còn phải quản lý cả những lần bàn giao (handoff) giữa chúng. Phải có ai đó giữ cho mục tiêu không bị lạc, giải thích ai chịu trách nhiệm phần nào, và kiểm xem toàn bộ chuyện này đang tốn bao nhiêu tiền.

Đó là chỗ Paperclip xuất hiện. Đây là một app open source để quản lý các team AI agent. Bạn có thể giao vai trò (role) cho từng agent, tổ chức công việc của chúng quanh các project, và theo dõi chúng đang làm gì từ một dashboard duy nhất.

Nó còn có cả org chart, nên vâng, giờ coding agent của bạn có thể có một người quản lý. Ý tưởng "điều hành một công ty AI" nghe rất hấp dẫn, nhưng cá nhân AICodeKing quan tâm hơn tới một câu hỏi thực tế: liệu Paperclip có làm cho một team agent nhỏ trở nên hữu ích mà không đẻ thêm việc cho người phải quản lý chúng hay không. Rồi anh đi thẳng vào nội dung.

2. Paperclip đứng phía trên các agent: adapter là gì

Paperclip nằm ở tầng phía trên các agent mà bạn kết nối vào. Claude Code hay Codex vẫn là thứ thật sự viết code. Paperclip lo phần tổ chức bao quanh công việc đó: giao task, chuyển việc giữa các agent, và giữ lại một bản ghi mà bạn có thể quay lại xem.

Nó hỗ trợ adapter cho các công cụ như Claude Code, Codex, Gemini CLI, Cursor, OpenCode và Pi. Ngoài ra còn có đường tích hợp cho các process tự viết (custom process) và các dịch vụ HTTP. Adapter đơn giản là cái kết nối cho phép Paperclip khởi động một agent và thu thập những gì đã xảy ra trong lần chạy (run) của nó. Bạn vẫn phải tự cấu hình runtime mà mình dùng.

AICodeKing thích sự linh hoạt này. Ví dụ, anh có thể muốn một agent lo phần implementation và một agent khác review các thay đổi. Anh chọn công cụ cho từng agent một cách riêng biệt, thay vì phải dựng cả workflow quanh một nhà cung cấp model duy nhất.

3. Mô hình tổ chức: organization, goal và CEO agent

Mô hình tổ chức của Paperclip khá thú vị. Bạn tạo một company, mà giao diện hiện tại gọi là organization, và nó cho team của bạn một chỗ để làm việc. Sau đó bạn thêm một goal và nối các project vào thứ bạn đang muốn đạt được.

Cách thiết lập trong tài liệu bắt đầu bằng một CEO agent. Việc của nó là đọc goal, đề xuất một kế hoạch, rồi giao việc (delegate). Các agent khác có thể báo cáo cho nó, hoặc bạn có thể dựng một hệ thống phân cấp lớn hơn với các manager và worker. Bạn đứng phía trên tất cả, là người đưa ra quyết định cuối cùng.

Dù vậy, anh sẽ giữ mọi thứ nhỏ lúc đầu. Nếu chỉ build một app cơ bản, có lẽ anh không cần sáu agent quản lý ngồi bàn xem frontend agent nên làm gì. Một coordinator cùng vài agent có nhiệm vụ rõ ràng sẽ là điểm khởi đầu hợp lý hơn nhiều.

4. Delegation và task: theo dõi một yêu cầu tách thành việc nhỏ

Delegation workflow của Paperclip cho phép coordinator tạo task và giao chúng cho các agent báo cáo cho nó. Các agent đăng cập nhật trong lúc làm, và các vướng mắc (blocker) có thể được đẩy ngược lên theo chuỗi báo cáo. Nhờ vậy, bạn có cách theo dõi một yêu cầu ban đầu đã được tách thành những phần việc nhỏ hơn ra sao.

Các task là một phần lớn của trải nghiệm. Mỗi issue có thể chứa brief, comment và các cập nhật tiến độ. Bạn có thể lọc công việc theo những thứ như trạng thái (status) hay người được giao (assignee), và mở một task đang bị chặn để xem nó cần gì.

5. Checkout và isolated workspace

Paperclip còn có một cơ chế checkout để ngăn các lần chạy cạnh tranh nhau cùng nhận (claim) một task. Điều đó hữu ích, nhưng AICodeKing lưu ý: hai task tách biệt vẫn có thể đụng vào cùng một phần code. Bạn cũng cần nghĩ xem workspace của chúng được cấu hình thế nào.

Cho chuyện này, Paperclip có một tính năng isolated workspace đang ở dạng thử nghiệm (experimental). Khi được bật và cấu hình, nó có thể cho mỗi task một git worktree và một branch riêng. Như vậy các thay đổi code có một bản làm việc riêng, dù sau đó bạn vẫn phải review và gộp các thay đổi lại.

6. Ví dụ notes app và cài đặt local

Giờ AICodeKing đi qua cách anh sẽ dựng một ví dụ nhỏ. Giả sử ta muốn một notes app trong đó bạn có thể tạo một note, sửa nó, xoá nó, và vẫn giữ được các note sau khi refresh trang. Đây là một kết quả cụ thể, kiểm tra được, mà không biến thí nghiệm đầu tiên thành một project khổng lồ.

Trước hết, bạn cần Node phiên bản 24.11 hoặc mới hơn. Trên màn hình, anh gõ node -v trong terminal và nhận về v24.11.0.

Để cài nhanh trên máy, mở terminal và chạy lệnh dưới đây. AICodeKing nhấn mạnh paperclipai được viết liền thành một từ trong lệnh:

npx paperclipai@latest onboard --yes

Lệnh này chấp nhận cấu hình mặc định và khởi động Paperclip ngay trên máy. Nó dùng một cơ sở dữ liệu PostgreSQL nhúng sẵn (embedded), nên bạn không phải dựng một database server riêng cho lần chạy đầu tiên này. README của repo Paperclip cũng ghi đúng lệnh này, kèm yêu cầu Node.js 24.11 trở lên.

7. Tài khoản model, agent đầu tiên và Test environment

Bạn cũng cần runtime của agent mà mình muốn kết nối. Nếu dùng adapter Claude Code hay Codex chạy local, hãy chắc rằng CLI đó đã được cài và đã đăng nhập trên chính máy chạy Paperclip. Bạn không nhất thiết phải mua thêm quyền truy cập API riêng: tài liệu adapter hỗ trợ cả việc dùng gói subscription đã đăng nhập sẵn của các công cụ này, lẫn cách thiết lập bằng API key. Tài khoản nào thực sự được dùng còn tuỳ vào adapter và cấu hình của nó, nên hãy kiểm tra điều đó trước khi bắt đầu chạy task.

Khi đã vào Paperclip, bạn đặt tên cho organization và cấu hình agent đầu tiên: chọn adapter, model và thư mục làm việc (working directory). Sau đó dùng Test environment để kiểm tra kết nối. AICodeKing sẽ làm bước này trước khi thêm phần còn lại của team. Nếu agent đầu tiên còn không chạy được, thêm bốn agent nữa chỉ cho bạn thêm bốn thứ phải gỡ lỗi.

8. Goal, ba vai trong team, duyệt strategy và duyệt hire

Tiếp theo, AICodeKing thêm goal cho notes app và viết rõ phạm vi. Đại ý như sau:

Build a local notes app with persistent storage, include tests for the main actions, and provide instructions for running it.

Anh cũng sẽ nói rõ rằng tài khoản người dùng và thanh toán nằm ngoài phạm vi của phiên bản đầu tiên này.

Về team, anh dùng ba vai: coordinator để tổ chức công việc, một coding agent để implement, và một review agent để kiểm tra kết quả. Đó chỉ là các vai ví dụ; bạn có thể chọn model hay công cụ khác tuỳ thứ bạn đang có quyền truy cập.

Khi coordinator đề xuất một strategy, anh sẽ đọc nó trước khi duyệt. Nếu nó muốn build một backend service và một hệ thống authentication cho cái demo bé xíu này, anh sẽ yêu cầu sửa lại (request revision): giữ phiên bản đầu ở dạng local và tập trung vào đúng các hành vi đã yêu cầu.

Approval flow cũng áp cho các đề xuất tuyển thêm agent (hire). Bạn có thể xem vai trò và cấu hình trước khi thêm một agent mới, và yêu cầu sửa nếu đề xuất không hợp lý. Như vậy team có thể tự đề xuất thứ nó cần, còn bạn vẫn là người quyết định việc đó có đáng làm không.

9. Review stage bắt buộc trước khi đóng task

Với task implementation, AICodeKing sẽ cấu hình một review stage và bắt reviewer kiểm tra app thật đang chạy: nó có tạo và sửa note được không? Xoá một note có xoá đúng note đó không? Refresh trang có giữ lại dữ liệu không? Những câu hỏi này cho reviewer một thứ cụ thể để phán xét.

Paperclip có thể ép buộc bước review này khi coding agent tìm cách đóng task. Nó chuyển issue sang reviewer, và các yêu cầu sửa (requested changes) có thể gửi task ngược lại agent ban đầu. Bạn cũng có thể cấu hình thêm một stage duyệt cuối cùng (final approval).

Anh coi đây là một trong những tính năng hữu ích hơn cả của Paperclip. Một agent nói "tôi xong rồi" mới chỉ là điểm bắt đầu của việc review công việc của nó. Với ví dụ này, anh muốn tận mắt thấy app chạy và xem kết quả test trước khi gọi là xong. Đó là workflow anh sẽ dùng cho một bản demo; chất lượng của app hoàn chỉnh vẫn cần được test.

10. Chi phí và budget

Giờ tới chi phí, vì đây là chỗ một team agent có thể trở nên đắt đỏ khá nhanh. Bản thân Paperclip miễn phí khi tự host và dùng giấy phép MIT. Tiền dùng model, các gói subscription bạn đang có, và chi phí hosting nếu có là những khoản riêng. Kết nối nhiều agent không cho bạn quyền dùng không giới hạn các dịch vụ đằng sau chúng.

Bạn có thể theo dõi mức chi tiêu được báo về và đặt budget ở cấp company, cấp agent hoặc cấp project. Có các ngưỡng cảnh báo (warning threshold) và các điểm dừng cứng (hard stop) cấu hình được, nên bạn có thể quyết định công việc nên tạm dừng ở đâu, thay vì để mọi thứ chạy tiếp không kiểm soát.

11. Budget không phải lời bảo đảm

Nhưng có một chi tiết ở đây. Việc thực thi budget dựa trên chi tiêu đã được ghi nhận, nên việc báo cáo usage, hoặc công việc đang chạy dở, có thể làm điểm dừng tới trễ. Vì vậy AICodeKing sẽ không coi một thiết lập budget là lời bảo đảm rằng hoá đơn của nhà cung cấp sẽ rơi đúng con số đó.

Cá nhân anh sẽ chạy một task nhỏ, xem usage, rồi mới quyết định cho mỗi agent bao nhiêu khoảng trống. Số tiền bạn tiêu sẽ tuỳ vào model và lượng việc chúng làm. Một reviewer qua lại nhiều vòng với người implement cũng làm tăng usage, ngay cả khi bản thân app khá đơn giản.

12. Heartbeats: đánh thức agent khi có việc

Chuyện này dẫn tới heartbeats. Paperclip dùng chúng để đánh thức agent và cho chúng làm việc. Việc giao task (assignment) và comment có thể kích hoạt một run, và bạn cũng có thể cấu hình một bộ hẹn giờ theo chu kỳ (interval timer).

Heartbeat theo timer mặc định tắt với agent mới, và AICodeKing thấy đó là lựa chọn hợp lý. Nếu một agent cứ vài phút lại thức dậy chỉ để phát hiện chẳng có gì để làm, bạn đang tạo ra hoạt động mà không thu về được bao nhiêu. Anh sẽ để agent chờ việc, trừ khi có một lý do cụ thể khiến nó cần kiểm tra thứ gì đó định kỳ.

13. Routines cho việc lặp lại

Với các việc lặp đi lặp lại, Paperclip có routines. Ví dụ, bạn có thể để một agent soạn bản tóm tắt hằng tuần những việc đã hoàn thành, hoặc kiểm tra các issue mới đến vào mỗi buổi sáng. Bạn định nghĩa công việc, giao cho một agent, rồi thêm một lịch chạy (schedule) hoặc một webhook trigger. Mỗi lần chạy cho bạn một phần việc được theo dõi mà bạn có thể mở ra xem lại.

Đây là tính năng anh nghĩ mình sẽ dùng khá nhiều. Với một bản báo cáo định kỳ, anh muốn biết nó có chạy hay không và kết quả đã đi đâu. Việc kết quả được gắn vào một task giúp dễ theo dõi hơn khi có thứ gì đó bị thiếu.

14. Shared skills và Skill Studio

Paperclip cũng có shared skills. Bạn có thể viết một quy trình (procedure) một lần và cho các agent cần nó cùng dùng. Với notes app, đó có thể là một checklist review giải thích cần thu thập bằng chứng gì trước khi duyệt một thay đổi.

Skill Studio cho phép bạn sửa những hướng dẫn đó, test chúng với các input đã lưu, xem output, và khôi phục các phiên bản trước. Nên nếu một thay đổi trong checklist làm cho việc review tệ đi, bạn có cách so sánh hành vi và quay lại.

AICodeKing thích cách này hơn việc cứ dán đi dán lại cùng một đoạn hướng dẫn dài vào nhiều cuộc chat khác nhau. Dù vậy, bản thân hướng dẫn vẫn phải tốt: chia sẻ một checklist mơ hồ cho mọi agent chỉ làm cùng một sự lúng túng lan ra khắp team.

15. Connector, MCP và quyền của từng agent

Paperclip còn có các kết nối dịch vụ (service connection), gồm app tools và các tích hợp MCP tự định nghĩa. Với những kết nối công cụ được hỗ trợ, bạn có thể kiểm soát agent nào được truy cập, và đặt từng hành động ở mức Allowed (cho phép), Ask first (hỏi trước) hoặc Off (tắt).

Có một điểm phân biệt quan trọng: các kiểm soát hành động này chỉ áp cho những lời gọi đi qua tool gateway của Paperclip. Chúng không tự động kiểm soát mọi lệnh shell mà một coding agent có thể chạy. Vì vậy AICodeKing sẽ kiểm tra quyền của runtime và các credential như một phần của việc dựng team, nhất là trước khi cho nó truy cập một project thật.

16. Paperclip dành cho ai

Vậy anh sẽ giới thiệu Paperclip cho ai? Nếu bạn đã có vài agent làm các task liên quan tới nhau và đang mất thời gian điều phối chúng, anh nghĩ Paperclip đáng để thử. Lịch sử task và các bước bàn giao review là những phần anh sẽ tập trung vào trước.

Nếu bạn chủ yếu dùng một coding agent cho những yêu cầu ngắn, có thể bạn sẽ thấy phần dựng tổ chức là thừa. Anh sẽ không tạo nguyên một cấu trúc công ty chỉ để đổi tên vài biến. Hãy bắt đầu với một task thật sự cần điều phối, và xem cấu trúc thêm vào có giúp ích không.

Anh cũng khuyên nên đón ý tưởng "công ty tự vận hành" (autonomous company) với chút hoài nghi. Một chức danh CEO không làm cho agent giỏi hơn trong việc quyết định nên build cái gì. Bạn vẫn cần một goal hữu ích, những hướng dẫn hợp lý, và một người sẵn lòng nhìn kỹ vào output.

Nhìn chung, anh thích hướng đi của Paperclip. Nó open source, chạy với nhiều loại agent, và cho bạn một chỗ để quản lý công việc mà nếu không có nó sẽ nằm rải rác qua các session. Với anh, bài test đầu tiên là liệu team notes app nhỏ kia có cho ra một kết quả anh kiểm chứng được, với mức chi phí anh thấy chấp nhận được hay không. Nếu có, anh sẽ bắt đầu giao cho nó nhiều trách nhiệm hơn. Nói chung là khá hay.

Cuối video, AICodeKing mời người xem để lại suy nghĩ trong phần bình luận và ủng hộ kênh.