# Paperclip: quản lý đội AI agent như một công ty — hướng dẫn cài đặt và dùng

> Paperclip là ứng dụng mã nguồn mở (một server Node.js kèm giao diện React) giúp bạn điều phối nhiều AI agent như Claude Code, Codex, Cursor, Gemini CLI trong một nơi, giống như quản lý nhân viên bằng phần mềm quản lý công việc. Bạn giao mục tiêu, phân vai, đặt ngân sách và duyệt kết quả từ một dashboard. Máy cần Node 24.11 trở lên; phần lệnh cài chi tiết nằm ở mục Quickstart của dự án.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-17 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/paperclip-quan-ly-doi-ai-agent-huong-dan-cai-dat

Paperclip là một ứng dụng mã nguồn mở, gồm server Node.js và giao diện React, dùng để quản lý cả một đội AI agent làm việc cho bạn. Bạn không phải mở hai chục cửa sổ terminal rồi nhớ cái nào đang làm gì. Bạn giao mục tiêu, phân vai, đặt ngân sách, rồi theo dõi và duyệt kết quả trên một dashboard.

Tác giả tóm tắt rất gọn: nếu OpenClaw là một nhân viên, thì Paperclip là cả công ty. Nhìn bề ngoài nó giống một app quản lý công việc. Bên trong là sơ đồ tổ chức, ngân sách, quy trình phê duyệt, liên kết mục tiêu và cơ chế để các agent phối hợp với nhau.

Bài này hợp với lập trình viên đang chạy nhiều Claude Code hoặc Codex cùng lúc, và với người làm kinh doanh muốn thử mô hình đội agent chạy việc lặp lại như báo cáo hay chăm sóc khách hàng. Repo hiện có khoảng 113.470 sao và 18.840 fork, giấy phép MIT. Bạn có thể xem video ngắn bên dưới để thấy giao diện trước khi cài.

```repo
- repo | paperclipai/paperclip
- kind | Ứng dụng
- desc | Ứng dụng mã nguồn mở để điều phối cả đội AI agent: giao mục tiêu, phân vai theo sơ đồ tổ chức, duyệt việc và theo dõi chi phí trên một bảng điều khiển.
- stars | 113k
- lang | TypeScript
- license | MIT
```

```video
- youtube | https://youtube.com/shorts/Zcxmh0j_iWk
- facebook | https://www.facebook.com/reel/1403900141506949
- title | Video giới thiệu paperclip
```

## Paperclip làm được gì

Mình gom các tính năng theo lợi ích thực tế, không chép lại nguyên README.

### Gom mọi agent về một sơ đồ tổ chức

Paperclip cho bạn mang agent của chính bạn vào. README liệt kê các công cụ đã tương thích: OpenClaw, Claude Code, Codex, Cursor (kèm bản Cloud), 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. Câu tác giả hay dùng: nếu nó nhận được một nhịp heartbeat thì nó được tuyển. Mỗi agent có chức danh, người quản lý, mô tả công việc và ngân sách riêng.

### Giao việc như dùng task manager

Công việc được lưu dưới dạng phiếu (ticket). Mỗi phiếu có luồng trao đổi, kế hoạch, vướng mắc, tệp đính kèm và lịch sử chạy. Bạn có thể giao phiếu cho agent hoặc cho người. Lợi ích rõ nhất: tắt máy đi bật lại, phiên làm việc vẫn còn, thay vì mất sạch như khi dùng nhiều tab terminal rời rạc.

### Agent hiểu vì sao phải làm việc đó

Bạn gắn task và dự án vào mục tiêu của tổ chức. Agent nhận được cả bối cảnh phía sau, không chỉ một cái tiêu đề. Bạn đỡ phải copy-paste ngữ cảnh mỗi lần nhắc việc.

### Heartbeat và lịch chạy định kỳ

Agent thức dậy khi có việc được giao, khi có tin nhắn tiếp theo, hoặc theo lịch bạn cấu hình. Với việc lặp lại, tính năng Routines tạo task theo lịch (cron), qua webhook hoặc qua API. Mỗi lần chạy đều có phiếu, người phụ trách và lịch sử để kiểm tra.

### Kiểm soát chi phí và quyền hạn

Bạn đặt ngân sách theo công ty, theo agent hoặc theo 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 việc khi chạm giới hạn. README có lưu ý trung thực: việc dừng dựa trên chi tiêu đã ghi nhận, nên báo cáo trễ hoặc việc đang chạy dở có thể làm chậm lệnh dừng.

### Quản trị và phê duyệt

Bạn cấu hình các bước review và approval, duyệt việc tuyển agent mới, tạm dừng, giao lại hoặc dừng việc khi cần. Thay đổi cấu hình được lưu thành các phiên bản, nên thay đổi xấu có thể hoàn tác.

### Kết nối ứng dụng ngoài

Bạn kết nối GitHub, Notion, Railway hoặc MCP server của riêng bạn. Mỗi hành động qua cổng kết nối đặt được ở ba mức: Allowed, Ask first, Off. Quyền của người, tư cách của agent và quyền của hành động là ba lớp tách biệt.

### Skills, đội mẫu và nhiều tổ chức

Skill Studio cho bạn cài hoặc tự viết skill dùng chung, thử với dữ liệu mẫu đã lưu và khôi phục phiên bản cũ. Bạn cũng xem trước và cài các đội dựng sẵn gồm vai trò, skill, dự án và routine. Một lần triển khai có thể chứa nhiều tổ chức, mỗi nơi tách riêng task, agent, quyền và lịch sử. README còn nhắc giao diện dùng được trên điện thoại, cùng tính năng Agent Chat và kết nối chat/email (Slack, Discord, Telegram, AgentMail) ở mức thử nghiệm.

## Cần chuẩn bị gì

Tư liệu mình có không liệt kê đầy đủ yêu cầu, nên mình chỉ nêu những gì thấy rõ:

- **Node.js từ 24.11.0 trở lên.** Đây là yêu cầu ghi trong package.json của repo. Đây là bản khá mới, nhiều máy chưa có.
- **Các agent của bạn.** Paperclip điều phối chứ không thay thế Claude Code, Codex hay công cụ khác. Bạn cần có sẵn agent và tài khoản hoặc key của chúng, theo cách mỗi công cụ yêu cầu.
- **Các biến cấu hình.** Tệp .env.example có các biến: DATABASE_URL, PORT, SERVE_UI, BETTER_AUTH_SECRET, PAPERCLIP_TOOL_ACTION_SIGNING_SECRET, PAPERCLIP_SENTRY_RUN_FAILURES. Ý nghĩa chi tiết từng biến README phần mình có không giải thích, bạn xem trong tài liệu dự án.
- **Hệ điều hành và phần cứng.** Tư liệu chưa nói rõ yêu cầu máy hay hệ điều hành cụ thể. Repo có Dockerfile, nên chạy bằng Docker là một hướng có thể, nhưng README phần mình đọc chưa hướng dẫn lệnh Docker.

Trang chủ dự án là paperclip.ing, tài liệu ở docs.paperclip.ing.

## Cài đặt từng bước

Phần README mình nhận được bị cắt trước mục Quickstart, nên mình không có lệnh cài chính thức để chép lại. Mình không đoán lệnh để tránh bạn gõ sai. Dưới đây là các bước chắc chắn, và chỗ cần xem hướng dẫn gốc.

```steps
- Kiểm tra Node | Bảo đảm máy có Node.js từ 24.11.0 trở lên
- Tải mã nguồn | Dùng git clone để lấy repo về máy
- Làm theo Quickstart | Mở mục Quickstart trong README hoặc docs.paperclip.ing để lấy lệnh cài và chạy
- Điền cấu hình | Chuẩn bị các biến trong .env.example, nhất là khóa bí mật
- Mở giao diện | Vào dashboard, tạo tổ chức và thêm agent đầu tiên
```

### Kiểm tra phiên bản Node

Mở terminal (trên Windows dùng PowerShell hoặc Windows Terminal) rồi chạy lệnh dưới. Đây là lệnh phổ thông của Node, không riêng gì Paperclip.

```bash
node --version
```

Nếu số hiện ra nhỏ hơn 24.11.0 thì bạn cần nâng Node trước. Đây là chỗ người mới hay vấp nhất, vì Node cũ là chuyện rất thường gặp.

### Tải mã nguồn về máy

Bạn cần cài sẵn Git. Lệnh dưới tải repo về và đi vào thư mục của nó. Hãy mở terminal ở nơi bạn muốn đặt thư mục dự án, ví dụ thư mục Documents.

```bash
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
```

### Làm theo Quickstart để cài và chạy

Repo dùng pnpm workspace (có pnpm-workspace.yaml và pnpm-lock.yaml) và có tên gói npm là paperclip. Tuy vậy, lệnh cài và lệnh chạy chính xác nằm ở mục Quickstart, mà phần README mình có chưa ghi. Bạn hãy mở nút Quickstart ở đầu README trên GitHub, hoặc vào docs.paperclip.ing, rồi chép đúng lệnh ở đó. Làm vậy an toàn hơn là tự suy ra cờ lệnh.

### Điền cấu hình

Trong thư mục repo có tệp .env.example. Đây là tệp mẫu liệt kê tên các biến cần điền. Hãy đọc hướng dẫn trong tài liệu để biết cách đặt tên tệp cấu hình thật và giá trị cho từng biến. Hai biến có chữ SECRET (BETTER_AUTH_SECRET và PAPERCLIP_TOOL_ACTION_SIGNING_SECRET) là khóa bí mật, nên đừng dùng giá trị đoán mò và đừng đăng chúng lên mạng.

```note
Không đưa tệp cấu hình thật (chứa khóa bí mật, chuỗi kết nối cơ sở dữ liệu) lên GitHub hay gửi cho người khác. Hãy đặt ngân sách cho từng agent ngay từ đầu, vì agent chạy tự động có thể tốn nhiều token nếu bị lặp vòng.
```

## Kiểm tra đã chạy được chưa

README phần mình có không mô tả chính xác màn hình hay dòng log khi chạy thành công. Dựa vào mô tả của tác giả (server Node.js kèm giao diện React) và các biến PORT, SERVE_UI trong cấu hình, dấu hiệu hợp lý là terminal không báo lỗi và bạn mở được giao diện web trên trình duyệt qua cổng mà server đang dùng. Bạn xem Quickstart để biết địa chỉ chính xác.

Sau khi vào được dashboard, bài kiểm tra thực tế là làm theo ba bước tác giả đưa ra: định nghĩa một mục tiêu, thêm một agent vào đội, rồi duyệt và cho chạy. Nếu agent nhận được phiếu việc và bạn thấy lịch sử chạy hiện ra, nghĩa là mọi thứ đã thông.

## Dùng vào việc thật

Các tình huống dưới đây bám theo những gì README mô tả. Giao diện cụ thể bạn sẽ thấy khi mở app.

### Dev đang mở nhiều terminal Claude Code

Bạn là lập trình viên và đang chạy cùng lúc vài phiên Claude Code cho các việc khác nhau. Khởi động lại máy là mất dấu mọi thứ. Bạn thêm các agent này vào Paperclip, mỗi agent có vai trò riêng, ví dụ một bên viết tính năng, một bên sửa lỗi. Sau đó bạn tạo mỗi việc thành một phiếu và giao cho đúng agent. Kết quả: mỗi việc có luồng trao đổi riêng, phiên làm việc còn nguyên sau khi khởi động lại, và bạn xem được ai đang làm gì ở một chỗ.

> Quản lý mục tiêu của doanh nghiệp, đừng quản lý từng pull request.
>
> — Ông T

### Chủ shop muốn báo cáo và việc lặp lại chạy tự động

Bạn có những việc làm đều đặn như tổng hợp báo cáo cuối tuần, trả lời khách hàng, đăng bài mạng xã hội. README nêu đúng các ví dụ này. Bạn tạo một Routine với lịch chạy, giao cho agent phù hợp, mô tả đầu ra mong muốn. Ví dụ nội dung giao việc: Mỗi sáng thứ Hai, tổng hợp số đơn tuần trước và các câu hỏi khách hàng còn mở thành một báo cáo ngắn. Mỗi lần chạy sinh ra một phiếu có người phụ trách và lịch sử, bạn chỉ cần mở lên đọc và góp ý thay vì nhớ đi nhắc.

### Quản lý chi phí khi nhiều agent chạy tự động

Bạn lo agent bị lặp vòng và đốt hết hạn mức. Bạn đặt ngân sách theo công ty, theo agent hoặc theo dự án, bật cảnh báo theo ngưỡng. Khi chạm giới hạn đã cấu hình, công việc bị tạm dừng. Hãy nhớ lưu ý của README: lệnh dừng dựa trên chi tiêu đã ghi nhận, nên đặt ngưỡng chừa dư một chút, đừng đặt sát mức bạn chịu được.

### Trưởng nhóm muốn duyệt trước khi agent hành động

Bạn cho agent kết nối GitHub hoặc Notion nhưng không muốn nó tự làm mọi thứ. Với từng hành động, bạn đặt Ask first hoặc Off. Với việc quan trọng, bạn cấu hình bước review trước khi coi như hoàn thành. Bạn duyệt một lần hoặc lưu thành quy tắc có thể thu hồi. Kết quả là agent làm việc nhanh nhưng mọi hành động nhạy cảm vẫn qua tay bạn.

## Lỗi hay gặp và cách xử lý

### Node quá cũ

Repo yêu cầu Node từ 24.11.0. Nếu cài hoặc chạy báo lỗi phiên bản, chạy node --version để kiểm tra, rồi nâng Node lên bản đáp ứng yêu cầu trước khi thử lại.

### Thiếu hoặc sai biến cấu hình

Server cần các biến như DATABASE_URL và BETTER_AUTH_SECRET. Nếu app không khởi động hoặc không đăng nhập được, hãy đối chiếu tệp cấu hình của bạn với .env.example, xem có biến nào thiếu hoặc để trống không. Đọc kỹ thông báo lỗi trong terminal, thường nó chỉ đúng tên biến.

### Cổng bị chiếm

Biến PORT quy định cổng server dùng. Nếu cổng đó đang có chương trình khác chiếm, app sẽ không lên. Đổi PORT sang giá trị khác trong cấu hình rồi chạy lại.

### Agent không nhận việc

Paperclip chỉ điều phối, còn agent phải tự chạy được trên máy bạn. Hãy chắc rằng công cụ agent (ví dụ Claude Code) đã cài và đăng nhập hoặc có key riêng, rồi xem lịch sử chạy của phiếu để biết agent dừng ở đâu.

### Chi phí vượt dự tính

Đây không phải lỗi phần mềm mà là rủi ro của việc cho agent chạy tự động. Đặt ngân sách và ngưỡng cảnh báo từ đầu, bắt đầu với một agent và một việc nhỏ, xem lịch sử chi tiêu rồi mới mở rộng.

## Có nên dùng không

**Điểm mạnh.** Paperclip giải quyết đúng nỗi đau khi dùng nhiều agent: mất dấu việc, mất ngữ cảnh, khó kiểm soát chi phí. Nó gom sơ đồ tổ chức, phiếu việc, lịch chạy, ngân sách và phê duyệt vào một chỗ. Nó không khóa bạn vào một hãng, vì dùng được nhiều loại agent. Mã nguồn mở, giấy phép MIT, và repo vẫn được cập nhật trong vài tháng gần đây.

**Giới hạn.** Đây là hệ thống lớn, có nhiều khái niệm (tổ chức, quản trị, kết nối, plugin), nên cần thời gian làm quen. Yêu cầu Node 24.11 trở lên có thể buộc bạn nâng môi trường. Phần README mình có chưa ghi rõ lệnh cài, cấu hình máy và cách chạy sản xuất, nên bạn phải đọc thêm Quickstart và docs. Một số tính năng như Agent Chat và kết nối chat/email vẫn ở mức thử nghiệm. Bản Cloud đang ở dạng danh sách chờ theo README.

**Khi nên chọn cách khác.** Nếu bạn chỉ dùng một agent cho vài việc đơn giản, chạy trực tiếp Claude Code hay Codex là đủ nhanh. Paperclip đáng thử khi bạn có nhiều agent, nhiều việc lặp lại, cần theo dõi chi phí và muốn có người duyệt trước khi agent hành động. Hãy bắt đầu nhỏ, với một tổ chức thử nghiệm và ngân sách thấp.

## 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à tự chạy được. Tuy nhiên chi phí của các agent bạn gắn vào (như API hay gói thuê bao của từng công cụ) là chuyện riêng. README có nhắc một danh sách chờ cho bản Paperclip Cloud, giá chưa có trong tư liệu.

### Paperclip cần Node phiên bản nào?

package.json của repo yêu cầu Node từ 24.11.0 trở lên. Bạn nên kiểm tra bằng node --version trước khi cài.

### Paperclip có thay thế Claude Code hay Codex không?

Không. Paperclip là lớp điều phối: bạn mang Claude Code, Codex, Cursor, Gemini CLI, OpenClaw và các agent khác vào, rồi giao việc và theo dõi chung. Agent vẫn cần được cài và cấp quyền riêng.

### Có cần GPU không?

Tư liệu không nhắc yêu cầu GPU. Paperclip là server Node.js kèm giao diện React, còn việc nặng do các agent và mô hình bạn chọn đảm nhiệm.

### Chạy được trên Windows không?

README phần mình đọc chưa nói rõ về hệ điều hành. Repo có Dockerfile và dùng Node, nhưng bạn nên xem Quickstart và tài liệu chính thức để xác nhận cách chạy trên Windows.

### Làm sao tránh agent tốn quá nhiều tiền?

Paperclip cho đặt ngân sách theo công ty, agent và dự án, có cảnh báo theo ngưỡng và tự tạm dừng khi chạm giới hạn. README lưu ý việc dừng dựa trên chi tiêu đã ghi nhận nên có thể trễ, vì vậy hãy đặt ngưỡng chừa dư.

### Dữ liệu và khóa bí mật có an toàn không?

README mô tả lưu trữ thông tin xác thực có mã hóa, bí mật theo công ty hoặc từng người, và tách biệt dữ liệu giữa các tổ chức. Mức an toàn thực tế còn phụ thuộc cách bạn cấu hình và nơi bạn chạy; bạn nên đọc thêm tài liệu và tệp SECURITY.md trong repo.
