Paperclip: quản lý cả đội AI agent như một công ty — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về paperclipai/paperclip — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: Paperclip: quản lý đội AI agent như một công ty — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
Paperclip là ứng dụng mã nguồn mở (MIT) giúp bạn quản lý một đội AI agent như quản lý nhân viên: có sơ đồ tổ chức, giao việc, ngân sách và quy trình duyệt. Bạn mang agent của mình (Claude Code, Codex, Cursor, Gemini CLI…) vào, Paperclip lo phần điều phối. Cài cần Node 24.11 trở lên và hơi kỹ thuật, nên hợp với người đã quen dùng terminal.
Paperclip là một ứng dụng mã nguồn mở gồm máy chủ Node.js và giao diện web React, dùng để điều phối cả đội AI agent làm việc cho bạn. Nhìn bên ngoài nó giống một phần mềm quản lý công việc. Bên trong là sơ đồ tổ chức, ngân sách, quy trình duyệt và cơ chế để nhiều agent phối hợp với nhau.
Bạn nên xem qua nếu đang mở cùng lúc nhiều cửa sổ Claude Code, Codex hay Cursor và không nhớ con nào đang làm gì. Câu tác giả hay dùng là: nếu OpenClaw là một nhân viên thì Paperclip là cả công ty. Bạn không quản lý từng dòng lệnh của từng agent nữa. Bạn đặt mục tiêu, giao việc, đặt ngân sách rồi theo dõi kết quả.
Điểm đáng giá nhất là tính "mang agent của bạn vào". Repo không bắt bạn dùng một mô hình riêng. Hiện repo có khoảng 113.470 sao và 18.840 fork, giấy phép MIT, và vẫn được cập nhật trong 3 tháng gần đây. Bạn có thể xem video ngắn bên dưới để thấy giao diện trước khi cài.
paperclipai/paperclip
Paperclip là máy chủ Node.js kèm giao diện web để điều phối nhiều AI agent: giao việc, theo dõi tiến độ, đặt ngân sách và duyệt kết quả trên một bảng điều khiển.
I.Paperclip làm được gì
Mình gom các tính năng theo việc bạn sẽ làm hằng ngày, không chép lại nguyên README.
A.Giao việc cho agent như giao ticket
Mỗi công việc là một "task" có luồng trao đổi riêng. Kế hoạch, vướng mắc, tệp đính kèm và lịch sử chạy đều nằm trong task đó. Bạn có thể giao task cho agent hoặc cho người thật. Nhờ vậy khi khởi động lại máy, bạn không mất ngữ cảnh như lúc để hàng chục tab terminal.
B.Sơ đồ tổ chức cho agent
Agent có chức danh, người quản lý, quyền hạn và ngân sách riêng. README ví dụ một đội gồm CEO, CTO, kỹ sư, nhà thiết kế, marketer. Việc giao xuống và báo cáo lên đi theo sơ đồ này.
C.Mang agent nào cũng được
README liệt kê các agent hoạt động cùng Paperclip: OpenClaw, Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Pi, Hermes, Grok Build, Kimi Code. Ngoài ra còn có tiến trình tự viết, endpoint HTTP và gói adapter bên ngoài. Nguyên tắc của tác giả: "nếu nó nhận được heartbeat thì nó được thuê".
D.Heartbeat: agent tự thức dậy khi có việc
Agent được đánh thức khi có việc được giao, có tin nhắn tiếp theo, hoặc theo lịch bạn cấu hình. Bạn không phải ngồi bấm chạy từng lần.
E.Kiểm soát chi phí
Bạn đặt ngân sách theo công ty, agent hoặc dự án. Hệ thống theo dõi chi tiêu được báo cáo, cảnh báo khi gần ngưỡng và tạm dừng khi chạm giới hạn. README có lưu ý trung thực: việc chặn dựa trên số liệu đã được ghi nhận, nên báo cáo chậm hoặc việc đang chạy dở có thể làm lệnh dừng đến muộn một chút.
F.Quản trị và duyệt việc
Bạn cấu hình các bước review và phê duyệt, duyệt việc "tuyển" agent mới, và có thể tạm dừng, giao lại hoặc dừng hẳn một việc. Thay đổi cấu hình được lưu theo phiên bản nên có thể hoàn tác.
G.Việc định kỳ (Routines)
Việc lặp lại như hỗ trợ khách, đăng mạng xã hội, làm báo cáo có thể chạy theo lịch, qua API hoặc webhook. Mỗi lần chạy tạo ra một task có người phụ trách và lịch sử.
H.Kết nối ứng dụng và kỹ năng
Bạn kết nối dịch vụ như GitHub, Notion, Railway hoặc MCP server của riêng bạn. Mỗi hành động có thể đặt ở ba mức: Cho phép, Hỏi trước, hoặc Tắt. Phần Skill Studio cho phép cài hoặc viết kỹ năng dùng chung, thử với dữ liệu mẫu đã lưu và khôi phục phiên bản cũ.
I.Nhiều tổ chức trong một hệ thống và đội mẫu
Một bản cài chạy được nhiều tổ chức, mỗi tổ chức có task, agent, quyền và lịch sử riêng. Bạn cũng có thể xem trước và cài các "đội dựng sẵn" gồm vai trò, kỹ năng, dự án và routine, rồi chỉnh theo ý mình.
II.Cần chuẩn bị gì
Mình chỉ liệt kê những gì tư liệu nói rõ.
- Node.js từ 24.11.0 trở lên. File package.json của repo yêu cầu như vậy. Bản cũ hơn có thể không chạy.
- Git, để tải mã nguồn về.
- Các agent bạn muốn quản lý. Paperclip không thay thế Claude Code hay Codex. Nó điều phối chúng. Bạn cần có sẵn những agent này và tài khoản hoặc khoá của chúng.
- Cấu hình môi trường. Repo có file mẫu .env.example với các biến: DATABASE_URL, PORT, SERVE_UI, BETTER_AUTH_SECRET, PAPERCLIP_TOOL_ACTION_SIGNING_SECRET và PAPERCLIP_SENTRY_RUN_FAILURES. Phần README mình đọc được chưa giải thích từng biến, nên giá trị cụ thể bạn cần xem trong tài liệu chính thức.
- Docker (tuỳ chọn). Repo có Dockerfile và thư mục docker/. Tư liệu chưa nói rõ cách dùng, nên mình không đưa lệnh.
Tư liệu chưa nói về yêu cầu phần cứng hay GPU. Paperclip là lớp điều phối, nên phần nặng nằm ở agent và mô hình bạn dùng.
III.Cài đặt từng bước
- Kiểm tra NodeChạy node --version, cần từ 24.11.0 trở lên
- Tải mã nguồngit clone repo về máy rồi vào thư mục
- Xem QuickstartLấy lệnh cài và chạy chính thức từ README và tài liệu
- Điền cấu hìnhDùng .env.example làm mẫu cho file cấu hình
- Mở giao diệnTruy cập địa chỉ máy chủ để tạo tổ chức và thuê agent
Lưu ý quan trọng: phần README mình có trong tay bị cắt trước đoạn hướng dẫn cài đặt. Vì vậy README chưa ghi cách cài trong phần mình đọc được, và mình không đoán lệnh cho bạn. Mình chỉ đưa những lệnh chắc chắn đúng, còn lệnh cài và chạy chính thức bạn lấy từ mục Quickstart ở đầu README, từ trang tài liệu docs.paperclip.ing, hoặc từ file CONTRIBUTING.md và package.json trong repo.
A.Kiểm tra phiên bản Node
Mở terminal (trên Windows là PowerShell hoặc Terminal, trên macOS và Linux là Terminal) rồi chạy:
node --versionKết quả phải là v24.11.0 hoặc cao hơn. Nếu thấp hơn, hãy cài lại Node trước. Đây là chỗ người mới hay vấp nhất, vì máy thường còn bản Node cũ.
B.Tải mã nguồn về máy
git clone https://github.com/paperclipai/paperclip.git
cd paperclipLệnh đầu tải toàn bộ repo vào một thư mục tên paperclip. Lệnh thứ hai đi vào thư mục đó. Các lệnh sau phải chạy ở trong thư mục này, nên hãy giữ nguyên cửa sổ terminal.
C.Làm theo Quickstart để cài và chạy
Repo dùng pnpm (có pnpm-workspace.yaml và pnpm-lock.yaml) và turbo, và package.json khai báo các lệnh chạy. Tuy vậy, mình không tự ghép lệnh từ suy đoán. Hãy mở Quickstart trong README hoặc docs.paperclip.ing, làm đúng thứ tự ở đó, và chỉ chép lệnh từ nguồn chính thức.
D.Điền cấu hình môi trường
Trong thư mục gốc có file .env.example. Đó là file mẫu liệt kê tên các biến. Nếu tài liệu bảo bạn tạo file .env, bạn sao chép file mẫu ra và điền giá trị:
cp .env.example .envTrên PowerShell, lệnh tương đương là Copy-Item .env.example .env. Hai biến có chữ SECRET (BETTER_AUTH_SECRET và PAPERCLIP_TOOL_ACTION_SIGNING_SECRET) là chuỗi bí mật, nên hãy đặt giá trị riêng của bạn và đừng chia sẻ.
Đừng đưa file .env hay bất kỳ khoá API nào lên GitHub hoặc gửi cho người khác. Agent chạy liên tục có thể tốn tiền token, nên hãy đặt ngân sách ngay từ đầu rồi mới cho chạy tự động.
E.Mở giao diện
Sau khi máy chủ chạy, bạn mở trình duyệt vào địa chỉ mà terminal báo. Biến PORT trong .env.example là cổng máy chủ lắng nghe. README nói Paperclip có hai chế độ triển khai là "trusted local" (tin cậy cục bộ) và "authenticated" (có đăng nhập). Nếu chỉ thử trên máy cá nhân, hãy ưu tiên chế độ cục bộ theo hướng dẫn trong tài liệu.
IV.Kiểm tra đã chạy được chưa
Tư liệu mình có không nêu một lệnh kiểm tra riêng. Dấu hiệu thành công hợp lý là:
- Terminal chạy máy chủ mà không báo lỗi đỏ và không tự thoát.
- Mở địa chỉ máy chủ trong trình duyệt thấy giao diện Paperclip, trông như một phần mềm quản lý task.
- Bạn tạo được một tổ chức (công ty) và thấy bảng điều khiển.
Nếu trang không hiện, hãy kiểm tra terminal xem máy chủ còn chạy không, rồi xem lại giá trị PORT.
V.Dùng vào việc thật
Các tình huống dưới đây bám theo tính năng README mô tả. Tên nút bấm cụ thể có thể khác, nên bạn đối chiếu với giao diện thực tế.
A.Dev đang mở quá nhiều tab Claude Code
Bạn là lập trình viên tự làm sản phẩm, đang chạy Claude Code ở nhiều dự án và mỗi lần khởi động lại máy là mất dấu. Bạn tạo một tổ chức trong Paperclip, thêm Claude Code làm một agent và giao từng việc dưới dạng task. Mỗi task có luồng trao đổi riêng và phiên làm việc được lưu giữ ở những adapter hỗ trợ. Kết quả là bạn nhìn danh sách việc để biết ai đang làm gì, thay vì lật từng tab.
Quản lý mục tiêu kinh doanh, đừng quản lý từng pull request.
Ông T
B.Chủ shop thử một đội agent chạy việc lặp lại
Bạn có những việc ngày nào cũng giống nhau, như soạn báo cáo cuối ngày hoặc trả lời câu hỏi khách quen. Bạn tạo một routine chạy theo lịch hoặc kích hoạt qua webhook. Mỗi lần chạy sinh ra một task có người phụ trách và lịch sử để bạn mở lại kiểm tra. Bạn vẫn là người duyệt cuối, nên việc nào quan trọng thì đặt bước phê duyệt trước khi hoàn tất.
C.Người làm kinh doanh đặt mục tiêu rồi duyệt kế hoạch
Bạn dùng đúng ví dụ trong README. Mục tiêu có thể ghi như sau:
Build the #1 AI note-taking app to $1M MRR.Bạn thuê một đội gồm CEO, CTO, kỹ sư, nhà thiết kế và marketer, mỗi vai gắn với một agent. Sau đó bạn duyệt chiến lược, đặt ngân sách và cho chạy. Các task gắn với mục tiêu nên agent biết cả "vì sao" chứ không chỉ tên việc. Đây là kịch bản tham vọng, nên hãy bắt đầu bằng một mục tiêu nhỏ hơn để xem đội chạy ra sao.
D.Người quản lý chi phí muốn đặt trần chi tiêu
Bạn lo agent chạy vòng lặp và đốt hết hạn mức. Bạn đặt ngân sách theo agent hoặc dự án, bật cảnh báo theo ngưỡng và để hệ thống tạm dừng khi chạm giới hạn. Nhớ lưu ý ở trên: việc chặn dựa trên số liệu đã ghi nhận nên có thể trễ một chút. Hãy đặt trần thấp hơn mức bạn thực sự chịu được.
VI.Lỗi hay gặp và cách xử lý
A.Báo phiên bản Node không đủ
Repo yêu cầu Node từ 24.11.0. Nếu cài hoặc chạy báo lỗi lạ ngay từ đầu, hãy chạy node --version để kiểm tra, rồi cài bản mới hơn. Nếu bạn dùng trình quản lý phiên bản Node, hãy chuyển sang bản phù hợp trước khi chạy lại.
B.Máy chủ không khởi động vì thiếu cấu hình
Dấu hiệu thường là lỗi nhắc đến biến môi trường hoặc cơ sở dữ liệu. Hãy mở .env.example, đối chiếu xem bạn đã điền các biến như DATABASE_URL, BETTER_AUTH_SECRET chưa. Ý nghĩa và giá trị chính xác của từng biến, bạn tra trong tài liệu chính thức.
C.Cổng bị chiếm
Nếu cổng đang bị chương trình khác dùng, máy chủ sẽ không lên được. Đổi giá trị PORT trong file cấu hình sang cổng khác rồi chạy lại, và mở đúng địa chỉ mới trong trình duyệt.
D.Agent không nhận việc hoặc không chạy
Paperclip chỉ điều phối, còn agent phải được cài và đăng nhập riêng trên máy. Hãy kiểm tra agent (ví dụ Claude Code) tự chạy được ngoài Paperclip trước, rồi mới thêm vào. Xem thêm trang adapter trong tài liệu để biết cách khai báo từng loại.
E.Chi phí vượt dự kiến
Đây là rủi ro của mọi hệ thống agent chạy tự động. Hãy đặt ngân sách và ngưỡng cảnh báo trước khi bật chạy liên tục. Bắt đầu với một agent và một việc nhỏ, xem mức tiêu thụ thực tế rồi mới mở rộng.
VII.Có nên dùng không
Điểm mạnh. Paperclip gom việc giao, theo dõi, duyệt, ngân sách và lịch chạy vào một chỗ, thay vì bạn tự ghép nhiều script. Nó hỗ trợ nhiều loại agent, có phân quyền, ghi lại hoạt động để kiểm tra và có thể hoàn tác thay đổi cấu hình. Giấy phép MIT và cộng đồng lớn là điểm cộng.
Giới hạn. Cài đặt đòi hỏi quen dùng terminal và Node phiên bản mới, nên chưa hợp người hoàn toàn chưa từng mở dòng lệnh. Hệ thống rộng với nhiều khái niệm như org chart, governance, routines, plugin, nên cần thời gian làm quen. Một số tính năng như Agent Chat và kết nối chat hoặc email (Slack, Discord, Telegram, AgentMail) được README ghi là thử nghiệm. Chặn chi tiêu dựa trên số liệu đã báo cáo nên không phải khoá tức thì. Ngoài ra bạn vẫn phải tự lo tài khoản và chi phí của từng agent.
Khi nên chọn cách khác. Nếu bạn chỉ dùng một agent cho một việc đơn lẻ, chạy thẳng Claude Code hay Codex sẽ gọn hơn. Paperclip đáng công khi bạn có nhiều agent, nhiều việc chạy song song, cần theo dõi và kiểm soát chi phí. Hãy bắt đầu nhỏ với một tổ chức thử và một vài task, rồi mở rộng khi đã quen.
Câu hỏi thường gặp
Paperclip có miễn phí không?
Mã nguồn dùng giấy phép MIT nên bạn tải và chạy tự do. Tuy nhiên, các agent và mô hình bạn gắn vào có thể tính phí riêng. README cũng nhắc tới danh sách chờ Paperclip Cloud, nhưng tư liệu mình có chưa nêu giá.
Paperclip cần Node phiên bản nào?
File package.json của repo yêu cầu Node từ 24.11.0 trở lên. Bạn nên chạy node --version để kiểm tra trước khi cài.
Paperclip có cần GPU không?
Tư liệu chưa nói về yêu cầu GPU hay phần cứng. Paperclip là máy chủ Node.js kèm giao diện web để điều phối, còn phần nặng phụ thuộc vào agent và mô hình bạn dùng.
Paperclip khác gì việc mở nhiều tab Claude Code?
Paperclip biến việc đó thành hệ thống có ticket, luồng trao đổi, sơ đồ tổ chức, ngân sách và quy trình duyệt. Phiên làm việc được lưu giữ qua các lần khởi động lại ở những adapter hỗ trợ. Mỗi agent thức dậy theo heartbeat khi có việc, nên bạn không phải canh từng tab.
Paperclip dùng được với những agent nào?
README liệt kê OpenClaw, Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Pi, Hermes, Grok Build và Kimi Code. Ngoài ra còn có tiến trình tự viết, endpoint HTTP và adapter bên ngoài. Nguyên tắc là agent nào nhận được heartbeat thì có thể được thêm vào.
Chạy được trên Windows không?
Tư liệu mình có chưa nêu rõ danh sách hệ điều hành được hỗ trợ. Yêu cầu chỉ thấy là Node 24.11.0 trở lên. Bạn nên xem Quickstart và tài liệu chính thức để biết chi tiết cho Windows.
Dữ liệu và khoá bí mật có an toàn không?
README nói có lưu trữ thông tin xác thực được mã hoá, secret theo công ty, kiểm soát quyền truy cập và nhật ký hoạt động. Các tổ chức trong cùng một bản cài được tách biệt bằng kiểm tra quyền theo công ty. Dù vậy, bạn vẫn nên tự giữ kín file .env và đừng đưa lên GitHub.


