Paperclip

1. Paperclip là gì?

Paperclip là phần mềm mã nguồn mở để quản lý một "đội nhân viên AI". Bạn đặt mục tiêu, "tuyển" các AI agent (chương trình AI tự làm việc, ví dụ Claude Code, Codex, Cursor, OpenClaw) vào các vị trí như giám đốc, kỹ sư, marketing, rồi theo dõi công việc và chi phí của cả đội trên một bảng điều khiển trong trình duyệt. Dự án tự mô tả: nếu OpenClaw là một nhân viên thì Paperclip là cả công ty.

Bề ngoài nó giống một ứng dụng quản lý công việc. Bên trong có sơ đồ tổ chức, ngân sách hằng tháng cho từng agent, quy trình duyệt, và nhật ký ghi lại mọi việc agent đã làm.

Paperclip miễn phí (giấy phép MIT), tự cài trên máy của bạn, không cần tài khoản Paperclip. Nhưng bản thân các agent thì không miễn phí: mỗi agent dùng một dịch vụ AI, và bạn trả tiền cho dịch vụ đó theo khóa API hoặc gói thuê bao của riêng bạn.

Nói thẳng: đây là công cụ cho người đã dùng AI agent và quen dòng lệnh. Dự án cũng viết rõ Paperclip không phải chatbot, và nếu bạn chỉ có một agent thì nhiều khả năng chưa cần tới nó.

Hợp với bạn nếu:

• Bạn đang chạy nhiều agent cùng lúc và không còn nhớ nổi agent nào đang làm gì.
• Bạn muốn agent tự làm việc theo lịch nhưng vẫn kiểm soát được và có giới hạn chi tiêu.
• Bạn muốn giao việc theo kiểu tạo đầu việc như trong ứng dụng quản lý công việc.

Chưa hợp nếu:

• Bạn muốn một ô chat để hỏi đáp với AI.
• Bạn chưa từng dùng AI agent nào và chưa có khóa API.
• Bạn chỉ có điện thoại. Bảng điều khiển xem được trên điện thoại, nhưng phần máy chủ phải chạy trên máy tính.

2. Cần chuẩn bị gì?

• Máy tính macOS, Linux, hoặc Windows có WSL2. Trình cài chính thức hỗ trợ macOS, Linux và WSL2.
• WSL2 (chỉ cho Windows): tính năng của Windows cho phép chạy Linux ngay trong máy. Hướng dẫn của Microsoft: https://learn.microsoft.com/windows/wsl/install . Sau khi có WSL2, bạn gõ mọi lệnh trong bài này ở cửa sổ Ubuntu.
• Node.js 24.11 trở lên: nền tảng chạy Paperclip. Trình cài chính thức sẽ tự lo việc này; nếu muốn tự cài, tải tại https://nodejs.org
• Khóa API hoặc một agent đã đăng nhập sẵn: ví dụ khóa của Anthropic, OpenAI hoặc OpenRouter, hoặc Claude Code/Codex đã đăng nhập trên máy. Đây là phần tốn tiền; giá do nhà cung cấp quy định.
• Không cần cài cơ sở dữ liệu. Khi chạy trên máy cá nhân, Paperclip tự tạo một cơ sở dữ liệu PostgreSQL nhúng sẵn.
• Git và pnpm 9.15 trở lên: chỉ cần nếu bạn chạy từ mã nguồn (dành cho lập trình viên).

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

Có hai cách chính. Cách A để thử nhanh, không cài gì lâu dài. Cách B là cách dự án khuyên dùng nếu bạn định dùng thật.

Cách A: Thử nhanh bằng một lệnh

Bước 1: Kiểm tra Node.js

node --version

Đúng là khi bạn thấy số phiên bản từ v24.11 trở lên. Nếu thấp hơn hoặc báo lỗi, cài Node.js từ https://nodejs.org hoặc chuyển sang Cách B.

Bước 2: Chạy Paperclip

npx --registry https://registry.npmjs.org paperclipai onboard --yes

Lệnh này tải Paperclip về dùng tạm và tự thiết lập với các lựa chọn mặc định. Đúng là khi cuối cùng màn hình in ra địa chỉ bảng điều khiển (một đường dẫn bắt đầu bằng http://). Mở địa chỉ đó trong trình duyệt.

Cách B: Cài đặt có quản lý (khuyên dùng)

Bước 1: Tải trình cài và file kiểm tra

curl -fsSLO https://paperclip.ing/install.sh
curl -fsSLO https://paperclip.ing/install.sh.sha256

Hai file install.sh và install.sh.sha256 xuất hiện trong thư mục hiện tại.

Bước 2: Kiểm tra file tải về không bị lỗi

Linux và WSL2:

sha256sum -c install.sh.sha256

macOS:

shasum -a 256 -c install.sh.sha256

Đúng là khi màn hình in install.sh: OK.

Bước 3: Chạy trình cài

bash install.sh

Trình cài kiểm tra hệ điều hành, bảo đảm có Node.js 24.11 trở lên, cài lệnh paperclipai, rồi bắt đầu hỏi bạn vài câu thiết lập. Nếu cần quyền quản trị cho lệnh nào, nó in lệnh đó ra và hỏi trước khi chạy. Trong lúc thiết lập, nó hỏi bạn có muốn cho Paperclip chạy nền (tự bật lại khi đăng nhập máy) hay không.

Đúng là khi cuối cùng bạn thấy địa chỉ bảng điều khiển và trình duyệt tự mở trang đó.

Bước 4: Kiểm tra

paperclipai doctor

Lệnh này kiểm tra bản cài, đường dẫn, phiên bản Node.js và trạng thái dịch vụ nền, rồi báo chỗ nào chưa ổn.

Cách C: Chạy từ mã nguồn (cho lập trình viên)

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev

Máy chủ chạy tại http://localhost:3100.

4. Dùng lần đầu

Bước 1: Mở bảng điều khiển

Mở địa chỉ mà trình cài đã in ra. Nếu lỡ đóng cửa sổ và đã cài dịch vụ nền, xem lại trạng thái bằng:

paperclipai service status

Bước 2: Làm theo ba việc cơ bản

Dự án mô tả luồng làm việc gồm ba bước:

1. Đặt mục tiêu. Viết ra điều công ty AI của bạn cần đạt được. Mọi đầu việc sau này đều nối về mục tiêu này, để agent biết vì sao mình làm.
2. Tuyển đội. Thêm các agent vào từng vị trí. Mỗi agent có chức danh, người quản lý trực tiếp và ngân sách tháng.
3. Duyệt và cho chạy. Xem chiến lược agent đề xuất, đặt ngân sách, bấm cho chạy, rồi theo dõi trên bảng điều khiển.

Theo mặc định, agent không chạy liên tục mà "thức dậy" theo lịch hoặc khi có sự kiện (được giao việc, được nhắc tên), kiểm tra việc rồi làm.

Cách thử nhanh có sẵn một agent giám đốc

Nếu muốn một bản thử tách riêng đã có sẵn agent CEO, dùng lệnh test-drive kèm khóa API của bạn (thay dấu ba chấm bằng khóa thật):

ANTHROPIC_API_KEY=... npx paperclipai test-drive

Bản thử này chạy ngay trong cửa sổ dòng lệnh, không cài dịch vụ nền, và chỉ mở trình duyệt khi thiết lập xong. Dữ liệu nằm trong một thư mục tạm; đường dẫn được in ra lúc khởi động.

Lưu ý: Hãy đặt ngân sách thấp cho lần đầu. Khi agent chạm giới hạn, nó dừng lại và các việc đang chờ bị hủy, nhờ vậy bạn không bị tốn tiền ngoài ý muốn.

Hướng dẫn chi tiết từng màn hình nằm ở tài liệu chính thức: https://docs.paperclip.ing

5. Lỗi thường gặp và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
npx báo E404 cho paperclipai	Máy bạn đang trỏ npm tới một kho riêng (thường do công ty cài trong file .npmrc).	Kiểm tra bằng npm config get registry, rồi chạy lại lệnh có kèm --registry https://registry.npmjs.org.
Cảnh báo phiên bản Node.js quá thấp	Paperclip cần Node.js 24.11 trở lên.	Nâng cấp Node.js, hoặc tải install.sh về rồi chạy như Cách B. Đừng dùng dạng gõ một dòng (nối thẳng curl sang bash) để sửa lỗi này, vì dạng đó đòi máy đã có sẵn Node.js đạt yêu cầu.
paperclipai: command not found sau khi cài	Thư mục ~/.local/bin chưa nằm trong PATH.	Thêm dòng export PATH mà trình cài đã in ra vào file khởi động của shell, rồi mở cửa sổ dòng lệnh mới.
paperclipai run từ chối khởi động	Paperclip đã đang chạy dưới dạng dịch vụ nền. Mỗi bản cài chỉ nên có một tiến trình máy chủ.	Dừng dịch vụ trước bằng paperclipai service stop.
Không cài được dịch vụ nền	Máy là container, WSL1, hoặc không có trình quản lý dịch vụ được hỗ trợ.	Không phải lỗi hỏng. Paperclip sẽ hướng dẫn chạy trực tiếp bằng paperclipai run; bạn giữ cửa sổ đó mở khi dùng.
Đã nâng Node.js nhưng dịch vụ nền vẫn báo bản cũ	Dịch vụ nền không đọc cấu hình trong shell của bạn.	Đặt thư mục Node.js mới lên đầu PATH, chạy npx paperclipai@latest install --yes, rồi paperclipai service restart.
Không rõ vì sao không chạy	Cần xem nhật ký.	Chạy paperclipai doctor, sau đó paperclipai service logs -f để xem nhật ký trực tiếp.

6. Gỡ cài đặt / cập nhật

Cập nhật:

paperclipai update

Trước khi đổi sang bản mới, Paperclip tự sao lưu cơ sở dữ liệu và kiểm tra bản mới; nếu lỗi, bản cũ vẫn được giữ. Nếu dịch vụ nền đang tắt, hãy bật nó bằng paperclipai service start trước khi cập nhật để việc sao lưu thực hiện được. Bản mới nhất lúc viết bài là v2026.916.1, phát hành ngày 21/9/2026.

Quay về bản trước:

paperclipai update --rollback

Gỡ:

paperclipai service uninstall
paperclipai uninstall

Hai lệnh này gỡ dịch vụ nền và phần chương trình. Dữ liệu của bạn (cấu hình, cơ sở dữ liệu, file tải lên, nhật ký, khóa bí mật, bản sao lưu) được cố ý giữ lại trong thư mục ~/.paperclip/instances/. Chỉ xóa thư mục đó khi bạn chắc chắn muốn bỏ hẳn mọi thứ, và nên sao lưu trước.

7. Câu hỏi hay gặp

Paperclip có mất tiền không? Phần mềm miễn phí, mã nguồn mở, không cần tài khoản Paperclip. Bạn trả tiền cho các dịch vụ AI mà agent sử dụng, theo khóa API hoặc gói thuê bao của bạn.

Dữ liệu có bị gửi đi đâu không? Dữ liệu công việc nằm trên máy bạn. Tuy nhiên Paperclip thu thập số liệu sử dụng ẩn danh và tính năng này bật sẵn. Dự án cho biết không thu thông tin cá nhân, nội dung đầu việc, câu lệnh cho AI, đường dẫn file hay khóa bí mật. Để tắt, đặt biến môi trường PAPERCLIP_TELEMETRY_DISABLED=1 hoặc DO_NOT_TRACK=1. Ngoài ra, nội dung bạn giao cho agent sẽ đi tới nhà cung cấp AI của agent đó.

Có cần mạng không? Cần để cài đặt và để agent gọi dịch vụ AI.

Tôi có xem được trên điện thoại không? Giao diện dùng được trên điện thoại. Để truy cập từ thiết bị khác, bạn phải thiết lập chế độ có xác thực bằng paperclipai onboard --yes --bind lan hoặc --bind tailnet (dùng Tailscale). Chi tiết xem tài liệu chính thức.

Một bản cài quản lý được nhiều công ty không? Được. Dự án cho biết một bản cài chạy được nhiều công ty, dữ liệu tách biệt hoàn toàn.