莫潇羽@无忆研习社（www.wuyi.wiki）原创内容，转载请注明出处。
快速摘要：Paperclip 是一个开源的 AI Agent 编排平台，它的核心思路不是"造一个新的 AI"，而是把你已有的各种 AI Agent（比如 Claude Code、Codex、Cursor 等）组织成一家"虚拟公司"——有组织架构、有汇报线、有预算控制、有审计日志。 它在 GitHub 上线不到两周就拿到了近两万颗 Star，MIT 协议开源、完全自托管。如果你正被多个 AI 工具的协调问题搞得焦头烂额，或者想探索用 AI 组建协作团队的可能性，这篇文章会帮你从原理到操作彻底弄清楚 Paperclip 到底是什么、怎么用。往下看有更详细的技术拆解和实操指南。
为什么需要一个"AI 公司操作系统"
这两年 AI Agent 领域发展极快。我们手上能用的工具越来越多——写代码的、搜信息的、做内容的、操作桌面的——每一个单独拎出来都很强。但站长莫潇羽在实际使用中发现，当你同时跑三个、五个甚至十几个 Agent 的时候，真正的痛点不是"AI 不够聪明"，而是"管理这些 AI 太累了"。
具体来说，多 Agent 协作场景下有几个绕不开的问题。
第一个是缺乏全局协调。每个 Agent 都在埋头干自己的活，但它们之间没有沟通机制。写代码的 Agent 不知道产品需求变了，做测试的 Agent 不知道代码改了哪里。你作为"老板"要手动在各个工具之间来回传话，效率反而比不用 AI 还低。
第二个是成本失控。AI Agent 调用大模型 API 的速度是毫秒级的。如果不加控制，一个 Agent 在某个问题上陷入死循环，或者反复尝试某个行不通的方案，几个小时下来，API 账单可能会让你大吃一惊。在开发者社区里，"一觉醒来发现 API 费用爆了"的故事并不罕见。
第三个是缺乏追溯能力。多个 Agent 同时在跑，出了问题你根本不知道是哪个环节出的错、为什么出错、当时的决策逻辑是什么。没有日志、没有审计，debug 的难度指数级上升。
第四个是上下文断裂。每个 Agent 都运行在自己的"沙盒"里，它只知道你当次交给它的信息。但在实际业务中，一个任务往往需要跨多个 Agent 的上下文传递。比如产品经理 Agent 定义了一个需求，开发 Agent 需要看到完整的需求描述；开发完成后，测试 Agent 需要知道开发做了哪些改动、哪些是重点测试区域。手动复制粘贴上下文不仅低效，还容易遗漏关键信息。
第五个是Agent 之间的"幻觉叠加"效应。单个 AI 产生幻觉（生成看似合理实则错误的内容）已经够头疼了。当多个 Agent 串联工作时，如果上游 Agent 产生了幻觉输出，下游 Agent 会基于这个错误的基础继续工作，像滚雪球一样把错误放大。没有中间的质量检查环节，最终交付的结果可能错得离谱。
Paperclip 要解决的就是上面这些问题。它的定位不是"又一个 AI Agent"，而是一个管理层——专门用来协调、监督、控制其他 AI Agent 的编排平台。用一个形象的比喻：如果各种 AI Agent 是"员工"，那 Paperclip 就是这家公司的"ERP 系统 + OA 系统 + 财务系统"的集合体。它通过引入企业管理中久经考验的组织设计原则——分工、层级、汇报、审批、预算——来解决 AI 协作中的这些顽疾。
传统上，人类用脚本、配置文件和手动操作来管理多个 AI Agent，就像用 Excel 管理一家上百人的公司一样——能用，但很痛苦，也很容易出错。Paperclip 把这些散乱的管理需求系统化了，用一个统一的平台来承载所有的协调工作。
Paperclip 是什么：定位与技术架构
项目基本信息
Paperclip 由 paperclipai 团队开发，于 2026 年 3 月初正式开源。项目采用 MIT 协议发布，这意味着你可以自由使用、修改和分发。截至莫潇羽@无忆研习社撰文时（2026年3月13日），Paperclip 在 GitHub 上的 Star 数已经突破 2 万，Fork 超过 2500。对于一个刚开源不到两周的项目来说，这个增长速度相当亮眼。
项目的 GitHub 地址是：https://github.com/paperclipai/paperclip
技术栈概览
Paperclip 的技术架构并不复杂，这也是它容易上手的原因之一。整个项目是一个 TypeScript 单体仓库（monorepo），核心由两部分组成：
后端是一个基于 Node.js + Express 的 REST API 服务器，负责所有的编排逻辑、任务调度、预算管理和数据持久化。数据库使用 PostgreSQL。在本地开发模式下，Paperclip 会自动启动一个嵌入式的 PGlite 实例，你不需要自己安装和配置 PostgreSQL——这一点对新手非常友好。到了生产环境，你可以指向自己的 PostgreSQL 实例。
前端是一个 React 应用，提供可视化的管理界面。你可以在浏览器里查看组织架构、创建任务、监控 Agent 状态、审批操作、查看审计日志等等。值得一提的是，前端还支持 PWA（Progressive Web App），你可以把它安装到手机上，随时随地通过移动端来管理你的"AI 公司"。
整体来看，Paperclip 的架构设计遵循了"简单但不简陋"的原则。本地运行只需要一个 Node.js 进程就能搞定一切，但它的数据模型和业务逻辑已经为多公司、多 Agent、高并发的场景做了充分准备。
核心概念详解：理解 Paperclip 的运作逻辑
要真正用好 Paperclip，你需要理解它的几个核心概念。这些概念构成了 Paperclip 的"世界观"，也是它区别于其他工具的关键所在。下面莫潇羽逐一拆解。
公司（Company）
在 Paperclip 的体系里，"公司"是最顶层的隔离单元。你可以在一个 Paperclip 实例上创建多个公司，每个公司之间的数据完全隔离——Agent、任务、预算、日志都是独立的。这就像你在同一台服务器上跑了多个互不干扰的业务。
每个公司都需要设定一个使命（Mission）。这不是一句装饰性的口号，而是 Paperclip 目标体系的根节点。后续的所有项目目标、具体任务，都必须能追溯到这个使命。这种设计确保了每个 Agent 的每一个动作都有据可查、有理可依。
Agent（智能体/员工）
在 Paperclip 里，每个 AI Agent 就是一名"员工"。你可以把各种类型的 Agent 接入进来，不管它是 Claude Code、Codex、Cursor、OpenClaw，还是一个简单的 Shell 脚本、Python 脚本，甚至是任何可以通过 HTTP 接收信号的服务。Paperclip 对此完全不做限制，这就是它"Bring Your Own Agent（自带 Agent）"的理念。
每个 Agent 在系统里都有一组关键属性：
- 适配器类型和配置（Adapter）：定义了这个 Agent 的运行方式。比如你接入的是 Claude Code，适配器就负责处理与 Claude Code 进程之间的通信。Paperclip 目前已经内置了 Claude Code、Codex、Cursor、OpenCode、Pi 等多种适配器，v0.3.0 版本还新增了 OpenClaw 网关适配器。
- 角色和汇报关系（Role & Reporting）：每个 Agent 都有一个职位头衔（比如 CEO、CTO、工程师、设计师、QA 等），以及明确的上下级关系——它向谁汇报、谁向它汇报。
- 能力描述（Capabilities）：用自然语言描述这个 Agent 擅长做什么，帮助调度系统决定把什么样的任务分配给它。
- 月度预算：这个 Agent 每个月最多可以消耗多少 Token（或者换算成多少费用）。
组织架构（Org Chart）
Paperclip 用一棵严格的树形结构来组织所有 Agent。除了"CEO"之外，每个 Agent 都必须有且只有一个直接上级。这个层级关系不仅仅是一个好看的图表，它直接决定了任务的流转方式：
任务可以在组织架构中自上而下委派。比如 CEO Agent 接到一个宏观目标后，可以把它拆解成多个子任务，分别委派给 CTO Agent 和市场总监 Agent。CTO Agent 拿到任务后，又可以进一步细分，委派给下面的工程师 Agent。
同时，成果也可以自下而上汇报。工程师 Agent 完成代码后，需要向 QA Agent 提交审查；QA Agent 审查通过后，再向 CTO Agent 汇报。这种机制形成了一个天然的相互监督链。一个 Agent 的输出会被另一个 Agent 验证，大大降低了 AI "幻觉"导致的错误被最终采纳的概率。
这是 Paperclip 最精妙的设计之一。传统的 AI 工具链里，人类用户是唯一的质量把关者。但在 Paperclip 的体系里，AI 之间就先互相审查了一轮，人类只需要在关键节点做最终决策。
工单/任务（Issue）
在 Paperclip 里，所有工作都以"工单"（Issue）的形式存在。每个工单有明确的负责人、状态和完整的沟通记录。工单的状态流转非常清晰：创建 → 待领取 → 进行中 → 完成/取消。
这里有一个非常重要的技术细节：工单的领取是原子操作。什么意思呢？当一个工单状态从"待领取"变为"进行中"时，系统会确保同一时刻只有一个 Agent 能成功领取。如果两个 Agent 同时尝试领取同一个工单，其中一个会收到 409 Conflict 错误。这个机制从底层杜绝了"两个 Agent 在做同一件事"的浪费场景。
每个工单都携带完整的目标层级信息（Goal Ancestry）。也就是说，一个工程师 Agent 在处理某个具体的编码任务时，它不仅知道"要做什么"，还知道"为什么要做"——这个任务属于哪个项目目标，这个项目目标又服务于公司的什么使命。这种上下文对于 AI 做出合理决策至关重要。
心跳机制（Heartbeat）
AI Agent 在 Paperclip 里不是 24 小时不间断运行的——这一点可能出乎很多人的意料。Paperclip 采用的是心跳调度机制：Agent 按照预设的时间表（比如每 15 分钟、每小时、每天）被"唤醒"一次，检查有没有分配给自己的新任务，处理手头的工作，然后再次"休眠"。
这个设计有几个好处：首先，它天然控制了 API 的调用频率，避免了 Agent 无意义地空转消耗 Token；其次，它让系统的行为变得可预测——你知道 Agent 在什么时候会工作；再次，它简化了并发控制和状态管理。
当然，心跳不是唯一的触发方式。某些事件也可以"立即唤醒"Agent，比如有新任务被分配给它、或者被其他 Agent @提及。如果你需要某个 Agent 持续运行（比如接入 OpenClaw 这样的长运行 Agent），Paperclip 也支持，只是默认推荐的模式是心跳调度。
理解心跳机制很重要，因为它是 Paperclip 实现"持久状态"的基础——Agent 可以跨多次心跳恢复之前的任务上下文，不需要每次都从头开始。这大大减少了重复的 Token 消耗。
预算控制：Paperclip 的"财务总监"
成本控制是 Paperclip 的核心卖点之一，也是开发者社区最关心的话题。莫潇羽@无忆研习社认为，这是 Paperclip 目前做得最扎实的模块之一。
预算的设置和执行
你可以为每个 Agent 设置月度 Token 预算。这个预算是硬限制，由系统强制执行。当一个 Agent 的累计消耗达到预算的 80% 时，系统会发出软警告；达到 100% 时，Agent 会被自动暂停，新任务也不会再分配给它。
预算的执行同样是原子操作——和任务领取一样，这确保了在高并发场景下不会出现"预算已经花完了但 Agent 还在继续调用 API"的情况。
作为管理者，你随时可以手动调整预算上限或者解除暂停。整个过程在审计日志中有完整记录。
多维度的成本追踪
Paperclip 的成本追踪做得非常细致。你可以从多个维度查看费用消耗情况：
- 按 Agent 维度看：每个 Agent 这个月花了多少
- 按任务维度看：每个工单消耗了多少 Token
- 按项目维度看：某个项目的总投入是多少
- 按目标维度看：实现某个业务目标的总成本
这种多维度的可视化让你能快速识别出"哪个 Agent 性价比最高"、"哪个任务的成本超出预期"，从而做出更好的资源配置决策。
治理机制：人类始终是"董事会"
Paperclip 虽然让 AI Agent 自主工作，但它的设计哲学是"AI 自治 + 人类监督"。你作为管理者，扮演的是"董事会"的角色，拥有最高权限。
审批门控（Approval Gates）
系统中的某些敏感操作需要人类审批才能执行。最典型的例子是"招聘新 Agent"——即使是 CEO Agent 也不能自行决定引入一个新的 Agent，必须经过你的批准。策略层面的重大决策同样需要你的审批。
这种机制防止了 AI 系统在缺乏人类判断的情况下做出不可逆的错误决策。
随时干预的能力
你可以在任何时候对系统进行干预：
- 暂停某个 Agent 的工作
- 恢复一个被暂停的 Agent
- 覆盖 AI 制定的策略
- 将任务从一个 Agent 重新分配给另一个
- 完全终止某个 Agent
所有这些操作都记录在不可变的审计日志中。"不可变"意味着日志只能追加、不能修改或删除，确保了完整的可追溯性。
配置版本控制与回滚
Paperclip 对系统配置的变更也做了版本管理。如果某次配置调整导致了问题，你可以安全地回滚到之前的状态。这在生产环境中非常重要。
从零开始：Paperclip 完整安装与配置教程
下面进入实操环节。莫潇羽会按照从易到难的顺序，带你一步步把 Paperclip 跑起来。
环境要求
在安装 Paperclip 之前，你需要确保本机已经安装了以下工具：
- Node.js 20 或更高版本：Paperclip 是基于 Node.js 构建的，这是必装项。可以去 Node.js 官网（https://nodejs.org/）下载安装，建议选择 LTS（长期支持）版本。
- pnpm 9.15 或更高版本：pnpm 是一个高效的 Node.js 包管理器。安装 Node.js 后，你可以通过
npm install -g pnpm来全局安装 pnpm。
检查版本的方法：
node --version
# 应该输出 v20.x.x 或更高
pnpm --version
# 应该输出 9.15.x 或更高如果你用的是 macOS，也可以通过 Homebrew 来安装这两个工具：
brew install node
brew install pnpm方式一：一键安装（推荐新手使用）
Paperclip 提供了一个交互式的安装向导，一行命令就能搞定数据库配置、身份认证设置和第一个公司的创建：
npx paperclipai onboard --yes这个命令会自动下载 Paperclip 的最新版本，引导你完成初始化配置。整个过程以命令行交互的方式进行，按照提示一步步操作即可。
方式二：手动安装（适合想研究代码的开发者）
如果你想深入研究 Paperclip 的源码，或者需要做一些自定义修改，可以选择手动安装：
# 第一步：克隆仓库
git clone https://github.com/paperclipai/paperclip.git
# 第二步：进入项目目录
cd paperclip
# 第三步：安装依赖
pnpm install
# 第四步：启动开发服务
pnpm devpnpm dev 命令会同时启动 API 服务器和前端 UI，并且开启文件监听模式（代码修改后自动重新编译）。如果你只想启动服务器而不需要前端热更新，可以用 pnpm dev:once。
启动后的状态
不管用哪种方式安装，启动成功后你会看到：
- API 服务器运行在
http://localhost:3100 - 一个嵌入式的 PostgreSQL 数据库已经自动创建并运行（不需要你额外安装 PostgreSQL）
- 前端管理界面可以通过浏览器访问
打开浏览器，输入 http://localhost:3100，你就能看到 Paperclip 的管理界面了。
开发相关的其他命令
如果你是开发者，以下命令可能会用到：
pnpm build # 构建所有模块（用于生产部署）
pnpm typecheck # TypeScript 类型检查
pnpm test:run # 运行测试
pnpm db:generate # 生成数据库迁移文件
pnpm db:migrate # 执行数据库迁移实战操作：创建你的第一个"AI 公司"
安装完成后，接下来莫潇羽@无忆研习社带你走一遍创建和使用的完整流程。
第一步：创建公司并设定使命
登录 Paperclip 的管理界面后，第一件事是创建一个"公司"。系统会要求你输入一个公司使命（Mission）。
这里有一个技巧：使命的描述要尽可能具体和可量化，而不是空泛的口号。比如"做最好的产品"就太模糊了，而"构建一个面向开发者的 AI 代码审查工具，支持 Python 和 JavaScript"就清晰得多。因为后续所有的目标分解和任务分配都会以这个使命为锚点，使命越清晰，AI Agent 的执行方向就越准确。
第二步：设计组织架构
公司创建完成后，你需要设计组织架构。这一步的核心是决定：你需要哪些"岗位"，它们之间的汇报关系是什么。
一个典型的软件开发团队架构可能长这样：
你（董事会 / Board）
└── CEO Agent（战略规划，用推理能力最强的模型）
├── CTO Agent（技术决策，负责架构设计）
│ ├── 工程师 Agent A（前端开发）
│ ├── 工程师 Agent B（后端开发）
│ └── QA Agent（测试验收）
└── 市场总监 Agent（内容营销）
├── SEO Agent（搜索优化）
└── 内容 Agent（文案撰写）在 Paperclip 的界面上，你可以可视化地构建这个层级结构，为每个节点设定职位名称、汇报对象和职责描述。
第三步：招聘 Agent
组织架构设计好后，就可以开始"招聘"了——也就是为每个岗位接入实际的 AI Agent。
以接入 Claude Code 为例，你需要在对应岗位上配置适配器类型为"Claude Code"，然后填写必要的连接参数。Paperclip 的安装向导（onboarding wizard）会引导你完成这个过程。
目前 Paperclip 已经内置适配器的 Agent 包括：
- Claude Code：Anthropic 的命令行编码 Agent
- Codex：OpenAI 的编码 Agent
- Cursor：AI 辅助编程 IDE
- OpenCode：开源编码 Agent
- Pi：支持本地 RPC 模式的 Agent
- OpenClaw：通过网关适配器接入
如果你用的 Agent 不在上述列表中，只要它能通过 HTTP 接收心跳信号，你就可以通过 Shell 命令适配器或 HTTP Webhook 适配器把它接进来。
需要注意的是，Agent 的招聘需要你（董事会）的审批。即使是 CEO Agent 也不能自行决定引入新的 Agent。这是治理机制的一部分。
第四步：设定目标和创建任务
Agent 就位后，你可以开始设定项目目标和创建具体任务了。
Paperclip 的目标体系是层层递进的：
公司使命（Mission）
└── 项目目标（Project Goal）
└── 具体任务（Issue）
└── 子任务（Sub-issue）你可以先设定一个项目级别的目标，比如"完成用户注册模块的开发"。然后在这个目标下创建具体的工单，比如"实现注册表单前端页面"、"实现注册 API 接口"、"编写注册流程的自动化测试"等。
任务创建后，你可以手动分配给特定的 Agent，也可以让上级 Agent（比如 CTO）来决定如何分配。分配后，Agent 在下一次心跳时就会"看到"这个任务并开始工作。
第五步：设置预算
在 Agent 开始工作之前，强烈建议先给每个 Agent 设好月度预算。操作很简单，在 Agent 的属性面板里填入预算金额即可。
一个实用的建议是：刚开始先设一个比较保守的预算（比如每个 Agent 每月几十元人民币等值的额度），观察一段时间实际消耗情况后再逐步调整。这样既能保证 Agent 有足够的资源工作，又不会因为配置失误导致成本失控。
第六步：监控和干预
一切就绪后，Agent 就会按照心跳节奏自动工作。你可以在 Paperclip 的仪表盘上实时查看：
- 每个 Agent 的当前状态（活跃/休眠/暂停）
- 任务的进度和状态
- 预算的消耗情况
- Agent 之间的沟通记录和决策日志
如果你发现某个 Agent 的方向跑偏了，可以随时暂停它、调整任务描述、甚至重新分配任务。所有操作都在管理界面上点几下就能完成。
深入原理：Paperclip 的关键技术机制
前面讲了宏观的使用流程，接下来莫潇羽再带你深入看看 Paperclip 底层的几个关键技术设计，这些才是它能"跑得稳"的根本原因。
原子执行（Atomic Execution）
前面提到的"任务领取原子性"和"预算扣减原子性"，其实是同一套机制。Paperclip 使用 PostgreSQL 的事务和行级锁来保证这些操作的原子性。用一段伪代码来描述：
BEGIN TRANSACTION;
-- 尝试把任务状态从 'open' 改为 'in_progress'
-- 同时检查该 Agent 的预算是否足够
-- 如果两个条件都满足，提交事务
-- 如果任何一个条件不满足，回滚事务
COMMIT;这种设计确保了在多个 Agent 并发工作的场景下，不会出现"两个 Agent 同时做同一件事"或者"预算已经超了但 Agent 还在继续花钱"的情况。
持久状态（Persistent State）
Agent 的工作不是一次性的。一个复杂的编码任务可能需要跨越多次心跳才能完成。Paperclip 通过持久化 Agent 的任务上下文来实现这一点：当 Agent 在某次心跳中处理了一部分工作后"休眠"，下一次被唤醒时，它能从上次中断的地方继续，而不需要重新理解整个任务背景。
这对于减少 Token 消耗非常关键。如果每次心跳都要重新把完整的项目上下文发给大模型，那 Token 成本会高得吓人。持久状态让 Agent 只需要处理增量信息。
运行时技能注入（Runtime Skill Injection）
Paperclip 有一个 SKILL.md 机制：Agent 在运行时可以动态加载和学习 Paperclip 特定的工作流程和项目上下文，而不需要对底层模型做任何微调或重新训练。
简单来说，当一个 Agent 被唤醒时，Paperclip 会把相关的"技能说明书"（SKILL.md 文件）注入到 Agent 的上下文中，告诉它"你现在在 Paperclip 系统里，你的角色是什么，你应该如何汇报工作、如何提交成果"。Agent 读完这些说明后，就知道该怎么在 Paperclip 的框架内正确地工作了。
不可变审计日志（Immutable Audit Log）
Paperclip 的所有操作日志都是追加式的（append-only），不能修改、不能删除。每一次 Agent 的 API 调用、每一次任务状态变更、每一次人类的干预操作，都会被完整记录下来。
这不仅仅是为了"看看 Agent 做了什么"。在多 Agent 协作的场景下，当出现问题时，你需要能回溯到问题发生时的完整上下文——是哪个 Agent 做了什么决策、基于什么信息做的、当时的系统状态是什么。不可变审计日志让这种回溯成为可能。
进阶配置：生产环境部署指南
如果你打算在生产环境中使用 Paperclip，本地开发模式的配置就不够用了。以下是一些关键的进阶配置建议，莫潇羽@无忆研习社根据官方文档和社区实践整理。
使用独立的 PostgreSQL 数据库
本地开发时，Paperclip 使用嵌入式的 PGlite，数据存储在本地文件中。生产环境下，你应该配置一个独立的 PostgreSQL 实例。只需要设置 DATABASE_URL 环境变量即可：
export DATABASE_URL="postgresql://user:password@host:5432/paperclip"然后运行数据库迁移：
pnpm db:migrate部署到云平台
Paperclip 可以部署到各种云平台。官方文档提到了 Vercel 部署方案。你也可以使用 Docker 来容器化部署——社区里已经有不少开发者分享了 Docker Compose 的配置方案。
远程访问：使用 Tailscale
如果你在家里或办公室的本地机器上运行 Paperclip，又想在外出时通过手机管理你的"AI 公司"，官方推荐使用 Tailscale。Tailscale 是一个基于 WireGuard 的组网工具，可以让你的设备形成一个安全的私有网络，从而在任何地方访问本地服务。
数据库备份
v0.3.0 版本新增了数据库备份功能：
paperclipai db:backup你还可以配置定时自动备份。在生产环境中，定期备份是必须的。
关闭公开注册
如果你不想让外部用户注册你的 Paperclip 实例，可以通过配置禁用注册功能：
export AUTH_DISABLE_SIGNUP=true或者在配置文件中设置 auth.disableSignUp: true。
实际应用场景：Paperclip 能帮你做什么
理论讲了很多，那 Paperclip 在实际场景中到底怎么用呢？以下是几个比较典型的应用方向。
软件开发团队自动化
这是 Paperclip 最直
