## 项目概述

Paperclip 是一个开源的 AI 智能体编排平台，旨在帮助用户管理多个 AI 智能体（如 Claude Code、Codex、Gemini CLI 等）协同工作。它通过组织架构图、任务管理、预算控制、治理审批和心跳机制，将智能体组织成一个虚拟公司，让用户像管理团队一样管理智能体，实现业务目标。项目采用 TypeScript 编写，基于 Node.js 服务器和 React UI，遵循 MIT 许可证。

## 核心功能

- **自带智能体 (Bring Your Own Agent)**：支持 Claude Code、Codex、Gemini CLI、Kimi Code CLI、OpenClaw 等多种智能体运行时，通过适配器（Adapter）接入。
- **组织架构图 (Org Chart)**：为智能体定义角色、头衔、汇报关系和权限，形成混合人机组织架构。
- **目标对齐 (Goal Alignment)**：每个任务都关联到公司、项目、目标，智能体明确知道做什么和为什么。
- **心跳执行 (Heartbeats)**：智能体按计划或事件触发唤醒，执行任务并汇报结果，支持会话持久化。
- **预算与成本控制 (Budget & Cost Control)**：按公司、智能体、项目等维度跟踪 token 和成本，设置预算阈值，超支自动暂停。
- **治理与审批 (Governance & Approvals)**：支持审批流程、执行策略、审计日志，可暂停、恢复或终止智能体。
- **任务与工单系统 (Ticket System)**：基于工单的任务管理，支持评论、附件、依赖、审批门禁，所有操作可追溯。
- **多组织隔离 (Multi-Organization)**：单实例可运行多个公司，数据完全隔离。
- **技能管理 (Skills)**：提供技能工作室、技能市场，支持运行时技能注入。
- **插件系统 (Plugins)**：支持外部适配器插件，扩展功能。
- **移动端支持 (Mobile Ready)**：可通过手机监控和管理智能体。

## 适用与不适用场景

**适用场景：**

- 需要构建自主 AI 组织，协调多个不同类型的智能体（如 OpenClaw、Codex、Claude Code）共同完成目标。
- 同时运行大量智能体终端（如 20 个 Claude Code 终端），需要统一跟踪和管理。
- 希望智能体 7x24 小时自主运行，但仍需审计和干预。
- 需要监控成本并强制执行预算。
- 希望用类似任务管理器的界面管理智能体。
- 需要从手机端管理自主业务。

**不适用场景：**

- 仅需要一个聊天机器人（Paperclip 不是聊天工具）。
- 需要构建智能体框架（Paperclip 不提供智能体构建能力）。
- 需要拖拽式工作流构建器（Paperclip 不提供）。
- 需要提示词管理工具（智能体自带提示词）。
- 仅管理单个智能体（Paperclip 面向团队）。
- 需要代码审查工具（Paperclip 不审查代码）。

## 技术架构与依赖

- **语言**：TypeScript
- **后端**：Node.js 服务器
- **前端**：React UI
- **数据库**：嵌入式 PostgreSQL（本地开发），生产环境可配置外部 PostgreSQL
- **包管理器**：pnpm
- **Node.js 版本**：24.11+，pnpm 9.15+
- **适配器**：支持 Claude Code、Codex、Gemini CLI、Kimi Code CLI、OpenCode、Cursor、Pi、Hermes、OpenClaw、Process、HTTP 等，可通过插件扩展。
- **可观测性**：可选 OpenTelemetry 自动埋点（trace），可选 Sentry 错误监控。
- **遥测**：默认启用匿名使用遥测，可通过环境变量或配置禁用。

## 安装与快速开始

**快速安装（推荐）：**

```bash
curl -fsSLO https://paperclip.ing/install.sh
curl -fsSLO https://paperclip.ing/install.sh.sha256
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c install.sh.sha256
else
  shasum -a 256 -c install.sh.sha256
fi
bash install.sh
```

安装脚本会确保 Node.js 24.11+ 可用，安装 Paperclip CLI 到 `~/.paperclip/cli`，并启动交互式引导。

**非交互式安装：**

```bash
curl -fsSL https://paperclip.ing/install.sh | bash -s -- --no-prompt --no-onboard
paperclipai onboard --yes
```

**临时体验（不安装）：**

```bash
npx --registry https://registry.npmjs.org paperclipai onboard --yes
```

**手动安装（开发）：**

```bash
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
```

启动后 API 服务器运行在 `http://localhost:3100`，自动创建嵌入式 PostgreSQL 数据库。

## 典型使用方法

1. **定义目标**：在 Paperclip 中创建公司，定义公司目标（如“构建 #1 AI 笔记应用，达到 $1M MRR”）。
2. **组建团队**：创建智能体（如 CEO、CTO、工程师、设计师），配置适配器（如 `claude_local`、`codex_local`），设置角色、汇报关系和预算。
3. **分配任务**：创建任务（Issue），关联到项目和目标，分配给智能体。
4. **审批与启动**：审查策略，设置预算，点击“开始”，智能体通过心跳机制自动执行任务。
5. **监控与干预**：通过仪表盘监控任务状态、成本、活动日志，必要时暂停、恢复或终止智能体。
6. **使用 API**：通过 REST API 管理智能体、任务、审批、成本等。

## 配置与部署要点

- **部署模式**：支持本地可信模式（无需认证）和认证模式（Better Auth 会话）。
- **数据库**：本地开发使用嵌入式 PostgreSQL，生产环境需配置外部 PostgreSQL。
- **认证**：智能体使用短期 JWT（`PAPERCLIP_API_KEY`）或长期 API 密钥；董事会操作员使用会话认证。
- **预算**：按月设置公司/智能体预算，80% 触发软告警，100% 硬停止并自动暂停智能体。
- **遥测**：默认启用匿名遥测，可通过 `PAPERCLIP_TELEMETRY_DISABLED=1`、`DO_NOT_TRACK=1`、`CI=true` 或配置文件禁用。
- **可观测性**：设置 `OTEL_EXPORTER_OTLP_ENDPOINT` 启用 OpenTelemetry trace；设置 `SENTRY_DSN_FRONTEND`/`SENTRY_DSN_BACKEND` 启用 Sentry 错误监控。
- **适配器配置**：每个适配器需配置工作目录（`cwd`）、超时、环境变量等，可使用“测试环境”功能验证。
- **安全**：本地 CLI 适配器在主机上非沙箱运行，需注意权限和密钥管理。

## 限制、风险与许可证

- **许可证**：MIT License，© 2026 Paperclip Labs, Inc。
- **风险**：本地 CLI 适配器非沙箱运行，存在安全风险；智能体输出不可信，需防御性解析；遥测默认启用，需注意隐私。
- **限制**：不是聊天机器人、不是智能体框架、不是工作流构建器、不是提示词管理器、不是单智能体工具、不是代码审查工具。
- **路线图**：内存/知识、MAXIMIZER MODE、工作队列、自组织、自动组织学习、CEO 聊天、桌面应用、自带工单系统等尚未实现。

## 官方链接

- **GitHub 仓库**：https://github.com/paperclipai/paperclip
- **官方文档**：https://docs.paperclip.ing
- **官方网站**：https://paperclip.ing
- **Discord 社区**：https://discord.gg/m4HZY7xNG3
- **Twitter/X**：https://x.com/papercliping
- **最新版本**：v2026.831.1（发布于 2026-09-02）

## 信息来源和分析时间

- **信息来源**：GitHub 仓库 README、文档（docs/ 目录）、CONTRIBUTING.md、最新发布信息。
- **分析时间**：2026-09-02（基于最新发布版本时间）