Paperclip AI 公司控制平面
本专题共 40 篇，依据
官方仓库
的 docs/ 用户文档与 doc/ 下的规范、运维与连接器手册整理。
请以仓库最新内容为准。
Paperclip 是什么：一个自己不跑 Agent 的控制平面，怎么管住一整家 AI 公司
Paperclip 把自己定位成「自主 AI 公司的控制平面」：一个实例可跑多家公司，每家公司有 AI 员工、组织架构、目标和预算，但它自己不执行 agent，只做编排。本文按官方文档梳理控制平面与执行层的分工、公司/员工/任务/委派/心跳/治理六个核心概念、一次心跳的完整请求链路，以及它明确声明「不是什么」。
装起来：部署模式决定后面所有事
一条 onboard 命令能跑起来，但三种部署模式、内嵌与外接数据库、密钥托管方式的选择会一路影响到能不能对外暴露、能不能多人协作。这一组按「选完之后会遇到什么」排，而不是按命令排。
Paperclip 怎么装：onboard 一条命令背后的四种安装方式与更新回滚
官方文档给了 npx onboard、install.sh 托管安装、全局 npm、源码 checkout 四条路，它们在更新、回滚、后台服务上待遇完全不同。这篇按官方文档梳理每条路的命令、托管安装的目录布局、PATH 与服务安装的取舍，以及 update/rollback、doctor、uninstall 分别动了哪些东西。
Paperclip 三种部署模式怎么选：local_trusted 与 authenticated 的私有、公网差别
按官方部署文档梳理 Paperclip 的两种运行模式与两种暴露策略，讲清 bind 为什么被单独拆成一个概念、四个 bind 取值分别对应什么场景、私有与公网模式在限流和 MCP 运行时上的默认值差异，以及从本地信任模式迁到认证模式时的 board claim 流程和首个管理员怎么产生。
Paperclip 用 Docker 部署：四条路径、两个必生成的密钥和数据落在哪
Paperclip 官方文档里的 Docker 部署其实分成 quickstart compose、手工 build+run、带 PostgreSQL 的全栈 compose 和 Podman Quadlet 四条路。这篇按官方原文把默认端口、数据目录、必须自己生成的两个 secret、UID/GID 权限参数、容器内预装的适配器 CLI 逐条拆开，并指出两份官方文档写法不一致的地方。
Paperclip 数据库怎么配：内嵌 Postgres、本机 Docker 与外接托管库的取舍
Paperclip 用 Drizzle ORM 连 PostgreSQL，官方给了内嵌、本机 Docker、托管三种跑法，切换只认 DATABASE_URL 一个变量。本文按官方部署文档梳理三种模式各自的落盘位置、初始化步骤、迁移命令，以及走事务型连接池时必须显式设为 false 的 DATABASE_PREPARED_STATEMENTS，附一份判定表和文档没说清的地方。
Paperclip 环境变量怎么读：分清必填、部署模式相关和可选调优三组
Paperclip 的环境变量参考页把变量平铺成四张表，但真正决定成败的是分组。这篇按「必填 / 部署模式相关 / 可选调优」重排，讲清每组变量各自控制什么、漏配或配错分别会撞上哪种症状，并指出哪些 PAPERCLIP_ 开头的变量其实是服务端注入给 Agent 的、你根本不该自己设。
Paperclip 密钥管理：主密钥、严格模式与 AWS provider 边界
把 API key 明文写进 agent 配置迟早出事。这篇按 Paperclip 官方文档梳理密钥系统的托管边界（注入之后就不再受保护）、本地主密钥的位置与备份规则、strict mode 的触发条件、env 绑定与按需取值的取舍，以及 AWS provider 的引导信任模型和最小 IAM 策略。
Paperclip 只能在 localhost 打开？Tailscale 私有访问与 AWS ECS 公网部署两条路
把 Paperclip 从「只有本机能开」变成手机、同事、公网都能访问，官方文档给了两条完全不同的路：一条是 --bind tailnet 走 Tailscale 私有网，一条是 ECS Fargate + RDS + EFS + ALB 的完整公网栈。本文按官方文档梳理两条路各自的命令、端口、安全组边界、健康检查口径和成本区间，并说明什么情况下这两条都不该选。
运营一家 AI 公司：组织、任务、审批与预算
Paperclip 把 Agent 当员工管：org chart、任务流转、审批闸门、按月的 token 预算与自动暂停。这一组也包括最高频的两类故障——Agent 建好了不干活、审批卡住没人裁决。
Paperclip 建第一家 AI 公司：官方六步顺序，以及每步跳过会留下什么坑
按 Paperclip 官方 board-operator 指南，把「建公司 → 定目标 → 建 CEO → 搭组织树 → 设预算 → 开心跳」六步的依赖关系讲清楚：每一步文档要求填哪些字段、为什么必须排在这个位置、漏了会在后面哪一环卡住，以及文档没写明、需要你在自己环境里确认的几处留白。
Paperclip 的组织架构与汇报线：一棵严格无环的树，决定了任务怎么往下派
拆开 Paperclip 官方文档里的 org-structure 与 delegation 两篇，讲清 reportsTo 单亲无环的硬规则、chainOfCommand 的三种用途、CEO 从目标到派单的完整生命周期，以及「设了目标却没人干活」时按顺序该查的六项。附跨团队任务不能取消的边界说明。
Paperclip 里的 Agent 怎么管：六种状态、创建六要素与暂停终止接口
把 Paperclip 官方文档里 Agent 生命周期这条线拆开讲：六种状态各自代表什么、建一个 Agent 必须填哪六项、adapter 类型键怎么对号、改配置有哪三块可调、暂停恢复清错误终止分别调哪个接口，以及预算 80%/100% 两道阈值触发什么动作。附状态表与适配器类型对照表。
Paperclip 里一个任务从创建到关闭要走哪几步：状态机、原子 checkout 与审查拦截
按官方文档梳理 Paperclip 的 issue 全流程——七个状态怎么迁移、in_progress 为什么是一把需要原子 checkout 的锁、409 冲突为什么不能重试、执行策略如何把 done 拦成 in_review、评论必留痕的兜底重试，以及整棵任务树停摆时看门狗按什么条件被唤醒。
Paperclip 里 Agent 建好了却不干活？从心跳、看门狗到卡住任务的排查顺序
Agent 配好了任务却没人接、跑了一半停住、整棵任务树静悄悄没人叫醒——这三种症状在 Paperclip 里的成因完全不同。本文按官方文档给出的机制，把定位顺序拆成五层：Agent 还能不能被唤醒、适配器能不能起来、心跳有没有 checkout 到任务、运行活性判成了什么、以及三种同名「看门狗」各自管什么。附 API 与配置项对照表。
Paperclip 审批卡住怎么办：从审批类型、生命周期到用 API 把队列查清楚
公司建好了、Agent 也在跑，任务却一步不动，多半卡在审批门。这篇按官方文档梳理 Paperclip 的两类审批、pending 到 resubmitted 的完整状态机、审批与 request_confirmation 的分工，以及审批通过后 Agent 该怎么接住结果，最后给出查队列和强制解卡的接口清单。
Paperclip 的预算怎么设：给 AI 员工发「token 工资」，80% 报警、100% 自动停
Paperclip 按公司和单个 Agent 两层设月度预算，字段是 budgetMonthlyCents，到 80% 转入只做关键任务、到 100% 直接自动暂停心跳。本文梳理成本事件记了哪五项、预算怎么改、超支后怎么恢复、Agent 自己该在心跳里怎么查余额，以及仪表盘、cost 系列命令和活动日志分别能帮你提前多久发现在烧钱。
Paperclip 成本报表怎么看：适配器怎么上报、字段有哪些、三个查询口径分别答什么
讲清 Paperclip 里一笔 token 花销从产生到能被查出来的完整链路——适配器在心跳结束后解析输出、写成一条成本事件、再由 summary / by-agent / by-project 三个接口分口径聚合。附字段清单、接口对照表，以及官方文档明确没说的那几处空白。
Paperclip 活动日志怎么查：把 Agent 干过的每一次改动追回来
Paperclip 把公司里所有写操作都落进 activity log，append-only 且不可修改。这篇讲清楚哪些事件会被记、一条活动记录有哪些字段、Web 端和 activity 接口各自能按什么过滤，以及官方文档给的四步排查法怎么用；同时点明文档没写清的几处边界，免得你按想当然去查。
Paperclip 仪表盘与状态卡片怎么读：五组指标的口径、数据来源与刷新机制
逐条拆开 Paperclip 官方文档写明的仪表盘指标口径——Agent 按状态计数、任务按状态计数、停滞任务、成本汇总、近期活动，以及一个 GET 接口如何一次取全。再讲实验特性「状态卡片」的 SQL 变更检测、四种刷新策略、官方给出的估算成本表和 Agent 自建卡片的配额限制。文中还标出两份官方文档在状态枚举上的不一致之处。
Paperclip 公司配置怎么导出导入：包结构、collision 策略与「导入后不自动跑」
把一家 Paperclip 公司搬到另一套环境，靠的是 markdown 包而不是数据库备份。本文讲清导出包的目录结构、export/import 两条命令的全部选项、--include 默认只带 company,agents 这个坑、三种命名冲突策略、GitHub 来源与 --ref 固定版本，以及导入后 agent 为什么不会自己跑起来。
Paperclip 实验特性开关怎么用：官方标为实验性的功能，开之前要想清楚什么
逐条梳理 Paperclip 官方文档对「实验性」的定性、开关所在的实例设置与两条 CLI 命令、目前文档里能查到被标注为实验的几处功能，并用状态卡片这个写得最细的实验特性当样本，说明打开一个实验开关会引入哪些新的刷新、成本与授权变量，以及哪些工作流不该依赖它。
执行层：控制平面自己不跑 Agent
真正干活的 Agent 通过适配器接进来。五类适配器各自的前提、自建适配器要实现什么契约、一次执行在语义上保证了什么（幂等、认领锁、活性合同），以及官方文档里怎么把 OpenClaw 接成执行层。
Paperclip 适配器怎么选：五类接入方式的前提、限制与官方对照表
Paperclip 把编排层和 agent 运行时之间的桥叫适配器。这篇按官方文档梳理内置适配器的完整清单、claude_local / codex_local / gemini_local 三个本地 CLI 适配器各自的安装前提与配置字段、凭据归属谁说了算、三档反馈粒度的差别，最后给一张选型对照表，并标出哪些还是实验状态。
Paperclip HTTP 适配器接入自建 Agent：要实现哪些端点、鉴权与回调契约怎么写
手上已经有一个跑在云函数或常驻服务里的 Agent，想挂到 Paperclip 上排任务。本文按官方文档梳理 http 适配器的三个配置字段、webhook 请求体里到底给了什么、PAPERCLIP_API_URL 与 API key 的鉴权路径，以及回调时必须遵守的 checkout、X-Paperclip-Run-Id 和 409 不重试这几条硬规矩。
Paperclip 进程适配器怎么用：把任意 shell 命令接进 Agent 编排，代价是什么
process 适配器是 Paperclip 里最朴素的一种接法——把一条 shell 命令当子进程拉起来跑完就算数。本文按官方文档梳理它的四个配置项（command/cwd/env/timeoutSec）、四步执行流程、注入的环境变量，以及官方明确劝退的两种场景和它在运行转录上要付的代价。
给 Paperclip 自己写一个适配器：外部插件包的结构、执行契约与 UI 解析器
Paperclip 内置的几类适配器接不上自家 Agent 运行时时，可以自己写一个适配器。这篇按官方文档梳理内置与外部插件两条路的差别、包结构与 package.json 关键字段、execute 的输入输出契约、环境自检的三档诊断、能力开关、会话持久化，以及 UI 解析器那六条硬约束和安装方式。
Paperclip 里的 Agent 不是常驻进程：心跳、唤醒与一次运行链路
按 Paperclip 官方文档拆开 agent 的驱动方式：一次 heartbeat 从触发到落盘经过哪六步、四种唤醒来源分别是什么、运行时注入了哪些 PAPERCLIP_ 环境变量、内置适配器有哪几类、timeoutSec 填 0 和填负数语义完全不同、会话什么时候该重置，以及运行反复失败时官方给的排查顺序。
Paperclip 执行语义：一次运行到底保证了什么（幂等、锁、终态与超时的定义）
不讲任务怎么点，只讲 Paperclip 官方执行语义文档给出的硬保证——结构与依赖为什么必须分开、checkoutRunId 和 executionRunId 各管什么、已接受计划的分解为什么是 exact-once 指纹、run 的四种终态与静默/超时如何区分、非终态任务的存活性合同列了哪几条合法路径，以及恢复为什么只重试一次。
Paperclip 执行工作区与 git worktree：一个 issue 到底跑在哪份代码上
拆解 Paperclip 官方文档里的执行工作区模型——项目工作区的 Services 与 Jobs 怎么定义、执行工作区如何继承与覆盖、心跳运行时解析工作区的五个步骤、懒加载预置命令的三种状态、私有仓库 token 的解析顺序，以及「不许 git push」的跨运行持久化契约。
Paperclip 内置 Agent 有哪些角色：briefs 与 learning 的注册表机制与自建方法
按官方文档口径梳理 Paperclip 内置 Agent（built-in agents）：目前只有 briefs 和 learning 两个注册键，它们靠 metadata.paperclipBuiltInAgent 标记而非硬编码 id 被查到。文中拆开注册表、标记、供给服务、路由四层，四种状态的判定，三个公司维度接口，以及新增一个内置 Agent 的八步流程与运维坑位。
Paperclip 接 OpenClaw 当执行层：邀请提示词、网关 preflight 与两次批准
按 Paperclip 官方的 OpenClaw onboarding 检查表和 Docker 指南，梳理这条对接链路到底分几步：怎么用受控端点生成邀请提示词、创建出来的 agent 为什么必须是 openclaw_gateway、tokenLen 和 devicePrivateKeyPem 要核对成什么样、首跑报 pairing required 该去哪批准，以及容器里 127.0.0.1 指向自己带来的回调坑。
Paperclip 里 Agent 之间怎么沟通：评论是唯一主通道，@提及是唤醒开关
Paperclip 没有给 Agent 准备聊天室，状态更新、提问、发现、交接全部落在 issue 评论里。这篇按官方文档梳理发评论的两种写法与那个会让审批阶段推不动的坑、@提及的三条硬规则、五种结构化交互卡片各自的用途，以及什么场合该建子任务而不是继续在评论里说话。
治理、扩展与接口
MCP 访问治理、低信任预设、连接器安全威胁模型这三块是这个项目里少见的「先写规范再写代码」的部分；另外还有 skill 与插件怎么写、API 怎么调、流水线怎么排。
Paperclip 插件规范怎么读：哪些能力现在能用，哪些还只是设计稿
Paperclip 仓库里同时放着插件规范和开发指南，前者是 post-V1 的目标架构，后者才是当前 alpha 能跑的面。这篇把两者的落差、manifest 字段、能力清单、worker 进程模型、托管资源与数据库边界拆开讲，帮你判断手里的插件想法现在能不能落地。
Paperclip 的 issues 与 agents 接口怎么用：字段、状态机与 409/400 的真实含义
把 Paperclip 官方 API 文档里 issues 和 agents 两组接口拆开讲：PATCH 回执里的 changes 字段、checkout 的原子认领与 409 不可重试、崩溃后如何重新认领、文档 baseRevisionId 冲突、interactions 卡片的五种 kind 与解决权限，以及 agents 的生命周期动作和会返回 400 的调用方式。
Paperclip 的 skill 怎么写：SKILL.md 格式、信任等级与技能库的完整流程
从官方文档拆解 Paperclip 的 skill 机制——SKILL.md 的目录结构与两个 frontmatter 字段、运行时按 description 路由的四个步骤、五条官方写法建议，以及写完之后技能怎么进公司库：安装/导入/本地新建/工作区扫描四条路径、三档信任等级对外部导入的限制、版本与漂移审计，还有 skill 最终怎么被注入到 agent 的工作区。
Paperclip 的目标与项目层怎么组织：goals、projects 与 workspaces 三层接口拆解
很多人在 Paperclip 里只用 issues，结果 agent 干活没方向、任务追溯不回公司目标。这篇按官方 API 文档把 goals 的三级层次、四个状态值、projects 与 goal 的关联字段，以及 workspace 的 cwd/repoUrl 规则逐个拆开，给出建目标、建项目、挂工作区的最小请求序列和字段约束。
Paperclip 低信任预设 low_trust_review：让 Agent 读外部输入时被围住的那套策略
当 Agent 要去审别人提的 PR、读外部工单和依赖 diff，输入本身就可能带提示词注入。Paperclip 文档给了一个叫 low_trust_review 的信任预设，用三处 JSON 策略字段取交集算边界，算不出具体范围就 fail closed，并对沙箱驱动、工作区模式、密钥引用提出硬性要求。本文按官方文档逐条拆解它管什么、默认关了什么、以及它明确不管什么。
Paperclip 连接器安全威胁模型：官方文档定的八条硬决策与负向测试清单
把 Paperclip 官方 Connections Security Threat Model 文档拆开讲：凭据只放 company_secrets、默认拒绝、广权限提供商必须带资源过滤器这八条硬性决策，逐个流程（OAuth 创建、目录刷新、工具执行、同步任务、Webhook、导入导出）的控制点，以及文档要求必须写的负向测试和它自己列出的残余风险。
Paperclip 连接器怎么接：默认做成目录条目而不是插件，以及首批 30 个的排期逻辑
Paperclip 的连接器手册把「接一个外部系统」拆成九步：先判断该做目录条目还是插件，再定复用路径、认证方式、资源过滤器、动作风险分级和治理默认值。本文按官方文档梳理这九步的判断依据、三条复用路径的分界线、首批 30 个供应商的批次与安全分级，以及 OAuth 端点是发现来的还是写死的那套优先级规则。
Paperclip 流水线（pipelines）与例行任务（routines）：阶段、关卡、触发器怎么配
把 Paperclip 官方 pipelines 教程和 routines 接口文档对着读，讲清 pipeline / case / routine 三层各管什么、五种 stage kind 与 config 字段如何构成关卡、父子 case 的 rollup 与 autoAdvanceOnChildrenTerminal、expectedVersion 引发的 409 冲突，以及 routine 的三类触发器和并发、补跑策略。
Paperclip API 总览：base URL、三种令牌与七个错误码分别代表什么
从官方 API 文档出发，梳理 Paperclip 控制平面接口的四件事：请求打到哪个地址、Authorization 里该放哪种令牌（Agent API key / 运行期 JWT / 会话 cookie）、公司作用域与运行审计头怎么带、以及 400 到 500 七个错误码各自要求调用方做什么动作，其中 409 和 500 官方给了明确的行为约定。
Paperclip MCP 访问治理：四层机制怎么拦住一次工具调用
把 Agent 调 MCP 工具这件事拆成连接、目录、画像、策略四层来管。这篇按官方运维文档梳理风险分级与变更隔离规则、画像绑定的作用域顺序、五类策略的判定次序、审批与信任规则的参数哈希约束，以及运行槽位与审计事件日志的排障入口，附上文档里给出的接口路径和已知边界。
想搞清楚 AI Agent 在组织里怎么落地？
从单个 Agent 到一整支数字团队，站内有成体系的组织管理内容。