PaperClip - 完整学习教程

PaperClip - 完整学习教程

教程级别: 从零到一 预计学习时间: 8-12 小时 前置知识: Node.js 基础、命令行操作、AI Agent 基本概念(推荐了解 OpenClaw 或 Claude Code)

环境搭建指南

系统要求

  • 操作系统:macOS / Linux / Windows(WSL2 推荐)
  • Node.js:20.0.0 或更高版本
  • pnpm:9.15.0 或更高版本(仅从源码构建时需要)
  • 磁盘空间:至少 500MB(含嵌入式 PostgreSQL)
  • 网络要求:需要访问 npm registry 和至少一个 Agent 运行时的 API

安装步骤

方式一:快速安装(推荐)

# 使用 npx 一键安装和启动
npx paperclipai onboard --yes

# 此命令将:
# 1. 安装 PaperClip CLI
# 2. 创建本地嵌入式 PostgreSQL 数据库
# 3. 启动 PaperClip 服务器
# 4. 打开交互式引导设置
# 5. 启动 React Dashboard

方式二:从源码构建

# 克隆仓库
git clone https://github.com/paperclipai/paperclip.git
cd paperclip

# 安装依赖
pnpm install

# 启动开发环境
pnpm dev

# 其他常用开发命令:
# pnpm dev:server   — 仅启动服务端
# pnpm build        — 构建全部
# pnpm typecheck    — 类型检查
# pnpm test:run     — 运行测试
# pnpm db:generate  — 生成数据库迁移
# pnpm db:migrate   — 应用数据库迁移

方式三:禁用遥测(敏感环境推荐)

# 通过环境变量禁用遥测
export PAPERCLIP_TELEMETRY=false

# 或通过配置文件禁用
npx paperclipai onboard --yes --no-telemetry

验证安装

# 检查 PaperClip 服务是否运行
curl http://localhost:3100/api/health

# 预期输出:
# {"status":"ok","version":"0.x.x"}
# 访问 Dashboard
# 浏览器打开 http://localhost:3100
# 应看到 PaperClip 的 React Dashboard 界面

第一部分:入门篇

1.1 理解"零人类公司"概念与公司模型

概念讲解:

PaperClip 的核心创新是将多 Agent 系统建模为"公司"而非"工作流"。这意味着你需要像创建一家真实公司一样思考:定义公司名称、使命声明、业务目标,然后雇佣 Agent 填充组织架构中的角色。

在 PaperClip 中,公司(Company) 是顶层组织单元。公司包含: - 名称(Name):公司标识 - 使命声明(Mission):向下传播到所有 Agent,每个 Agent 都知道自己为什么工作 - 目标(Goals):可量化的业务目标 - 项目(Projects):目标的分解 - 任务(Tasks):项目的进一步分解,分配给具体 Agent

代码示例: 基于 PaperClip 官方 README 和 Towards AI 文章

# 启动 PaperClip 后,通过 Dashboard 创建第一个公司
# 步骤 1:打开浏览器访问 http://localhost:3100
# 步骤 2:点击 "Create Company"
# 步骤 3:填写公司信息

# 公司名称:My Content Agency
# 使命声明:提供高质量的 AI 驱动内容营销服务
# 业务目标:
#   - 每周发布 3 篇博客文章
#   - 每月获取 100 个新潜在客户
#   - 社交媒体月互动率提升 20%

执行结果:

Company created successfully!
  Name: My Content Agency
  Mission: 提供高质量的 AI 驱动内容营销服务
  Goals:
    [1] 每周发布 3 篇博客文章
    [2] 每月获取 100 个新潜在客户
    [3] 社交媒体月互动率提升 20%
  Dashboard: http://localhost:3100/company/my-content-agency

注意事项: - 使命声明非常重要——它会被向下传播到每个 Agent 的每条指令中 - 目标应该是可量化的,便于 PaperClip 追踪进度 - PaperClip 支持多公司隔离,可以在同一平台上运行多个独立公司

练习题: 1. 创建一个名为 "Crypto Trading Desk" 的公司,使命为"通过 AI Agent 团队实现稳定的加密货币交易收益" 2. 思考:如果你要运营一个自动化电商公司,应该如何定义使命和目标?


1.2 组织架构图与 Agent 雇佣

概念讲解:

有了公司之后,下一步是设计组织架构图(Org Chart)。PaperClip 的组织架构采用层级结构,类似真实公司的汇报线:

  • CEO Agent:接收公司使命,分解为战略目标,委派给下属
  • CTO/CMO 等高层 Agent:接收战略目标,分解为具体项目
  • 执行层 Agent:执行具体任务(编码、写作、数据分析等)

每个 Agent 通过适配器(Adapter) 连接到 PaperClip。适配器是 PaperClip 与外部 Agent 运行时之间的桥梁。

代码示例: 雇佣第一个 CEO Agent

// 在 PaperClip Dashboard 中创建 CEO Agent
// 适配器类型选择 "process"(本地 Claude Code)
{
  "agentName": "CEO Agent",
  "role": "CEO",
  "adapterType": "process",
  "adapterConfig": {
    "adapter": "claude_local",
    "model": "claude-sonnet-4-20250514",
    "billingType": "api",
    "sessionBehavior": "resume-or-new",
    "heartbeatSchedule": {
      "enabled": true,
      "intervalSec": 1800
    }
  },
  "monthlyBudget": 50.00,
  "description": "负责将公司使命分解为战略目标,并委派给下属 Agent"
}

执行结果:

Agent hired successfully!
  Name: CEO Agent
  Role: CEO
  Adapter: process (claude_local)
  Budget: $50.00/month
  Heartbeat: Every 30 minutes
  Status: Idle (waiting for first heartbeat)

Dashboard 显示:
  My Content Agency
  └── CEO Agent [Idle] — Budget: $0.00/$50.00

注意事项: - sessionBehavior: "resume-or-new" 确保 Agent 在心跳间保持会话上下文,而非每次从零开始 - monthlyBudget 设置月度预算上限,80% 警告,100% 自动暂停 - CEO Agent 是组织架构的起点,后续所有 Agent 都由 CEO 推荐、人类审批

练习题: 1. 在你的 "Crypto Trading Desk" 公司中雇佣一个 CEO Agent,使用 OpenClaw 作为运行时(适配器类型选择 openclaw_gateway) 2. 思考:CEO Agent 应该具备什么能力?它的 SOUL.md 应该如何定义?


第二部分:进阶篇

2.1 心跳调度与任务分配

概念讲解:

心跳(Heartbeat) 是 PaperClip 实现 Agent 自主运营的核心机制。继承自 OpenClaw 的心跳概念,PaperClip 将其扩展为跨 Agent 协调层:

  1. 每个 Agent 按预设时间表被唤醒
  2. 唤醒后检查工作队列,有任务则执行
  3. 执行完成后向上级报告结果
  4. 无任务则返回 HEARTBEAT_OK,继续休眠
  5. 心跳间 Agent 完全休眠,不消耗 Token

CEO Agent 的心跳会将公司使命分解为目标 → 项目 → 任务,然后通过工单系统(Ticket System) 分配给下属 Agent。

代码示例: 配置心跳并触发任务分配

// 配置 CEO Agent 的心跳任务
// CEO 每次心跳时执行的战略分解逻辑
{
  "heartbeatConfig": {
    "enabled": true,
    "intervalSec": 1800,
    "maxRetries": 3,
    "retryDelaySec": 60,
    "onFailure": "notify_board"
  }
}
# 手动触发 CEO Agent 的心跳(用于调试)
# 通过 PaperClip CLI
npx paperclipai heartbeat --agent "CEO Agent" --company "My Content Agency"

# 或通过 API
curl -X POST http://localhost:3100/api/companies/my-content-agency/agents/ceo-agent/heartbeat

执行结果:

Heartbeat triggered for CEO Agent...
  Reading company mission: "提供高质量的 AI 驱动内容营销服务"
  Reading goals:
    [1] 每周发布 3 篇博客文章
    [2] 每月获取 100 个新潜在客户

  CEO 决策:
  → 创建项目 "Content Pipeline"
  → 分解为任务:
    [T-001] 研究本周热门话题 → 分配给 Content Strategist
    [T-002] 撰写博客草稿 → 分配给 Writer
    [T-003] 审核并发布 → 分配给 Publisher

  3 个工单已创建,等待 Agent 执行

注意事项: - 心跳间隔不宜过短(建议不低于 15 分钟),否则会产生不必要的 API 调用 - 首次运行时 CEO 需要"招聘"下属 Agent,这需要人类"董事会"审批 - 如果心跳连续失败 3 次,PaperClip 会自动通知人类操作者

练习题: 1. 为你的 "Crypto Trading Desk" 设计心跳调度策略:市场监控 Agent 每 5 分钟心跳,风控 Agent 每 15 分钟心跳,CEO Agent 每 30 分钟心跳 2. 思考:在什么情况下应该禁用某个 Agent 的心跳?


2.2 适配器系统与 Agent 集成

概念讲解:

PaperClip 的适配器系统(Adapter System) 是其"框架无关性"的核心。适配器是可插拔模块,桥接 PaperClip 编排层与外部 Agent 运行时。内置三种适配器类型:

  1. Process Adapter:本地进程适配器,在当前机器上启动 Agent 子进程。适用于 Claude Code、Codex、Cursor 等本地 Agent
  2. HTTP Adapter:远程 HTTP 适配器,通过 webhook 调用远程 Agent。适用于自建 Agent 服务或第三方 API
  3. OpenClaw Gateway Adapter:专用适配器,通过 WebSocket 与 OpenClaw 实例通信。支持设备认证(Ed25519 密钥对)和会话持久化

代码示例: 配置不同类型的适配器

// Process Adapter — 本地 Claude Code Agent
{
  "adapterType": "process",
  "adapterConfig": {
    "adapter": "claude_local",
    "model": "claude-sonnet-4-20250514",
    "billingType": "api",
    "sessionBehavior": "resume-or-new",
    "heartbeatSchedule": {
      "enabled": true,
      "intervalSec": 1800
    }
  }
}
// HTTP Adapter — 远程自定义 Agent
{
  "adapterType": "http",
  "adapterConfig": {
    "url": "https://my-agent.example.com/invoke",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{MY_AGENT_TOKEN}}"
    },
    "timeoutMs": 30000,
    "payloadTemplate": {
      "paperclip": {
        "agentId": "{{agent.id}}",
        "companyId": "{{company.id}}",
        "runId": "{{run.id}}"
      }
    }
  }
}
// OpenClaw Gateway Adapter — OpenClaw Agent
{
  "adapterType": "openclaw_gateway",
  "adapterConfig": {
    "gatewayUrl": "ws://localhost:3271",
    "authToken": "{{OPENCLAW_TOKEN}}",
    "sessionStrategy": "per-run",
    "devicePrivateKeyPem": "/path/to/device_key.pem"
  }
}

// 首次连接 OpenClaw 需要设备配对
// 在 OpenClaw 端运行:
// openclaw devices approve --latest

执行结果:

# 成功连接各适配器后的 Dashboard 状态
My Content Agency
├── CEO Agent [Idle] — Adapter: process (claude_local)
├── Content Strategist [Idle] — Adapter: openclaw_gateway
├── Writer [Idle] — Adapter: process (claude_local)
├── Editor [Idle] — Adapter: process (claude_local)
└── Publisher [Idle] — Adapter: http (custom-webhook)

All adapters connected. 5 agents ready.

注意事项: - OpenClaw Gateway 适配器首次连接需要设备配对,完成后设置持久密钥可避免重复审批 - HTTP 适配器的密钥存储在加密的 company_secrets 表中,运行时注入,永不硬编码在适配器配置中 - Process 适配器会在每次心跳时启动/恢复子进程,确保系统重启后 Agent 状态可恢复 - 第三方可以发布自定义适配器(如 Nous Research 的 hermes-paperclip-adapter

练习题: 1. 为你的 "Crypto Trading Desk" 设计适配器策略:市场数据 Agent 使用 HTTP 适配器连接交易所 API,交易执行 Agent 使用 OpenClaw Gateway 适配器,风控 Agent 使用 Process 适配器 2. 尝试编写一个简单的 HTTP 适配器配置,连接到一个自定义的 Agent 端点


第三部分:高级篇

3.1 预算控制与治理机制

详细讲解:

PaperClip 的预算控制(Budget Controls) 在多个层级运作:

  • Agent 级别:每个 Agent 有独立的月度 Token 预算
  • 任务级别:单个任务的成本上限
  • 项目级别:项目的总成本约束
  • 目标级别:目标的资源分配
  • 公司级别:公司的总运营预算

当 Agent 使用量达到 80% 时发出警告;达到 100% 时自动暂停,新任务被阻止。人类操作者("董事会")可以覆盖此限制。

治理机制(Governance) 包括: - 审批门控(Approval Gates):招聘新 Agent、执行高成本任务需要董事会审批 - 配置版本化:所有配置变更可追踪、可回滚 - 审计日志:仅追加,不可编辑、不可删除

代码示例: 配置多层级预算和治理规则

// 公司级预算配置
{
  "companyBudget": {
    "monthlyTotal": 200.00,
    "currency": "USD",
    "alertThreshold": 0.8,
    "autoPauseThreshold": 1.0,
    "boardOverrideEnabled": true
  },
  "agentBudgets": {
    "CEO Agent": 50.00,
    "Content Strategist": 30.00,
    "Writer": 40.00,
    "Editor": 30.00,
    "Publisher": 20.00
  },
  "governanceRules": {
    "requireApprovalForHiring": true,
    "requireApprovalForBudgetOver60": true,
    "configVersioning": true,
    "auditLogRetention": "365d"
  }
}
# 查看当前预算使用情况
curl http://localhost:3100/api/companies/my-content-agency/budget

# 预期输出:
# {
#   "companyMonthly": {"limit": 200.00, "used": 47.35, "percent": 23.7},
#   "agents": [
#     {"name": "CEO Agent", "limit": 50.00, "used": 12.80, "percent": 25.6},
#     {"name": "Content Strategist", "limit": 30.00, "used": 8.50, "percent": 28.3},
#     {"name": "Writer", "limit": 40.00, "used": 15.20, "percent": 38.0},
#     {"name": "Editor", "limit": 30.00, "used": 6.85, "percent": 22.8},
#     {"name": "Publisher", "limit": 20.00, "used": 4.00, "percent": 20.0}
#   ]
# }

注意事项: - 预算控制是 PaperClip 区别于 CrewAI、AutoGen、LangGraph 等框架的独特能力 - 在生产环境中,务必设置公司级月度总预算,防止单个 Agent 失控导致巨额账单 - 审计日志的保留期限需要根据合规要求配置(默认 365 天)


3.2 预构建公司与快速部署

详细讲解:

PaperClip 提供 16 个预构建公司模板(Pre-built Companies),包含 440+ 预配置 Agent 和 500+ 技能。这些模板覆盖了常见的业务场景,可以一键导入快速部署。

部分预构建公司模板: - Content Marketing Agency(8 Agents):内容策划、写作、编辑、发布、社交媒体 - Crypto Trading Desk(12 Agents):市场监控、技术分析、交易执行、风控、报告 - E-commerce Operator(10 Agents):商品管理、价格优化、客服、物流、评价管理 - YouTube Factory(6 Agents):选题研究、脚本编写、视频描述、缩略图、发布 - Dev Agency(9 Agents):需求分析、架构设计、编码、测试、部署、运维 - Real Estate Leads(7 Agents):房源搜集、客户筛选、预约安排、跟进

# 通过 companies.sh 导入预构建公司
npx paperclipai import-company --template content-marketing-agency --name "我的内容营销公司"

# 导出当前公司配置
npx paperclipai export-company --name "我的内容营销公司" --output my-company.json

执行结果:

Importing company template: content-marketing-agency
  Loading 8 agents...
  Loading 24 skills...
  Loading 3 goals...
  Loading org chart...

Company "我的内容营销公司" imported successfully!
  Agents:
    [1] CEO — Content Strategy (process, claude_local)
    [2] Content Strategist — Topic Research (openclaw_gateway)
    [3] Writer — Draft Creation (process, claude_local)
    [4] Editor — Review & Polish (process, claude_local)
    [5] Social Media Manager — Distribution (http, webhook)
    [6] SEO Specialist — Optimization (process, claude_local)
    [7] Analytics Agent — Performance Tracking (openclaw_gateway)
    [8] Publisher — Final Posting (http, custom-api)

  Ready to launch! Run: npx paperclipai start --company "我的内容营销公司"

注意事项: - 预构建模板中的 Agent 适配器配置需要根据你的实际环境调整(API Key、Agent 运行时地址等) - 导入后建议先在"观察模式"下运行,确认 Agent 行为符合预期后再启用自主模式 - Clipmart(公司模板市场)在路线图中,未来将支持社区共享模板


3.3 最佳实践

  1. 从单个 Agent 开始,逐步扩展 — 不要一开始就创建完整的组织架构。先用一个 CEO Agent 验证基本流程,再逐步添加下属 Agent。Flowtivity 的建议是:3-4 个 Agent 以下不需要 PaperClip,5 个以上才是 PaperClip 的甜蜜区。

  2. 预算设置要保守 — 初始月度预算设为预期消耗的 50%,观察一周后根据实际使用量调整。使用 80% 警告阈值,确保有缓冲时间处理预算告警。

  3. 使命声明要具体且可操作 — 避免"成为最好的 AI 公司"这类模糊使命。使用"每月通过 AI 生成的内容获取 100 个新用户"这类可量化的使命。

  4. 善用审计日志 — 定期审查审计日志,了解 Agent 的决策过程。这不仅是合规要求,也是优化 Agent 行为的重要数据来源。

  5. 测试适配器连接 — 在正式部署前,用 npx paperclipai test-adapter 命令验证每个适配器的连通性,避免心跳失败。


第四部分:实战项目

项目需求

构建一个自动化内容营销公司,包含完整的组织架构,能够: 1. 自动研究热门话题并生成内容选题 2. 根据选题撰写博客文章草稿 3. 审核文章质量并优化 4. 自动发布到外部平台 5. 全程在预算控制下运行,所有操作可审计

项目设计

组织架构:

CEO Agent (战略决策)
├── Content Strategist Agent (选题研究,OpenClaw)
│   └── 输出:Topic Proposals (工单)
├── Writer Agent (内容创作,Claude Code)
│   └── 输出:Blog Draft (工单)
├── Editor Agent (质量审核,Claude Code)
│   └── 输出:Approved Article (工单)
└── Publisher Agent (发布,HTTP Webhook)
    └── 输出:Published URL (工单)

预算分配: - 公司月度总预算:$150 - CEO:$30(决策量少,预算低) - Content Strategist:$30 - Writer:$40(产出最多,预算最高) - Editor:$25 - Publisher:$25

完整实现代码

步骤 1:创建公司

# 启动 PaperClip
npx paperclipai onboard --yes

# 在 Dashboard 中创建公司
# 名称:Auto Content Agency
# 使命:每周自动发布 3 篇高质量技术博客

步骤 2:配置 CEO Agent

{
  "agentName": "CEO Agent",
  "role": "CEO",
  "adapterType": "process",
  "adapterConfig": {
    "adapter": "claude_local",
    "model": "claude-sonnet-4-20250514",
    "billingType": "api",
    "sessionBehavior": "resume-or-new",
    "heartbeatSchedule": {
      "enabled": true,
      "intervalSec": 3600
    }
  },
  "monthlyBudget": 30.00,
  "soulFile": "You are the CEO of Auto Content Agency. Your mission is to ensure we publish 3 high-quality tech blog posts per week. Break this mission into weekly content plans and delegate to your team."
}

步骤 3:配置下属 Agent

// Content Strategist — 使用 OpenClaw Gateway
{
  "agentName": "Content Strategist",
  "role": "Content Strategist",
  "reportsTo": "CEO Agent",
  "adapterType": "openclaw_gateway",
  "adapterConfig": {
    "gatewayUrl": "ws://localhost:3271",
    "sessionStrategy": "per-run"
  },
  "monthlyBudget": 30.00,
  "skills": ["web_research", "keyword_analysis", "topic_scoring"]
}

// Writer — 使用 Process Adapter
{
  "agentName": "Writer",
  "role": "Writer",
  "reportsTo": "CEO Agent",
  "adapterType": "process",
  "adapterConfig": {
    "adapter": "claude_local",
    "model": "claude-sonnet-4-20250514",
    "billingType": "api",
    "sessionBehavior": "resume-or-new"
  },
  "monthlyBudget": 40.00,
  "skills": ["blog_writing", "seo_optimization"]
}

// Editor — 使用 Process Adapter
{
  "agentName": "Editor",
  "role": "Editor",
  "reportsTo": "CEO Agent",
  "adapterType": "process",
  "adapterConfig": {
    "adapter": "claude_local",
    "model": "claude-sonnet-4-20250514",
    "billingType": "api",
    "sessionBehavior": "resume-or-new"
  },
  "monthlyBudget": 25.00,
  "skills": ["copy_editing", "fact_checking", "quality_scoring"]
}

// Publisher — 使用 HTTP Adapter
{
  "agentName": "Publisher",
  "role": "Publisher",
  "reportsTo": "CEO Agent",
  "adapterType": "http",
  "adapterConfig": {
    "url": "https://my-cms.example.com/api/publish",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer {{CMS_API_TOKEN}}"
    },
    "timeoutMs": 30000
  },
  "monthlyBudget": 25.00,
  "skills": ["cms_publishing", "social_media_posting"]
}

步骤 4:配置治理规则

{
  "companyBudget": {
    "monthlyTotal": 150.00,
    "alertThreshold": 0.8,
    "autoPauseThreshold": 1.0
  },
  "governanceRules": {
    "requireApprovalForHiring": true,
    "requireApprovalForBudgetOver60": true,
    "requireApprovalForPublishing": false,
    "configVersioning": true,
    "auditLogRetention": "90d"
  }
}

步骤 5:启动公司运营

# 启动所有 Agent 的心跳
npx paperclipai start --company "Auto Content Agency"

# 监控运行状态
npx paperclipai status --company "Auto Content Agency"

# 查看审计日志
npx paperclipai audit-log --company "Auto Content Agency" --last 24h

代码解析

本项目综合运用了教程中的以下知识点:

  1. 公司模型(知识点 1.1) — 创建了"Auto Content Agency"公司,定义了明确的使命声明"每周自动发布 3 篇高质量技术博客",使命向下传播到所有 Agent
  2. 组织架构图(知识点 1.2) — 设计了 CEO → 4 个下属 Agent 的层级架构,每个 Agent 有明确的角色和汇报关系
  3. 适配器系统(知识点 2.2) — 混合使用了 3 种适配器:Process(Writer、Editor)、OpenClaw Gateway(Content Strategist)、HTTP(Publisher),展示了 PaperClip 的框架无关性
  4. 心跳调度(知识点 2.1) — CEO Agent 每 3600 秒心跳一次,分解周度内容计划为具体任务,通过工单系统传递给下属 Agent
  5. 预算控制与治理(知识点 3.1) — 配置了公司月度总预算 $150,每个 Agent 有独立预算,80% 警告 + 100% 自动暂停

扩展挑战

  1. 添加 Analytics Agent:在组织架构中增加一个数据分析 Agent,使用 OpenClaw Gateway 适配器,每周自动分析博客文章的流量和互动数据,并反馈给 CEO Agent 用于优化选题策略
  2. 多公司隔离:在同一 PaperClip 实例上创建第二个公司(如"SEO Consulting Agency"),验证多公司数据隔离功能
  3. Clipmart 模板:将你的公司配置导出为模板文件,未来可通过 Clipmart 分享给社区

第五部分:常见问题与排查指南

常见错误及解决方案

错误信息 原因 解决方案
Adapter connection failed: ECONNREFUSED Agent 运行时未启动或地址配置错误 检查 Agent 运行时是否已启动,确认适配器配置中的 URL/端口正确
Heartbeat failed after 3 retries Agent 连续 3 次心跳失败 检查网络连接、API Key 有效性、Agent 运行时日志。使用 npx paperclipai test-adapter --agent <name> 诊断
Agent auto-paused: budget exceeded Agent 月度 Token 使用量达到 100% 在 Dashboard 中调整预算上限(董事会操作),或等待下月重置
Device pairing required OpenClaw Gateway 适配器首次连接需要设备配对 在 OpenClaw 端运行 openclaw devices approve --latest,然后设置持久密钥
PostgreSQL connection error 嵌入式数据库启动失败 检查磁盘空间和端口占用,尝试 npx paperclipai db:reset 重置数据库
Company not found 公司标识符错误 使用 npx paperclipai list-companies 查看所有公司
Telemetry warning on startup 默认启用遥测 设置环境变量 PAPERCLIP_TELEMETRY=false 或使用 --no-telemetry 参数

调试技巧

  1. 逐步验证适配器 — 不要一次性启动所有 Agent。先用 npx paperclipai test-adapter 逐个验证每个适配器的连通性,确认所有适配器正常后再启动心跳调度。

  2. 使用审计日志追踪问题 — 当 Agent 行为异常时,检查审计日志中的完整工单链:npx paperclipai audit-log --company <name> --agent <agent> --last 1h。日志会显示 Agent 接收到的指令、执行过程和返回结果。

  3. 从预构建模板开始 — 如果自定义配置遇到问题,先用预构建公司模板验证 PaperClip 本身是否正常工作。模板中的适配器配置经过测试,可以作为调试基准。


第六部分:学习路线推荐

官方文档推荐阅读顺序

  1. GitHub README — 快速了解 PaperClip 的定位、特性和限制(特别是"What Paperclip is not"部分)
  2. Quick Start Guide — 完成第一次 npx paperclipai onboard --yes 体验
  3. Adapter Configuration — 理解 Process / HTTP / OpenClaw Gateway 三种适配器的配置和使用场景
  4. Budget & Governance — 学习多层级预算控制和治理机制的最佳实践
  5. Pre-built Companies — 研究 16 个预构建公司模板,理解不同业务场景的组织设计
  6. API Reference(Mintlify 文档)— 学习 Dashboard API 的完整接口定义

推荐进阶资源