攀岩者

Paperclip部署手册：打造你的AI Agent公司

作者：

climbing

在

从零开始，用 Paperclip 搭建一个由 AI Agent 组成的”公司”

前言

你有没有想过，如果 AI Agent 能像员工一样组成一家公司，自动分工协作、完成任务、汇报进度，那该多好？

Paperclip 就是这样一个开源项目——它是一个 AI Agent 编排平台，让你可以把多个 AI Agent（如 Hermes、OpenClaw、Claude Code 等）组织成一家”公司”，分配任务、追踪进度、控制成本。

一句话总结：如果 OpenClaw 是一个员工，Paperclip 就是整个公司。

一、Paperclip 是什么？

1.1 核心概念

Paperclip 的核心理念是把 AI Agent 当作公司员工来管理：

概念 说明 类比

|——|——|——|

Company 一个公司实例 你的企业
Agent 一个 AI Agent 一个员工
Role Agent 的角色 CEO、CTO、工程师
Issue 一个任务 一张工单
Heartbeat 定期唤醒 Agent 员工上班打卡
Budget 月度预算 员工报销额度

1.2 支持的 Agent 类型

Paperclip 支持多种 AI Agent：

Agent 说明 特点

|——-|——|——|

Hermes Agent 通用 AI 助手 工具丰富、可扩展
OpenClaw 代码 Agent 专注编程任务
Claude Code Anthropic 的代码 Agent 强大的代码能力
Codex OpenAI 的代码 Agent GPT 驱动
Cursor AI 编程 IDE 集成开发环境
Bash 命令行 Agent 执行系统命令

1.3 架构图

`

┌─────────────────────────────────────────────┐

│ Paperclip 服务器 │

│ http://localhost:3100 │

├─────────────────────────────────────────────┤

│ │

│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │

│ │ CEO │ │ CTO │ │ 工程师 │ │

│ │ Agent │ │ Agent │ │ Agent │ │

│ └────┬────┘ └────┬────┘ └────┬────┘ │

│ │ │ │ │

│ ▼ ▼ ▼ │

│ ┌─────────────────────────────────────┐ │

│ │ Issue 任务系统 │ │

│ └─────────────────────────────────────┘ │

│ │ │ │ │

│ ▼ ▼ ▼ │

│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │

│ │ Heartbeat│ │ Budget │ │ Activity│ │

│ │ 调度器 │ │ 预算控制│ │ 活动日志│ │

│ └─────────┘ └─────────┘ └─────────┘ │

│ │

└─────────────────────────────────────────────┘

`

二、环境准备

2.1 系统要求

项目 要求

|——|——|

操作系统 Linux / macOS / Windows (WSL2)
Node.js 20+
pnpm 9.15+
内存 2GB+
磁盘 1GB+

2.2 安装 Node.js 和 pnpm

`bash

# 安装 Node.js (使用 nvm)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

source ~/.bashrc

nvm install 20

nvm use 20

# 安装 pnpm

npm install -g pnpm@latest

`

2.3 安装 Paperclip

`bash

# 全局安装

npm install -g paperclipai@latest

# 验证安装

npx paperclipai –version

`

三、初始化 Paperclip

3.1 快速初始化

`bash

# 一键初始化（推荐）

npx paperclipai onboard –yes

`

这个命令会：

  1. 创建配置文件 ~/.paperclip/instances/default/config.json
  2. 启动嵌入式 PostgreSQL 数据库
  3. 创建默认公司和 CEO Agent
  4. 启动 API 服务器（默认端口 3100）

3.2 自定义初始化

`bash

# 指定绑定模式

npx paperclipai onboard –yes –bind lan # 局域网访问

npx paperclipai onboard –yes –bind tailnet # Tailscale 访问

`

3.3 手动初始化

如果你想更精细地控制配置：

`bash

# 克隆仓库

git clone https://github.com/paperclipai/paperclip.git

cd paperclip

pnpm install

pnpm dev

`

四、配置详解

4.1 配置文件位置

`

~/.paperclip/instances/default/

├── config.json # 主配置文件

├── db/ # PostgreSQL 数据目录

├── data/

│ ├── backups/ # 自动备份

│ └── storage/ # 文件存储

├── logs/

│ └── server.log # 服务器日志

└── secrets/

└── master.key # 加密密钥

`

4.2 核心配置项

`json

{

“server”: {

“deploymentMode”: “local_trusted”, // 本地信任模式

“exposure”: “private”, // 私有部署

“bind”: “loopback”, // 绑定到 127.0.0.1

“host”: “127.0.0.1”,

“port”: 3100 // API 端口

},

“database”: {

“mode”: “embedded-postgres”, // 嵌入式数据库

“embeddedPostgresPort”: 54329

},

“storage”: {

“provider”: “local_disk” // 本地存储

}

}

`

4.3 修改配置

`bash

# 使用 CLI 修改配置

npx paperclipai configure

# 或直接编辑配置文件

nano ~/.paperclip/instances/default/config.json

`

五、启动和停止

5.1 启动 Paperclip

`bash

# 前台启动（开发模式）

npx paperclipai run

# 后台启动（生产模式）

nohup npx paperclipai run > /tmp/paperclip.log 2>&1 &

# 使用 systemd 管理（推荐）

sudo tee /etc/systemd/system/paperclip.service << 'EOF'

[Unit]

Description=Paperclip AI Agent Orchestration

After=network.target

[Service]

Type=simple

User=your_username

ExecStart=/usr/local/bin/npx paperclipai run

Restart=always

RestartSec=10

[Install]

WantedBy=multi-user.target

EOF

sudo systemctl enable paperclip

sudo systemctl start paperclip

`

5.2 停止 Paperclip

`bash

# 前台模式：Ctrl+C

# 后台模式

pkill -f paperclipai

# systemd 模式

sudo systemctl stop paperclip

`

5.3 检查状态

`bash

# 健康检查

curl http://localhost:3100/api/health

# 查看日志

tail -f ~/.paperclip/instances/default/logs/server.log

`

六、创建 Agent 团队

6.1 创建 CEO Agent

`bash

# CEO 是公司的最高管理者

npx paperclipai agent create

–company-id

–payload-json ‘{

“name”: “CEO”,

“role”: “ceo”,

“adapterType”: “hermes_local”,

“adapterConfig”: {

“timeoutSec”: 300,

“persistSession”: true,

“model”: “xiaomi/mimo-v2.5-pro”,

“provider”: “xiaomi”

}

}’

`

6.2 创建 CTO Agent

`bash

# CTO 负责技术决策

npx paperclipai agent create

–company-id

–payload-json ‘{

“name”: “CTO”,

“role”: “cto”,

“adapterType”: “hermes_local”,

“adapterConfig”: {

“timeoutSec”: 300,

“persistSession”: true,

“model”: “xiaomi/mimo-v2.5-pro”,

“provider”: “xiaomi”

}

}’

`

6.3 创建工程师 Agent

`bash

# 工程师 Agent（使用 OpenClaw）

npx paperclipai agent create

–company-id

–payload-json ‘{

“name”: “Engineer-1”,

“role”: “engineer”,

“adapterType”: “openclaw_local”,

“adapterConfig”: {

“timeoutSec”: 600,

“persistSession”: true

}

}’

`

6.4 查看 Agent 列表

`bash

# 列出所有 Agent

npx paperclipai agent list –company-id

# 查看单个 Agent 详情

npx paperclipai agent get

`

七、配置 Agent 参数

7.1 修改模型配置

`bash

# 使用 Xiaomi MiMo 模型

npx paperclipai agent update

–payload-json ‘{

“adapterConfig”: {

“model”: “xiaomi/mimo-v2.5-pro”,

“provider”: “xiaomi”

}

}’

# 使用 OpenRouter

npx paperclipai agent update

–payload-json ‘{

“adapterConfig”: {

“model”: “anthropic/claude-sonnet-4”,

“provider”: “openrouter”

}

}’

`

7.2 配置 Heartbeat（定时唤醒）

`bash

# 启用 Heartbeat，每 300 秒唤醒一次

npx paperclipai agent update

–payload-json ‘{

“runtimeConfig”: {

“heartbeat”: {

“enabled”: true,

“intervalSec”: 300,

“cooldownSec”: 10,

“maxConcurrentRuns”: 5

}

}

}’

`

7.3 设置预算

`bash

# 设置月度预算（单位：分，10000 = $100）

npx paperclipai agent update

–payload-json ‘{

“budgetMonthlyCents”: 10000

}’

`

八、常见问题

8.1 Agent 状态显示 “error”

原因： API 密钥未配置或模型不可用

解决：

`bash

# 检查 Agent 配置

npx paperclipai agent get

# 修改为可用的模型

npx paperclipai agent update

–payload-json ‘{“adapterConfig”:{“model”:”xiaomi/mimo-v2.5-pro”,”provider”:”xiaomi”}}’

# 重置运行状态

npx paperclipai agent runtime-state:reset-session

# 重新激活

npx paperclipai agent resume

`

8.2 Heartbeat 不触发

原因： Heartbeat 未启用或配置错误

解决：

`bash

# 检查 Heartbeat 配置

npx paperclipai agent get | grep heartbeat

# 手动触发 Heartbeat

npx paperclipai agent heartbeat:invoke

`

8.3 数据库连接失败

原因： 嵌入式 PostgreSQL 未启动

解决：

`bash

# 重启 Paperclip

pkill -f paperclipai

npx paperclipai run

`

8.4 端口被占用

解决：

`bash

# 查找占用端口的进程

lsof -i :3100

# 修改端口

npx paperclipai configure

# 或编辑 config.json 修改 port

`

九、备份和恢复

9.1 自动备份

Paperclip 默认每 60 分钟自动备份一次，保留 30 天。

配置文件中的备份设置：

`json

{

“database”: {

“backup”: {

“enabled”: true,

“intervalMinutes”: 60,

“retentionDays”: 30,

“dir”: “~/.paperclip/instances/default/data/backups”

}

}

}

`

9.2 手动备份

`bash

# 创建备份

npx paperclipai db:backup

# 备份文件位置

ls ~/.paperclip/instances/default/data/backups/

`

9.3 恢复数据

`bash

# 停止服务

pkill -f paperclipai

# 恢复数据库

pg_restore -d paperclip

# 重启服务

npx paperclipai run

`

十、安全建议

10.1 生产环境配置

`json

{

“server”: {

“deploymentMode”: “authenticated”,

“exposure”: “private”,

“bind”: “0.0.0.0”,

“host”: “0.0.0.0”,

“port”: 3100,

“allowedHostnames”: [“your-domain.com”]

},

“auth”: {

“disableSignUp”: true

}

}

`

10.2 使用 HTTPS

推荐使用 Caddy 或 Nginx 作为反向代理：

`bash

# Caddy 配置示例

your-domain.com {

reverse_proxy localhost:3100

}

`

10.3 限制访问

`bash

# 使用防火墙限制访问

sudo ufw allow from 192.168.1.0/24 to any port 3100

`

附录：CLI 命令速查

命令 说明

|——|——|

npx paperclipai run 启动服务
npx paperclipai configure 修改配置
npx paperclipai doctor 诊断检查
npx paperclipai company list 列出公司
npx paperclipai agent list 列出 Agent
npx paperclipai agent create 创建 Agent
npx paperclipai agent get 查看 Agent
npx paperclipai agent update 更新 Agent
npx paperclipai agent delete 删除 Agent
npx paperclipai agent resume 恢复 Agent
npx paperclipai agent pause 暂停 Agent
npx paperclipai agent heartbeat:invoke 手动触发 Heartbeat
npx paperclipai issue list 列出 Issue
npx paperclipai issue create 创建 Issue
npx paperclipai db:backup 手动备份

维护者：攀岩者

最后更新：2026年6月15日

版本：v1.0

项目地址：https://github.com/paperclipai/paperclip

官方文档：https://paperclip.ing/docs

评论

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

更多文章