奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

Paperclip 连接器怎么接：默认做成目录条目而不是插件，以及首批 30 个的排期逻辑

2026-08-17

接第一个外部系统时，多数人的第一反应是写插件：新建一个包，装几张表，起个 worker，把调用逻辑塞进去。接到第五个就会发现问题——五套凭据存法、五套权限判断、五种审计格式，谁都说不清某个 Agent 到底能动哪些资源。

Paperclip 的连接器手册（CONNECTOR-PLAYBOOK）给的答案是反过来的：默认把供应商做成目录里的一条数据，不是一段代码。 只有当这个集成确实塞不进通用连接模型时，才升级成插件。这个判断放在整个流程的第一步，不是最后一步。

手册是个九步模板，配一份《首批 30 个连接器矩阵》（FIRST-30-MATRIX）作为排期依据。下面按这两份文档的原文口径过一遍每一步的判断标准——真正难的不是写代码，是决定这个供应商该走哪条路。

第一步：这事到底该不该写插件

手册的默认立场很明确：只要供应商能被表达成「元数据 + 一种传输方式」，就做目录条目。具体是三个条件：

  • 连接指向的是远程 MCP 端点、经批准的本地 stdio 模板，或者基于文档化 API 生成的 shim；
  • 配置流程只需要普通字段、OAuth 回调处理、资源过滤器、策略默认值、健康与目录检查；
  • 供应商不需要自己的数据库表、后台 worker、定制的 issue 线程交互或专属 UI 页面。

反过来，出现下面任何一类需求才用插件：需要定制页面或超出表单驱动的富配置界面（产品面）；需要插件自有的表、迁移或长期本地状态（数据模型）；需要 worker、调度器、webhook、同步循环、文件处理器这类不是简单传输 shim 的运行时（执行）；或者第三方希望以扩展包形式发布（打包）。

手册里有一句写得很硬：插件可以捆绑目录条目，但仍然必须创建正常的 application、connection、凭据引用、目录条目、profile、策略和审计事件，不得绕过 gateway、策略引擎、company_secrets、变更动作隔离和调用事件审计日志。写插件换来的是产品形态自由，不是治理豁免。这条边界和 MCP 访问治理 的口径一致。

三条复用路径，决定后面所有事

第二步是分类。手册要求用矩阵里的统一术语，这样排期、安全评审和 QA 才能横向比较不同供应商：

复用路径什么时候用典型传输文档举的例子
MCP-direct供应商有官方或稳定的 MCP server，工具语义能直接映射到 Paperclip 的授权模型mcp_remote；local_stdio 仅限已批准的可信模板Linear、Notion、Sentry、Vercel、Exa、Apify、Context7
OpenAPI-shim有文档化的 REST/OpenAPI 面，但没有稳定的 MCP server，用生成的薄 shim 暴露安全动作shim 服务或已批准模板，对 Paperclip 呈现 MCP 兼容的目录Datadog、Apollo、QuickBooks、Ramp/Brex、Zendesk
Vendor-deep-wrapper边界依赖应用安装令牌、事件校验、复杂领域语义、资源授权或高危写入供应商专用 wrapper，仍然挂在同一套连接模型下GitHub、Slack、Google Workspace 写入、Atlassian、Microsoft 365、Cloudflare、Figma、Stripe、Salesforce、HubSpot、Intercom、PagerDuty

分类结果要连同传输方式和「为什么更轻的路径不够用」一起写进提案。上表的归类照录自官方文档。

凭据只有一个去处

第三步选认证模式，四选一：OAuth（有委派 scope 和吊销 API 的供应商）、API key（只在 scope 能收窄、且密钥以 company_secrets 引用存储时使用）、app-installation（bot/应用安装凭据）、none（公开只读系统或第一方 fixture）。不管选哪种，凭据永远存在 company_secrets 里，带脱敏元数据和版本化材料。目录条目记录的是绑定形状，不是密钥值：

{
  "credentialSecretRefs": [
    {
      "configPath": "credentials.authorization",
      "label": "Linear OAuth access token",
      "required": true
    }
  ],
  "credentialRefs": [
    {
      "name": "Authorization",
      "placement": "header",
      "key": "Authorization",
      "prefix": "Bearer ",
      "secretId": "<resolved at connect time>"
    }
  ]
}

手册列了一串禁地：不要把长期有效的供应商凭据放进 Agent 环境变量、项目或运行时环境变量、适配器配置、issue 评论、截图、日志、fixture JSON、插件配置。Agent 拿到的是运行级 gateway token，供应商凭据由 Paperclip 服务端解析并审计。存储侧细节见 密钥管理。

资源过滤器：开写权限之前的前置条件

第五步是资源过滤器，手册的措辞是「每个连接器提案在启用写动作之前都需要资源过滤器」。过滤器属于连接配置，必须由 gateway 或 wrapper 强制执行，不能只靠 UI 选择器——UI 里的过滤器选择框是便利功能，不是执行边界。

常见的过滤维度分五类：账户边界（workspace、org、team、tenant、site 等）、资源边界（repo、channel、page、database、project、zone、file、dashboard 等）、对象边界（issue 状态、标签、分支、环境、对象类型、字段列表、参会人域名）、出口边界（域名允许/拒绝列表、结果条数上限、内容类别、附件与文件类型限制）、变更边界（仅创建、仅草稿、仅评论、禁删除、禁外发、必须 dry-run）。

对 S3/S4 供应商，必需过滤器缺失时，连接健康检查和目录发现应当直接失败或告警。

动作分级与「变更即隔离」

第六步是动作目录。手册强调不要只依赖供应商自己的工具名，Paperclip 需要归一化的元数据来做评审、策略和审计。每个动作要记录：稳定工具名与展示标题、运营者语言的描述、输入输出 schema、读/写/破坏性标记与风险级别、用到的过滤器字段、脱敏方案、审计字段、默认状态（启用/禁用/隔离），以及一个负向访问用例（未授权的调用方、不允许的资源、已吊销的连接、跨公司尝试）。

三档风险的默认值：

风险例子默认行为
read在允许资源范围内搜索、列举、取元数据或内容profile 覆盖该 app 或该读风险级别时即为启用
write建 issue、加评论、改状态、追加 block、触发重新部署默认 ask-first；初次评审之后才发现的新增或变更写工具，一律先隔离
destructive删除、退款、取消生产部署、外发消息、租户级大范围变更隔离。需要运营者显式评审，评审后通常仍要挂 require_approval 策略

「变更动作隔离」是强制的：目录刷新时发现新增或 schema 变更的写/破坏性动作，在运营者评审并重新启用前对 Agent 一律不可见。手册补了句很实际的提醒——别因为之前有个名字相近的动作是启用状态，就把变更后的动作也标成启用。ask-first 落到队列之后怎么走，见 审批卡住怎么办。

第八步治理默认值的推荐是：只在读动作风险低或中、且过滤器齐备时才建只读默认 profile；recommendedDefaults.askFirstRiskLevels 设成 ["write", "destructive"]（纯只读连接器除外）；破坏性动作在安全工程师评审前显式 block 或隔离；对配额敏感和付费 API 加限流；任何外发、部署、退款、删除、租户级变更，一律要求审批。

首批 30 个是按什么排的

矩阵文档把 30 个供应商分成六个批次，分批的依据是运行时与认证模式，不是知名度：

批次运行时/认证模式目的
0 已完成验证内建/深度 wrapper、应用安装、Google OAuth验证代码仓、聊天、文档三条流程
A 标准扩展直连 MCP 或薄 wrapper，OAuth/API key，中等风险验证可复用的连接器模板
B 企业套件租户级 OAuth，宽的目录/文档/聊天 scope验证企业账户范围划分与 CRM 授权
C 设计与数据多为直连 MCP 或 API key，读多写少写权限收窄的前提下扩展品类广度
D 收入与受监管操作OAuth/API key，高风险财务与客户写入审批 UX 加强之后再接入
E 事件、支持与会议OAuth/API key 加事件/webhook 同步接入值班、基础设施、工单与会议记录

首个实施批次（Batch A）点名五个：Linear、Notion、Sentry、Vercel、Exa。文档同时写明，Stripe、Salesforce、Zendesk、QuickBooks、Ramp/Brex 以及范围较大的 Microsoft 365 写入排除在首批之外，理由是涉及更高风险的财务、客户、支持或租户级面，应再多走一轮授权与吊销验证。还有一条硬约束：在 Apps v2 底座稳定、且连接器验证范围能跑通 connect / configure / grant / execute / revoke / activity 全链路之前，不要开始供应商实现。

安全分级 S1 到 S4 横切在批次之上：S1 是只读的公开或商业数据，不含客户 PII、资金流动、部署或外发消息；S2 是业务数据读取加带过滤器的低风险窄写入；S3 是宽范围文档、基础设施、事件、客户支持或部署写入，需要显式授权评审和强活动日志；S4 是支付、财务、受监管数据、租户级管理或不可逆的面向客户写入，需要安全工程师评审和高风险审批/dry-run 默认值。矩阵里每一行都标了 tier，写提案时直接抄——文档说 FIRST-30 对 riskTier 和 requiredResourceFilters 是权威来源。威胁面的推演见 连接器的安全威胁模型。

OAuth 端点：发现来的还是写死的

MCP-direct 这条路上有个容易踩的坑，手册单独开了一节。现在不少供应商的授权服务器是从 MCP 端点本身发现出来的：未认证请求返回 401 带 WWW-Authenticate，指向 RFC 9728 的 /.well-known/oauth-protected-resource，再到 RFC 8414 的 /.well-known/oauth-authorization-server 拿 authorize、token 和可能的 registration 端点。

但发现不是无条件执行的。broker 解析端点的顺序是三档：

  1. 如果 manifest 的 method defaults 里带了完整的一对（authorizationEndpoint 和 tokenEndpoint），就无条件用这一对，发现逻辑根本不跑，连接自身 OAuth 配置里存的端点和 401 挑战给的提示都不看；
  2. 否则，对 mcp_remote 连接调发现逻辑，它会先看连接自身 OAuth 配置里已存的端点（逐字段回落到 401 提示），凑齐完整一对就直接用，不发 .well-known 请求；
  3. 只有前两档都凑不齐时，才走完整的发现链。

手册的结论很直白：完整的 manifest 端点提示是权威值，不是提示——它会覆盖此前发现并持久化的端点，一旦过期 broker 会继续用旧的。所以对支持发现的供应商，defaults 里只写 serverUrl；只有确实不发布 RFC 9728/8414 元数据的供应商才显式写端点，写了就得自己维护。

配套的是动态客户端注册（RFC 7591）：授权服务器公布了 registration_endpoint、且支持公开客户端（token_endpoint_auth_method 为 none 加 PKCE S256）的供应商，不需要预先配置任何 OAuth 应用。首次连接时实例自己注册一个客户端并把 client_id 存在连接上，之后所有 authorize/refresh 复用它——重复注册会让此前的授权在某些供应商那里成为孤儿。配了 PAPERCLIP_TOOL_OAUTH_<PROVIDER>_CLIENT_ID/_SECRET 时，环境变量客户端优先级最高（customer 所有权），broker 跳过注册。

文档还反复强调：DCR 永远是实例本地的，云托管和自托管走同一条路径，唯一差别是回调 URI 里的主机名。id.paperclip.ing 只认证运营者，从不持有资源令牌。

交出去的东西长什么样

一份完整提案要产出：目录 manifest 条目；传输与认证配置；指向 company_secrets 的凭据引用（不是原始环境值）；带风险级别、schema、过滤器和隔离默认值的动作目录元数据；三档风险的默认 profile 与策略；以及一份冒烟清单。

每份连接文档还必须包含三样东西：服务参与声明（明说 Paperclip ID 或 Paperclip Connect 是否参与）、时序图加确切端点（authorize、token、registration、Paperclip 自己的回调路径）、管理员配置说明（要注册什么、在哪注册、怎么端到端验证）。

冒烟清单是固定的七项：

- Connect：对真实供应商用类生产配置连接成功
- Catalog：目录发现产出预期动作，新增/变更的高危动作被隔离
- Allowed read：被允许的读调用经 gateway 成功
- Ask-first write：写调用进待审队列，审批后才执行
- Denied/quarantined：被阻断的动作，Agent 既列不出也调不动
- Revoke：吊销后工具立刻消失、执行立刻被拒
- Audit：活动行能证明调用方、run/issue 上下文、资源 id、决策、原因码与结果

画廊卡片如果没法对真实供应商跑通这条路径，文档要求下架或标为不可用，直到缺失的认证、传输或治理依赖补上。

什么时候这套不适用，以及还没解决的

方向反了就不适用。 这份手册管的是 Paperclip 主动去操作外部系统（出站）。外部客户端来操作 Paperclip（入站）走的是 gateway 和 webhook 那套指引：入站客户端用有作用域的 Paperclip 鉴权，出站供应商调用才走 Apps v2 的连接治理栈。

过滤器在 v1 阶段的执行位置未必是你以为的那个。 文档在 Notion 的示例里明说，v1 的执行方式是 gateway 策略加「过滤器即配置」，矩阵里提到的「针对 block/database 策略的薄 wrapper」被明确推迟——某些细粒度约束这一版靠策略层兜，不是靠专用 wrapper。

回调 URI 约束要真的探过才知道。 手册要求在写 manifest 之前用真实注册请求去探供应商的 redirect_uris 规则，把结果记进 AppDefinition 的 redirectConstraints 字段。目前支持的第一个取值是 https-or-loopback-http：任意主机上的 HTTPS，或仅限回环地址的明文 HTTP。踩中会以 oauth_redirect_origin_unsupported 快速失败，而不是让人去猜供应商侧含糊的 invalid_redirect_uri。手册还提醒，回调规则和浏览器可达性是两个独立维度——私有 HTTPS 主机可能合法，同机的明文 HTTP 却不行。

令牌生命周期各家不同，得逐个记。 文档记录过一种刷新令牌行为：每次刷新即轮换、旧令牌立即失效，重放过期的那个可能导致整份授权被吊销。对应处理是 broker 先持久化轮换后的令牌再发布新访问令牌，并对每个连接串行化刷新，刷新拿到 invalid_grant 视为终局——清空令牌、要求重新授权、绝不重试。这类细节不会从模板里自动长出来。

还有一点：动作评审、隔离解除、破坏性动作放行都要人来点。连接器做成数据而不是代码，省掉的是重复的集成工程，省不掉的是评审工作量。

延伸阅读

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

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员