# 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ở gồm máy chủ Node.js và giao diện React, dùng để điều phối một đội AI agent như một công ty: có sơ đồ tổ chức, giao việc, ngân sách và phê duyệt. Bạn mang agent của mình đến (Claude Code, Codex, Cursor, Gemini CLI...) rồi theo dõi công việc và chi phí ở một chỗ. Cài cần Node 24.11 trở lên và chút quen thuộc với terminal, không quá khó nhưng không phải kiểu bấm một nút.

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

Paperclip là một ứng dụng mã nguồn mở (máy chủ Node.js kèm giao diện React) để quản lý cả một đội AI agent làm việc cho bạn. Tác giả tóm gọn bằng một câu: nếu OpenClaw là một _nhân viên_ thì Paperclip là _cả công ty_. Bạn đặt mục tiêu, "thuê" agent vào các vị trí, rồi theo dõi công việc và chi phí trên một bảng điều khiển trông giống phần mềm quản lý task.

Repo hợp với ai? Hợp với người đang mở cùng lúc nhiều cửa sổ Claude Code hay Codex và không nhớ nổi con nào đang làm gì. Cũng hợp với chủ doanh nghiệp nhỏ, người làm vận hành, hoặc lập trình viên muốn agent chạy đều, có người duyệt, có giới hạn tiền. Hiện repo có khoảng 113.470 sao và 18.840 fork, giấy phép MIT, viết chủ yếu bằng TypeScript.

Điểm đáng giá nhất là bạn quản lý _mục tiêu_ chứ không quản lý từng dòng lệnh. Mỗi việc là một ticket có luồng trao đổi, lịch sử chạy và ngân sách đi kèm. Mình sẽ đi từ việc nó làm được gì, cài thế nào, đến vài tình huống dùng thật. Bạn 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 | Paperclip là ứng dụng mã nguồn mở giúp giao việc, theo dõi chi phí và quản lý nhiều AI agent (Claude Code, Codex, Cursor...) từ 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ì

Paperclip không phải một agent mới. Nó là lớp quản lý đặt lên trên các agent bạn đã có. README gọi nó là "control plane" (trung tâm điều khiển), không phải một lớp bọc mỏng. Dưới đây là những phần bạn sẽ dùng nhiều nhất.

### Mang agent của bạn vào, kiểu gì 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 và 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ê". Lợi ích thực tế là bạn không bị khoá vào một hãng AI nào, mỗi agent chọn mô hình riêng.

### Sơ đồ tổ chức và giao việc

Agent có chức danh, người báo cáo, mô tả công việc, quyền hạn và ngân sách. Bạn có thể dựng cả CEO, CTO, kỹ sư, thiết kế, marketing. Việc được giao theo cấp bậc, và mỗi task gắn với dự án và mục tiêu của công ty. Nhờ đó agent biết "vì sao" mình làm việc này, không chỉ nhận một tiêu đề trơ trụi.

### Heartbeat: agent tự thức dậy khi có việc

Agent được đánh thức khi có việc mới, có tin nhắn tiếp theo hoặc đến lịch đã đặt. Bạn không phải ngồi canh từng phiên. Hệ thống còn có cơ chế khoá để hai lần chạy không giành cùng một task (README gọi là atomic task checkout).

### Kiểm soát chi phí

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 chạm ngưỡng và tạm dừng ở mức giới hạn. README có nói rõ: việc dừng dựa trên chi tiêu đã 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 trễ một chút. Cần biết điều này để không kỳ vọng quá.

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

Bạn đặt các bước duyệt, phê duyệt việc "thuê" agent mới, tạm dừng, giao lại hoặc dừng hẳn công việc. Thay đổi cấu hình được lưu theo phiên bản và có thể hoàn lại khi làm sai.

### Routine: việc lặp lại theo lịch

Bạn đặt việc định kỳ chạy theo lịch (cron), hoặc kích hoạt qua webhook hay API. Mỗi lần chạy tạo ra một task có người phụ trách và lịch sử. Rất hợp với báo cáo hằng ngày, chăm sóc khách hàng hay đăng bài.

### Kỹ năng, kết nối ứng dụng và nhiều công ty trong một nơi

- **Skill Studio:** cài hoặc tự viết skill dùng chung, thử với dữ liệu đã lưu, xem kết quả và quay lại phiên bản cũ.
- **Apps & Connections:** nối các dịch vụ như GitHub, Notion, Railway hoặc MCP server của bạn. Mỗi hành động đặt ở một trong ba mức: Cho phép, Hỏi trước, hoặc Tắt.
- **Nhiều tổ chức:** một lần triển khai chạy được nhiều công ty, mỗi nơi có task, agent, quyền và lịch sử riêng.
- **Mẫu đội dựng sẵn:** xem trước và cài các đội có sẵn vai trò, skill, dự án, routine. Bạn cũng xuất hoặc nhập cả công ty, README nói có xoá bí mật khi xuất.
- **Dùng trên điện thoại:** giao diện được thiết kế để theo dõi từ xa.

Ngoài ra có tính năng thử nghiệm Agent Chat và kết nối chat hoặc email (Slack, Discord, Telegram, AgentMail), phải bật trong cài đặt thì mới dùng được.

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

Theo tư liệu, bạn cần các thứ sau:

- **Node.js từ 24.11.0 trở lên.** Đây là yêu cầu ghi trong package.json. Bản cũ hơn sẽ không đạt.
- **Git** để tải mã nguồn về.
- **Ít nhất một agent mà bạn định điều khiển**, ví dụ Claude Code hoặc Codex, cùng tài khoản hoặc key của chính agent đó. Paperclip điều phối agent, không thay thế việc bạn có tài khoản AI.
- **Các biến cấu hình** trong file .env.example: DATABASE_URL, PORT, SERVE_UI, BETTER_AUTH_SECRET, PAPERCLIP_TOOL_ACTION_SIGNING_SECRET và PAPERCLIP_SENTRY_RUN_FAILURES.

Repo cũng có sẵn Dockerfile, nên về nguyên tắc bạn có thể chạy bằng Docker. Phần README mình có không nói rõ yêu cầu hệ điều hành hay phần cứng (GPU, RAM), nên mình không khẳng định gì thêm ở đây. Gói npm của dự án tên là paperclip.

```note
Đây là công cụ cho agent chạy tự động và có thể tiêu tiền thật ở các dịch vụ AI. Trước khi bấm chạy, hãy đặt ngân sách cho từng agent, và chỉ cấp cho agent những kết nối thật sự cần. Các giá trị như BETTER_AUTH_SECRET là bí mật: đừng đăng lên mạng hay commit vào Git.
```

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

Một lưu ý trung thực: phần README mình nhận được bị cắt trước khi tới mục Quickstart, nên mình không chép được lệnh cài chính thức. Mình sẽ không đoán lệnh. Thay vào đó, mình chỉ bạn chỗ xem lệnh đúng, còn các lệnh phổ thông thì mình viết ở dưới.

```steps
- Chuẩn bị máy | Cài Node.js từ 24.11.0 trở lên và git
- Tải mã nguồn | Dùng git clone rồi cd vào thư mục dự án
- Làm theo Quickstart | Lấy lệnh cài và chạy chính thức từ README và trang tài liệu
- Tạo file .env | Sao chép .env.example rồi điền các biến cần thiết
- Mở giao diện | Vào địa chỉ máy chủ vừa chạy bằng trình duyệt
```

### Kiểm tra Node.js và git

Mở terminal. Trên Windows, bạn dùng PowerShell hoặc Windows Terminal. Gõ hai lệnh dưới đây. Nếu Node báo phiên bản thấp hơn 24.11.0, hãy cài bản mới hơn trước khi làm tiếp, vì đây là chỗ người mới hay vấp nhất.

```bash
node --version
git --version
```

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

Lệnh đầu tải repo, lệnh sau đi vào thư mục vừa tải. Mọi lệnh sau này phải chạy _trong thư mục này_, nếu không terminal sẽ báo không tìm thấy gì.

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

### Lấy lệnh cài chính thức

Repo dùng pnpm workspace (có file pnpm-workspace.yaml và pnpm-lock.yaml) và package.json khai báo các lệnh chạy. README có mục Quickstart ở dòng điều hướng đầu trang, và dự án có trang tài liệu riêng. Hãy mở mục Quickstart đó và chép đúng lệnh cài và chạy mà tác giả ghi. Nếu bạn muốn tự xem các lệnh sẵn có, mở file package.json trong thư mục gốc và đọc phần scripts.

Mình không ghi lệnh cài ở đây vì tư liệu mình có không chứa nó, và đoán sai một cờ lệnh có thể làm bạn mất cả buổi.

### Tạo file .env

Repo có file mẫu .env.example. Cách phổ thông là sao chép nó thành .env rồi mở bằng trình soạn thảo để điền. Trên PowerShell:

```powershell
Copy-Item .env.example .env
```

Trên macOS hoặc Linux:

```bash
cp .env.example .env
```

Trong file này, hãy chú ý mấy biến sau:

- **DATABASE_URL:** chỗ chứa dữ liệu của Paperclip.
- **PORT:** cổng mà máy chủ lắng nghe.
- **SERVE_UI:** liên quan đến việc có phục vụ giao diện web hay không.
- **BETTER_AUTH_SECRET** và **PAPERCLIP_TOOL_ACTION_SIGNING_SECRET:** các chuỗi bí mật. Hãy tự đặt giá trị riêng, đừng dùng lại chuỗi ví dụ.

Ý nghĩa chi tiết từng biến mình không có trong tư liệu, nên hãy đọc chú thích trong chính file .env.example và trang tài liệu.

### Chạy và mở giao diện

Sau khi chạy máy chủ theo Quickstart, mở trình duyệt vào địa chỉ máy chủ đang lắng nghe (liên quan đến PORT bạn đặt). README nói Paperclip có hai chế độ triển khai: "trusted local" (tin cậy, chạy trên máy bạn) và "authenticated" (có đăng nhập). Nếu chỉ thử trên máy cá nhân, chế độ local là chỗ hợp lý để bắt đầu.

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

Tư liệu mình có không mô tả một lệnh "kiểm tra" chính thức, nên mình đưa ra dấu hiệu hợp lý dựa trên cách repo vận hành:

1. Terminal chạy máy chủ không báo lỗi đỏ và không tự thoát ngay.
2. Trình duyệt mở được địa chỉ máy chủ và bạn thấy giao diện Paperclip (trông như một bảng quản lý task).
3. Bạn tạo được một công ty và một mục tiêu đầu tiên trong giao diện.
4. Sau khi nối một agent (ví dụ Claude Code), một task nhỏ được giao thì agent thức dậy, chạy và để lại lịch sử chạy trong task.

Nếu đến bước 4 mà agent không phản hồi, hãy xem phần lỗi hay gặp ở dưới. Cách đối chiếu chắc nhất vẫn là so với mô tả trong mục Quickstart của dự án.

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

Dưới đây là bốn tình huống bám đúng các khả năng README nêu. Tên vai trò và nội dung task là ví dụ của mình để bạn hình dung, không phải mẫu có sẵn trong repo.

### Chủ shop online: báo cáo mỗi sáng không cần nhớ

Bạn bán hàng trên mạng, mỗi sáng muốn có bản tổng hợp tình hình. Bạn tạo một routine đặt lịch chạy hằng ngày và giao cho một agent. Nội dung task có thể viết như sau:

```text
Mỗi sáng, tổng hợp những việc cần xử lý trong ngày và ghi vào một tài liệu ngắn.
Nêu rõ việc nào cần tôi duyệt.
```

Mỗi lần chạy, Paperclip tạo ra một task có người phụ trách và lịch sử. Bạn mở bảng điều khiển trên điện thoại, đọc tài liệu agent tạo ra và để lại bình luận ngay trên đoạn cần sửa. Bạn không phải nhớ bấm chạy.

### Lập trình viên đang mở 20 cửa sổ Claude Code

Bạn có nhiều việc song song và đã mất dấu việc nào đang ở đâu. Hãy chuyển từng việc thành một task trong Paperclip, giao cho agent phù hợp, và gắn vào cùng một dự án. Hội thoại, kế hoạch, vật cản và lịch sử chạy nằm trong từng task. README cũng nói phiên làm việc được lưu lại qua các lần chạy nếu adapter hỗ trợ, nên khởi động lại máy không làm bạn mất bối cảnh.

Kết quả: thay vì nhìn 20 tab, bạn nhìn một danh sách task có trạng thái và duyệt kết quả qua diff, ảnh chụp màn hình hay test (theo mô tả trong README).

> Quản lý mục tiêu, đừng quản lý từng dòng lệnh.
>
> — Ông T

### Người quản lý lo chi phí token

Bạn sợ một vòng lặp lỗi đốt hết hạn mức mà không hay. Hãy đặt ngân sách theo agent và theo dự án, bật ngưỡng cảnh báo và giới hạn dừng. Khi chi tiêu chạm ngưỡng, Paperclip cảnh báo và tạm dừng công việc ở mức đã đặt. Nhớ rằng lệnh dừng dựa trên chi tiêu đã ghi nhận nên vẫn có thể trễ chút, vì vậy hãy đặt giới hạn thấp hơn số tiền bạn thật sự chấp nhận mất.

### Người làm vận hành: nhân bản đội đã chạy tốt

Bạn dựng được một đội ổn (vai trò, skill, routine) và muốn dùng lại cho công ty thứ hai hoặc chia sẻ cho đồng nghiệp. README nói bạn có thể xuất và nhập cả tổ chức, agent và skill, kèm xoá bí mật và xử lý trùng tên. Bạn cũng có thể xem trước và cài các đội dựng sẵn rồi tự chọn runtime. Kết quả là bạn không phải dựng lại từ đầu mỗi lần.

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

### Báo phiên bản Node không đạt

Dự án yêu cầu Node từ 24.11.0 trở lên. Nếu máy bạn đang dùng bản cũ hơn, lệnh cài hoặc chạy có thể báo lỗi ngay. Chạy `node --version` để kiểm tra, rồi nâng Node lên bản đủ mới, sau đó mở terminal mới và chạy lại.

### Máy chủ không lên vì thiếu hoặc sai biến trong .env

Các biến như DATABASE_URL và BETTER_AUTH_SECRET có vẻ là thứ máy chủ cần để chạy. Nếu bạn chưa tạo file .env hoặc để trống, máy chủ có thể báo lỗi lúc khởi động. Hãy đọc kỹ thông báo trong terminal, đối chiếu với .env.example và điền lại. Đừng dán giá trị bí mật vào chỗ công khai khi nhờ người khác giúp.

### Cổng đã bị chương trình khác dùng

Nếu một ứng dụng khác đang chiếm cổng, máy chủ sẽ không mở được. Hãy đổi giá trị PORT trong .env sang số khác rồi chạy lại, và nhớ mở trình duyệt đúng cổng mới.

### Agent được "thuê" nhưng không làm gì

Paperclip chỉ điều phối. Agent bên dưới (Claude Code, Codex...) vẫn phải được cài và đăng nhập sẵn trên máy chạy Paperclip. Hãy chạy thử agent đó riêng, ngoài Paperclip, để chắc là nó hoạt động. Rồi mới xem lại cách nối adapter trong tài liệu.

### Chi phí tăng nhanh hơn dự kiến

Agent chạy tự động có thể tiêu token liên tục. Hãy đặt ngân sách và ngưỡng cảnh báo từ đầu, đặt giới hạn thấp hơn mức bạn chịu được, và với kết nối nhạy cảm thì để ở mức "Hỏi trước" thay vì "Cho phép".

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

**Điểm mạnh:**

- Gom nhiều agent khác hãng vào một bảng điều khiển, không bị khoá vào một nhà cung cấp.
- Có sẵn những thứ bạn sẽ phải tự dựng: giao việc, phân quyền, phê duyệt, ngân sách, lịch chạy, lịch sử hoạt động.
- Mã nguồn mở, giấy phép MIT, được cập nhật trong vài tháng gần đây và có cộng đồng rất lớn.
- Hỗ trợ nhiều tổ chức trong một lần triển khai, hợp với người làm cho nhiều khách hàng hay nhiều dự án.

**Giới hạn cần biết:**

- Đây là một hệ thống lớn (máy chủ, giao diện, cơ sở dữ liệu, nhiều khái niệm), nên không đơn giản như cài một tiện ích nhỏ. Người hoàn toàn mới với terminal sẽ cần thời gian làm quen.
- Nó không thay thế các agent: bạn vẫn phải có tài khoản và chịu chi phí của các dịch vụ AI bên dưới.
- Một số tính năng như Agent Chat và kết nối chat hoặc email còn ở mức thử nghiệm.
- Việc dừng theo ngân sách dựa trên chi tiêu đã ghi nhận, nên không phải "ngắt tức thì".

**Khi nào chọn cách khác:** nếu bạn chỉ dùng một agent cho một việc đơn lẻ, cứ dùng trực tiếp agent đó, đừng thêm một lớp quản lý. Paperclip đáng cân nhắc khi bạn bắt đầu có nhiều agent, nhiều việc chạy song song, cần người duyệt và cần kiểm soát tiền. Lúc đó nó giúp bạn bớt cảnh "chạy một đống script rời rạc".

## 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, tức là bạn tải và dùng tự do. Tuy nhiên các agent và mô hình AI bên dưới (Claude Code, Codex...) có chi phí riêng theo nhà cung cấp. README có nhắc đến một danh sách chờ cho bản Paperclip Cloud, nhưng mình chưa có thông tin về giá.

### Paperclip khác gì việc tự mở nhiều cửa sổ Claude Code?

Paperclip biến mỗi việc thành một task có hội thoại, lịch sử chạy, ngân sách và người phụ trách, thay vì nhiều tab rời rạc. README nói phiên làm việc được lưu lại qua các lần chạy nếu adapter hỗ trợ. Bạn cũng có thêm sơ đồ tổ chức, bước phê duyệt và routine chạy theo lịch.

### Cài Paperclip cần yêu cầu gì?

package.json yêu cầu Node.js từ 24.11.0 trở lên. Bạn cũng cần git để tải mã và các biến trong file .env.example. Phần tư liệu mình có chưa nói rõ về hệ điều hành hay phần cứng, nên chưa có thông tin về GPU hay RAM tối thiểu.

### Paperclip chạy đượ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ó tiến trình tự viết, endpoint HTTP và gói adapter bên ngoài. Nguyên tắc chung là agent nào nhận được heartbeat thì dùng được.

### Có kiểm soát được chi phí và quyền của agent không?

Có. Bạn đặt ngân sách theo công ty, agent hoặc dự án, nhận cảnh báo theo ngưỡng và tạm dừng ở giới hạn. Với kết nối ứng dụng, mỗi hành động đặt được ở mức Cho phép, Hỏi trước hoặc Tắt. README lưu ý việc dừng dựa trên chi tiêu đã ghi nhận nên có thể trễ một chút.

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

README nói có lưu trữ thông tin xác thực được mã hoá, tham chiếu bí mật thay vì chép giá trị vào cấu hình agent, và kiểm tra quyền theo từng công ty. Có hai chế độ triển khai: tin cậy cục bộ hoặc có xác thực. Mình chưa có thông tin kiểm định bảo mật độc lập, nên bạn nên đọc file SECURITY.md trong repo trước khi dùng cho dữ liệu nhạy cảm.

### Có dùng được trên điện thoại không?

README ghi tính năng "Mobile Ready", cho phép theo dõi và quản lý từ xa. Tư liệu mình có chưa mô tả chi tiết cách truy cập, nên bạn xem thêm trong tài liệu của dự án.
