Paperclip 环境变量怎么读：分清必填、部署模式相关和可选调优三组
Paperclip 的环境变量参考文档是一张平铺的清单：Server Configuration、Secrets、Agent Runtime、LLM Provider Keys 四张表，二十多个变量，每个一行描述。照着从上往下配，很容易配出一个”能启动但行为不对”的实例——比如登录页出不来、Agent 拿到的 API 地址是内网回环地址、或者密钥明明填了却被拒。
问题出在这张清单没有告诉你变量之间的依赖关系。有的变量只有在另一个变量取特定值时才生效，有的压根不是给你写的，还有一批是纯调优、不动也能跑。把它们按「必填 / 部署模式相关 / 可选调优」重新分成三组，再对着每组去想”漏了会怎样、写错会怎样”，这张表才有用。
下面按这个分法过一遍。所有变量名和默认值都以官方环境变量参考页为准，涉及部署模式、数据库、密钥的补充信息来自对应的部署文档。
先剔掉不该你配的那一组：Agent Runtime 注入变量
参考页里有一张表叫 “Agent Runtime (Injected into agent processes)“，开头一句话就写明了：这些是服务器在调起 Agent 时自动设置的。它包含 PAPERCLIP_AGENT_ID、PAPERCLIP_COMPANY_ID、PAPERCLIP_API_KEY、PAPERCLIP_RUN_ID、PAPERCLIP_TASK_ID、PAPERCLIP_WAKE_REASON、PAPERCLIP_WAKE_COMMENT_ID、PAPERCLIP_APPROVAL_ID、PAPERCLIP_APPROVAL_STATUS、PAPERCLIP_LINKED_ISSUE_IDS。
这一组是给 Agent 进程读的，不是给运维填的。其中 PAPERCLIP_API_KEY 文档描述为”短时效的 JWT”，意味着它每次运行都会重新签发，你手写一个进去没有意义。如果你在写自定义适配器或进程型 Agent，这张表是你的输入契约——你要读它；如果你在部署服务器，这张表整个跳过。
有一个坑值得单独点出来：密钥文档提到，项目级 env 会先于 Agent 级 env 生效，然后 Paperclip 才注入自己的 PAPERCLIP_* 运行时变量（原文是 the project value wins before Paperclip injects its own PAPERCLIP_* runtime variables）。也就是说，如果你在项目或 Agent 的环境变量里手工塞了一个同名的 PAPERCLIP_*，最终生效的是 Paperclip 注入的那个。这类”我明明设了但没生效”的排查，往往就卡在这里。
第一组：必填——文档里真正标了 required 的只有一个
翻遍整张 Server Configuration 表，唯一标注为 Required 的是 PAPERCLIP_BIND_HOST，而且它是条件必填：当 PAPERCLIP_BIND=custom 时必须给。其余变量都带默认值，理论上一个都不设也能起来。
但”能起来”和”能用”是两回事。真正意义上的必填要看你的用途：
| 变量 | 什么时候必须给 | 不给的症状 |
|---|---|---|
PAPERCLIP_BIND_HOST | PAPERCLIP_BIND=custom 时 | 文档标为 Required，即选了 custom 却没有可绑定的主机名 |
ANTHROPIC_API_KEY | 要跑 Claude Code 适配器 | Docker 文档写明：没有 key 应用照常运行，但适配器的环境检查会暴露缺失的前置条件 |
OPENAI_API_KEY | 要跑 Codex 适配器 | 同上 |
DATABASE_URL | 用外接 Postgres 时 | 不设就走内嵌 Postgres，不会报错，但你以为连了 RDS 其实连的是本地内嵌库 |
最后一行是最容易翻车的：数据库文档明确写了 DATABASE_URL 未设置就自动启动内嵌 PostgreSQL 实例，并在 ~/.paperclip/instances/default/db/ 建库、自动跑迁移。它不会因为你忘配连接串而报错——它会安安静静地建一套新库开始服务。等你发现数据不在 RDS 里，可能已经积了一堆运行记录。这个”三态”关系（不设 = 内嵌、localhost = 本地 Docker、hosted = 托管）在内嵌 Postgres 与外接数据库怎么选里有完整对照。
Docker 场景下还要补一句 PAPERCLIP_HOME。手动 docker run 的示例里它被设成 /paperclip，并配一个 bind mount 挂到宿主机目录。内嵌 Postgres 数据、上传资产、本地密钥、Agent 工作区全在这个目录下——设了 PAPERCLIP_HOME 却没挂卷，容器一删数据全没，包括那把解密密钥。
第二组：部署模式相关——它们是一套，不是一个个独立开关
这一组是最容易配出”半成品状态”的地方，因为几个变量互相咬合：
PAPERCLIP_DEPLOYMENT_MODE=authenticated PAPERCLIP_BIND=lan pnpm paperclipai run
这条命令来自部署模式文档，它演示的是运行时覆盖。要理解它，得先分清两个正交的维度：
PAPERCLIP_DEPLOYMENT_MODE（默认local_trusted）决定要不要登录。local_trusted不需要登录，自动创建一个本地 board 用户；authenticated走 Better Auth 登录。PAPERCLIP_BIND（默认loopback）决定谁能连上，可选loopback/lan/tailnet/custom。文档明确说了可达性是和部署模式分开配置的。PAPERCLIP_DEPLOYMENT_EXPOSURE（默认private）只在部署模式为authenticated时才有意义，取private或public。
把这三个拆开看，几种典型配错的症状就清楚了：
只改了 BIND 没改 MODE。 你把 PAPERCLIP_BIND 设成 lan 想让同事访问，但 PAPERCLIP_DEPLOYMENT_MODE 还是默认的 local_trusted。结果是：服务确实在局域网上可达了，但这个模式本身不要求登录。文档对 local_trusted 的定位写得很直白——“单操作者本地使用”，host binding 是 loopback only。把一个不需要登录的实例挂到局域网上，等于把整个 AI 公司的控制台裸奔在网段里。
从 local_trusted 切到 authenticated 后没人是管理员。 部署模式文档描述了 Board Claim 流程：迁移到 authenticated 时，Paperclip 会在启动时输出一个一次性 claim URL，形如 /board-claim/<token>?code=<code>。已登录用户访问这个链接才会被提升为实例管理员，同时把自动创建的本地 board 管理员降级。如果你切了模式却没留意启动日志、把这个一次性链接刷过去了，就会出现”能登录但什么都改不了”。这类模式选择的完整取舍见三种部署模式怎么选。
反向代理后面 URL 全错。 PAPERCLIP_API_URL 默认是自动推导的（auto-derived），从监听主机和端口拼出来。参考页对它有一段专门说明：当这个值由外部设置时（例如 Kubernetes ConfigMap、负载均衡器或反向代理），服务器会保留你给的值，而不是从本地 bind 地址推导。这个变量的影响面比看起来大——Agent Runtime 那张表里同名的 PAPERCLIP_API_URL 描述为”继承服务器级的值”。也就是说你不设它，Agent 进程拿到的回调地址就是本地绑定地址。在 ALB 或 Nginx 后面部署时，这是”面板打得开、Agent 却回调不上来”的常见原因。相关的私有网络与云上部署路径见Tailscale 私有访问与 AWS ECS 部署。
HOST 和 PAPERCLIP_BIND 撞车。 参考页把 HOST（默认 127.0.0.1）标注为 legacy host override，并建议新部署优先用 PAPERCLIP_BIND。两个同时设置会怎样，文档没有说明——所以别同时设，新部署统一用 PAPERCLIP_BIND。Docker 文档里的 -e HOST=0.0.0.0 属于容器内必须监听所有接口的老写法，照抄时心里要有数。
密钥的 PAPERCLIP_SECRETS_STRICT_MODE（默认 false）也属于这一组，因为它跟部署模式联动：密钥文档写明，authenticated 部署默认开启严格模式，除非用配置或 PAPERCLIP_SECRETS_STRICT_MODE=false 显式覆盖。严格模式下，匹配 *_API_KEY、*_TOKEN、*_SECRET 的敏感 env key 必须用 secret 引用，不能写内联明文值。所以”本地跑得好好的，切到 authenticated 就报 key 不合法”，多半不是密钥错了，是模式变了导致校验变严。这条链路的细节在密钥管理与 AWS provider里。
第三组：可选调优——不动也能跑，但动之前要知道副作用
这一组的共同点是都有可用默认值，出问题时往往表现为性能或路径异常，而不是启动失败。
| 变量 | 默认 | 调它的场景与副作用 |
|---|---|---|
PORT | 3100 | 端口冲突时改。ECS 指南里目标组、安全组、健康检查全按 3100 写死，改了要一起改 |
PAPERCLIP_HOME | ~/.paperclip | 所有数据的基准目录。改路径等于换数据位置 |
PAPERCLIP_INSTANCE_ID | default | 一台机器跑多实例时区分。它决定 ~/.paperclip/instances/<id>/ 下的库和密钥路径，改了等于切到另一套数据 |
PAPERCLIP_SECRETS_MASTER_KEY | 来自文件 | 32 字节密钥，支持 base64、hex 或原始字符串 |
PAPERCLIP_SECRETS_MASTER_KEY_FILE | ~/.paperclip/.../secrets/master.key | 自定义密钥文件路径 |
数据库文档另外给了一组客户端调优变量，参考页没有收录：DATABASE_PREPARED_STATEMENTS、DATABASE_POOL_MAX、DATABASE_IDLE_TIMEOUT_SECONDS、DATABASE_CONNECT_TIMEOUT_SECONDS，未设置时用驱动默认值。其中第一个不是”调优”而是”必改”：文档写明使用连接池的 transaction 模式时，要通过环境变量关掉预处理语句，无需改源码。
DATABASE_PREPARED_STATEMENTS=false
托管数据库还有一条容易漏的路由规则：迁移用直连（5432 端口），应用用池化连接（6543 端口）。两个端口混用时，迁移和运行时会表现出完全不同的故障形态。
关于密钥主密钥，还有一条运维层面的硬约束值得抄进备份手册：密钥文档说，数据库备份没有密钥文件无法解密本地密钥，而只有密钥备份、没有数据库元数据，也不足以还原命名的密钥版本——两者必须一起备份。这不是变量配置问题，但它是 PAPERCLIP_SECRETS_MASTER_KEY_FILE 指向的那个文件真正的分量。
两份文档对不上的地方
Docker 文档里出现的 PAPERCLIP_PORT 和 PAPERCLIP_DATA_DIR，在环境变量参考页里找不到。它们出现在 compose 快速启动的命令行前缀里，用于覆盖宿主机端口（默认 3100）和数据目录（默认 ./data/docker-paperclip）。文档还专门提醒：PAPERCLIP_DATA_DIR 是相对 compose 文件所在的 docker/ 目录解析的，所以 ../data/pc 实际落在项目根的 data/pc。
同样地，Docker 文档提到的 GEMINI_API_KEY / GOOGLE_API_KEY（Gemini CLI）和 GEMINI_SANDBOX=false（镜像内置设定，避免 Gemini CLI 在容器里再起一层沙箱），以及 AWS ECS 指南里的 PAPERCLIP_AUTH_DISABLE_SIGN_UP=true（首个用户注册拿到管理员后关闭公开注册），参考页里也都没有。
结论很实际：别把环境变量参考页当成唯一真相源。它覆盖的是服务器配置主干，容器编排层、数据库客户端调优、云上加固的变量散在各自的部署文档里。排查一个变量没生效之前，先确认它到底属于哪一层。
这份分组解决不了什么
几件事需要说在前面。
一是优先级。变量之间的覆盖顺序，官方文档只写明了一处（项目 env 优先于 Agent env，然后 Paperclip 注入 PAPERCLIP_*）。环境变量与 paperclipai configure 写入的配置文件之间谁赢，文档没有系统说明——只在部署模式那页把 env 形式称为”运行时覆盖（runtime override）“。稳妥做法是长期配置走 configure --section server，环境变量只用于临时验证，不要两边各写一半。
二是校验时机。哪些变量在启动时校验、哪些要等到实际调用才暴露，文档没有统一说明。可以确定的是适配器 key 属于后者——Docker 文档写的是应用照常运行、由适配器环境检查暴露缺失前置条件。所以”服务起来了”不能作为”变量都配对了”的证据，paperclipai doctor 才是文档反复推荐的校验入口。
三是取值合法性。比如 PAPERCLIP_SECRETS_MASTER_KEY 写明支持 base64、hex 或原始字符串三种形式，但三种形式如何区分、写错格式报什么错，参考页没有展开。这类问题只能以实际运行时的报错为准。
把这三组分清之后，再回头看那张平铺的清单，大部分排查其实可以在三十秒内定位到组：起不来先看部署模式那一组，数据不对先看 DATABASE_URL 和 PAPERCLIP_INSTANCE_ID，Agent 跑不动先看适配器 key 和 PAPERCLIP_API_URL。
延伸阅读
- 从头读起：Paperclip 是什么：一个自己不跑 Agent 的控制平面，怎么管住一整家 AI 公司
- 本专题共 40 篇，完整分组目录见专题页
- Paperclip 密钥管理：主密钥、严格模式与 AWS provider 边界
- Paperclip 只能在 localhost 打开？Tailscale 私有访问与 AWS ECS 公网部署两条路
本文依据 Paperclip 官方仓库（github.com/paperclipai/paperclip，MIT 协议）的 docs/ 用户文档
与 doc/ 下的规范、运维与连接器手册整理，核对日 2026-08-17。
我们没有部署或运行过 Paperclip，因此不涉及界面外观与操作手感；
部分规范文档描述的是目标架构而非当前实现，文中已就地标注，不构成对实际行为的保证。
请以仓库最新内容为准。