Paperclip 开源半年 9.5 万星：一群 AI Agent 该怎么管

你手上大概同时开着好几个 AI 编码助手。它们各自都挺能干，但你不知道谁在干什么，不知道这个月烧了多少钱，重启一次连会话都找不回来。

Paperclip 要解决的就是这件事。它不关心你的 AI Agent 用哪个模型、怎么写 prompt，它管的是这家「公司」本身怎么运转：谁汇报给谁、每个任务为什么存在、预算是多少、哪些决定必须经人点头。

先划清边界：它是公司，不是员工

README 里有一句话把定位说得最清楚：

如果 OpenClaw 是一个员工，Paperclip 就是那家公司。

它自己列了一份「不是什么」的清单，比「是什么」更有信息量：

不是	是
不是聊天机器人	agent 有岗位，不是聊天窗口
不是 agent 框架	不教你怎么造 agent，只教你怎么用一群 agent 开公司
不是工作流搭建器	没有拖拽式流水线，建的是公司模型
不是 prompt 管理器	prompt、模型、运行时都由 agent 自己带
不是单 agent 工具	一个 agent 用不上，二十个就非它不可
不是代码审查工具	它编排工作，不处理 PR

六个概念，看懂它的世界观

官方文档把整套模型压在六个词里。前四个是结构，后两个才是它真正的差异点。

Company（公司）

一个公司有目标、员工、组织架构、月预算（单位是美分）和任务树。一个 Paperclip 实例可以跑多家公司，数据互相隔离。

Agent（员工）

每个员工是一个 agent，带适配器类型与配置、职级与汇报关系、能力描述、月度预算、运行状态。组织是一棵严格的树：每个 agent 只有一个上级，CEO 除外。

Issue（任务）

任务是工作单位，带标题、描述、状态、优先级、唯一负责人、父任务、所属项目。状态流转是固定的：

backlog → todo → in_progress → in_review → done
in_progress → blocked

关键在「原子结账」：任务转入进行中必须抢占，同一时刻只允许一个 agent 持有。两个 agent 同时抢，其中一个会直接收到 409 Conflict。这条规则消灭了重复劳动。

Heartbeat（心跳）

agent 不是常驻跑着烧钱，而是被唤醒、干活、然后睡下。唤醒来源有五种：定时器、任务派发、被 @提及、人在界面上点 Invoke、以及一个待审批被批准或驳回。每次醒来，它按固定协议做事：确认身份 → 查待办 → 挑活 → 抢占任务 → 干活 → 更新状态。

Delegation（委派）

CEO 是主要拆解者：先给出一份战略交人审批，通过后把目标拆成任务，按角色和能力派下去，人手不够还能申请招人。你不需要手动派每一个任务。

Governance（治理）

招人、CEO 战略这类决定需要人来批。人可以随时暂停、恢复、终止任意 agent，也能改派任意任务。每一次变更都进审计日志。

架构：控制平面和执行平面是分开的

这是它最重要的一条设计决定，官方文档里的原话是：控制平面不运行 agent，只负责协调；agent 在自己那里跑，然后打电话回家。

中间是控制平面，两侧接的是各种执行端：Claude Code、Codex、CLI agent、HTTP/webhook 机器人。控制平面管状态，执行端管出力。

技术栈

层级	技术
前端	React 19 · Vite 6 · React Router 7 · Tailwind CSS 4 · TanStack Query
后端	Node.js 24.11+ · Express 5 · TypeScript
数据库	PostgreSQL 17 或内嵌 PGlite · Drizzle ORM
鉴权	Better Auth（会话 + API Key）

一次心跳的完整流转

1. 触发：调度器、人工调用，或者一个事件（派单、被 @）
2. 适配器被调用，带着执行上下文
3. 适配器拉起 agent 进程，注入环境变量和提示词
4. agent 反过来调 Paperclip 的 REST API，查看待办、抢任务、干活、更新状态
5. 适配器回收输出，解析用量和花费
6. 服务端落库：这次运行的结果、成本、以及供下次心跳复用的会话状态

左栏是组织：CEO、CTO、CMO、Data Analyst 一栏排开。主区四个数字是「启用的 agent 数 / 进行中的任务 / 本月花费 / 待审批数」，下面四张图分别是运行活跃度、任务优先级分布、状态分布和成功率。

装机：三条路，都能跑到第一次心跳

官方给了三条路径，按「只是想看看 / 想长期用 / 要改代码」分开。

路径一：正式安装（带校验和）

curl -fsSLO https://paperclip.ing/install.sh
curl -fsSLO https://paperclip.ing/install.sh.sha256
sha256sum -c install.sh.sha256
bash install.sh

脚本会确保 Node.js 24.11 以上可用，把 CLI 装到 ~/.paperclip/cli，然后进入交互式引导。在支持的 Linux 和 macOS 上还能注册成后台服务。

路径二：不落盘试跑

# 快速引导
npx --registry https://registry.npmjs.org paperclipai onboard --yes

# 隔离实例，自带一个 CEO，仅前台运行
ANTHROPIC_API_KEY=... npx paperclipai test-drive

test-drive 会起一个临时实例，不装服务、不建首个任务，装好之后才打开浏览器。不带 --data-dir 的话，每次都是全新目录，路径会在启动时打印出来。

路径三：源码编译

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

启动后 API 和界面都在 localhost:3100。内嵌 PostgreSQL 会自动创建，不需要另外装数据库。要求 pnpm 9.15 以上。

三种部署模式

模式	说明
local_trusted	免登录，只绑回环地址。默认值，单人本地用
authenticated + private	要登录，绑所有网卡。局域网、Tailscale、VPN 用
authenticated + public	要登录，必须明确指定公网地址。面向公网部署

引导时用 --bind lan 或 --bind tailnet 直接切到鉴权模式。跑完引导，进界面建公司、定目标、配 CEO，就能开始了。

每个 agent 的配置就长这样：选执行环境、适配器类型、模型、思考强度、指令文件，环境变量里可以把密钥标成 Secret 在运行时解析。最下面是运行策略——心跳间隔默认 900 秒。

适配器：能收心跳，就能入职

官方那句话是「任何能收到心跳的东西都能被雇佣」。落到代码上，就是 12 个内置适配器，加一条插件式的扩展路径。

适配器	类型键	干什么
Claude Code	claude_local	本地跑 Claude Code CLI
Codex	codex_local	本地跑 OpenAI Codex CLI
Gemini CLI	gemini_local	实验性，尚未进稳定枚举
Kimi Code CLI	kimi_local	走 ACP，可选无头模式
OpenCode	opencode_local	多供应商 model 指定
Cursor	cursor	后台模式运行
Pi	pi_local	内嵌 Pi agent
Hermes	hermes_local	每轮心跳拉起本地 hermes CLI
Hermes 网关	hermes_gateway	已有 Hermes 服务时改调 API
OpenClaw 网关	openclaw_gateway	接 OpenClaw 侧端点
Process	process	任意 shell 命令
HTTP	http	给外部 agent 发 webhook

另外还有一个走 npm 安装的第三方插件适配器 Droid。想自己写一个也不难，一个适配器包就三个模块：服务端的执行逻辑、给界面用的输出解析器、给终端用的格式化器。

选择适配器还决定了一件事：你能看到多少细节。

适配器类型	可见程度
原生 ACP 引擎	最细。每个工具调用、思考增量、上下文用量都能实时看到
CLI 包装器	中等。取决于该 CLI 自己输出多少
通用进程 / HTTP	只有原始 stdout，没有结构化记录

钱是怎么被管住的

自治的风险有两个：一是它干砸了，二是它在你看不见的地方一直烧钱。后者更常见，也更贵。这部分是 Paperclip 做得最实的。

• 每个 agent 一笔月预算。 按美分计，可以给公司和单个 agent 各设一层。
• 六个维度记账。 公司、agent、项目、目标、任务、供应商与模型，任意一层都能查。
• 超支是硬停，不是提醒。 碰到上限会直接暂停 agent，并且取消它排队里的工作。
• 结账是原子的。 任务抢占和预算扣减在同一笔里完成，不会出现两个 agent 干同一件事、或者同一笔钱被算两次。

一个任务页里能看到：问题描述、根因分析、子任务进度（3/3 完成、0 阻塞）、状态与优先级、负责人、所属项目、父任务、被谁阻塞、关联任务。右侧那一列就是「谁在负责、卡在哪」的答案。

治理：留给人的那几个开关

全自动不等于没人管。Paperclip 保留了几个必须由人按下的按钮：

开关	说明
招人审批	agent 可以申请招下属，但需要人来批（可开关）
战略审批	CEO 的首份战略计划必须经人确认
随时接管	暂停、恢复、终止任意 agent，改派任意任务
审计	每一次变更都留痕，能追到具体是谁做的
可回滚	配置改动带版本，改错了能退回去

它在路线图里把态度写得很直接：要的不是隐藏的自治，而是每个监督者更多的产出。

agent 不是在某个看不见的地方改文件。每次执行有独立工作区，改动以 diff 形式呈现，改了 16 个文件、+502 行、−74 行，哪一种模式看差异都能切。

几个容易被忽略的细节，和该知道的边界

ClipHub：下载一家公司

除了编排能力，它还定义了一种可移植的「公司模板」——包含公司元信息、完整组织架构、每个 agent 的定义、适配器配置、种子任务和预算默认值。导出之后可以发布到公开注册表 ClipHub，别人一条命令就能在自己实例上把这家公司立起来。模板只含结构，不含在途任务和历史花费。除了整家公司，也能单独发一个 agent 模板、一个子团队模板，或者一份适配器配置。

一个彩蛋

logo 是一枚回形针，而路线图里躺着一项还没做的功能，名字叫 MAXIMIZER MODE ——更高自治度的执行模式。熟悉 AI 安全的人看到这个词会心一笑。

三条要提前知道的

提醒	细节
遥测默认开	匿名使用数据默认上报。四种关法：环境变量 PAPERCLIP_TELEMETRY_DISABLED=1、DO_NOT_TRACK=1、CI 环境下自动关、或配置文件里写 telemetry.enabled: false
默认模式无鉴权	local_trusted 只绑回环地址、不要求登录。放到局域网或公网之前，先切到 authenticated 模式
路线图还有一堆空的	记忆与知识、工作队列、自组织、CEO 对话、桌面端都未完成。核心功能可用，但这些别当成已有能力

任务可以带一个 Planning 标记，走的是「先交方案再执行」的流程，方案本身就是任务里的一个文档，不会被当成已完成工作。

用它之前，先想清楚三件事

第一，它是给「一群 agent」用的。 如果你只跑一个编码助手，装它是负担。当你开始同时开五个、十个窗口，并且记不清谁在干什么的时候，它的价值才出现。

第二，自治的前提是先把边界写死。 上线之前把每个 agent 的预算、能碰的密钥、需要审批的动作全部定好。这些东西一旦跑起来再补，往往是在出事之后。

第三，它不替你做技术判断。 它保证的是每件事有人认领、每笔钱有上限、每个决定有记录。代码好不好、方案对不对，还是得人来看。

AI 越能干，越需要有人告诉它三件事：

你归谁管，你花谁的钱，你的活什么时候算完。