Paperclip开源AI智能体编排系统安装与配置指南

1. 项目概述

Paperclip是一个开源的AI智能体编排系统，它能够将多个AI智能体组织起来，形成一个完整的"零人工公司"运作体系。这个框架特别适合那些希望用AI自动化运行整个业务流程的用户。

我第一次接触Paperclip时就被它的设计理念吸引了。它不仅仅是一个任务管理器，更像是一个完整的公司管理系统 - 有组织架构、预算控制、工作流程和审计追踪。想象一下，你可以像管理真实员工一样管理一群AI智能体，给它们分配任务、设定预算、监控工作进度，而这一切都在一个统一的仪表板中完成。

2. 系统架构解析

2.1 核心组件

Paperclip由两个主要组件构成：

1. Node.js后端服务：负责智能体的调度、任务分配和系统管理
2. React前端界面：提供直观的管理控制台

这种前后端分离的设计使得系统既保持了灵活性，又能提供良好的用户体验。后端使用PostgreSQL作为数据库，确保数据的安全性和可靠性。

2.2 智能体协调机制

Paperclip最核心的功能是它的智能体协调系统。它通过以下几种机制确保智能体高效协作：

• 心跳机制：智能体会定期"唤醒"检查任务
• 目标对齐：每个任务都与公司整体目标关联
• 预算控制：为每个智能体设置月度预算上限
• 治理规则：可以审批、暂停或终止任何智能体

3. 安装准备

3.1 硬件要求

Paperclip可以运行在多种环境中：

• 群晖NAS（DSM 7.0及以上）
• 任何支持Docker的Linux服务器
• 本地开发环境（用于测试）

建议配置：

• 至少2核CPU
• 4GB内存
• 20GB可用存储空间

3.2 软件依赖

在开始安装前，请确保已安装：

1. Docker（版本20.10.0或更高）
2. Docker Compose（版本1.29.0或更高）

可以通过以下命令检查版本：

bash复制docker --version
docker-compose --version

4. 详细安装步骤

4.1 创建项目目录

首先需要为Paperclip创建专用的工作目录。这一步非常重要，因为后续所有数据都会存储在这些目录中。

bash复制# 创建主目录和子目录
mkdir -p /volume1/docker/paperclip/{data,pgdata}

# 进入paperclip目录
cd /volume1/docker/paperclip

# 设置目录权限
chmod a+rw data

注意：如果你使用的是群晖NAS，/volume1/docker是推荐的Docker应用存储位置。在其他Linux系统上，你可以选择任何合适的路径。

4.2 配置docker-compose.yml

创建docker-compose.yml文件是安装的核心步骤。这个文件定义了所有服务容器及其配置。

yaml复制version: '3.8'

services:
  db:
    image: postgres:17-alpine
    container_name: paperclip-db
    restart: unless-stopped
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: paperclip
      POSTGRES_PASSWORD: paperclip
      POSTGRES_DB: paperclip
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U paperclip -d paperclip"]
      interval: 2s
      timeout: 5s
      retries: 30

  server:
    image: tuyenvd/paperclip:latest
    container_name: paperclip-web
    restart: unless-stopped
    ports:
      - "3198:3100"
    volumes:
      - ./data:/paperclip
    environment:
      DATABASE_URL: postgres://paperclip:paperclip@db:5432/paperclip
      PORT: "3100"
      SERVE_UI: "true"
      PAPERCLIP_DEPLOYMENT_MODE: "authenticated"
      PAPERCLIP_DEPLOYMENT_EXPOSURE: "private"
      PAPERCLIP_PUBLIC_URL: "http://你的IP:3198"
      BETTER_AUTH_SECRET: "请替换为你的密钥"
    depends_on:
      db:
        condition: service_healthy

4.3 关键配置说明

4.4 安全设置建议

1. 认证密钥生成：

bash复制openssl rand -base64 32

将生成的随机字符串作为BETTER_AUTH_SECRET的值。

2. 访问控制：

• 保持PAPERCLIP_DEPLOYMENT_EXPOSURE为private
• 考虑配置防火墙规则限制访问IP

3. 数据备份：

• 定期备份pgdata和data目录
• 考虑设置自动备份脚本

5. 启动与初始化

5.1 启动服务

使用以下命令启动Paperclip：

bash复制docker-compose up -d

启动后，可以通过以下命令查看日志：

bash复制docker-compose logs -f

5.2 数据库初始化

首次启动时，系统会自动初始化数据库。这个过程可能需要几分钟时间。你可以通过以下命令检查数据库状态：

bash复制docker exec -it paperclip-db psql -U paperclip -c "\l"

6. 系统配置与使用

6.1 首次访问

服务启动后，在浏览器中访问：

code复制http://<你的服务器IP>:3198

6.2 管理员账号创建

首次访问时需要进行系统初始化：

1. 进入容器执行初始化命令：

bash复制docker exec -it paperclip-web /bin/bash
pnpm paperclipai onboard

2. 选择"Quickstart"选项生成管理员邀请链接

3. 在浏览器中打开邀请链接，创建管理员账号

注意：密码必须包含大小写字母、数字和特殊字符，长度至少8位。

6.3 公司设置

创建账号后，需要设置第一个公司：

1. 输入公司名称和描述
2. 设置公司时区
3. 配置默认货币

6.4 智能体配置

添加第一个AI智能体：

1. 选择适配器类型（如OpenCode）
2. 配置模型参数
3. 设置工作目录（确保目录已存在）
4. 配置预算限制

7. 常见问题解决

7.1 启动问题排查

7.2 运行时报错处理

1. 工作目录不存在：

bash复制docker exec -it paperclip-web mkdir -p /paperclip/project

2. 智能体不响应：

• 检查智能体心跳配置
• 验证API密钥是否正确
• 查看智能体日志

3. 预算超支：

• 调整智能体预算设置
• 检查任务分配是否合理

8. 高级配置建议

8.1 多公司管理

Paperclip支持同时管理多个独立公司：

1. 在管理员界面创建新公司
2. 为每个公司分配不同的智能体
3. 设置公司间的数据隔离策略

8.2 自定义智能体

除了内置的智能体类型，你还可以：

1. 开发自定义适配器
2. 集成专有AI模型
3. 配置混合智能体工作流

8.3 监控与告警

建议配置：

1. 系统健康监控
2. 智能体活动告警
3. 预算使用通知

可以通过以下命令查看系统资源使用情况：

bash复制docker stats paperclip-web paperclip-db

9. 维护与升级

9.1 日常维护

1. 日志管理：

bash复制docker-compose logs --tail=100 -f

2. 数据备份：

bash复制tar -czvf paperclip_backup_$(date +%Y%m%d).tar.gz /volume1/docker/paperclip

3. 性能监控：

bash复制docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

9.2 系统升级

1. 停止现有服务：

bash复制docker-compose down

2. 备份数据目录

3. 拉取最新镜像：

bash复制docker-compose pull

4. 重新启动：

bash复制docker-compose up -d

10. 使用心得与技巧

在实际使用Paperclip几个月后，我总结了一些实用技巧：

1. 智能体分组：按功能或部门对智能体进行分组管理，可以提高效率。

2. 任务优先级：合理设置任务优先级，确保关键任务优先执行。

3. 预算分配：初期可以给每个智能体设置较低的预算限制，根据实际使用情况逐步调整。

4. 工作目录规划：为不同类型的项目创建独立的工作目录，避免混乱。

5. 定期审查：每周检查智能体的工作日志和成本报告，及时调整策略。

一个特别有用的技巧是使用"心跳间隔"来控制智能体的活跃程度。对于不需要实时响应的任务，可以适当延长心跳间隔来节省成本。