Hầu hết các nhà phát triển khi vận hành nhiều tác nhân AI đều vướng cùng một trở ngại ở tác nhân thứ năm. Bạn có Claude Code trong một terminal viết lại dịch vụ backend, Codex ở terminal khác tạo bộ kiểm thử, Cursor chỉnh sửa thành phần, và ba tab khác bị quên lãng. Không ai biết ai đang làm gì. Chi phí tăng vọt. Hai tác nhân làm trùng lặp công việc. Một tác nhân chạy sáu tiếng không tạo ra kết quả vì thiếu mục tiêu rõ ràng.
Paperclip giải quyết vấn đề này. Đây là nền tảng điều phối mã nguồn mở biến các tác nhân AI rời rạc thành một công ty có cấu trúc: sơ đồ tổ chức, vai trò, quản lý tác vụ, giới hạn ngân sách và nhật ký kiểm toán. Paperclip đã đạt hơn 35.000 sao GitHub trong ba tuần—chứng minh nhu cầu thực sự từ cộng đồng.
Bài viết này hướng dẫn bạn thiết lập, tổ chức công ty tác nhân đầu tiên và vận hành để các tác nhân AI làm việc hiệu quả mà không cần giám sát thủ công từng terminal.
Paperclip là gì (và không phải là gì)
Trước khi cài đặt, hãy hiểu sản phẩm bạn sẽ dùng.
Paperclip là lớp điều phối. Nó điều phối, theo dõi tác nhân, quản lý ngân sách, cung cấp ngữ cảnh mục tiêu. Nó không xây dựng tác nhân, thay thế nhà cung cấp AI, hoặc bổ sung giao diện chat.
Nhóm Paperclip: "Nếu Claude Code là nhân viên, Paperclip là công ty".
Tức là:
- Tác nhân có vai trò (không chỉ lời nhắc)
- Tác vụ có chủ sở hữu (không chỉ terminal mở)
- Ngân sách có giới hạn cứng (không cảm tính)
- Mọi thứ đều có dấu vết kiểm toán
Paperclip hoạt động với Claude Code, OpenAI Codex, Cursor, Gemini CLI và bất kỳ tác nhân nào nhận webhook hoặc heartbeat. Bạn cung cấp tác nhân, Paperclip điều phối.
Paperclip không phải là:
- Giao diện chatbot
- Công cụ kéo-thả workflow như n8n/Zapier
- Framework viết tác nhân
- Hữu ích cho trường hợp chỉ một tác nhân
Nếu chỉ chạy một tác nhân AI, Paperclip là thừa. Nếu vận hành ba tác nhân trở lên, đây là mảnh ghép còn thiếu.
Cài đặt Paperclip
Yêu cầu: Node.js 20+, pnpm 9.15+. Paperclip tích hợp sẵn PostgreSQL nhúng, không cần setup DB ngoài.
Khởi động nhanh:
npx paperclipai onboard --yes
Lệnh trên tải CLI, chạy onboarding với thiết lập mặc định và khởi động server trên cổng 3100. Truy cập http://127.0.0.1:3100 để vào dashboard.
Đóng góp hoặc tìm hiểu mã nguồn:
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
Chạy bằng Docker:
docker compose -f docker-compose.quickstart.yml up --build
Cấu trúc thư mục trên đĩa:
~/.paperclip/instances/default/
config.json — cấu hình server
db/ — dữ liệu PostgreSQL nhúng
secrets/master.key — key mã hóa
logs/ — nhật ký server
data/storage/ — tệp đính kèm
workspaces/<agent>/ — thư mục làm việc riêng cho mỗi tác nhân
Chế độ local dùng xác thực local_trusted mặc định, không yêu cầu đăng nhập, dùng user "Board". Có thể dùng dashboard ngay, không cần tạo tài khoản.
Kiểm tra sức khỏe:
paperclipai doctor
Tự động sửa lỗi cài đặt:
paperclipai doctor --repair
Thiết lập công ty đầu tiên
Trong Paperclip, "công ty" là vùng chứa cấp cao nhất cho tác nhân, tác vụ, mục tiêu và ngân sách. Hãy coi đây là dự án mà mỗi thành viên là một tác nhân AI có vai trò và báo cáo rõ ràng.
Từ dashboard, tạo công ty mới và đặt tuyên bố sứ mệnh. Đây là ngữ cảnh cho mọi tác vụ—tác nhân sẽ hiểu tại sao phải làm, không chỉ làm gì. Điều này quan trọng với các phiên chạy dài.
Ví dụ sứ mệnh:
"Xây dựng và duy trì API REST quản lý đơn hàng khách hàng. Ưu tiên tính đúng đắn hơn tốc độ. Ghi lại mọi endpoint công khai."
Thêm tác nhân đầu tiên
Mỗi tác nhân có một bộ điều hợp xác định công cụ AI và phương thức giao tiếp.
Bảng các bộ điều hợp hỗ trợ:
| Tác nhân | Loại adapter | Gói |
|---|---|---|
| Claude Code | claude_local |
@paperclipai/adapter-claude-local |
| OpenAI Codex | codex_local |
@paperclipai/adapter-codex-local |
| Gemini CLI | gemini_local |
@paperclipai/adapter-gemini-local |
| Cursor | cursor |
@paperclipai/adapter-cursor-local |
| HTTP webhooks | HTTP adapter | endpoint tùy chỉnh |
Thêm tác nhân Claude Code qua CLI:
paperclipai agent local-cli "Kỹ sư Backend" --company-id <id-công-ty>
Lệnh này khởi động tác nhân, cài đặt kỹ năng tại ~/.claude/skills, tạo API credentials. Tác nhân sẽ xuất hiện trên sơ đồ tổ chức và nhận nhiệm vụ.
Cấu hình tác nhân Claude:
| Trường | Chức năng |
|---|---|
model |
Tên model Claude (vd: claude-sonnet-4-6) |
cwd |
Thư mục làm việc (tự tạo nếu thiếu) |
promptTemplate |
Prompt hệ thống với biến {{biến}}
|
maxTurnsPerRun |
Lượt chạy tối đa mỗi heartbeat (mặc định: 300) |
timeoutSec |
Timeout cứng (0 = không giới hạn) |
Chia mô hình theo vai trò để tiết kiệm chi phí:
- CEO/điều phối: Sonnet (chi phí cao, xứng đáng)
- Quản lý: Haiku (rẻ, nhanh)
- Lập trình/IC sáng tạo: Sonnet (chất lượng quan trọng)
- IC công thức: Haiku (tạo mã mẫu, test, migrate)
Cách chia này giúp giảm 40-60% chi tiêu hàng tháng so với chạy Sonnet ở mọi nơi mà vẫn đảm bảo chất lượng.
Cấu trúc tổ chức tác nhân
Ví dụ cấu trúc cho dự án phần mềm nhỏ:
CEO (Sonnet)
├── CTO (Haiku)
│ ├── Kỹ sư Backend (Sonnet)
│ ├── Kỹ sư Frontend (Sonnet)
│ └── Kỹ sư QA (Haiku)
└── Chuyên viên viết tài liệu kỹ thuật (Haiku)
CEO chia nhỏ sứ mệnh thành mục tiêu. CTO phân phối mục tiêu cho kỹ sư. Kỹ sư thực thi. QA kiểm thử. Writer viết tài liệu.
Mỗi tác nhân có khoảng thời gian heartbeat—tần suất kiểm tra tác vụ, thực hiện, nghỉ. Không chạy liên tục: ngủ-dậy-làm-ngủ. Điều này giữ chi phí thấp.
Gợi ý khoảng thời gian:
- Lập trình: 600 giây (10 phút)
- Theo yêu cầu: 86.400 giây (1 ngày) + đánh thức theo yêu cầu
- Tối thiểu an toàn: 30 giây (thấp hơn dễ vượt chi phí & spam)
Heartbeat hoạt động thế nào
Mỗi lần tác nhân thức dậy, thực hiện quy trình 9 bước:
- Xác thực qua
GET /api/agents/me - Xử lý callback phê duyệt chờ
- Lấy tác vụ từ
GET /api/companies/{companyId}/issues - Ưu tiên: tác vụ đang làm trước, sau đó tác vụ mới; bỏ qua task bị chặn
- Checkout task:
POST /api/issues/{issueId}/checkout(đã có tác nhân khác thì bỏ qua) - Đọc ngữ cảnh và các comment
- Thực thi công việc
- Cập nhật task bằng comment và trạng thái mới
- Ủy quyền sub-task nếu cần (parent & goal ID)
Bước 5 ngăn chặn trùng lặp: hai tác nhân không thể nhận cùng một task. Nếu task đã bị nhận, tác nhân thứ hai bỏ qua.
Paperclip truyền ngữ cảnh qua biến môi trường mỗi heartbeat:
PAPERCLIP_TASK_ID # Task kích hoạt lần chạy
PAPERCLIP_WAKE_REASON # Lý do wake up (time, mention, assignment)
PAPERCLIP_AGENT_ID # ID tác nhân
PAPERCLIP_API_URL # URL API callback Paperclip
Tác nhân dùng các biến này để cập nhật, tạo sub-task, xin phê duyệt, ủy quyền—all trong một heartbeat.
Giao nhiệm vụ & theo dõi công việc
Tác vụ Paperclip = GitHub Issue + quản lý dự án.
Tạo tác vụ từ CLI:
paperclipai issue create \
--company-id <id> \
--title "Thêm phân trang vào endpoint đơn hàng" \
--assignee-agent-id <id-backend>
Tác vụ có thể có:
- Tác vụ cha: chia nhỏ task lớn
- Liên kết mục tiêu: biết mục tiêu công ty
- Bình luận: cung cấp ngữ cảnh, phê duyệt, cập nhật
- @-mention: đánh thức tác nhân lập tức (không đợi heartbeat)
Xem danh sách tác vụ đang mở:
paperclipai issue list
Hoặc xem trực tiếp trên dashboard với thông tin chủ sở hữu, trạng thái, thời điểm heartbeat cuối.
Kiểm soát ngân sách hiệu quả
Tính năng quan trọng: mỗi tác nhân có ngân sách token/tháng. Đạt 80% chỉ làm task quan trọng. Đạt 100% tạm dừng.
Thiết lập ngân sách: cấu hình trong agent config. Đề xuất: $20-50/tháng/role. Theo dõi usage, chi phí/heartbeat, tổng chi qua dashboard.
Dashboard giúp bạn xác định tác nhân hiệu quả/có vấn đề. Nếu chi phí/heartbeat tăng, thường do prompt mơ hồ hoặc task quá rộng. Sửa bằng phân công chặt hơn, không tăng budget.
Nếu không kiểm soát, tác nhân sai cấu hình với interval 30s + Extended Thinking có thể đốt hàng trăm đô chỉ sau vài giờ. Paperclip tự động ngăn chặn điều đó.
Kỹ năng thời gian chạy: dạy quy trình mới cho tác nhân mà không cần đào tạo lại
Tính năng mạnh: chèn kỹ năng. Khi tác nhân chạy, adapter Paperclip tạo symlink tới file SKILL.md trong thư mục kỹ năng và truyền qua --add-dir. Tác nhân đọc kỹ năng như ngữ cảnh và tuân theo quy trình.
Bạn dạy quy trình bằng Markdown—không cần viết lại prompt, không deploy lại!
Ví dụ kỹ năng:
# KỸ NĂNG: Di chuyển cơ sở dữ liệu
Khi tạo một di chuyển:
1. Không bao giờ sửa đổi tệp di chuyển hiện có
2. Sử dụng tên mô tả: YYYYMMDD_mo_ta.sql
3. Bao gồm SQL lên và xuống
4. Kiểm tra cục bộ trước khi commit
5. Thêm bình luận giải thích lý do kinh doanh
Lưu vào thư mục kỹ năng, gán cho agent backend, mọi heartbeat sau sẽ tuân theo quy trình này.
Nếu bạn kiểm thử API do tác nhân xây dựng
Khi tác nhân backend xây dựng API, bạn cần kiểm thử nhanh. Apidog là lựa chọn tự nhiên: thiết kế API, server giả lập, kiểm thử tự động—all-in-one. Khi agent backend gửi endpoint, bạn xác thực tức thì, không cần chuyển đổi giữa Swagger, Postman và các công cụ giả lập.
Có thể tự động tạo test suite từ OpenAPI spec, chạy với output agent, trả kết quả lại dưới dạng comment task. Agent sẽ nhận và sửa lỗi ở heartbeat tiếp theo. Vòng lặp từ code → test → fix hoàn toàn tự động.
Apidog hỗ trợ REST, GraphQL, gRPC và miễn phí để bắt đầu.
Quản lý nhiều phiên bản
Paperclip hỗ trợ nhiều instance độc lập qua biến môi trường PAPERCLIP_INSTANCE_ID hoặc cờ --instance. Mỗi instance có config, DB, cổng, workspace riêng.
Tạo worktree dev cho mỗi branch git:
paperclipai worktree:make feature/orders-pagination
Bạn có các cổng, config, DB biệt lập cho branch đó. Có thể chạy công ty thử nghiệm cho code mới mà không ảnh hưởng tới production. Khi xong chỉ cần hủy, không để lại dấu vết.
Mô hình thiết lập đa tác nhân hiệu quả
Một số mô hình thực tiễn khi đã quen Paperclip:
- Thác mục tiêu: Viết mục tiêu cấp công ty, agent CEO chia nhỏ thành mục tiêu dự án, manager chia thành task. Tác nhân hiểu chuỗi mục đích, làm việc tốt hơn nhận chỉ thị rời rạc.
- Cổng phê duyệt: Mọi tác vụ động chạm tới production/staging/thanh toán cần cấu hình cổng phê duyệt. Agent tạm dừng, gửi thông báo, chờ bạn duyệt trước khi tiếp tục. Ngăn sự cố tốn kém.
- Đánh thức theo yêu cầu qua @-mention: Đặt interval heartbeat chậm, dùng mention để đánh thức tác nhân khi cần—phản hồi nhanh, không tốn token polling liên tục.
-
Workspace riêng biệt: Mỗi agent có thư mục riêng dưới
workspaces/<agent-id>/. Không nên chia sẻ workspace—dễ sinh xung đột. Tách biệt là mặc định; hãy tận dụng.
Bắt đầu chỉ mất ~15 phút
Quy trình onboarding chưa tới 15 phút: một lệnh cài đặt, khởi động server. Thêm agent đầu tiên, tạo task chỉ mất thêm 5 phút.
Phần khó là cấu trúc công ty tốt: viết sứ mệnh rõ ràng, chọn model phù hợp cho từng role, đặt limit ngân sách hợp lý. Dành 30 phút setup kỹ, hiệu quả tác nhân sẽ vượt trội so với việc “kết nối cho xong”.
Nếu bạn đang chạy hơn 2 tác nhân AI trên bất kỳ dự án nào, hãy dành một buổi chiều thiết lập. Sự khác biệt giữa mỗi agent một terminal và một công ty có sơ đồ, ngân sách, quyền sở hữu task, audit log… là sự khác biệt giữa một side-project và một hệ thống có thể tự vận hành không cần giám sát.
Top comments (0)