Paperclip 三种部署模式怎么选：local_trusted 与 authenticated 的私有、公网差别

2026-08-17

装 Paperclip 的时候，onboard 会问你一串关于服务器的问题。第一次跑的人通常直接一路回车，之后想让同事也能访问，就开始纠结：到底选哪个模式？改了模式还要不要重新登录？之前本地建的公司会不会丢？

官方把这块单独写了一份规范文档（doc/DEPLOYMENT-MODES.md，文档头部标注状态为「Canonical deployment and auth mode model」，日期 2026-02-23），加上 docs/deploy/ 下的两篇面向使用者的说明。三份文档口径基本一致，但侧重点不同：规范文档讲的是模型本身和安全策略，使用文档讲的是选哪个、命令怎么敲。

这篇把三份文档合起来读一遍，重点解决一个容易混淆的地方——Paperclip 的「认证模式」和「监听地址」是两件事，不要当成一件事来选。

先拆开：auth 模型和 reachability 模型

文档里写得很直白：Paperclip 现在把 bind 当作独立于 auth 的关注点。

auth 模型：local_trusted 还是 authenticated，认证模式下再分 private / public 两种暴露策略；
reachability 模型：server.bind 取 loopback | lan | tailnet | custom。

也就是说运行模式只有两个，不是三个。authenticated 带两个暴露策略，加起来才是使用文档里说的「三种部署配置」。这样拆的目的，官方的原话意思是：保留一套统一的认证栈，同时把「私有网络的低摩擦默认值」和「面向公网的加固要求」分开。

三种组合的官方对照

规范文档给的是这张表：

运行模式	暴露策略	人工认证	主要用途
`local_trusted`	不适用	无需登录	单人本机工作流
`authenticated`	`private`	需要登录	私有网络访问（例如 Tailscale / VPN / LAN）
`authenticated`	`public`	需要登录	面向互联网 / 云端部署

使用文档 docs/deploy/overview.md 的选型建议更口语化：只是试用就用默认的 local_trusted；要在私有网络里和团队共享就用 authenticated + private；要往云上部署就用 authenticated + public。

bind 的四个取值

bind	含义	典型用途
`loopback`	只监听 localhost	默认的本地用法，以及反向代理部署
`lan`	监听所有网卡（`0.0.0.0`）	LAN / VPN / 私有网络访问
`tailnet`	监听探测到的 Tailscale IP	只允许 Tailscale 访问
`custom`	监听指定的主机 / IP	需要绑定特定网卡的进阶场景

这里有个细节值得留意：docs/deploy/overview.md 在概括 authenticated + private 时写的是「绑定到所有网卡以支持网络访问」，而规范文档和 docs/deploy/deployment-modes.md 都写的是私有模式下 bind 可以在 loopback、lan、tailnet、custom 之间选。概览页那句是简化说法，真要配的时候以能选四个值的口径为准。

local_trusted：默认模式让掉了什么

规范文档给它的安全策略只有三条：仅回环绑定、没有人工登录流程、为最快的本地启动做优化。使用文档补了一条：board 身份是自动创建的本地 board 用户。

换句话说，这个模式的前提是「这台机器上能访问 localhost 的人就是你」。它不是关掉了认证，而是压根没有人工登录环节。所以只要机器上有别的进程或别的用户能打到 localhost，这个前提就不成立了。

authenticated + private：限流默认是关的

私有模式的策略里，有一条容易被忽略：

Better Auth 的请求限流在私有模式下默认关闭，目的是避免本地 / 局域网的反复修复调试把操作者自己锁在门外；要打开就设 PAPERCLIP_AUTH_RATE_LIMIT_ENABLED=true。

这条是有意为之的取舍，不是疏漏。但它意味着：如果你把「私有网络」理解得比较宽松——比如办公室网段里什么设备都能连——那默认配置下登录接口是没有速率限制的。真要放在这种网络里，把这个变量显式打开更稳妥。

私有模式还有两个配置面：URL 走 auto base URL 模式（摩擦更低），以及必须配置 private-host 信任策略。如果用的是自定义的 Tailscale 主机名，使用文档给了单独的命令：

npx paperclipai allowed-hostname my-machine

authenticated + public：三处默认值反过来了

公网模式的策略和私有模式几乎处处相反：

必须显式给出公网 URL，不能靠自动推断；
doctor 会执行更严格的部署检查，检查不过会直接失败；
Better Auth 限流默认开启，只有当外层已经有明确的入口限流器覆盖这个部署时，才设 PAPERCLIP_AUTH_RATE_LIMIT_ENABLED=false；
推荐的 bind 是 loopback 挂在反向代理后面，直接用 lan / custom 属于进阶用法；
本地 stdio 的 MCP 运行时槽位默认 fail closed，只有在配置了受信任的 worker / runtime 主机来监管这些进程时，才去设 PAPERCLIP_TRUSTED_MCP_RUNTIME_HOST；文档明确写了远程 HTTP MCP 才是公网托管场景下更推荐的路径。

最后这条对选型影响很大：如果你的 Agent 依赖一堆本地 stdio 启动的 MCP server，直接搬到公网模式会发现它们默认起不来。这不是 bug，是策略。

onboard 是先问可达性、再定模式

规范文档里的「Onboarding UX 契约」说明了交互顺序，默认的 onboard 保持交互式、不带标志位：

pnpm paperclipai onboard

行为约定是这样的：

quickstart 加 --yes 时，默认 server.bind=loopback，因而落到 local_trusted/private；
进阶的服务器设置先问可达性，再由可达性推出模式：Trusted local → bind=loopback + local_trusted/private；Private network → bind=lan + authenticated/private；Tailnet → bind=tailnet + authenticated/private；Custom → 手动输入模式 / 暴露策略 / 主机；
只有 Custom 这条路径才需要手填主机地址；
只有 authenticated + public 才要求显式的公网 URL。

configure --section server 遵循同样的交互行为。文档给出的几个非交互示例是：

pnpm paperclipai onboard --yes
npx paperclipai onboard --yes --bind lan
npx paperclipai run --bind tailnet

改模式除了重跑 configure，使用文档还给了环境变量的运行时覆盖写法：

PAPERCLIP_DEPLOYMENT_MODE=authenticated PAPERCLIP_BIND=lan pnpm paperclipai run

安装与 onboard 的完整流程见 Paperclip 快速安装，这里出现的几个 PAPERCLIP_* 变量的完整清单见环境变量怎么读。

从 local_trusted 迁到 authenticated：别把自己锁在外面

这是最实际的一个迁移问题。你本地跑了很久，公司、任务、Agent 都建好了，现在要改成需要登录——原来那个自动创建的本地 board 身份怎么办？

文档给的机制是 board claim：在 authenticated 模式下，如果实例里唯一的管理员还是 local-board，Paperclip 会在启动时发出一条警告，并给出一次性的高熵 claim URL，格式是 /board-claim/<token>?code=<code>。已登录的人访问这个 URL 之后：

把当前登录用户提升为 instance_admin；
把 local-board 的管理员角色降级；
确保这个用户在已有的各家公司里都有生效的 owner 成员身份。

文档写明这套设计就是为了防止用户从长期的本地信任用法迁到认证模式时被锁在外面。

顺带说一句为什么非要有「真实用户」这件事：规范文档的「Board/User 集成契约」要求 board 身份必须对应数据库里真实的用户主体，需要 authUsers 里有真实用户行、instance_user_roles 里有 board 管理员权限条目、以及 company_memberships 的集成，因为用户指派路径会校验 assigneeUserId 的成员身份是否有效。

全新认证安装：第一个管理员从哪来

全新的 authenticated 安装会处于 bootstrap_pending 状态，直到第一个 instance_admin 出现。产生方式分两种：

authenticated/private 支持浏览器优先的设置路径：从私有网络或设备 UI 打开 Paperclip 的 URL → 登录或注册 Paperclip 账号 → 在设置页选择 Claim this instance。这个端点只对 authenticated/private 下真实的浏览器会话主体开放，未认证请求、agent key、board API key、本地隐式 board 主体都会被拒绝。

CLI 兜底在所有认证态的设置状态下都可用：

pnpm paperclipai auth bootstrap-ceo

它会打印一次性的首管理员邀请 URL。浏览器 claim 和 bootstrap 邀请共用同一个首管理员事务，谁先成功，后来者就会拿到冲突。

authenticated/public 下浏览器首管理员 claim 是被有意禁用的，公网部署必须走高熵的 bootstrap 邀请路径，除非将来有明确改变该策略的公网托管设置方案。

这篇没覆盖到的部分

先说文档本身的边界。规范文档第 9 节标题就是「当前代码现状（截至 2026-02-23）」，写明运行时取值是 local_trusted | authenticated，认证模式用 Better Auth 会话与 bootstrap 邀请流程。它同时说明了命名与兼容策略：规范命名就是 local_trusted / authenticated 加 private / public，被废弃的命名变体不提供长期兼容别名层。所以如果你在老的笔记或第三方文章里看到别的模式名，直接以这套命名为准。

再说选型上真正要注意的：

这三份文档只讲模式与 bind，具体到反向代理怎么配、证书怎么签、云上跑哪种编排，都在别的文档里。私有网络访问和 AWS ECS 的具体做法见 Tailscale 私有访问与 ECS 部署。
文档没有给任何性能数字。local_trusted 说的是「为最快的本地启动做优化」，但快多少、和别的模式差多少，官方文档未说明。
doctor 在公网模式下具体会多跑哪些检查项，这几份文档只说「更严格」，没有逐条列出。
一个反直觉的点是：quickstart --yes 落到的是 local_trusted/private 这个组合，private 在这里出现并不代表启用了认证。判断有没有登录环节，只看运行模式那一维。

如果你还不确定 Paperclip 本身解决的是什么问题、这些「公司」「board」的概念从哪来，可以先看 Paperclip 是什么，再回头选模式会顺一些。

延伸阅读

从头读起：Paperclip 是什么：一个自己不跑 Agent 的控制平面，怎么管住一整家 AI 公司
本专题共 40 篇，完整分组目录见专题页
Paperclip 用 Docker 部署：四条路径、两个必生成的密钥和数据落在哪
Paperclip 数据库怎么配：内嵌 Postgres、本机 Docker 与外接托管库的取舍

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