paperclipai/paperclip · 上手攻略

仓库：paperclipai/paperclip
链接：https://github.com/paperclipai/paperclip
分类：agent / 多 agent 编排控制平面（Node.js + React）
作者：spark
更新：2026-10-28

一、它是什么

Paperclip 是一个开源的多 agent 编排控制平面：一个 Node.js 服务 + React UI，用来 orchestrate 一支 AI agent 团队去「经营一家公司」。

它的自我定位很直接——README 里写「If OpenClaw is an employee, Paperclip is the company」（如果 OpenClaw 是员工，Paperclip 就是公司）。它不是 agent 框架（原文：「Not an agent framework. We don't tell you how to build agents. We tell you how to run a company made of them」），也不是工作流构建器，更不是 prompt 管理器。它管的是「agent 们组成的那家公司怎么运转」：任务、组织架构、目标、预算、审批、审计。

作者明确划清了四条边界：

Not just a chatbot — 对话永远附着在任务、计划、决策和产出上。
Not an agent framework — agent 自带 prompt、模型和运行时，Paperclip 管他们工作的组织环境。
Not just a workflow builder — Routines 在一个有角色、目标、预算和治理的组织里运行。
Not limited to one agent — 从一个 agent 起步，逐步长成有共享技能、委派和评审的团队。

底层架构分两层：Paperclip Server（Node.js 服务 + React UI + 嵌入式 PostgreSQL）和一层 adapter（Claude Code / Codex / Cursor / Gemini CLI / OpenCode / Grok Build / Kimi Code / Hermes 等，以及 HTTP/webhook bot 和自定义 adapter 插件）。作者的解释很直白：「It can receive a heartbeat, it's hired.」（能接收心跳就算入职。）

支撑它的「四大支柱」：Agentic Task Manager（任务、审批门、审计工作流）、Org Chart for Agents（混合人类+agent 的组织架构、职责、委派、治理、作用域化密钥）、Agent Employee Training（Skill Studio、evals、绩效评估、技能版本历史）、Agentic OS（跨 provider 运行时、沙箱、MCP、SSO/GRC/RBAC、成本控制、数据隐私与内部 trace）。

许可 MIT。写作时点（2026-10-28）GitHub API 显示 108,024 star / 17,906 fork，默认分支是 master（不是 main），仓库创建于 2026-03-02。

二、它解决什么问题

具体针对四类痛点，README 用「没有 Paperclip / 有 Paperclip」的对照表说得很直白：

痛点 1：多 agent 并行时上下文丢失。 典型场景是「20 个 Claude Code 终端开着，忘了谁在干什么，重启后什么都没了」。Paperclip 的解法是：任务即工单、对话有线程、会话跨重启持久化；上下文从任务向上穿过项目直达公司目标，agent 始终知道自己在干什么、为什么干。

痛点 2：agent 各自为战，不对齐目标。 任务和项目可以链接到组织目标，agent 收到的是目标上下文而不只是一个标题（README 的说法是 goal ancestry，让 agent 看到「why」而非仅标题）。

痛点 3：成本失控。 公司级、agent 级、项目级、目标级、工单级、provider 级、模型级的预算与成本追踪；告警阈值和硬停；到达上限自动暂停工作。

痛点 4：没有治理与问责。 审批与评审阶段（review gates）、agent 的入职审批、预算硬停、暂停/改派/终止 agent、连接器动作的审批（Allowed / Ask first / Off 三档）。所有变更活动落成持久化 activity 记录，可审计「发生了什么、为什么」。

作者也给出了明确的「这不是什么」：Paperclip is a full control plane, not a wrapper（它是完整的控制平面，不是套壳）。

三、快速安装

前置条件

Node.js 24.11.0 或更高（文档原文「Node.js 24.11+」，站点写「specifically 24.11.0 or newer」）。托管安装会直接拒绝在更老的 Node 上运行；npx 安装或直接起服务在 Node 22/23 上会打印版本不支持警告但继续——文档说得很实在：「a warning is not support」。
源码开发需要 pnpm 9.15+。
想用本地 Claude / Codex 订阅登录，Paperclip 宿主机上还需要 Python 3 和对应的 provider CLI（Docker 镜像里已包含）。
源码构建若启用自托管的 Paperclip Runner（默认），需要 Rust 工具链，或设 PAPERCLIP_RUNNER_BINARY 指向兼容的预编译 runner。

路径 A：npx 一条命令（最快）

node --version   # 必须 v24.11.0 或更高

npx paperclipai@latest onboard --yes

onboard 会写实例配置、确保 agent JWT 密钥（PAPERCLIP_AGENT_JWT_SECRET）和本地 secrets 密钥文件存在，然后启动服务。默认是 trusted local loopback 模式。

私有 npm registry 的坑：README 专门开了 Troubleshooting 一节。如果你的全局 ~/.npmrc 指向私有 registry（如 GitHub Packages），npx 可能解析不到公共包，报 E404。诊断：npm config get registry；绕过：

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

路径 B：托管安装（推荐长期使用）

npx paperclipai install

这会下载并校验最新发布版，把 paperclipai 装进 ~/.local/bin，并给你三个 npx 给不了的能力：一键更新、瞬时回滚、可作为后台服务运行。

磁盘布局：

内容	路径
托管存储根	`~/.paperclip/cli`
下载的各版本 payload	`~/.paperclip/cli/installs`
安装清单	`~/.paperclip/cli/install.json`
当前版本软链	`~/.paperclip/cli/current`
`paperclipai` 命令	`~/.local/bin/paperclipai`

安装通道可选：paperclipai install（最新稳定）、--canary、--version 2026.609.0（精确版本）、--ref main（从 GitHub 源码构建）。--canary 与 --version 互斥，--ref 不能与二者同时用。--ref 会在你机器上运行该 commit 的依赖与构建脚本，非交互 shell 里必须加 --yes。

paperclipai --version
paperclipai channels          # 看 stable / beta / nightly / canary 四个通道
paperclipai update            # 更新
paperclipai update --rollback  # 回滚到上一个版本
paperclipai uninstall         # 卸载（数据保留在 ~/.paperclip）

路径 C：源码开发

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

UI 和 API 会在 http://localhost:3100 启动，嵌入式 PostgreSQL 数据库会自动创建，不需要另行搭库。

路径 D：隔离测试实例

ANTHROPIC_API_KEY=... npx paperclipai test-drive
OPENAI_API_KEY=... npx paperclipai test-drive --harness codex
OPENROUTER_API_KEY=... npx paperclipai test-drive \
  --harness opencode \
  --model openrouter/anthropic/claude-sonnet-4.5

test-drive 用于已初始化、已带 CEO agent 的隔离手动测试实例：保持前台运行、不安装服务、不创建第一个任务，只在 setup 成功后打开浏览器。每次不带 --data-dir 的运行会获得一个唯一的、保留的临时目录（绝对路径在启动时打印）。加 --data-dir 可复用，加 --no-browser 可不开浏览器。

绑定模式（远程访问）

npx paperclipai@latest onboard --yes --bind lan      # 局域网
npx paperclipai@latest onboard --yes --bind tailnet  # Tailscale

--bind 可选 loopback / lan / tailnet。默认 quickstart 是 trusted local loopback 模式。

四、核心用法

4.1 启动与认证

paperclipai onboard    # 写配置
paperclipai run        # 校验并启动服务

run 做的事：解析活动实例与配置路径、加载实例 env 文件；若无配置且是交互式终端则先交给 onboarding；默认带修复能力跑 doctor 检查，任一项失败就停下不起服务；最后启动服务器。

paperclipai run --instance dev              # 第二个隔离实例
paperclipai run --data-dir ./tmp/paperclip-dev   # 状态全放 worktree 里
paperclipai run --no-repair                 # 只诊断不改文件

⚠️ 术语陷阱：paperclipai run（无子命令）是本地 bootstrap，起服务；paperclipai run <subcommand>（list / live / get / events / log / cancel 等）是通过 API 检查和控制 heartbeat run 的控制面命令。两者语义完全不同。

认证（两种人格）：

人格	权限	用途
Board operator	全实例的完整 board 授权	bootstrap、建组织、签发凭证、全面操盘
Agent	限定到一个 company + 一个 agent	agent 操作自己的工作

# 交互式向导：解析 API base、健康检查、以 board 登录、选 persona/company/agent、签 token、存 profile
paperclipai connect

# 非交互式 board 登录（设备码/浏览器批准流）
paperclipai auth login

# 签发凭证
paperclipai token board create       # 命名、支持过期与吊销、服务端审计
paperclipai token agent create       # 限定一个 company + 一个 agent，明文只显示一次

4.2 API base 解析顺序（排查连不上时先看这个）

第一个产出 URL 的来源获胜：

--api-base
PAPERCLIP_API_URL
所选 context profile 的 apiBase
本地 Paperclip 配置的 server port
http://localhost:3100

文档给了实用提示：命令连不上时，错误信息里会包含它实际尝试的 URL 和一个检查 GET /api/health 的提示——先读那个 URL，别瞎猜。

4.3 Context profile（避免重复敲参数）

默认存在 ~/.paperclip/context.json。profile 是 persona-aware 的：board profile 记 persona=board；agent profile 记 persona=agent 加 agentId 和 agentName。

关键安全设计：profile 存的是 apiKeyEnvVarName（环境变量名），不是明文 token。key 留在你的环境里，profile 只记住去哪找。

paperclipai context set --api-base http://localhost:3100 --company-id <company-id>
paperclipai context set --api-key-env-var-name PAPERCLIP_API_KEY
export PAPERCLIP_API_KEY=...
paperclipai context show
paperclipai context use default

4.4 把方向盘交给 AI

paperclipai agent local-cli <agent-id> -C <company-id>

一条命令完成：创建长期 agent API key、把 Paperclip skills 装进 ~/.codex/skills 和 ~/.claude/skills、打印 PAPERCLIP_API_URL / PAPERCLIP_COMPANY_ID / PAPERCLIP_AGENT_ID / PAPERCLIP_API_KEY 四个 export 行。

4.5 常用控制面命令族

几乎所有控制面命令共享这些通用 flag：

--data-dir <path>      # 把所有本地状态隔离到 ~/.paperclip 之外
--api-base <url>       # 指向远程或非默认服务器
--api-key <token>      # 直接用 token 认证，不走 profile
--context <path>       # 指定 context 文件
--profile <name>       # 选择 context profile
--json                 # 机器可读输出，用于脚本化

公司范围的命令额外接受 --company-id <id>（部分命令有 -C 短别名，如 run）。

命令族覆盖：companies、projects、goals、issues、agents、prompts、runs、routines、approvals、activity、dashboards、cost、workspaces、access、adapters、assets、skills、secrets、cloud、plugins、feedback。

4.6 关键机制的实操含义

原子任务签出（atomic task checkout）：单一 assignee 加执行锁，防止两个并发 run 抢到同一个任务。这是多 agent 场景里最容易出错的地方——没有锁时两个 agent 会同时改同一个工单。

Heartbeat（心跳）：agent 为被分配的工作、后续消息或配置的周期而醒来；委派沿组织架构上下流动。这正是「It can receive a heartbeat, it's hired」这句的口语来源。

Routines（例行任务）：cron、webhook、API 三种触发器，每次执行创建一个可追踪的 issue 并唤醒指定 agent。支持并发策略与 catch-up 策略。

连接器与网关动作：连接 GitHub、Notion、Railway 或自建 MCP server；网关动作可设为 Allowed / Ask first / Off 三档。人类访问权、agent 资格、网关动作权限是三个独立控制项。

Skills 与 Skill Studio：安装或编写组织共享技能，用保存的输入测试，查看结果，可回滚到早期版本（技能版本历史 + restore）。

组织可移植性：预览/导出/导入组织包（agents、skills，可选 projects、routines、tasks、attachments），带 secret 清洗和冲突处理。文档明确警告：引用的 secret 值会被省略，但普通环境变量值和本地路径可能残留，导出后分享前要审查。

4.7 CLI 与 UI 的关系

文档反复强调：CLI 和 UI 是同一控制平面、同一份数据的两个界面，「Anything in this documentation can equally be done on screen」。Paperclip 是 UI-first 的——Web UI 是主界面，CLI 是终端更合适时的替代（安装配置、自动化与 CI、批量操作、无浏览器 headless 运维）。

还有一条重要的心智模型：CLI 不跑模型。agent 的实际工作（LLM 调用、写代码、做研究）跑在服务端的 Paperclip runtime 和 adapter 里。CLI 只是触发并观察（agent wake / heartbeat run 是 POST 到 /api/agents/:id/wakeup，服务端跑 adapter，CLI 把 run events 和日志流回终端）。文档原话：「You are conducting, not computing.」

五、典型适用场景

场景 1：把一堆 agent 变成一支有组织的团队。 从「20 个 Claude Code 标签页」变成有 org chart、汇报线、岗位描述、权限边界的团队。

场景 2：需要审计与问责的多 agent 作业。 审批门、决策追踪、预算硬停、agent 暂停/终止、持久化 activity 记录。

场景 3：成本治理。 按公司/agent/项目/目标/工单/provider/模型分层设预算，配告警阈值和硬停。

场景 4：CI 里的 headless 编排。 --json 输出 + --data-dir 隔离 + API base 解析顺序，适合脚本化。

场景 5：移动端监控。 README 强调「Manage your autonomous businesses from your phone」，有移动端 UI（仓库里有 pnpm dev:mobile 脚本）。

场景 6：多组织（多公司）部署。 一个部署可托管多个组织，组织间数据与访问检查隔离。

场景 7：把 agent 接入既有服务。 GitHub、Notion、Railway 连接器 + 自建 MCP server + 自定义 adapter 插件（out-of-process worker、能力门控的宿主服务、作业调度、工具暴露、UI 贡献）。

六、坑与注意

坑 1：Node 版本是硬门槛，且警告不等于支持。 现象：需要 Node 24.11.0+；托管安装在老版本上直接拒绝，npx 路径在 Node 22/23 上只打印警告继续跑。影响：以为能跑，等到某个特性触发才炸。修复：先 node --version 确认；文档原话「a warning is not support — upgrade Node before you rely on it」。

坑 2：run 一词两义，极易误用。 现象：paperclipai run（无子命令）= 起本地服务；paperclipai run list/live/get/events/log/cancel = 通过 API 管控 heartbeat run。影响：脚本里想「看一眼有哪些 run 正在跑」，却不小心执行了「启动一个服务」，在 CI 里可能占端口或拉起后台进程。修复：脚本里写 paperclipai run list，别只写 paperclipai run；加 --no-repair 只诊断。

坑 3：私有 npm registry 会让 npx 找不到包。 现象：全局 ~/.npmrc 指向私有 registry（如 GitHub Packages）时，npx paperclipai@latest 报 E404。影响：以为 Paperclip 挂了，其实是解析到了错误的 registry。修复：npm config get registry 诊断，然后用 npx --registry https://registry.npmjs.org paperclipai@latest ... 强制公共源。

坑 4：--ref 会在你机器上执行陌生代码。 现象：paperclipai install --ref main 会下载该 commit 并在你机器上运行其依赖安装与构建脚本；非交互 shell 下必须 --yes。影响：这是明确的代码执行风险面。修复：只对你信任的 ref 使用；生产用 --version 固定版本；--canary / --version / --ref 三者只能选一个通道。

坑 5：数据在 ~/.paperclip，uninstall 不删。 现象：paperclipai uninstall 会停服务、删命令、移除 PATH 块、删掉 ~/.paperclip/cli，但「Your companies, config, database, logs, and secrets all live elsewhere under ~/.paperclip and are untouched」。影响：以为卸载干净了，结果密钥和数据库还在磁盘上。修复：卸载后手动确认 ~/.paperclip 残留；多实例用 --instance / --data-dir 分开。

坑 6：导出包会残留环境变量值和本地路径。 现象：文档明确写「Referenced secret values are omitted; review packages before sharing because plain environment values and local paths can remain」。影响：把组织包发给同事或传外部时可能泄露路径、内部主机名、明文环境变量。修复：导出后先人工审查；把「导出即分享」这一步当成数据出境来管。

坑 7：Onboard 会自动写密钥文件。 现象：onboarding 会确保 PAPERCLIP_AGENT_JWT_SECRET 和本地 secrets 主密钥文件存在，缺失就创建。影响：密钥文件生成后权限/备份策略无人负责。修复：确认 ~/.paperclip 的文件权限与备份策略；不要把该目录纳入版本库或宽松的云同步。

坑 8：多实例端口冲突。 现象：同一实例已作为后台服务运行时，再跑 paperclipai run 会报错而不是启动第二份；要强制得用 --force。影响：CI 里以为「起不来了」其实是服务已在跑。修复：先 paperclipai service status；需要并行实例用 paperclipai run --instance dev 或 --data-dir。

坑 9：--bind lan / --bind tailnet 改变暴露面。 现象：quickstart 默认是 trusted local loopback；--bind lan 或 --bind tailnet 会把服务放到可路由网络。影响：在没有额外认证配置的情况下扩大攻击面。修复：远程访问优先用 authenticated 模式 + 私有网络绑定（如 Tailscale），别直接 --bind lan 裸奔。

坑 10：预算硬停有延迟。 现象：文档写「Enforcement uses recorded spend; usage reporting and in-flight work can delay a stop」。影响：以为设了硬停就一定不超支，实际上有窗口期。修复：预算阈值要留余量；对关键场景配合 usage 告警。

坑 11：仓库默认分支是 master 不是 main。 现象：raw.githubusercontent.com/paperclipai/paperclip/main/README.md 返回 404，正确路径是 master。影响：照抄别人写的 main 路径会拿到 404，误以为项目挂了。修复：克隆后用 git branch -a 确认；抓取 raw 文件时注意分支名。

坑 12：版本号有两套体系，别混。 现象：npm 包 cli/package.json 的 version 是 0.3.1（语义化版本），而 GitHub release tag 用的是日期式 v2026.1023.0（最新 release，发布于 2026-10-24），更早还有 v2026.1012.0 / v2026.1005.0 / v2026.1001.0。安装文档里举的 paperclipai install --version 2026.609.0 又是第三种写法。影响：写文档/锁版本时容易搞错该填哪个。修复：以 paperclipai channels 和 paperclipai update 的输出为准；锁定时明确是 npm 版本号。

坑 13：版本发布节奏快、issue 数量大。 现象：写作时点 108,024 star / 17,906 fork / 6,726 个 open issue，最近提交就在 2026-10-28。影响：文档、CLI 参数可能在你读的时候已变；issue 多到难以逐条跟进。修复：以官方站点 docs.paperclip.ing 为准（它与仓库同步维护），版本相关行为先在隔离实例上验证。

坑 14：「不是 agent 框架」是设计立场，不是缺陷。 现象：它不提供 agent 抽象、不定义模型接入方式，agent 自带运行时。影响：如果你的诉求是「写一个 agent」，Paperclip 是错的工具。修复：先确认你要的是「运行一支 agent 团队」而非「造一个 agent」。

七、与同类对比

方案	定位	关键能力	与 Paperclip 的差别
Paperclip	多 agent 编排控制平面	org chart、目标对齐、预算、审批治理、heartbeat、routines、审计、MCP/连接器、插件	——
OpenClaw	个人 agent harness	单 agent 运行时、工具、记忆	Paperclip 用它作为 adapter（README 明列 OpenClaw 在"Works with"清单里）
Claude Code / Codex / Cursor	单 agent CLI / IDE	各自的 agent 运行时	Paperclip 把它们当被编排的劳动力，不是竞品
Linear / Jira / Asana / Trello	人类任务管理	工单、看板	Paperclip 面向 agent，且承认「Bring-your-own-ticket-system is on the Roadmap」；agent 编排的微妙处（谁签出了任务、会话怎么续、成本怎么盯、治理怎么立）它替你做了
Temporal / Airflow	通用工作流编排	持久化执行、重试、调度	Paperclip 的 workflow 单元是「agent 在一个组织里干活」，带组织语义、预算和治理，不是纯 DAG
自建脚本 + cron	轻量自动化	便宜、灵活	Paperclip 提供原子签出、执行锁、预算硬停、审计、活动记录、跨重启会话

真正的差异点：Paperclip 把「agent 团队」当成一家公司来建模——org chart、汇报线、岗位描述、负责人（responsible-user attribution）、公司边界、跨组织隔离、导入导出。这是通用工作流引擎和任务管理器都不提供的语义层。

八、一句话推荐结论

推荐给已经在同时跑多个 agent（Claude Code / Codex / OpenClaw 等）并感到失控的团队——它的 org chart + 预算硬停 + 原子签出 + 审批治理这套组合正好补上多 agent 并行的真实空白，MIT 许可、自托管、无需 Paperclip 账号；但如果你的诉求是「写一个 agent」而非「运营一支 agent 团队」，它明确不解决那个问题（作者自己划了这条线）。

附：核对与不确定说明

已核实（直接 fetch）：README 全文（GitHub 页面渲染版）、docs.paperclip.ing/reference/cli/installation/、docs.paperclip.ing/reference/cli/overview/、根 package.json 与 cli/package.json（npm 包名 paperclipai、version 0.3.1、MIT、bin 名）、GitHub API 仓库元数据（star/fork/issue 数、创建与推送时间、默认分支 master）、release tag 列表（最新 v2026.1023.0，2026-10-24）、仓库根目录结构（cli / server / ui / packages / plugins / skills / integrations / evals / docker 等）。
版本标注：三套版本号并存——npm CLI 0.3.1、GitHub release v2026.1023.0、安装文档示例 2026.609.0。本文在涉及处分别标注，未做换算（换算规则未在文档中明示）。
不确定项：① npm registry 上 paperclipai 的实际最新发布版本未查（只读了仓库内 cli/package.json 的 0.3.1，该文件可能领先于已发布包）；② 6,726 个 open issue 的构成与质量未逐条评估；③ 「merged over 2,700 pull requests」为 README 自述，未独立核实；④ Docker 部署路径（docker/ 目录、docs 的 /reference/deploy/docker/）未展开阅读；⑤ adapter 插件的实际生态规模未核实；⑥ 未 clone 仓库、未启动任何实例、未验证 npx 路径。
来源性质说明：本文所引命令、flag 与目录布局均来自官方文档站 docs.paperclip.ing（与仓库同源维护）与仓库 README，未使用第三方博客或新闻稿。