Paperclip 怎么装：onboard 一条命令背后的四种安装方式与更新回滚

2026-08-17

搜”Paperclip 怎么安装”的人，多半已经在 Quickstart 页面看到那一行 npx paperclipai onboard --yes 了。问题是这一行跑完之后，你会发现自己处在一个说不清的状态：装到哪儿了？以后怎么更新？出了问题怎么退回上一版？要不要让它开机自启？

这些问题 Quickstart 不回答，答案在另一篇 INSTALLING.md 里。官方文档在那篇开头就写明，Paperclip 支持四种安装形态：托管安装（managed installation）、用 npx 的临时试用（ephemeral tryout）、传统的全局 npm 安装，以及从源码 checkout 开发。四种都能把服务跑起来，但后续待遇差别很大——文档明确推荐托管安装，理由是它提供原子更新、回滚、按 git ref 安装，以及给后台服务一个稳定的入口点。

所以”一条命令装起来”这句话本身没错，只是那条命令有好几个版本，选哪一条决定了你半年后升级时是敲一行 paperclipai update，还是自己去翻 npm。下面把四条路各自的命令、代价和适用场合按官方文档过一遍。

四种安装方式，先看差别再动手

方式	典型命令	文档写明的特点
托管安装（推荐）	`bash install.sh` → 委托 `paperclipai install`	原子更新、可回滚、支持 git ref 安装、后台服务入口稳定
npx 临时试用	`npx --registry https://registry.npmjs.org paperclipai onboard --yes`	无托管安装；文档提醒后续所有命令都得继续用 `npx paperclipai`
全局 npm	`npm install --global --registry https://registry.npmjs.org paperclipai` 后 `paperclipai onboard`	`paperclipai update` 可以更新这类安装
源码 checkout	`git clone` → `pnpm install` → `pnpm dev`	面向给 Paperclip 本身提交代码的人；`update` 不会自动改动 checkout，只提示对应的 git 流程

这里有一个很容易踩的坑，Quickstart 专门用引用块标了出来：如果你是用 npx 完成的初始安装，之后所有命令都要继续用 npx paperclipai 这个形式；pnpm paperclipai 那种写法只在克隆下来的 Paperclip 仓库目录里才成立。文章、群聊里抄命令的时候，这两种前缀混着抄，报”命令找不到”的概率相当高。

想先摸清楚 Paperclip 到底是个什么东西再决定装哪一种，可以先看什么是 AI 公司控制平面；如果你已经确定要往正经环境上放，三种部署模式怎么选是安装之前更该先想清楚的一步。

推荐路径：先把 install.sh 下下来校验，再执行

文档给出的推荐安装写法，适用于 macOS、Linux 或 WSL2：

curl -fsSLO https://paperclip.ing/install.sh
curl -fsSLO https://paperclip.ing/install.sh.sha256
if command -v sha256sum >/dev/null 2>&1; then
  sha256sum -c install.sh.sha256
else
  shasum -a 256 -c install.sh.sha256
fi
bash install.sh

注意它不是常见的 curl | bash 一把梭，而是先落地、先校验、再执行。这个引导脚本按文档说明做四件事：确认平台受支持；确保 Node.js 20 或更新版本可用；把真正的安装工作委托给 paperclipai install；当 stdin 和 stdout 都是终端时，接着进入交互式 onboarding。

有一段值得单独拎出来，因为它是官方自己写下的安全边界，而不是营销话术：paperclip.ing 上那个校验和能发现传输或发布环节的失误，但它和脚本来自同一个来源，不构成独立的真实性证明。文档给出的替代方案是从 GitHub 下载一份按 release tag 或 commit 固定的副本，自己审一遍再执行本地文件。对应命令是：

raw_base=https://raw.githubusercontent.com/paperclipai/paperclip
curl -fsSL "$raw_base/master/scripts/install.sh" | bash

文档同时提醒，做审计或事件响应时应当把这个 raw URL 从 master 换成具体的 release tag 或 commit SHA，并且先下载再看。这条路径的价值在于它和 paperclip.ing 是两条独立的分发通道。

需要无人值守的场景，脚本支持管道形式，但有前提条件——只有当受支持的 Node.js、npm、npx 已经装好时才会继续；如果还需要引导安装 Node.js，文档要求先把脚本下下来，好让那些需要提权的命令在执行前是可检查的：

curl -fsSL https://paperclip.ing/install.sh | bash -s -- --no-prompt --no-onboard
paperclipai onboard --yes

--no-prompt 用于自动化，--no-onboard 表示装完就停。另外文档提到每个安装器 flag 都有对应的 PAPERCLIP_INSTALL_* 环境变量写法，在管道里传参不方便的时候用得上。整个安装过程中，任何需要提升权限的命令，脚本都会打印出来并要求确认；第三方 Node.js 引导脚本会被固定版本并做 SHA-256 校验，一旦发布出来的脚本发生了预期外的变化，安装就会停下。

装什么版本：稳定版、canary、指定版本、git ref

托管安装并不是只能拿最新稳定版。文档列了几组 paperclipai install 的用法：

npx --registry https://registry.npmjs.org paperclipai install
npx --registry https://registry.npmjs.org paperclipai install --canary
npx --registry https://registry.npmjs.org paperclipai install --version 2026.720.0

也可以直接从 GitHub 装某个分支、标签或提交：

npx --registry https://registry.npmjs.org paperclipai install --ref master
npx --registry https://registry.npmjs.org paperclipai install --ref v2026.720.0
npx --registry https://registry.npmjs.org paperclipai install --ref <commit-sha>

用 fork 的话再加 --repo owner/repository。上面出现的 2026.720.0 是官方文档里的示例版本号（截至 2026-08-17 的文档写法），不是让你照抄的目标版本。

git ref 安装有一条明确的风险提示：请求的 ref 会先被解析成确切的 commit 再构建，而安装一个 git ref 意味着在你的机器上执行该修订版本的包安装脚本和 release 构建脚本。换句话说，随手指一个别人的分支装上去，等于同意跑对方仓库里的构建脚本。

托管安装的目录长什么样：代码和数据是分开的

这一节能解释后面很多行为。文档给出的布局是：

~/.paperclip/cli/
├── install.json
├── current -> installs/npm/2026.720.0
└── installs/
    ├── npm/<version>/
    └── git/<sha12>/

~/.local/bin/paperclipai

关键设计是：~/.local/bin/paperclipai 这个 shim 始终不变，而 current 这个符号链接在若干套完整负载（payload）之间原子切换。Paperclip 会保留前两套托管负载用于回滚。配置、数据库、上传文件、日志、密钥和工作区全部放在 ~/.paperclip/instances/ 下，不存在 CLI 负载内部。

顺带一个高频问题：如果 ~/.local/bin 不在 PATH 上怎么办。文档写的是，交互式安装时安装器会主动提出帮你改对应的 shell 启动文件；非交互式安装则不会偷偷改文件，而是把该执行的 export PATH 命令原样打印出来，让你自己加。

onboard 与后台服务：默认不装服务这件事得知道

非交互安装完成后，跑 onboarding：

paperclipai onboard

交互式 onboarding 会在平台支持后台服务时，询问你要不要把 Paperclip 作为后台服务运行。而自动化 onboarding 是刻意不装服务的，除非你明确要求：

paperclipai onboard --yes                    # 只做配置，不装服务
paperclipai onboard --yes --install-service  # 自动化场景下显式选择装服务
paperclipai onboard --yes --no-install-service

这条默认值经常被忽略：CI 或脚本里跑了 --yes，然后奇怪为什么重启机器之后什么都没起来——按文档，这就是预期行为。

服务相关命令是带命名空间的一组：

paperclipai service install
paperclipai service status
paperclipai service start
paperclipai service stop
paperclipai service restart
paperclipai service logs -f
paperclipai service uninstall

平台差异文档也写清楚了：在 Linux 和带 user systemd 的 WSL2 上用 systemd user service，在 macOS 上用 LaunchAgent。容器、WSL1，以及没有受支持的用户级服务管理器的系统，不会硬失败，而是转而给出前台运行 paperclipai run 的指引。服务本身走的是那个稳定的托管安装 shim，崩溃后会重启，也可以设置成登录时启动；在 Linux 上，安装服务时可能会提出启用 user lingering，好让它在没有活动登录会话时继续运行——这属于系统级动作，命令会先解释并要求确认。

还有一条容易在多人环境里踩的硬约束：每个实例只能有一个 server 进程。当同一个实例已经处于被监管状态时，paperclipai run 会拒绝启动；正确做法是先把服务停掉，只有在你确实接受单写入者风险时才用 --force。

更新与回滚：为什么建议先把服务起起来再更新

按安装清单（install manifest）里记录的来源和渠道更新：

paperclipai update

显式选择别的发布来源：

paperclipai update --latest
paperclipai update --canary
paperclipai update --version 2026.720.0

托管更新的动作顺序是：先做数据库备份，再校验新的 CLI，然后原子地翻转 current，最后重启已安装的服务。如果安装或校验失败，前一套负载保持生效。

这里有个反直觉的建议：如果服务是停着的，先 paperclipai service start 再更新，这样 Paperclip 才能拿到那份安全备份。只有当你有意接受”没有回滚保障地更新”时，才用 paperclipai update --no-backup。另一种情况是从未 onboard 过、没有配置和实例数据的实例，它会自动跳过备份，因为没东西可存。

回滚到上一套保留的负载：

paperclipai update --rollback

upgrade 是 update 的别名。确切版本号和 commit SHA 是被固定住的，想让它们往前走，得显式给一个新目标——这解释了为什么有人 --version 装完之后发现 update 再也不动了。

装完不对劲：doctor 查哪几项

paperclipai doctor
paperclipai service status

按文档，doctor 检查托管安装存储、manifest、current 链接、shim、PATH、Node.js 版本和服务状态。服务诊断则覆盖单元文件是否存在及是否漂移、运行状态、配置端口的归属、以及正在运行的 server 版本。排查安装类问题，先跑这两条比翻日志省事。

本地开发这条路：pnpm dev 与内嵌 Postgres

给 Paperclip 本身写代码的人走另一条：前置条件是 Node.js 20+ 和 pnpm 9+，克隆仓库后

pnpm install
pnpm dev

这会启动 API server 和 UI，地址是 http://localhost:3100。文档特别写明不需要外部数据库，Paperclip 默认使用一个内嵌的 PostgreSQL 实例。数据库要不要外接、什么时候该外接，可以看内嵌 Postgres 与外接数据库。

在克隆下来的仓库里还可以用：

pnpm paperclipai run

它会在配置缺失时自动 onboard，跑带自动修复的健康检查，然后启动 server。

另外，如果你已经装过一次，重新跑 onboard 不会破坏现状——文档说明它会保留当前的配置和数据路径；只想改设置的话用 paperclipai configure。日常重新启动则是 npx paperclipai run。

卸载会留下什么

paperclipai service uninstall
paperclipai uninstall

paperclipai uninstall 移除的是托管 shim、manifest 和 CLI 负载。它刻意保留 ~/.paperclip/instances/，包括配置、数据库、上传文件、日志、密钥、备份和工作区。只有当你确实打算把这个 Paperclip 实例删掉时，才单独备份并删除那部分数据。这个设计和前面”代码与数据分离”的布局是一致的：卸载动的是代码，不动数据。

跑起来之后的下一步

Quickstart 给的后续路线是六步：在 Web UI 里建第一家公司；定义公司目标；创建一个 CEO agent 并配置它的适配器；用更多 agent 把组织架构搭出来；设置预算并分派初始任务；然后开跑，agent 开始心跳，公司就运转起来。第一步的完整做法见建第一家公司的完整步骤。

什么时候这套装法不适用，以及文档没说的

几点需要说清楚的边界：

平台：推荐安装脚本的适用范围，文档写的是 macOS、Linux 或 WSL2。原生 Windows（非 WSL2）路径官方文档在这两篇里没有给，不要照搬。
容器与 WSL1：不会拿到后台服务，只会得到前台 paperclipai run 的指引。要在容器里长期跑，得靠容器自身的进程管理，具体走 Docker 部署那条线。
多实例、多写入者：文档只给了”一个实例一个 server 进程”这条约束和 --force 这个逃生口，没有描述多实例共享数据时会发生什么。别拿 --force 当常规手段。
版本号：本文出现的 2026.720.0 全部来自官方文档示例，不代表当前最新版；--version 和 --ref 该填什么，以你安装时的实际发布为准。
没验证过的部分：这篇完全基于官方 Quickstart 和 INSTALLING 文档整理，没有实际安装运行过，因此不涉及界面长什么样、每一步耗时多久、某个报错的具体文案。遇到具体报错，先跑 doctor，再对照上面那份检查项清单定位是 PATH、Node 版本、shim 还是服务状态的问题。

如果只是想试一眼，npx paperclipai onboard --yes 足够；只要这套东西会在你机器上待超过一周，直接走托管安装，把原子更新和回滚这两个能力拿到手，比事后补迁移省事得多。

延伸阅读

从头读起：Paperclip 是什么：一个自己不跑 Agent 的控制平面，怎么管住一整家 AI 公司
本专题共 40 篇，完整分组目录见专题页
Paperclip 三种部署模式怎么选：local_trusted 与 authenticated 的私有、公网差别
Paperclip 用 Docker 部署：四条路径、两个必生成的密钥和数据落在哪

本文依据 Paperclip 官方仓库（github.com/paperclipai/paperclip，MIT 协议）的 docs/ 用户文档与 doc/ 下的规范、运维与连接器手册整理，核对日 2026-08-17。 我们没有部署或运行过 Paperclip，因此不涉及界面外观与操作手感；部分规范文档描述的是目标架构而非当前实现，文中已就地标注，不构成对实际行为的保证。请以仓库最新内容为准。