PaperClip 学习教程
PaperClip 学习教程
从零开始，手把手教你构建零人工 AI 公司
目录
一、快速开始
1.1 环境准备
前置要求： - [ ] Node.js 20+ 已安装 - [ ] pnpm 9.15+ 已安装 - [ ] Git 已安装
检查环境：
node -v # 需要 v20+
pnpm -v # 需要 9.15+
git --version
1.2 一键安装（推荐）
npx paperclipai onboard --yes
这个命令会： 1. 检查环境依赖 2. 下载并配置 PaperClip 3. 启动服务
1.3 手动安装
# 克隆仓库
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev
1.4 验证安装
启动后，访问：
- API: http://localhost:3100
- Dashboard: http://localhost:3100 (React UI 自动加载)
看到 Dashboard 界面说明安装成功！
二、核心概念
2.1 PaperClip 是什么？
PaperClip = AI 公司运营平台
传统公司: CEO → 员工 → 任务
AI 公司: AI CEO → AI Agent → 任务 (PaperClip 编排)
2.2 核心架构
┌─────────────────────────────────────────────────────────────────┐
│ PaperClip 核心架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 你 (Board of Directors) │
│ │ │
│ ├── 📊 Dashboard (监控、审批、管理) │
│ │ │
│ ├── 🏢 Company (公司实体) │
│ │ │ │
│ │ ├── 👔 CEO Agent │
│ │ │ │ │
│ │ │ ├── 💼 CTO Agent │
│ │ │ │ └── 👨💻 Engineer Agents │
│ │ │ │ │
│ │ │ ├── 📈 CMO Agent │
│ │ │ │ └── 📝 Content Agents │
│ │ │ │ │
│ │ │ └── 💰 CFO Agent │
│ │ │ │
│ │ └── 💓 Heartbeats (定时任务) │
│ │ │
│ └── 🎫 Tickets (任务追踪) │
│ │
└─────────────────────────────────────────────────────────────────┘
2.3 核心术语
| 术语 | 英文 | 解释 |
|---|---|---|
| 公司 | Company | 一个完整的 AI 公司实体 |
| Agent | Agent | AI 员工，有特定角色和职责 |
| 组织架构 | Org Chart | Agent 之间的层级关系 |
| 目标 | Goal | 公司/项目/任务的目标层级 |
| 心跳 | Heartbeat | Agent 定时唤醒执行任务 |
| Ticket | Ticket | 任务记录，可追溯 |
| 预算 | Budget | Agent 的月度费用限制 |
| 治理 | Governance | 你作为董事会的控制权 |
2.4 目标层级
◎ Company Mission (公司使命)
"Build the #1 AI note-taking app to $1M MRR"
│
├── ◉ Project Goal (项目目标)
│ "Ship collaboration features"
│ │
│ ├── ○ Agent Goal (Agent 目标)
│ │ "Implement real-time sync"
│ │ │
│ │ └── • Task (任务)
│ │ "Write WebSocket handler"
│
└── ...
三、完整工作流教程
3.1 场景：创建一个内容营销 AI 公司
让我们通过一个实际例子来学习 PaperClip。
Step 1: 启动 PaperClip
cd paperclip
pnpm dev
Step 2: 创建公司
在 Dashboard 中点击 "Create Company"：
Company Name: Content Marketing Co
Mission: "Build a content marketing agency that generates 100K monthly traffic"
Step 3: 设计组织架构
创建 Agent 角色：
┌─────────────────────────────────────────────────────────────────┐
│ Content Marketing Co 组织架构 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 👔 CEO (Claude) │
│ │ 预算: $60/月 │
│ │ 职责: 战略决策、任务分配 │
│ │ │
│ ├── 📈 CMO (OpenClaw) │
│ │ │ 预算: $40/月 │
│ │ │ 职责: 营销策略、内容规划 │
│ │ │ │
│ │ ├── 📝 Content Writer (Claude) │
│ │ │ 预算: $30/月 │
│ │ │ 职责: 撰写博客、社媒内容 │
│ │ │ │
│ │ ├── 🔍 SEO Specialist (Claude) │
│ │ │ 预算: $30/月 │
│ │ │ 职责: SEO 优化、关键词研究 │
│ │ │ │
│ │ └── 📱 Social Manager (Claude) │
│ │ 预算: $30/月 │
│ │ 职责: 社媒发布、互动管理 │
│ │ │
│ └── 💰 CFO (Claude) │
│ 预算: $20/月 │
│ 职责: 成本监控、预算报告 │
│ │
└─────────────────────────────────────────────────────────────────┘
Step 4: 配置 Agent
为每个 Agent 设置：
# Content Writer 配置示例
name: Content Writer
provider: claude
model: claude-sonnet-4-6
budget: $30/month
role: |
你是内容营销公司的专业写手。
负责撰写博客文章、社交媒体内容、邮件营销文案。
写作风格：专业但友好，SEO 友好。
heartbeat: every 4h
skills:
- blog_writing
- social_media
- email_copy
Step 5: 设置 Heartbeats
配置定期任务：
# Content Writer 心跳
schedule: every 4h
tasks:
- Check content calendar
- Draft blog post (if needed)
- Review and edit drafts
- Submit for approval
Step 6: 创建第一个任务
在 Dashboard 中创建任务：
Title: Write blog post about AI marketing
Assigned to: Content Writer
Goal: Create engaging blog content
Priority: High
Due: Today
Description:
Write a 1500-word blog post about "How AI is transforming content marketing".
Include:
- Introduction with hook
- 3 key benefits of AI in marketing
- Real-world examples
- Call to action
Step 7: 监控执行
在 Dashboard 中查看：
┌─────────────────────────────────────────────────────────────────┐
│ Task Progress │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Task: Write blog post about AI marketing │
│ Status: 🔄 In Progress │
│ Agent: Content Writer │
│ Cost: $0.42 / $30 │
│ │
│ Timeline: │
│ ├── 10:00 - Task assigned │
│ ├── 10:05 - Agent started │
│ ├── 10:15 - Research completed │
│ ├── 10:30 - Draft created │
│ └── 10:45 - Submitted for review │
│ │
│ Output: │
│ [Preview draft...] │
│ │
│ [Approve] [Request Changes] [Reject] │
│ │
└─────────────────────────────────────────────────────────────────┘
Step 8: 审批和发布
作为董事会： 1. Review - 审阅 Agent 的工作 2. Approve - 批准发布 3. Override - 或要求修改
四、功能详解
4.1 功能：组织架构管理
📌 功能概述
可视化管理 AI 员工的层级关系
🔧 原理说明
- 每个公司有一个组织架构图
- Agent 有上级和下属关系
- 任务按层级流动
📝 基础用法
创建 Agent：
1. 进入 Dashboard
2. 点击 "Add Agent"
3. 填写配置：
- Name: Agent 名称
- Provider: claude / openclaw / codex
- Model: 模型选择
- Budget: 月度预算
- Role: 角色描述
设置层级：
CEO
├── reports_to: null
└── direct_reports: [CTO, CMO, CFO]
CTO
├── reports_to: CEO
└── direct_reports: [Engineer1, Engineer2]
🚀 进阶用法
多公司管理：
Dashboard
├── 📱 Mobile Marketing Co (8 agents)
├── 💰 Crypto Trading Fund (14 agents)
└── 🎬 TikTok Factory (5 agents)
4.2 功能：心跳机制 (Heartbeats)
📌 功能概述
Agent 按计划自动唤醒执行任务
🔧 原理说明
- 基于时间的触发器
- Agent 唤醒后检查工作队列
- 执行完成后进入休眠
📝 基础用法
# 配置心跳
agent: Content Writer
schedule: every 4h
tasks:
- Check content queue
- Process pending items
- Report status
🚀 进阶用法
复杂心跳配置：
# SEO Analyst 心跳
schedule:
weekday: "0 8,16 * * 1-5" # 工作日 8AM, 4PM
weekend: "0 10 * * 0,6" # 周末 10AM
tasks:
- name: Crawl audit
priority: high
- name: Keyword research
priority: medium
- name: Rank tracking
priority: low
紧急任务：
# Social Manager 心跳
schedule: every 12h
urgent_triggers:
- brand_mention_spike
- negative_sentiment
- viral_content_opportunity
4.3 功能：成本控制
📌 功能概述
管理每个 Agent 的预算和成本
🔧 原理说明
- 每个 Agent 有月度预算
- 实时追踪 Token 消耗
- 超限自动暂停
📝 基础用法
Budget Dashboard:
CEO Claude $12.50 / $60
████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
CMO OpenClaw $8.20 / $40
████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
[Adjust Budget] [Pause Agent] [View Details]
⚠️ 注意事项
- 80% 警告 - 达到 80% 时收到通知
- 100% 暂停 - 达到 100% 时自动暂停
- 董事会覆盖 - 你可以随时调整限制
4.4 功能：Ticket 系统
📌 功能概述
每个对话可追溯，每个决策有解释
🔧 原理说明
- 结构化任务记录
- 完整工具调用追踪
- 不可变审计日志
📝 基础用法
Ticket #1234
──────────────────────────────────────
Title: Deploy pricing page update
Status: ✅ Completed
Agent: CTO
Cost: $0.85
Duration: 15 min
Conversation:
──────────────────────────────────────
You (10:00):
"Deploy the updated pricing page to production. Run tests."
CTO Agent (10:02):
"Running test suite and staging deployment now..."
CTO Agent (10:10):
"Tests passed. Staging deployment complete."
You (10:11):
"Approved. Go ahead."
CTO Agent (10:15):
"Production deployment complete. All systems green."
Trace:
──────────────────────────────────────
├── run_tests() ✅ passed (2m)
├── deploy_to_staging() ✅ done (3m)
├── smoke_test() ✅ passed (1m)
└── deploy_to_production() ✅ done (2m)
4.5 功能：治理层
📌 功能概述
你作为董事会保持对公司的完全控制
🔧 原理说明
- 审批门强制执行
- 配置变更可回滚
- 随时暂停任何 Agent
📝 基础用法
治理权限：
作为董事会，你可以：
✅ 批准新 Agent 招聘
✅ 审阅和修改策略
✅ 覆盖任何决策
✅ 暂停任何 Agent
✅ 重新分配任何任务
✅ 调整任何预算
✅ 终止任何 Agent
五、配置指南
5.1 配置文件结构
paperclip/
├── config/
│ ├── default.yaml # 默认配置
│ ├── agents/ # Agent 配置
│ │ ├── ceo.yaml
│ │ ├── cto.yaml
│ │ └── ...
│ └── companies/ # 公司配置
│ ├── marketing.yaml
│ └── trading.yaml
└── data/
└── paperclip.db # 嵌入式数据库
5.2 Agent 配置模板
# agents/content_writer.yaml
name: Content Writer
provider: claude
model: claude-sonnet-4-6
budget:
monthly: 30 # 月度预算 (美元)
warning_at: 0.8 # 80% 警告
halt_at: 1.0 # 100% 暂停
role: |
你是专业内容写手，负责撰写博客和社媒内容。
写作风格：专业、友好、SEO 优化。
heartbeat:
schedule: "0 */4 * * *" # 每 4 小时
timezone: "Asia/Shanghai"
skills:
- blog_writing
- seo_optimization
- social_media
limits:
max_tasks_per_heartbeat: 5
max_tokens_per_task: 10000
reporting:
to: CMO
frequency: daily
5.3 公司配置模板
# companies/marketing.yaml
name: Content Marketing Co
mission: "Build a content marketing agency generating 100K monthly traffic"
org_chart:
ceo:
agent: ceo
reports_to: null
direct_reports: [cmo, cfo]
cmo:
agent: cmo
reports_to: ceo
direct_reports: [content_writer, seo_specialist, social_manager]
cfo:
agent: cfo
reports_to: ceo
direct_reports: []
settings:
governance_level: high # high / medium / low
auto_approve: false # 自动审批
require_review: true # 需要人工审阅
5.4 开发命令
# 开发
pnpm dev # 完整开发 (API + UI)
pnpm dev:once # 无文件监控
pnpm dev:server # 仅服务器
# 构建
pnpm build # 构建全部
pnpm typecheck # 类型检查
# 测试
pnpm test:run # 运行测试
# 数据库
pnpm db:generate # 生成迁移
pnpm db:migrate # 应用迁移
六、实战案例
案例 1：内容营销公司
Company: Content Marketing Co
Mission: Generate 100K monthly traffic
Agents: 8
Budget: $240/month
Org Chart:
CEO (Claude)
├── CMO (OpenClaw)
│ ├── Content Writer
│ ├── SEO Specialist
│ └── Social Manager
├── CTO (Cursor)
│ └── Developer
└── CFO (Claude)
Heartbeats:
- Content Writer: every 4h
- SEO Specialist: every 8h
- Social Manager: every 12h
案例 2：加密交易基金
Company: Crypto Trading Fund
Mission: Generate alpha through systematic trading
Agents: 14
Budget: $500/month
Org Chart:
Managing Partner (Claude)
├── Trading Lead (Claude)
│ ├── Spot Trader
│ ├── Derivatives Trader
│ └── Execution Engine
├── Research Lead (OpenClaw)
│ ├── Market Analyst
│ ├── On-chain Analyst
│ └── Sentiment Analyst
├── Risk Manager (Claude)
└── Quant Lead (Codex)
├── Strategy Developer
└── Backtester
Heartbeats:
- Traders: every 1h (market hours)
- Research: every 4h
- Risk: every 30m
案例 3：TikTok 工厂
Company: Faceless TikTok Factory
Mission: Create viral short-form content
Agents: 6
Budget: $150/month
Org Chart:
Producer (Claude)
├── Scriptwriter (Claude)
├── Video Editor (Codex)
├── Voice (ElevenLabs)
├── Thumbnail (DALL-E)
└── Analytics (Claude)
Workflow:
1. Scriptwriter creates script
2. Voice generates narration
3. Video Editor assembles
4. Thumbnail creates cover
5. Producer reviews & publishes
6. Analytics tracks performance
七、常见问题
Q1: PaperClip 和 Claude Code 有什么区别？
A: PaperClip 使用 Claude Code 等 Agent。它将它们编排成一个公司 —— 有组织架构、预算、目标、治理和问责制。
Q2: 如何添加自定义 Agent？
A:
# 1. 创建 Agent 配置
config/agents/my_agent.yaml
# 2. 添加到组织架构
# 在公司配置中引用
# 3. 重启服务
pnpm dev
Q3: 成本太高怎么办？
A: 1. 使用 budget 配置文件 2. 调整 Agent 心跳频率 3. 使用更便宜的模型 (如 Haiku) 4. 设置更严格的预算限制
Q4: 如何监控 Agent 活动？
A: - Dashboard 实时监控 - Ticket 系统完整追踪 - 预算面板查看成本 - 审计日志查看历史
Q5: 支持哪些 Agent 提供商？
A: | 提供商 | 支持 | |--------|------| | Claude (Anthropic) | ✅ | | OpenClaw | ✅ | | Codex (OpenAI) | ✅ | | Cursor | ✅ | | 自定义 HTTP | ✅ |
八、最佳实践
8.1 组织架构设计
✅ 好的设计：
CEO (战略层)
├── CTO (技术层)
│ └── Engineers (执行层)
└── CMO (营销层)
└── Content Team (执行层)
❌ 不好的设计：
CEO 直接管理 20 个 Agent (扁平化太严重)
8.2 预算设置
建议预算分配：
- CEO: $50-100/月
- 部门主管: $30-50/月
- 执行 Agent: $20-30/月
8.3 心跳频率
根据角色设置：
- 交易员: 每 30 分钟
- 内容创作者: 每 4 小时
- 分析师: 每 8 小时
- 报告生成: 每天
8.4 治理级别
高治理 (推荐新手):
- 所有决策需要审批
- 完整审计追踪
中治理 (有经验后):
- 常规任务自动执行
- 重要决策需要审批
低治理 (完全自治):
- Agent 自主决策
- 仅监控异常
九、速查表
# 安装
npx paperclipai onboard --yes
# 启动
pnpm dev
# 创建公司
Dashboard → Create Company
# 添加 Agent
Dashboard → Add Agent
# 创建任务
Dashboard → New Task
# 查看进度
Dashboard → Tickets
# 管理预算
Dashboard → Budgets
# 治理操作
Dashboard → Governance
十、总结
PaperClip 的核心价值
1. 🏢 组织架构 - Agent 有老板、职位、工作描述
2. 🎯 目标对齐 - 每个任务追溯到公司使命
3. 💰 成本控制 - 预算管理，防止 Token 浪费
4. 🛡️ 治理层 - 你是董事会，保持控制
5. 💓 心跳机制 - 自动定期工作
6. 🎫 Ticket 系统 - 完整审计追踪
7. 📱 移动就绪 - 随时随地管理
8. 🏢 多公司 - 一个部署，无限公司
适用人群
✅ 想构建自主 AI 公司的人
✅ 协调多个不同 Agent 的人
✅ 有 20 个 Claude Code 终端的人
✅ 希望 Agent 24/7 自主运行但保持审计的人
✅ 想监控成本并执行预算的人
✅ 管理多个自主业务的人
一句话总结
Open source under MIT. Built for people who want to run companies, not babysit agents.
MIT 开源。为想要运营公司而不是看管 Agent 的人而构建。
十一、资源链接
- 官网: paperclip.ing
- GitHub: github.com/paperclipai/paperclip
- 教程: paperclipai.info
- 视频: YouTube Tutorial
- 部署: Zeabur Template
文档版本: 1.0 创建日期: 2026-03-17