Node.js Paperclip 编排AI智能体团队的虚拟公司操作系统

如果你曾经同时打开过五个以上的 Claude Code 终端窗口，一边写代码一边担心某个 Agent 陷入死循环把 API 额度烧光，那你一定理解这种感受：管理一群 AI 智能体，比管理真人团队还要累。单个 Agent 能力再强，一旦数量上去，任务归属、上下文传递、成本控制、质量把关全部变成一团乱麻。Paperclip 解决的正是这个问题。它不生产 Agent，而是给 Agent 建了一家公司——有组织架构、有预算约束、有审批流程，让一群各自为战的智能体真正像一个团队那样运转。

项目基本信息

信息项详情
项目名称paperclip
GitHub地址https://github.com/paperclipai/paperclip
项目描述The open-source app everyone uses to manage agents at work
作者paperclipai
开源协议MIT License
开源状态公开状态
LanguagesTypeScript
支持平台Web / Windows / macOS / Linux
最后更新2026-10-28

一、项目介绍

Paperclip 是一个开源的 AI 智能体编排平台，用一句话概括它的定位：如果 Claude Code 或 OpenClaw 是员工，那 Paperclip 就是公司本身。

它的核心构成并不复杂：一个 Node.js 服务端加上 React 前端界面，底层使用 PostgreSQL（本地运行时自动嵌入），通过适配器连接各种 Agent 运行时（Claude Code、Codex、Gemini CLI、Kimi 等），再由一套任务系统和心跳调度机制驱动整个“公司”运转。你不需要改变 Agent 本身的任何工作方式，Paperclip 管理的是它们协作的那一层。

很多人第一次看到 Paperclip 的界面会以为它是个任务管理器。表面上看确实如此：左侧有组织架构，中间是任务看板，右侧有活动流和成本面板。但真正让它区别于普通项目管理工具的地方在于，任务不是给人看的，是给 Agent 执行的。一个任务从公司使命逐层拆解到项目、再到具体工单，Agent 被唤醒后读取的是完整的上下文链，知道自己在为什么目标服务，而不是只看到一个孤立的标题。

Paperclip 的另一个关键设计是心跳机制。Agent 不会一直空转烧钱，而是在被分配任务或到达预定心跳时间时才会“醒来”，检查待办工作，执行，然后停止。这意味着你可以让一个 Agent 团队在夜间自动推进项目，早上起来看结果和账单，而不是整夜盯着终端。

二、核心优势

自带 Agent，不锁定运行时

Paperclip 最务实的设计是“Bring Your Own Agent”。你不需要放弃已经在用的 Claude Code、Codex 或 Cursor。只要对应的运行时能接收 Paperclip 的调用，就可以被“雇佣”进组织架构中，获得一个岗位、一条汇报线和一个预算额度。对于已经在某个 Agent 上建立了工作流的开发者来说，迁移成本几乎为零。

成本控制是硬约束，不是事后统计

这是 Paperclip 真正让重度 Agent 用户安心的地方。你可以给每个 Agent、每个项目甚至整个公司设置预算上限。当记录的成本达到阈值时，Paperclip 会硬性停止该 Agent 的新运行，而不是发一封警告邮件了事。虽然官方文档也坦承由于计费延迟和进行中的工作，可能存在少量超支，但“停下来”这个动作本身，足以避免那种一觉醒来发现额度被烧光的噩梦场景。

治理机制：你是董事会，不是旁观者

Paperclip 把人类放在了一个明确的位置：董事会。你可以批准或拒绝 Agent 的“聘用”，设置任务完成前的审批阶段，随时暂停或终止任何一个 Agent，并且所有操作都有不可篡改的审计日志。Agent 不能悄悄花钱、不能绕过审批发布结果、不能在你不知情的情况下改变策略。这种治理深度是大多数 Agent 工具不具备的。

真正的多公司隔离

一次部署可以运行多个“公司”，彼此之间的数据、Agent、预算和审计记录完全隔离。如果你同时管理几个不同方向的项目，或者为客户运行独立的自动化流程，这个特性省去了维护多套实例的麻烦。

三、适用场景

场景一：同时驱动多个编码 Agent。 你手上有三个项目，分别用 Claude Code 和 Codex 在推进，每个项目都需要前端、后端和测试的配合。Paperclip 让你在一个仪表盘里看到谁在做什么、花了多少、卡在哪里。

场景二：需要 7×24 自动运行但不敢放任不管。 客服回复、内容摘要、日报生成这类规律性工作，可以交给心跳调度。你设定好预算和审批规则，Agent 按时唤醒执行，异常时停下来等你介入。

场景三：构建“零人员”业务原型。 如果你对完全由 AI 驱动的小型业务感兴趣，Paperclip 提供了现成的组织模板和导出导入机制，可以快速复制一套配置到另一台机器上。

不适用的情况也很明确：如果你只有一个 Agent，或者你需要的只是简单的定时脚本，Paperclip 的组织架构和治理开销会让你觉得笨重。官方文档自己就说得很直白：“如果你只有一个 Agent，你大概不需要 Paperclip。如果你有二十个——你肯定需要。”

四、安装教程

系统要求

根据 Paperclip 官方文档和社区实践，运行 Paperclip 需要以下环境：

工具用途版本要求
Node.js运行环境24.11.0 或以上
pnpm包管理器9.15 或以上
Git克隆项目最新版本即可

需要留意的是，Node.js 的版本要求是 24+，而不是常见的 18 或 20。这可能会让一些习惯于旧版本的用户感到意外，但 Paperclip 的现代依赖栈确实需要较新的运行时支持。

最快启动方式：一行命令

Paperclip 提供了一条命令完成初始化的方式：

npx paperclipai onboard --yes

--yes 会接受所有默认设置：本地信任模式（无需登录）、嵌入式 PostgreSQL、本地磁盘存储。命令执行完毕后，浏览器会自动打开 http://localhost:3100。整个过程不需要手动创建数据库或配置文件。

如果你希望从源码启动或进行二次开发，手动方式如下：

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

启动后 API 和 UI 都会运行在 3100 端口，嵌入的 PostgreSQL 会自动创建。

安装中可能遇到的问题

npx 命令返回 E404 错误。 这通常发生在你配置了私有 npm 注册表的情况下。npx 会优先从私有源解析 paperclipai 包，自然找不到。解决方案是强制指定公共源：

npx --registry https://registry.npmjs.org paperclipai@latest onboard --yes

Node.js 版本不够。 如果终端提示引擎版本不匹配，检查 node --version 的输出。低于 24.11.0 的话，从 Node.js 官网下载 LTS 版本覆盖安装即可。

首次启动后不知道下一步做什么。 浏览器打开后你会进入创建第一个“公司”的引导流程。先给公司起个名字，然后创建一个 Agent（最简单的只需填一个名称），就可以开始分配任务了。

五、使用示例

示例：组建一个最小可用的开发团队

假设你要构建一个简单的数据看板项目，但不想自己从头写每一行代码。你可以用 Paperclip 组织三个 Agent 来协作。

第一步：创建公司和目标

在 Paperclip 中创建一个公司，使命设定为“在两周内交付一个可用的销售数据看板”。这个使命会作为上下文传递给每一个后续任务。

第二步：创建 Agent 并设置角色

创建两个 Agent：一个命名为“Builder”，使用 Claude Code 适配器；另一个命名为“Reviewer”，同样使用 Claude Code，但职责不同。在 Agent 设置中，给 Builder 设置每月 20 美元的预算上限，Reviewer 设置 5 美元。Reviewer 的预算更低，因为它只做代码审查，不执行长时间生成。

第三步：创建任务并分配

创建一个工单：“实现销售数据看板的首页和图表组件”。将其分配给 Builder。再创建一个关联工单：“审查看板页面的代码质量和边界情况”，分配给 Reviewer，并将第一个工单设为它的阻塞依赖。这意味着 Reviewer 的任务在 Builder 完成之前不会唤醒。

第四步：监控和审批

当 Builder 的心跳触发时，它会读取任务上下文（包括公司使命和项目目标），开始编码。你可以在活动流中看到它的工具调用和成本累积。当 Builder 将任务标记为完成后，Reviewer 会被唤醒，检查代码并给出意见。如果你在 Paperclip 中开启了任务审批，Builder 的产出需要你点击“批准”才会进入下一步。

这个流程的价值不在于“AI 写代码”——Claude Code 本身就能做到。价值在于：你知道 Builder 花了多少钱、Reviewer 看了哪些文件、任务在哪个环节卡了多久，以及如果预算耗尽，两个 Agent 都会自动停下来。

导出和复用公司配置

当你调好了一套好用的团队配置，可以通过公司导出功能生成一个 bundle，在另一台机器或另一个实例上导入。导出的内容包含 Agent 定义、技能配置、项目结构和任务模板，但不会携带密钥等敏感信息。

六、常见问题

Paperclip 支持 Windows 吗？

支持。Paperclip 本身是 Node.js 服务端加 Web 界面，Windows 上安装 Node.js 24+ 后即可运行。不过部分 Agent 适配器（如 Claude Code 的本地订阅登录）可能需要在主机上安装对应的 CLI 工具。

数据存在哪里？模型调用会把数据发到哪里？

公司记录存在你配置的存储中（默认是本地磁盘和嵌入式 PostgreSQL）。但 Agent 执行任务时，上下文会发送给你选择的模型提供商。Paperclip 官方文档对这个问题的回答很诚实：“公司记录存在你的服务器上，而 Agent 读到的任何内容都会随其模型调用一起发送给你选择的提供商。”如果你在意数据流向，选择自托管模型或可控的 API 提供商即可。

预算硬停之后，Agent 会怎样？

达到预算上限时，该 Agent 的新运行会被阻止，队列中的相关工作也会被取消。你可以在仪表盘上看到预算触发记录，调整上限或等到下个周期后，Agent 可以恢复正常运行。但要注意，已经发出但尚未计费的 API 调用可能造成少量超支，这是所有基于记录成本的预算系统共有的局限。

我可以只用一个 Agent 吗？

技术上可以，但体验上没有必要。Paperclip 的开销在于组织架构和治理配置，单个 Agent 用 Claude Code 或 Codex 直接操作更轻快。Paperclip 的设计目标从一开始就是“团队”，而不是“个人助手”。

和直接给 Agent 写 system prompt 有什么区别？

System prompt 控制的是“一个 Agent 怎么做事”。Paperclip 控制的是“多个 Agent 之间怎么协作、谁向谁汇报、花了多少钱、谁有权批准”。前者是个人能力，后者是组织能力。两者不冲突，可以叠加使用。

七、总结

Paperclip 代表了一类正在出现的工具形态：Agent 编排层。它不试图取代 Claude Code 或任何具体的执行引擎，而是解决当 Agent 数量超过个位数之后必然出现的协作和治理问题。MIT 协议、自托管、不锁定运行时、硬预算控制，这些选择都指向同一个用户群体：认真地把 AI Agent 当作生产力来用、而不是当作玩具来试的人。

它的学习曲线不算平缓。你需要理解组织架构、心跳、适配器这些概念，需要配置 Agent 和预算，需要适应“公司”而非“聊天”的交互模式。但如果你已经在日常工作中同时运行多个 Agent，并且感受到了管理的混乱和成本的不可控，Paperclip 提供的这套框架值得花一个下午来搭建和体验。毕竟，管理二十个 Agent 的混乱，比学会一个新工具要痛苦得多。