Bạn đã biết Paperclip giải quyết vấn đề gì và vận hành thế nào bên trong. Bây giờ hãy cài đặt nó. Trong bài này, bạn sẽ đi từ một terminal trống đến một CEO agent đang chạy heartbeat đầu tiên — 7 bước, 15 phút.
Mỗi bước trong bài đều có 2 cách thực hiện: qua giao diện UI (phù hợp cho lần đầu) và qua CLI (phù hợp khi đã quen hoặc cần tự động hóa). Bạn chọn cách nào cũng được — kết quả giống nhau.
Yêu cầu hệ thống — Bạn cần đúng 3 thứ
Trước khi bắt đầu, kiểm tra máy bạn có 3 thứ sau:
- Node.js 20 trở lên — kiểm tra bằng
node --version. Nếu chưa có hoặc version cũ, cài qua nvm:nvm install 20. - pnpm 9.15 trở lên — package manager cho monorepo. Cài nhanh:
npm install -g pnpm. Kiểm tra:pnpm --version. - Một API key từ Anthropic — Paperclip cần một LLM adapter để agent thực thi. Bài này dùng Claude (Anthropic) làm ví dụ. Bạn cũng có thể dùng GPT-4, Gemini, hoặc model chạy local — nhưng Claude cho kết quả ổn định nhất với Paperclip hiện tại.
Vậy thôi. Không cần Docker. Không cần cài PostgreSQL riêng. Không cần tài khoản AWS hay bất kỳ cloud provider nào. Paperclip tự quản lý embedded database và storage trên máy bạn.
Nếu bạn đã có Node.js và một terminal mở sẵn — bạn thiếu đúng 1 thứ: pnpm.
Cài đặt Paperclip — Clone, install, chạy
Có hai cách cài đặt. Chọn cách phù hợp với bạn.
Cách 1 — Nhanh nhất (1 lệnh, không cần clone):
npx paperclipai onboard --yes
Lệnh này tải Paperclip CLI, chạy onboarding wizard với config mặc định (embedded PostgreSQL, port 3100, không authentication), rồi tự động khởi động server. Xong.
Cách 2 — Clone repo (khuyến nghị nếu bạn muốn đọc source):
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
Sau khi pnpm install xong (khoảng 1-2 phút tùy mạng), khởi động server:
pnpm dev
pnpm dev khởi động API server và UI ở chế độ development với watch mode. Embedded PostgreSQL được tạo tự động — không cần setup database riêng.
Nếu bạn muốn kiểm soát từng phần — chọn external PostgreSQL thay vì embedded, đổi port, cấu hình S3 storage — chỉnh trực tiếp trong ~/.paperclip/instances/default/config.json hoặc chạy lại pnpm paperclipai onboard. Nhưng cho lần đầu, defaults là đủ.
Paperclip tạo folder ~/.paperclip/instances/default/ chứa mọi thứ cần thiết:
config.json— cấu hình server, database, storagedb/— embedded PostgreSQL data. Không cần cài PostgreSQL riêng — Paperclip bundle sẵn.secrets/master.key— mã hóa API keys và credentialslogs/— server logs
Khi terminal hiện dòng Listening on http://127.0.0.1:3100, server đã sẵn sàng. Mở browser, truy cập http://localhost:3100.
Một điều đáng chú ý: toàn bộ dữ liệu nằm trên máy bạn. Không có cloud service nào được gọi ở bước này. Server chạy local, database chạy local, UI serve từ cùng process. Bạn có thể chạy Paperclip hoàn toàn offline (trừ lúc agent cần gọi LLM API).
Nếu port 3100 đã bị dùng, Paperclip sẽ báo lỗi. Xem phần Troubleshooting cuối bài.
Onboarding Wizard — Tạo company, agent, và task đầu tiên qua UI
Khi mở http://localhost:3100 lần đầu tiên, Paperclip không hiện dashboard trống. Thay vào đó, một Onboarding Wizard xuất hiện và hướng dẫn bạn qua 4 bước để tạo company, agent đầu tiên, và giao task ngay lập tức. Đây là cách nhanh nhất để bắt đầu.
Bước 1 — Đặt tên company
Wizard yêu cầu bạn nhập tên cho company. Ví dụ “My AI Team” hoặc tên project của bạn.
Company trong Paperclip là một workspace cách ly hoàn toàn. Mỗi company có agents, tasks, budget, và audit trail riêng. Agents trong company A không biết company B tồn tại — giống như hai công ty khác nhau dùng chung một tòa nhà văn phòng.
Trong thực tế, nhiều team dùng mỗi company cho một project riêng: “E-commerce Backend”, “Mobile App”, “Data Pipeline”. Cách ly dữ liệu, cách ly ngân sách, cách ly quyền truy cập. Agent trong project A không bao giờ vô tình đọc code của project B — Paperclip enforce ranh giới này ở tầng API.
Bước 2 — Tạo agent đầu tiên
Wizard chuyển sang màn hình tạo agent. Bạn đặt tên — ví dụ “CEO” — và chọn model (Claude Opus, Claude Sonnet, GPT, v.v.). Claude Code và Codex được hiển thị là recommended adapters, các loại khác collapse bên dưới. Wizard tự động kiểm tra adapter environment — nếu thành công sẽ hiện animation xanh, nếu thất bại sẽ hiện debug output.
Click Next để tiếp tục.
Adapter là gì? Trong bài trước, chúng tôi giải thích Paperclip là control plane — nó tổ chức, không thực thi. Adapter là “cơ bắp” thực thi: nơi LLM thực sự chạy. claude_local gọi Claude qua Anthropic API trên máy bạn. Paperclip cũng hỗ trợ codex_local (OpenAI Codex), cursor (Cursor IDE), gemini_local (Google Gemini, từ v0.3.1), openclaw_gateway (OpenClaw), và custom HTTP adapter cho bất kỳ model nào.
Bước 3 — Giao task đầu tiên cho CEO
Wizard hiện form để bạn nhập task đầu tiên. Có sẵn placeholder text mặc định — nội dung yêu cầu CEO tự tạo metadata files cho mình: AGENTS.md, SOUL.md, HEARTBEAT.md, TOOLS.md. Bạn có thể dùng mặc định này hoặc nhập task khác.
Bước 4 — Publish issue
Click Publish (hoặc Create Issue) để giao task cho CEO. Task được tạo và assign cho agent.
Sau khi publish, Paperclip tự trigger heartbeat cho CEO. Agent thức dậy, đọc task, bắt đầu làm việc. Bạn có thể theo dõi tiến trình trong dashboard và inbox.
Khi CEO hoàn thành task đầu tiên, bạn sẽ thấy reply trong Inbox — thường là CEO đề xuất hire thêm agent (ví dụ engineer) và cần Board approval từ bạn. Click Approve để duyệt.
Vậy là xong — 4 bước trên UI, không cần gõ lệnh nào cả.
Cách làm tương tự qua CLI (cho power users)
Nếu bạn muốn dùng terminal thay vì UI — hoặc cần tự động hóa quy trình — đây là cách thực hiện cùng những bước trên bằng CLI.
Tạo agent:
pnpm paperclipai agent local-cli ceo --company-id <company-id>
Lệnh này tạo agent “ceo” với adapter claude_local. Terminal sẽ hiện env vars block — copy và paste vào terminal:
export PAPERCLIP_API_URL='http://127.0.0.1:3100'
export PAPERCLIP_COMPANY_ID='<your-company-id>'
export PAPERCLIP_AGENT_ID='<your-agent-id>'
export PAPERCLIP_API_KEY='pcp_...'
Lệnh local-cli còn cài Paperclip skills vào ~/.claude/skills/ — tập hợp instructions dạy agent cách follow heartbeat protocol, cách checkout task, cách comment kết quả, cách escalate khi bị stuck. Không có skills, agent không biết mình là thành viên của một “công ty”. Có skills, agent biết chính xác vai trò của mình và quy trình phải tuân thủ.
Tạo task:
pnpm paperclipai issue create \
--company-id <company-id> \
--title "Tạo file hello-world.md" \
--description "Tạo một file hello-world.md với nội dung giới thiệu ngắn về project." \
--status todo \
--assignee-agent-id <agent-id>
Trigger heartbeat thủ công:
pnpm paperclipai heartbeat run --agent-id <agent-id>
Terminal bắt đầu stream log real-time. Agent thức dậy, gọi GET /api/agents/me xác nhận danh tính, GET /api/agents/me/inbox-lite kiểm tra task, POST /api/issues/{id}/checkout để claim task. Quá trình mất khoảng 30-90 giây tùy độ phức tạp.
Trong production, heartbeat chạy tự động — theo interval hoặc event-driven. Ở đây bạn trigger thủ công để quan sát toàn bộ quy trình.
Cấu hình agent sau khi tạo — Tuỳ chỉnh trên UI
Dù bạn tạo agent qua wizard hay CLI, bạn đều có thể chỉnh sửa cấu hình sau đó trên UI. Vào company → chọn agent → mở trang settings. Giao diện chia thành các tab:
Agent Settings: Đổi tên (ví dụ từ “CEO” thành tên cụ thể), đặt title hiển thị trên org chart, mô tả capabilities (agent làm được gì — giúp các agents khác biết nên delegate cho ai).
Adapter: Chọn adapter type (Claude Code, Codex, Cursor, OpenCode, v.v.), cấu hình working directory (dùng absolute path), trỏ đến agent instruction file (đường dẫn đến AGENTS.md).
Config: Chọn model (Claude Opus, Sonnet, hoặc model khác — bạn có thể dùng model khác nhau cho từng agent để tối ưu chi phí), bật/tắt thinking mode, bật Chrome browser access cho agent.
Heartbeat: Cấu hình heartbeat interval — bao lâu agent thức dậy một lần, có enable heartbeat tự động hay chỉ manual trigger.
Bạn không cần chỉnh gì cho lần đầu — defaults đủ tốt. Nhưng khi scale lên 5-10 agents, đây là nơi bạn fine-tune từng agent cho đúng vai trò.
Xem kết quả — Dashboard, audit trail, và chi phí
Quay lại UI, mở dashboard. Bạn sẽ thấy:
Task status: done — task đã hoàn thành. Nếu bạn click vào task, bạn thấy toàn bộ comment thread: agent checkout lúc nào, làm gì, kết quả ra sao.
Chi phí: mỗi heartbeat ghi nhận chi phí thực tế. Ví dụ: “Run #1 — $0.85 — 45s — 1 task completed.” Bạn biết chính xác mỗi dollar đi vào đâu. Không có hóa đơn bất ngờ cuối tháng.
Audit trail: mỗi action gắn với một run ID — mã định danh của lần heartbeat. Agent checkout task lúc 14:32:05, comment lúc 14:32:47, mark done lúc 14:32:48. Trace được ai làm gì, lúc nào, tốn bao nhiêu. Khi team scale lên 10 agents, audit trail này là cách bạn giữ kiểm soát: không agent nào hành động mà không để lại dấu vết.
Org Chart: vào tab Org Chart để xem sơ đồ tổ chức trực quan — ai report cho ai, hierarchy rõ ràng. Khi CEO hire thêm agents (sau khi bạn approve), sơ đồ tự động cập nhật.
So sánh với cách chạy AI agents thông thường: bạn mở terminal, chạy Claude Code hay Cursor, giao task bằng miệng hoặc prompt, xong rồi không biết agent tốn bao nhiêu token, làm bao lâu, hay có bỏ qua bước nào không. Paperclip biến quy trình mờ đó thành transparent hoàn toàn.
Vậy là bạn đã có: 1 company, 1 agent, 1 task hoàn thành, toàn bộ audit trail, và con số chi phí chính xác. Tất cả trong 15 phút.
Troubleshooting — 5 lỗi thường gặp và cách sửa
1. Port 3100 đã bị dùng
Lỗi: EADDRINUSE: address already in use :::3100. Sửa: kill process cũ (lsof -i :3100 trên Mac/Linux, netstat -ano | findstr :3100 trên Windows) hoặc đổi port trong ~/.paperclip/instances/default/config.json → server.port.
2. Node.js version quá cũ
Lỗi: syntax errors hoặc SyntaxError: Unexpected token. Sửa: node --version kiểm tra. Cần 20+. Cài nhanh: nvm install 20 && nvm use 20.
3. Embedded PostgreSQL không start
Lỗi: Failed to start embedded postgres. Nguyên nhân phổ biến: folder ~/.paperclip/ không có quyền ghi, hoặc một instance cũ vẫn đang chạy. Sửa: pnpm paperclipai doctor --repair — lệnh này tự chẩn đoán và sửa hầu hết vấn đề.
4. Agent không nhận task
Heartbeat chạy nhưng agent nói “No work found.” Kiểm tra 3 thứ: (a) task đã assign đúng agent ID chưa? (b) task status có phải todo không? (c) env vars đã source đúng chưa? Kiểm tra: echo $PAPERCLIP_AGENT_ID.
5. Heartbeat timeout
Agent bắt đầu nhưng bị timeout trước khi xong. Nguyên nhân: task quá phức tạp cho timeout mặc định, hoặc LLM API key hết hạn/không valid. Sửa: tăng timeoutSec trong agent config, kiểm tra API key trên dashboard Anthropic.
Tip chung: pnpm paperclipai doctor là bước đầu tiên khi gặp bất kỳ vấn đề nào. Lệnh này kiểm tra database, config, permissions, và tự sửa những gì sửa được. Thêm flag --repair để tự động apply fix mà không cần confirm từng bước.
Nếu tất cả 5 cách trên đều không giải quyết được — kiểm tra logs ở ~/.paperclip/instances/default/logs/. Log file ghi chi tiết mọi thứ server làm, kể cả lỗi mà terminal output không hiện rõ.
Tiếp theo: từ 1 agent lên 10
Bạn đã có 1 agent hoạt động, 1 task hoàn thành, và toàn bộ infrastructure sẵn sàng. Nền tảng đã vững.
Nhưng 1 agent chỉ là khởi đầu. Khi bạn thêm agent thứ 2, thứ 3, thứ 10 — ai report cho ai? Ai có quyền approve code? Ai bị giới hạn budget? Trong bài tiếp theo, bạn sẽ thiết kế org chart cho AI team — từ hierarchy đến phân quyền, từ chain of command đến budget allocation.
