Paperclip：把企业管理架构搬进 AI Agent 世界的开源编排平台

开源AgentAI

当 AI Agent 的数量从 1 个增长到 20 个，问题就变了。单个 Claude Code 或 Codex 实例运行在一个终端窗口里，开发者能跟踪它做什么。但当 20 个 Agent 同时跑在同一个代码库上，每个都在自己的终端里，没有共享的任务追踪、预算控制或审计日志时，编排就成了一个全新的工程问题。

Paperclip（MIT 许可证，GitHub 7.7 万 Star）给出的答案是将整套企业管理概念搬进 Agent 世界：组织架构图、角色权限、预算上限、审批门禁、心跳调度、审计追踪。它不自建模型，也不替代 Claude Code、Codex 等编码 Agent，而是在这些 Agent 之上搭建一个组织层，让它们像公司里的员工一样被分配任务、汇报工作、消耗预算。

Paperclip

核心隐喻：Agent 即员工

Paperclip 的设计中心是一个完整的组织模型。每个 Agent 在系统中拥有一个"员工身份"：角色（CEO、CTO、工程师、设计师）、汇报关系、权限范围、月度预算。任务从公司目标出发，逐层拆解到项目和具体 issue，Agent 通过"领取"任务（atomic checkout）获得排他执行权，完成后提交工作产物供人类审查。

这套模型的关键设计选择包括：

  • 原子任务领取：同一时间只有一个 Agent 能 checkout 一个任务，避免重复工作。任务领取和预算检查在同一个事务中完成，不存在"领了任务但预算已超"的竞态。
  • 持久化 Agent 状态：Agent 的会话上下文在心跳之间持久化，下次唤醒时恢复之前的上下文而非从头开始。
  • 目标链追溯：每个任务携带完整的目标祖先链，Agent 在执行时能看到这个任务属于哪个项目、哪个公司目标，而不只是一个标题。
  • 审批门禁：关键操作（雇佣新 Agent、修改策略、发布代码）需要人类"董事会"批准，配置变更带版本控制，支持回滚。

心跳执行模型

Paperclip 的调度核心是"心跳"（Heartbeat）机制。Agent 默认不持续运行，而是按预设的 cron 表达式被唤醒。每次唤醒的流程：

  1. 心跳队列从数据库中取出待执行的唤醒任务，进行去重合并（coalescing）
  2. 预算检查：当前 Agent 本月剩余预算是否足够执行这次任务
  3. 工作区解析：确定 Agent 应该在哪个目录、哪个分支上工作
  4. 密钥注入：根据 Agent 的权限范围注入对应的 API Key 和密钥
  5. 技能加载：注入该 Agent 角色对应的工作流技能和项目上下文
  6. 适配器调用：通过 adapter 模式调用实际的 Agent 运行时（Claude Code、Codex、Cursor、OpenClaw、HTTP webhook 等）
  7. 产出记录：运行产出结构化日志、成本事件、会话状态和审计追踪

心跳机制的意义在于成本控制。持续运行的 Agent 会不断消耗 token，而心跳模式下 Agent 只在被需要时唤醒，执行完即休眠。Paperclip 的预算系统按公司、Agent、项目、目标、issue、提供商、模型七个维度追踪 token 消耗，超出阈值时自动暂停 Agent 并取消队列中的任务。

四大子系统

Paperclip 将自身定位为 Agent 时代的控制平面（Control Plane），而非 Agent 框架。其架构由四个子系统组成。

组织与身份系统：管理 Agent 的角色、权限和汇报关系。Agent API Key 与短生命周期运行 JWT 分离，每个变更请求都可追溯到具体的行为主体。支持两种部署模式：本地可信模式（trusted local loopback，无需认证，最快上手）和认证私有模式（适合团队或多 Agent 跨网络协作）。

工作与任务系统：任务携带公司/项目/目标/父任务链接，支持阻塞依赖、评论、文档、附件和工作产物。任务的原子领取带执行锁，确保不会有两个 Agent 同时处理同一个任务。

治理系统：董事会审批工作流、执行策略带审查/批准阶段、预算硬停止、Agent 暂停/恢复/终止、完整审计日志。治理对象包括：Agent 的雇佣和解雇、策略变更、预算调整、以及 Agent 产出的代码发布。

基础设施系统：项目工作区和隔离执行工作区（git worktree、operator 分支）、运行时服务（开发服务器、预览 URL）、插件系统（out-of-process worker、能力门控、UI 贡献）、密钥管理（实例级和公司级密钥、加密本地存储、按需注入）。同时支持 OpenTelemetry 追踪和多种沙箱环境（e2b、Cloudflare、Daytona、Modal、Novita、自建 Kubernetes）。

与同类工具的定位差异

Paperclip 明确定义了自己"不是什么"：不是聊天机器人（Agent 有工作而非聊天窗口），不是 Agent 框架（不告诉你怎么构建 Agent，而是告诉你怎么运营一个由 Agent 组成的公司），不是工作流构建器（没有拖拽管道），不是 Prompt 管理器（Agent 自带 prompt、模型和运行时）。

与 OpenClaw、Claude Code 等单 Agent 工具的关系是互补而非竞争：Paperclip 使用这些 Agent，将它们编排进组织架构。与 Linear、Asana 等传统任务管理器相比，Paperclip 的差异在于 Agent 是一等公民——任务领取、状态持久化、预算追踪、心跳调度都是为非人类"员工"量身设计的。

一个更容易理解其定位的类比：如果 Claude Code 是一个员工，Paperclip 就是这家公司。它管理的对象是业务目标、组织架构和预算，PR 和代码审查需要自行接入。

技术栈与部署

Paperclip 的技术栈是 Node.js 服务端（TypeScript）+ React UI，内嵌 PostgreSQL（开发模式无需外部数据库）。构建工具使用 pnpm monorepo。

自托管部署的最低要求是 Node.js 20+ 和 pnpm 9.15+。一行命令安装：

bash
curl -fsSL https://paperclip.ing/install.sh | bash

安装后执行交互式 onboarding，或使用 --no-prompt 跳过交互：

bash
paperclipai onboard --yes

开发模式启动 API 服务在 http://localhost:3100，嵌入式 PostgreSQL 数据库自动创建。生产部署可指向外部 PostgreSQL，配合 Docker 或任何 Node.js 托管平台。

Agent 通过 adapter 模式接入。适配器的接口契约是"如果它能接收心跳信号，它就是雇员"。当前支持的适配器包括 Claude Code、Codex、Cursor、Gemini、Bash CLI agent、HTTP webhook bot 以及外部插件适配器。Agent 可以跑在本地、远程 SSH、云沙箱（e2b、Modal、Cloudflare）或自建 Kubernetes 集群上。

多公司隔离

Paperclip 支持单一部署运行多个"公司"（多租户隔离）。每个实体（Agent、任务、项目、技能、密钥）都是 company-scoped 的，不同公司之间的数据完全隔离。这设计面向同时运营多个自主业务的场景——例如一个人管理多个 SaaS 产品，每个产品作为独立公司部署，共享同一个 Paperclip 实例但拥有各自的组织架构、Agent 团队和审计追踪。

公司层面支持完整的导入导出：Agent 配置、技能、项目、例行任务和 issue 可以打包为模板，带密钥擦除和冲突处理，方便在新环境中快速复制一个组织。

适用边界

Paperclip 的 FAQ 部分坦率说明了它不适合的场景：只有 1 个 Agent 时不需要它（直接用 Claude Code 或 Codex 即可）；需要拖拽式工作流可视化的场景不适合（Paperclip 模拟的是组织而非管道）；需要细粒度代码审查工具的场景也不适合（Paperclip 编排工作但不审查 PR，审查流程需自行接入）。

Paperclip 适合的目标用户画像很明确：同时运行 5-20 个编码 Agent、需要追踪每个 Agent 的工作和成本、需要定期执行例行任务（客户支持、报告生成、社交媒体管理）、希望 Agent 7x24 小时自主运行但仍保留人工审计和介入能力的开发者或小团队。