Paperclip：把多个 AI Agent 组织成可治理的自动化团队

当我们同时开启多个 Claude Code、Codex 或其他 coding agent 时，真正困难的往往不是「如何再叫一个模型写程式」，而是如何管理任务上下文、权限、成本、排程与责任归属。Paperclip 将这个问题往上抽象：它不是另一个 agent framework，而是一个用来协调 AI agent 团队的开源 control plane。

Paperclip 的核心想法很直白：agent 负责工作，Paperclip 负责组织。使用者可以先定义公司或专案目标，再建立角色与回报关系，接着把不同 runtime 的 agent 接进来，由同一个 dashboard 管理任务、预算、审批与执行纪录。对正在把 AI 从单次对话推向长时间自动化的团队来说，这是一个值得拆开研究的架构。

阅读导航

1. 为什么多 agent 系统需要 control plane

1. Paperclip 的核心模型：目标、组织、任务与 heartbeat

1. 从成本控制到治理，Paperclip 解决了什么问题

1. 本机启动与第一个实验

1. 适用场景、限制与导入建议

先厘清：Paperclip 不想取代 agent

Paperclip README 将自己的定位说得很清楚：它是 Node.js server 加上 React UI，用来协调一组 AI agent 执行工作。它不规定你要怎么建造 agent，也不是聊天机器人、prompt manager 或拖拉式 workflow builder。

这个区分很重要。Claude Code、Codex、Cursor、Bash agent 或 HTTP bot 都可以是执行端；Paperclip 则处理执行端上方的管理问题。换句话说，Paperclip 不是把所有 agent 重新包装成同一个模型，而是提供一层跨 runtime 的共同语言：谁负责什么、任务从哪个目标而来、现在花了多少成本、下一步是否需要人批准。

这种分层也让架构比较容易演进。当团队替换模型或 agent runtime 时，组织目标、任务记录与治理规则不必一起重写；当工作从一个人扩大到多个 agent 时，也不需要继续依赖一堆散落的 shell script、终端机分页与手动提醒。

四个核心模型

1. Goal：让 agent 知道「为什么」

单一任务通常只描述「做什么」，但多 agent 系统还需要知道「为什么做」。Paperclip 将公司、专案、目标与 issue 串起来，让任务保留完整的 goal ancestry。这代表 agent 取得的上下文不只是一张孤立的 ticket，而是可以一路追溯到更高层的组织目标。

这种设计能降低一个常见问题：每个 agent 都完成了局部工作，整体却没有朝同一个方向前进。当任务与父层目标有明确关联，管理者可以检查工作是否仍然值得执行，agent 也比较容易在遇到取舍时使用一致的优先顺序。

2. Org chart：用角色与边界取代一堆独立 session

Paperclip 将 agent 视为有角色、职称、回报线、权限与预算的组织成员。README 的示例包括 CEO、CTO、工程师、设计师与行销角色，但重点不在于模仿人类公司，而在于把责任、委派与权限变成可追踪的资料模型。

有了 org chart，管理者可以让一个 agent 负责拆解目标，再把子任务委派给其他 agent；也可以把不同 agent 限制在特定公司、专案或工具范围内。对需要同时管理多个产品或客户环境的部署来说，这比把所有 bot 放在同一个共享工作区更容易维持隔离。

3. Issue 与 workspace：把工作变成可恢复的执行单位

Paperclip 的任务系统不只储存标题。官方文件列出的 issue 关联包含 company、project、goal、parent、blocker dependency、comment、document、attachment 与 work product；任务也使用 atomic checkout 与 execution lock，避免两个 agent 同时抢同一份工作。

这里的价值在于可恢复性。多 agent 系统不应该假设每次执行都一次成功，也不应该把上下文绑死在某个终端机视窗。Paperclip 以持久化 issue、session state、结构化 log 与 worktree workspace 保存执行状态。即使服务重启，agent 仍有机会从原本的任务脉络继续，而不是重新猜测上一轮发生了什么。

4. Heartbeat：用事件与排程启动工作

Paperclip 的 heartbeat 是把 agent 从「等人下指令」推向「依规则工作」的关键。agent 可以按照排程醒来，检查自己的工作，或在任务指派、@mention 等事件发生时被唤起。README 也描述了 cron、webhook 与 API trigger，以及 concurrency 与 catch-up policy。

这让周期性工作可以被建模为 routine，而不是由人记得手动启动。例如每日整理客服资料、定期产生报告、检查某个专案的测试结果，都可以留下可追踪的 routine execution，并且建立对应 issue。重要的是，每次执行仍然会进入同一套预算、权限与稽核流程。

Paperclip 的治理层：让自动化不等于放任自流

只要 agent 能长时间执行，治理就不是附加功能，而是系统边界的一部分。Paperclip 将治理拆成几个可操作的机制。

预算与成本硬停止

Paperclip 可依 company、agent、project、goal、issue、provider 与 model 追踪 token 与成本，并设定 warning threshold 和 hard stop。当 agent 超过预算时，系统可以暂停它并取消排队中的工作。这比事后才从帐单发现 agent 进入 runaway loop 更实用。

导入时，我会先为每个 agent 设定小额上限，再观察正常任务的成本分布；确认 heartbeat 频率、重试策略与工具呼叫都符合预期后，才逐步放宽。预算不是只为了省钱，也是让实验具有明确的爆炸半径。

Approval、pause 与 audit log

Paperclip README 列出 board approval workflow、execution policy、review stage、decision tracking，以及 pause、resume、terminate agent 等治理操作。这让高风险工作可以采用「agent 提案，人类核准，系统执行」的流程，而不是把所有权限一次交出去。

同时，mutating action、heartbeat 状态、成本事件、审批、留言与 work product 都能形成 durable activity。当结果不如预期时，团队可以回头追查谁在什么时间做了哪个决定，而不必只依赖模型产生的最后一段文字。

Secrets 与工具边界

多 agent 部署最容易被忽略的是秘密与工具权限。Paperclip 描述了 instance secret、company secret、加密本机储存，以及依 scope 将秘密注入特定 run 的机制；MCP tool gateway 与 plugin system 则提供延伸工具与受控能力的方向。

实务上，我不会把整个 .env 或 production token 放进所有 agent 都能读取的 workspace。比较安全的做法是按照工作角色分配最小权限，将需要的秘密限定在一次执行、特定公司与特定工具，并让每次使用都能在 activity log 中被追踪。

从原始码看它的形状

Paperclip 的 control plane 可以用几个模组理解：

Identity and Access：管理 board user、agent API key、run JWT、company membership 与邀请流程。
Org Chart and Agents：保存角色、职称、回报关系、权限与预算，并透过 adapter 连接不同 runtime。
Work and Task System：处理 issue、依赖、留言、附件、工作产物与 atomic checkout。
Heartbeat Execution：管理 wakeup queue、预算检查、workspace resolution、secret injection、skill loading 与 adapter invocation。
Governance and Approvals：提供审批、政策、决策纪录、硬停止及完整 audit log。
Plugins、MCP 与 Observability：让系统可扩充，并以 opt-in OpenTelemetry traces 或 Sentry error monitoring 观察服务。

这个切法揭示一个架构判断：Paperclip 的核心不是「如何呼叫一次 LLM」，而是如何把一次 agent run 放进可重试、可审批、可计费、可稽核的企业流程。这也是它和一般 agent framework 的差异。

本机启动：先建立安全的小型实验

官方 README 提供两条快速路径。直接使用 installer 时，官方建议先下载安装脚本及其 SHA-256 档案，完成检查后再执行。README 同时提醒，checksum 与脚本来自同一个来源；若需要独立验证，应改用 release tag 或 commit pinned 的 GitHub 版本。

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

也可以采用手动开发模式：

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

官方目前列出的需求是 Node.js 24.11 或更新版本，以及 pnpm 9.15 或更新版本。开发模式会启动 API server，预设位址是 http://localhost:3100；README 说明 embedded PostgreSQL 会自动建立，因此初次试用不必先准备独立资料库。

我的建议是把第一次测试限制在本机 loopback，先建立一个低权限 agent，并使用小额预算。先验证以下四件事，再考虑 LAN、tailnet 或正式部署：

1. 任务是否能正确从目标传递到 agent。

1. heartbeat、重试与 orphaned run recovery 是否符合预期。

1. 预算达到上限时，执行是否真的停止。

1. 审批、工具呼叫、成本与 work product 是否留下可读的纪录。

不要因为介面看起来像 task manager，就直接让 agent 拥有 production repo 的写入权限。先用测试资料与隔离 workspace 做演练，往往比事后清理一次错误委派更省成本。

什么时候值得使用 Paperclip

我认为 Paperclip 最适合以下三种情境。

第一，你已经有多个 agent runtime，而且开始遇到「谁正在做什么」的可见性问题。Paperclip 可以把不同供应商或 CLI agent 放进同一个组织与任务脉络。

第二，你有大量周期性或事件驱动工作，希望 agent 不只是被动回答，而是按照排程、任务与权限持续推进。Heartbeat、routine 与 durable activity 能让这些工作比较接近可运维的服务。

第三，你需要在自主性与人类控制之间取得平衡。预算、审批、pause、terminate、secret scope 与 audit log 都是把「可以自动做」变成「可以在边界内自动做」的基础。

相反地，如果你只有一个 agent、几个手动任务，或只是需要一个 prompt chaining library，Paperclip 可能会显得过重。它的价值来自组织与治理；没有多 agent 协作问题时，直接使用原本的 agent 工具通常更简单。

导入时的三个判断

先定义不可自动化的事情

不是所有动作都该交给 agent。先列出需要人类核准的资源、资料与外部副作用，再把 approval policy 写进流程，而不是等事故发生后才补规则。

把成本当成产品指标

除了总额，也要看每个 goal、issue、provider 与 model 的成本。若某个任务反复重试或工具呼叫异常，成本资料应能帮你找到根因，而不只是提供月底报表。

让可携性早于规模化

Paperclip 的 company export/import、secret scrubbing 与 collision handling，显示组织本身也应该是可移动的资产。建立范本时，将秘密、环境差异与 agent adapter 分开保存，未来才容易复制到另一个专案或隔离环境。

结语：AI agent 的下一个瓶颈是运营

当 agent 从一次性的聊天工具变成长时间工作的团队成员，瓶颈会从模型能力转向运营能力：任务如何排队、上下文如何保存、成本如何限制、权限如何收敛、决策如何追踪，以及人类何时介入。

Paperclip 的做法是提供一个开源、可 self-host 的 control plane，把 goal、org chart、issue、heartbeat、budget 与 governance 放进同一个系统。它不承诺替你建造最聪明的 agent，而是试图让不同 agent 在清楚的组织边界内工作。

对 AI 工程团队而言，最值得借鉴的未必是某一个 UI 功能，而是这个分层：把 agent runtime 和公司级协作、治理、观测分开。当我们开始管理的不只是几次模型呼叫，而是一群会持续行动的数位工作者，这层 control plane 很可能会成为不可或缺的基础设施。

参考资料