paperclip 详细介绍：开源项目架构、功能与实践指南

项目快照：paperclipai/paperclip，约 78,594 个 Star，14,394 个 Fork；最新推送时间 2026-08-17T06:32:47Z。本文基于仓库公开资料撰写。

项目地址：https://github.com/paperclipai/paperclip · https://paperclip.ing

paperclip 从代码、运行环境到实践流程的项目封面 — paperclip 的项目能力与实践流程示意。

项目速览（TL;DR）

paperclip 是一个采用 TypeScript 编写的开源应用，用于在工作场景中编排和管理多个人工智能代理（AI agent）。仓库描述为 “The open-source app everyone uses to manage agents at work”，README 则将其定义为面向代理团队的开源编排系统。

项目由 Node.js 服务器和 React 用户界面组成，支持接入不同代理、分配目标、跟踪工作与成本，并在控制台中处理组织结构、预算、治理和代理协作。根据 GitHub 仓库资料，项目默认分支为 master，许可证为 MIT，仓库标注语言为 TypeScript。

项目属性	资料值
仓库	paperclipai/paperclip
GitHub Stars	78594
GitHub Forks	14394
主要语言	TypeScript
默认分支	master
许可证	MIT
仓库描述	The open-source app everyone uses to manage agents at work

“Paperclip is a Node.js server and React UI that orchestrates a team of AI agents to run a business.”

来源：README

定位与目标用户

Paperclip 的定位不是单个代理的提示词界面，而是用于管理代理组织的控制平面（control plane）。它把业务目标、代理角色、任务分配、审批、预算和审计放在同一个应用中，工作对象从单个代码提交扩展到可追踪的业务任务。

README 使用了“如果 OpenClaw 是员工，Paperclip 就是公司”的比喻。这里的“公司”对应的是组织图、职责边界、治理规则和成本控制等管理能力；该比喻是项目原文中的产品定位，不代表仓库对代理自主经营结果作出保证。

目标使用场景

需要把 OpenClaw、Codex、Claude Code、Cursor 等不同代理协调到同一目标下的团队。
同时运行多个 Claude Code 终端，需要通过任务、会话和组织关系跟踪进度的使用者。
希望代理持续运行，同时保留人工审核、暂停和介入能力的团队。
需要按代理设置月度预算，并在达到额度后停止代理执行的管理场景。
需要从移动设备查看和管理自主运行任务的使用者。

上述场景均来自 README 的适用性描述。关于可承载的代理数量、并发任务数、单实例数据规模和生产服务等级，官方仓库未提供该信息，建议以最新 README 和文档为准。

核心功能

Paperclip 的功能可以按任务、组织、训练和基础设施四个支柱理解。每项能力都围绕“代理如何被安排、执行、审核和约束”展开，而不是只提供一个聊天窗口。

目标对齐与任务管理

使用者先定义业务目标，再把工作拆成任务并分配给代理。README 给出的流程是“定义目标、组建团队、审批并运行”：目标是输入，代理执行任务，控制台用于查看结果、策略和成本。

任务采用票据（ticket）和线程式对话组织，README 还提到会话可跨重启持久化。每个任务可以连接到更高层目标，从而让代理理解“做什么”以及“为什么做”；具体数据模型、接口签名和持久化实现细节，官方仓库资料未完整提供。

代理组织图与治理

组织图（org chart）为代理配置角色、职务、汇报关系和职责范围，也允许人类与代理处于同一组织结构中。代理之间可以沿组织关系进行委派，角色和边界则用于表达谁可以执行什么操作。

治理能力包括审批代理聘用、覆盖策略、暂停或终止代理。README 还列出角色权限、作用域密钥和公司边界等内容；具体权限枚举、策略配置格式和鉴权接口，官方仓库未提供该信息，建议以最新文档为准。

心跳与持续运行

心跳（heartbeat）是代理被定期唤醒并检查工作的触发机制。代理在收到心跳后检查待处理事项，然后执行工作或向组织关系中的其他代理委派任务；README 将其概括为“如果能接收心跳，就可以被雇用”。

这一机制要求被接入的代理运行时具备接收心跳的能力，但仓库资料没有给出统一心跳周期、重试次数、队列实现或具体事件格式。部署时不应依据本文推断这些参数，应以对应适配器和官方文档为准。

成本控制

成本控制以代理为粒度设置月度预算。当代理达到预算上限时，README 描述的行为是停止该代理，以避免失控成本。输入是预算配置，执行过程产生成本记录，输出是控制台中的成本跟踪和预算状态。

仓库资料没有提供计费单位、不同模型的价格来源、预算统计口径或账单校准方式。因此，Paperclip 的成本功能应被理解为项目提供的管理和限制机制，不应直接当作外部供应商账单的法律或财务结算依据。

审计、票据和审批

票据系统用于记录对话和决策，README 还列出工具调用追踪（tool-call tracing）以及不可变审计日志（immutable audit log）。在工作流中，审批门和审核节点可以把代理生成的结果交给人类验证，验证材料包括差异、截图和测试结果。

资料未说明审计日志的存储周期、导出格式、删除策略和不可变性的技术实现。涉及监管取证时，应先核对实际部署版本和数据库策略，再决定是否满足组织的审计要求。

系统架构与关键模块

从 README、package.json 和 Dockerfile 可以确认，项目采用 Node.js 服务端、React UI 和 pnpm 工作区（workspace）组织代码。Docker 构建过程把依赖安装、前端构建、插件 SDK 构建和服务端构建拆成不同阶段，生产容器通过 Node.js 启动服务端。

运行时组成

服务器：工作区包名为 @paperclipai/server，生产镜像的启动命令为 node --import ./server/node_modules/tsx/dist/loader.mjs server/dist/index.js。
用户界面：工作区包名为 @paperclipai/ui，Dockerfile 在构建阶段执行其生产构建。
数据库包：工作区包含 packages/db，根脚本提供 db:generate、db:migrate 和 db:backup。
共享代码：工作区包含 packages/shared 和 packages/adapter-utils 等共享模块。
命令行工具：根脚本通过 paperclipai 调用 cli/src/index.ts。

适配器与插件

Dockerfile 列出了多个代理适配器目录，包括 claude-local、codex-local、cursor-cloud、cursor-local、gemini-local、grok-local、hermes、hermes-gateway、openclaw-gateway、opencode-local 和 pi-local。这些目录说明项目通过适配器连接不同代理运行时，但资料没有给出每个适配器的参数表和兼容性矩阵。

插件相关目录包括 packages/plugins/sdk、沙箱提供方目录以及多个示例或功能插件。Dockerfile 的 cloud 构建目标会构建沙箱提供方插件；默认 production 目标与该云变体的插件打包范围不同，部署时需要明确选择构建目标。

前端与服务端构建关系

根脚本 build 会先运行工作区链接预检，再执行所有工作区构建；Docker 构建阶段则分别执行 UI、插件 SDK 和服务器构建，并检查 server/dist/index.js 是否存在。该检查表明服务端构建产物是生产镜像启动的必要文件。

依赖与运行环境

本地开发环境至少需要满足 package.json 声明的 Node.js 和 pnpm 要求。仓库声明 Node.js 版本为 >=20，包管理器为 pnpm@9.15.4；Dockerfile 使用 node:lts-trixie-slim 作为基础镜像，并通过 Corepack 启用包管理器。

组件	资料中的要求或实现	用途
Node.js	`>=20`	执行服务端、脚本和构建任务
pnpm	`9.15.4`	安装依赖并管理工作区
TypeScript	`^5.7.3`	开发依赖中的类型系统与编译工具
Vitest	`^4.1.10`	运行测试脚本
Playwright	`^1.61.1`	端到端和视觉测试相关工具
React	`^19.2.7`，由 pnpm overrides 指定	构建用户界面
PostgreSQL	连接示例为 `postgres://paperclip:paperclip@localhost:5432/paperclip`	由 DATABASE_URL 指定数据库连接

依赖版本来自 package.json 的 engines、packageManager、devDependencies 和 pnpm overrides。数据库连接字符串来自 .env.example，但仓库资料没有提供数据库初始化服务的完整操作步骤；开发者应根据最新 README 和文档配置数据库。

快速开始

最小闭环是安装工作区依赖、启动开发服务，再执行仓库已有的类型检查或测试脚本验证环境。以下命令只针对本地开发或测试环境，不包含公网暴露、生产密钥和第三方服务授权配置。

安装

corepack enable
pnpm install

corepack enable 与 pnpm install 对应 Dockerfile 和 package.json 所使用的包管理方式。安装完成后，仓库的 postinstall 脚本会执行 scripts/link-plugin-dev-sdk.mjs。

运行开发服务

pnpm dev:both

dev:both 是 package.json 中定义的脚本，用于调用 scripts/dev-both.mjs。若需要分别启动组件，也可以使用 pnpm dev:server 和 pnpm dev:ui；具体服务输出地址以当前命令行日志为准。

验证安装

pnpm typecheck
pnpm test:run

pnpm typecheck 会运行工作区链接预检和各工作区类型检查，pnpm test:run 会运行稳定测试脚本。这里的验证覆盖代码类型和测试执行，不等同于完整生产验收，也不代表所有代理适配器均已连接成功。

配置说明

仓库提供的配置样例集中在 .env.example，Dockerfile 还给出了生产容器环境变量。下表仅列出资料中真实出现的字段；“默认值”只填写样例或 Dockerfile 明确给出的值，未出现的内容不作推断。

字段名	类型	默认值	作用
`DATABASE_URL`	字符串	`postgres://paperclip:paperclip@localhost:5432/paperclip`	指定数据库连接地址
`PORT`	数字字符串	`3100`	指定服务端口
`SERVE_UI`	布尔值字符串	`false`（.env.example）	控制是否由服务端提供 UI
`BETTER_AUTH_SECRET`	字符串	`paperclip-dev-secret`	认证相关密钥配置
`PAPERCLIP_TOOL_ACTION_SIGNING_SECRET`	字符串	`paperclip-dev-tool-action-signing-secret-change-me`	工具动作签名密钥配置
`HOST`	字符串	`0.0.0.0`（Dockerfile）	生产容器中服务监听的主机地址
`PAPERCLIP_HOME`	路径字符串	`/paperclip`（Dockerfile）	生产容器中的 Paperclip 主目录
`PAPERCLIP_CONFIG`	路径字符串	`/paperclip/instances/default/config.json`（Dockerfile）	指定默认实例配置文件
`PAPERCLIP_DEPLOYMENT_MODE`	字符串	`authenticated`（Dockerfile）	生产容器的部署模式
`PAPERCLIP_DEPLOYMENT_EXPOSURE`	字符串	`private`（Dockerfile）	生产容器的暴露范围设置

BETTER_AUTH_SECRET 和 PAPERCLIP_TOOL_ACTION_SIGNING_SECRET 的样例值明确带有开发用途含义，部署到共享环境时不应继续使用样例密钥。仓库资料没有说明密钥轮换、密钥长度、配置文件完整 schema 或环境变量优先级，相关细节应以官方文档为准。

进阶用法

进阶使用重点在工作区脚本、数据库维护、适配器和插件构建，而不是修改单个前端页面。仓库已经把多类操作封装为根级命令，使用时应优先采用这些脚本，以减少直接调用内部文件的差异。

数据库与工作区操作

pnpm db:generate
pnpm db:migrate
pnpm db:backup

这三个命令分别映射到数据库工作区的生成、迁移以及仓库提供的备份脚本。资料没有给出迁移前置条件、备份文件位置和恢复命令，因此执行前应在本地测试数据库上确认脚本行为，并为生产数据库建立独立备份策略。

构建、类型检查与文档开发

pnpm build：执行工作区链接预检并构建工作区。
pnpm typecheck：执行工作区链接预检和类型检查。
pnpm storybook：启动 UI 工作区的 Storybook。
pnpm docs:dev：进入 docs 目录并运行 Mintlify 文档开发命令。
pnpm test:e2e：使用仓库中的 Playwright 配置执行端到端测试。

如果需要开发插件 SDK，package.json 提供了 @paperclipai/plugin-sdk 相关构建步骤。插件沙箱提供方不在 pnpm 工作区中，Dockerfile 的 cloud 构建阶段会在对应目录中独立安装并构建插件。

可观测性与运维

项目将工作状态、成本、对话、工具调用和审计记录放入管理界面或相关运行链路中，适合把代理执行过程纳入日常运维。Dockerfile 还设置了构建版本和构建提交环境变量，用于在没有 Git 元数据的镜像中保留构建识别信息。

运维相关脚本

pnpm dev:list：列出开发服务。
pnpm dev:stop：停止开发服务。
pnpm db:backup：调用数据库备份脚本。
pnpm test:release-smoke：运行发布冒烟测试。
pnpm smoke:openclaw-join：运行 OpenClaw 加入流程冒烟脚本。
pnpm smoke:hermes-gateway-e2e：运行 Hermes 网关端到端冒烟脚本。

Dockerfile 将容器端口设置为 3100，并声明 EXPOSE 3100。仓库没有提供监控指标名称、日志格式、告警规则、健康检查接口完整定义或 SLA，因此这些运维内容不能从现有资料中补充推断。

安全与合规边界

Paperclip 能够协调代理执行工作、调用工具并持续运行，因此部署时必须把代理权限限制在已授权的本地环境、测试环境或组织资产范围内。本文只讨论合法授权场景，不提供针对未授权目标的攻击教程、绕过检测方法或凭据滥用步骤。

密钥与权限

不要把 BETTER_AUTH_SECRET、PAPERCLIP_TOOL_ACTION_SIGNING_SECRET 或第三方服务凭据提交到代码仓库。
.env.example 中的开发密钥只能用于本地测试，不能据此判断生产密钥策略。
为代理分配最小必要权限，并通过 README 提到的角色、权限、作用域密钥和公司边界进行隔离设计。
在启用自动运行、工具调用或外部集成前，先设置人工审批、预算上限和暂停路径。

README 列出 SSO、GRC、RBAC、沙箱、MCP 服务器和数据隐私等能力方向，但资料没有提供完整合规认证、数据驻留区域、加密实现、审计保留期限或第三方安全评估。涉及个人信息、商业秘密、受监管数据或跨境处理时，应由组织的安全与合规团队进行单独评估。

许可证与商用条款

MIT License 不替使用者处理第三方模型、代理运行时、云服务、数据保护法规或组织内部审批要求。Paperclip 本身的许可证与所连接服务的许可证、服务条款和数据处理条款应分别核查。

局限性与已知限制

现有资料能够说明项目的目标、脚本和容器构建路径，但不能替代完整的部署手册。对于生产规模、性能上限、可靠性指标和各适配器的兼容性，官方仓库未提供该信息，建议以最新 README 和官方文档为准。

README 资料在“Problems Paperclip solves”对照表处被截断，完整问题清单无法依据当前材料复原。
没有提供公开的性能基准、吞吐量、并发上限、任务延迟或资源消耗数据。
没有提供数据库 schema、迁移兼容矩阵、备份恢复演练要求和数据保留策略。
没有提供统一代理适配器的输入输出协议、心跳格式、重试策略和失败恢复语义。
没有提供 SSO、RBAC、GRC、MCP 和沙箱能力的完整配置字段及安全边界说明。
默认生产 Docker 镜像与 cloud 目标在插件打包范围上不同，不能把一个构建目标的插件行为直接推断到另一个目标。

根据本文作者的经验判断，在引入多个代理之前，应先用单一代理完成目标、任务、审批、预算和审计链路的验收，再逐步增加适配器和自动化权限。该建议属于工程实践判断，不是仓库声明的性能或部署承诺。

适合谁

Paperclip 更适合已经存在明确代理协作需求，并且愿意为权限、预算和审核建立管理流程的团队。下面的判断信号可用于评估是否值得在本地测试环境中引入。

团队已经同时运行 OpenClaw、Codex、Claude Code、Cursor 或其他适配器，需要统一查看任务和状态。
组织需要把代理角色、汇报关系、委派边界和人工审批固化为可审计流程。
代理任务需要持续运行，但负责人仍要求随时暂停、终止或覆盖代理策略。
模型调用成本需要按代理或业务目标跟踪，并且需要预算达到上限后停止执行。
团队拥有 Node.js、TypeScript、pnpm 和 PostgreSQL 相关维护能力，能够处理工作区构建与数据库运维。

不适合谁

如果需求只是一次性调用模型、简单聊天或单个脚本自动化，Paperclip 的组织与治理层可能超出所需范围。以下信号表示应先评估更小的实现，或继续使用现有工具；资料没有明确列出其他替代产品，因此不在此虚构产品对比。

只有一个短生命周期任务，不需要任务线程、代理汇报关系、预算和审批记录。
团队不能维护 Node.js、pnpm、数据库和容器环境，也没有计划承担自托管运维责任。
所有数据都属于受严格监管的敏感数据，但组织尚未完成代理权限、数据驻留和第三方服务审查。
业务要求已明确的高并发、低延迟、可用性或 SLA 指标，而当前资料没有对应性能和可靠性承诺。
组织不允许代理访问工作区文件、外部工具或持续运行进程，因而无法使用项目所描述的代理编排模式。

常见问题与排查（FAQ / Troubleshooting）

排查时应先区分依赖安装、工作区链接、数据库配置、开发服务和代理适配器五类问题。仓库提供了多个预检、构建、测试和冒烟脚本，可优先使用这些已定义命令收集可复现信息。

为什么安装后工作区包无法解析

根 package.json 提供了 preflight:workspace-links，并在构建、类型检查和测试脚本中调用它。可以先运行 pnpm install，再执行 pnpm typecheck；如果仍然失败，应保留命令输出并核对当前分支与锁文件状态。

为什么服务启动后 UI 不可用

.env.example 中 SERVE_UI=false，而 Dockerfile 的生产环境设置为 SERVE_UI=true。这说明不同运行方式的 UI 提供策略不同，但仓库资料没有给出全部环境变量优先级；应检查实际加载的环境和启动日志，而不是直接复制生产配置。

数据库连接失败如何处理

先核对 DATABASE_URL 是否指向本地 PostgreSQL，并确认使用的数据库名、用户名、主机和端口与环境一致。之后根据需要执行 pnpm db:generate 和 pnpm db:migrate；迁移失败时不要直接删除生产数据，先在测试数据库复现。

如何确认构建产物完整

可以运行 pnpm build，并检查服务端构建是否成功。Dockerfile 明确检查 server/dist/index.js，如果该文件缺失，生产镜像不会进入可用状态；更细的构建失败原因需结合对应工作区日志判断。

代理或网关连接问题如何排查

仓库定义了 OpenClaw 和 Hermes 网关的冒烟脚本，也定义了多个本地代理适配器。应在授权的本地或测试环境运行对应 smoke 命令，并查看适配器自身日志；官方资料未提供统一连接诊断接口、凭据格式或网络重试参数。

项目地址与资源

以下链接均来自仓库 README 或项目资料，用于访问源代码、官方文档和项目官方站点。