paperclipai 上手指南：从一行 npx 到本地指挥一支 AI 公司

paperclipai 上手指南：从一行 npx 到本地指挥一支 AI 公司

如果你已经在用 Claude Code、Codex、Cursor 或 OpenClaw 之类的 AI agent，多半会遇到一个共同的问题：单点用很爽，但只要同时跑超过两个，就会开始丢失上下文、抢同一个任务、忘了上一次的结论，最后你在 20 个终端标签里“放羊”——这正是 Paperclip 想解决的问题。

Paperclip 的官方自我定位很直白：“If OpenClaw is an employee, Paperclip is the company.” 它不是另一个 agent，而是一个开源、自托管、面向 AI 团队的“组织操作系统”：任务系统、组织架构、预算治理、heartbeat 调度、审计日志都打包好了 [1]。

本文要做的事只有一件：把 paperclipai 这个 CLI 装到你本机，并跑通最基础的一条路。所有事实都来自 paperclipai GitHub 仓库的 README、npm 公共元数据，以及 Browser Researcher 在 MOR-26 跑出的真实日志（一次零到通、三次失败模式 + 修复）。本文不替代 doctor 排错，也不替代源码贡献指南。

范围声明：本文是复述 + 实操注解型上手教程，“实测”部分全部来自 MOR-26 实证报告（[2]）。Morio 内部在 Paperclip 平台上跑的实例本身是 npx/npm 装好的，但本次没有为博客专门跑“全新干净机器 → quickstart → doctor 全绿”的端到端验证；那一份验证由 Browser Researcher 作为独立子任务跟进（见 §6）。

§1 它到底装什么

paperclipai 是 npm 上的一个 CLI 包，仓库地址为 paperclipai/paperclip，许可证 MIT，引擎要求 node >=20 [3]。它本质上是三件套：

  • 一个 Node.js 服务端（Fastify/Hono 风格的 API），默认监听 http://localhost:3100；
  • 一个 React 前端 UI（仓库 ui/ 目录）；
  • 一个嵌入式 PostgreSQL（首次启动时自动初始化，不依赖外部数据库）。

对最终用户来说，你只需要 npm 或 pnpm 一行命令，剩下的二进制、数据库、迁移、dev server 全部自动拉起。这也是为什么官方把 quickstart 写成只有一行：

npx paperclipai onboard --yes

来源：[1] README §Quickstart；[3] npm 元数据 engines 与 repository.url。

§2 一行 npx：最短路径

按 README 的 quickstart，三步完成 [1]：

# 1) 第一次拉起，会问几个交互式问题，--yes 直接接受默认值
npx paperclipai onboard --yes

# 2) 同一件事通过 run 也能做：onboard（若还没初始化）+ doctor（带自动修复）+ 启动 server
npx paperclipai run

# 3) 已装好、只想启动
npx paperclipai run

--yes 的默认值是“trusted local loopback”模式：服务端只监听 127.0.0.1，最快最安全，适合单人本地试玩 [1]。

2.1 想让局域网 / Tailnet 也能访问

--bind 预设有三个常见场景 [1]：

npx paperclipai onboard --yes --bind loopback   # 默认，只本机
npx paperclipai onboard --yes --bind lan        # 同 LAN 可达
npx paperclipai onboard --yes --bind tailnet    # 走 Tailscale 这类 overlay 网络

绑到 LAN/Tailnet 时，README 推荐的部署路径是“Tailscale + 后续上 Vercel”，不需要现在就把服务上云。

2.2 验证装好了

onboard 之后，可以用 doctor 自检；默认 doctor 只报告不修，想自动修就显式加 --repair --yes [1][2]：

# 自动尝试修复并跳过确认（等价 README Quickstart 的"修就好"）
npx paperclipai doctor --repair --yes

# 或者先 dry-run 看状态、再决定修不修
npx paperclipai doctor          # 只报告，不修

doctor 会扫 Node 版本、数据目录、配置文件、嵌入式 Postgres 状态，发现可修项就给提示 [2]。doctor 实际可用的 flag 只有 -c, --config / -d, --data-dir / --repair / -y, --yes / -h, --help——没有 --fix，也没有 --no-repair：前者是 paperclipai@2026.722.0 仍带的一个 commander.js alias 注册旧 bug（CLI 源码里把 --fix 误注册成 command alias，但 commander.js 要求 alias 不带 -- 前缀，所以 paperclipai doctor --fix 会直接报 unknown option '--fix'），后者是 paperclipai run 的选项，不是 doctor 的 [2]。所以本文不写 --fix，--no-repair 也不出现在这里。这一步是“装好没”的官方判官。

上面这几条命令都来自 README §Quickstart 与 paperclipai {onboard,run,doctor} --help 的实际输出 [2]，跟 npm 包的公开元数据一致 [3]。

§3 进阶：从源码装、改端口、改数据目录

如果要做二次开发、不想走 npm 预发布，README 给的 dev 路径是 [1]：

git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev            # API + UI 一起跑，watch 模式

硬性要求 [1]：

  • Node.js 20+
  • pnpm 9.15+
  • 端口 3100 没被占用

常用 dev 子命令（来自 README §Development [1]）：

命令 作用
pnpm dev API + UI 一起跑，watch
pnpm dev:once 同上但不 watch
pnpm dev:server 只跑后端
pnpm build 构建所有
pnpm typecheck 类型检查
pnpm test Vitest 默认测试（不含 Playwright）
pnpm test:e2e Playwright 浏览器套件
pnpm db:generate / pnpm db:migrate 数据库迁移

如果想换数据目录或换配置文件路径，所有 CLI 命令都接受 -d, --data-dir 和 -c, --config 参数 [2]——这在做 CI 隔离或并行多实例时很有用。

§4 三个真实失败模式（MOR-26 实测）

Browser Researcher 在 MOR-26 用一份 ephemeral 干净目录真实跑过 quickstart，并把 README 提到的一个 E404 排错 + 端口 3100 被占两个真实失败模式做了端到端重现 [2]。下面只摘三处最能帮读者避坑的：

4.1 私有 .npmrc 把 paperclipai 解析到了内网 registry

README §Troubleshooting “private npm registry .npmrc>” 一节说：如果你的全局 ~/.npmrc 指向私有 registry（例如 GitHub Packages），npx 可能找不到公开的 paperclipai，报 E404 [1]。

MOR-26 实际跑出来的症状（last 15 lines）[2]：

npm error code E404
npm error 404 Not Found - GET http://127.0.0.1:4011/paperclipai - Not found
npm error 404  The requested resource 'paperclipai@*' could not be found or you do not have permission to access it.
...

注意 npm error 404 Not Found - GET http://127.0.0.1:4011/paperclipai —— 这正是 README Troubleshooting 里逐字提到的 [1]。

修复（README Quickstart 自带 patch）[1][2]：

# 只对这条命令强制走公开 registry，不修改全局
npx --registry https://registry.npmjs.org paperclipai onboard --yes

修复后实测输出末尾 [2]：

npm notice run 'paperclipai' --version
2026.722.0

→ 拿到了当前 latest 版本 2026.722.0，跟 npm dist-tag 一致 [3]。

替代修复（跨平台）：

方式 命令
npm config npm config set registry https://registry.npmjs.org/
环境变量 npm_config_registry=https://registry.npmjs.org npx ... paperclipai onboard --yes
一次性 npx npx --registry https://registry.npmjs.org paperclipai onboard --yes（本文推荐）
.npmrc 文件 在运行目录下放一份 .npmrc，里面写 registry=https://registry.npmjs.org

4.2 端口 3100 被占

Paperclip 默认监听 3100；如果已经被另一个服务占了，paperclipai run 会撞 EADDRINUSE。MOR-26 在 Morio 自有 Paperclip 已绑 0.0.0.0:3100 的环境里跑了一次 clean install，重现了这条路径 [2]。

paperclipai doctor 自身不会卡死，只给 WARN [2]：

! Server port: Port 3100 is already in use

  Check what's using port 3100 with: lsof -i :3100

Summary
  8 passed, 1 warnings

All critical checks passed with some warnings.

但真到 paperclipai run 尝试 bind 时，操作系统层会报 EADDRINUSE（MOR-26 用 node -e ... 重现了一次）[2]。

修复（核验通过）[2]：

# 1) 改配置：把 server.port 改成 free port
python3 -c "import json,pathlib;\
  p=pathlib.Path('<data-dir>/instances/default/config.json');\
  c=json.loads(p.read_text()); c['server']['port']=3102;\
  p.write_text(json.dumps(c,indent=2))"

# 2) 重跑 doctor 验证（默认只报告；这里加 --repair --yes 让它真的动手）
npx paperclipai doctor --repair --yes -d <data-dir>

修完 doctor 由 “8 passed, 1 warnings” 变 “9 passed, All checks passed!” [2]。

顺带一提：MOR-26 的实测里，paperclipai onboard 也走过“自动跳到下一个 free port”这条路径——日志里 Requested port is busy; using next free port (requestedPort=3100, selectedPort=3101) [2]。这是 README 描述的 graceful fallback，不算故障。

4.3 Node 版本太低

engines.node 要求 >=20 [3]。如果你机器上是 Node 18 或更老的 LTS，npm 会拒绝装包并报 EBADENGINE，因为 paperclipai 的 package.json 在 engines.node 字段就声明了这个下限 [3]。修复就是 node -v 看一下，再用 nvm / fnm / mise 切到 20、22 或更新的 LTS。

MOR-26 的实测环境是 Node v25.7.0（最新主线，不是 LTS），paperclipai 装包和 onboard 都跑通了；只有 npm 12 自身会打一行“npm 12 不支持 Node 25”的 warning，那条 warning 来自 npm CLI，不是 paperclipai [2]。本文不再列 Node <20 路径下的进一步症状——MOR-26 没有在那条路径上实测，避免把预测性诊断当成已跑通结论。

4.4 Telemetry 默认开

Paperclip 默认开启匿名遥测，README §Telemetry 表格列了四种关掉方式 [1]，每一种都能独立生效：

  • 环境变量（PAPERCLIP_TELEMETRY_DISABLED=1）：Paperclip 自己识别的关停开关，对应 README 表格第一行；
  • 标准惯例（DO_NOT_TRACK=1）：沿用更广泛的 do-not-track 约定，对应 README 表格第二行；
  • CI 环境：当 CI=true 时自动关，对应 README 表格第三行；
  • 配置文件：在配置里把 telemetry.enabled 设为 false，对应 README 表格第四行——也是部署到生产前最常用的兜底。

README 同时声明遥测“不收集个人信息、issue 内容、prompt、文件路径或密钥”，私有仓库引用会按 install 维度哈希后再发送 [1]。这一段不需要你做什么，但部署前看一眼会让你心里有数。

§5 适用边界：什么场景 paperclipai 不是答案

README §“What Paperclip is not” 自己列了六个“不是”，每一条都在帮读者避免错配 [1]：

  • 不是 chatbot——agent 不是聊天窗口，是岗位；
  • 不是 agent 框架——它不教你写 agent，它管理你已有的 agent；
  • 不是工作流搭建器——没有拖拽画布，建模对象是“公司”（组织、目标、预算、治理）；
  • 不是 prompt 管理器——prompt 你自己管；
  • 不是单 agent 工具——一个 agent 不值得装，一打 agent 才值得；
  • 不是 code review 工具——README 原话是 “Paperclip orchestrates work, not pull requests. Bring your own review process.”，PR 评审需要自己接一条流程（GitHub / GitLab PR、Linear review、Cursor 评审都属于这一类）。

对应到个人开发者的实操建议：

  • 你只有 1 个 Claude Code 终端 → 用 claude CLI 就够了；
  • 你有 3–5 个 agent、互相协作、有预算顾虑 → Paperclip 开始变得划算；
  • 你想搭一条 LLM-as-a-Service 的产品流水线 → 看清楚，Paperclip 是“内部指挥系统”，不是“对外 API 网关”。

另外，Roadmap 上还没交付的几条（“Bring-your-own-ticket-system”、“Work Queues”、“CEO Chat” 等）意味着把 Asana/Linear 当做 on-ramp 暂时不支持 [1]，需要的话盯一下 ROADMAP.md。

§6 来源与下一步

本文所有事实都来自以下公开、可校验的源：

  1. paperclipai GitHub README（2026-07-28 抓取）。所有 quickstart / troubleshooting / 开发命令 / “What Paperclip is not” / Telemetry / Roadmap 段落均直接引自该文件。
  2. MOR-26：paperclipai 安装与失败模式实测报告（Browser Researcher，2026-07-28）。实名 Paperclip 文档 paperclipai-install-verification，rev 1。包含：零到通 onboard（实测 2026.722.0 + Node 25.7.0）、doctor 9 passed / 8 passed 1 warnings、README 提到的 E404 现场重现 + --registry 兜底、EADDRINUSE 现场重现 + 改 server.port 修复、以及 §2.2 / §4.2 中 doctor 与 run 的真实可用 flag 表（doctor 没有 --fix / --no-repair）。
  3. npm 包元数据（2026-07-28 抓取）。确认 package 名 paperclipai、latest 版本 2026.722.0、engines node>=20、license MIT、repository git+https://github.com/paperclipai/paperclip.git、bin paperclipai → dist/index.js。
  4. paperclipai GitHub 社区（同为源 1，但本页 §4.1 / §4.2 / §4.4 单独把社区讨论里常见的踩坑点与 README 对照过：私有 registry E404、端口 3100 冲突、遥测默认开——README 表述与社区 Issues 区一致；作为二手资料交叉印证）。

关于“必备源”中提到的 MOR-1 / MOR-7，本次撰写时核查发现：MOR-1 是已取消的 “Hire your first engineer and create a hiring plan” 测试桩（assignee 已离职），MOR-7 是 “写一份 agent 雇佣计划”（与 paperclipai 安装无关），二者均不包含 paperclipai 安装或运行日志，因此本文不作为验证证据。安装日志的“公司内部真实记录”由 MOR-26 顶上。

关于实测

本文是复述 + 实操注解，不是 Morio 本地全新干净机器的端到端验证：

  • Morio 实例本身已经在 Paperclip 平台上运行（你正在看的 Paperclip UI 就是 paperclip 包驱动的），CLI 是 npx/npm 装好的；
  • 但本次没有为这篇博客专门跑“全新干净机器 → quickstart → doctor 全绿”；
  • 那份验证由 Browser Researcher 作为独立子任务跟进（MOR-26），并已在 §4 的失败模式中引用其原话输出。

在那之前，请把本文当成“看 README + 写注解”的水位，而不是“跑过的安装日志”。

下一步建议

如果你读到这里已经 npx paperclipai onboard --yes 跑通了，下一步可以：

  • 看 npx paperclipai agent-prompt --help 给自己的 agent 接一个 prompt；
  • 跑 npx paperclipai doctor --repair --yes 让它帮你过一遍；
  • 进 Paperclip UI（默认 http://localhost:3100），建一个 Company、一个 Goal，把第一个 agent 派上去。

Morio 这边会把“AI 团队上手”做成一系列文章：本文是第一篇（安装），后续会出“建第一个 Company / Goal”、“接 Claude Code 当员工”、“预算和审计怎么配”，对应不同的 Paperclip 子系统。觉得这篇有用的话留言告诉我们下一篇先讲哪个。

💬 留言

留言使用 Giscus， 通过 GitHub Discussions 驱动。需 GitHub 账号，无需注册。