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

Paperclip 审批卡住怎么办：从审批类型、生命周期到用 API 把队列查清楚

2026-08-17
站内工具 AI 编程工具报错分诊器 → 把报错原文贴进去，先分清是网络、额度、配置还是上游故障，再决定往哪个方向查。

把 Paperclip 的公司建起来之后，最容易撞上的一类”故障”其实不是报错，而是没有报错：Agent 在，任务在，日志也在滚，但某条线就是不往前走。CEO 的任务停在待办里迟迟不进 in_progress，或者某个 manager 说要招人、然后就没有下文了。

这类现象大部分时候不是崩了，是卡在审批门上。Paperclip 官方文档对审批的定位写得很直白：approval gate 的作用是让人类董事会操作者（board operator）保住关键决策的控制权。既然是”门”，门没开，后面的流程当然停在原地。

麻烦的是审批这套东西在 Paperclip 里有三处入口——董事会操作者视角的审批队列、Agent 开发者视角的请求与响应、还有一组 REST 接口。你只看其中一处，很容易得出”我明明批了啊”这种结论。下面按官方文档把三处拼到一起。

先分清：这件事到底该不该走审批

排查审批卡住，第一步不是去看队列，而是先确认这件事根本就不该进审批队列。

官方在 Agent 开发者文档里划了一条清楚的界：审批系统是给那些需要留正式董事会记录的”受治理动作”用的，文档举的例子是招聘、战略门、支出审批、安全敏感动作。而普通的 issue 线程里的是/否决策，应该用 request_confirmation 这种交互，而不是开一条审批。

文档甚至直接列了三个”不该用审批”的典型问句：

  • “接受这个方案吗？”
  • “按这个拆解继续吗？”
  • “用方案 A，还是驳回并要求修改？”

这三类应该用下面这个接口造卡片：

POST /api/issues/{issueId}/interactions
{ "kind": "request_confirmation" }

这条界线之所以对排查有用，是因为两边的”卡住”表现几乎一样——都是任务不动、都在等人点头——但查的地方完全不同。如果一个 Agent 把”要不要按这个方案做”塞进了审批队列，你在审批页面能看到它；反过来，如果它按规范走了 request_confirmation，那东西挂在 issue 线程上，你盯着审批队列刷新一整天也不会有任何变化。

顺带说一句方案确认卡的四条官方规范，它们本身就是防卡死设计：更新 plan 文档 → 绑定最新 plan 修订版创建 request_confirmation → 用 confirmation:${issueId}:plan:${latestRevisionId} 这种幂等键 → 设 supersedeOnUserComment: true，让后续的董事会/用户评论把过期请求作废，最后等确认被接受再去创建实现子任务。幂等键管的是同一个方案不要反复弹卡，supersedeOnUserComment 管的是你已经在评论区说过话了、那张老卡片不该继续挂着占位。

两种审批类型，和一条状态机

官方文档目前明确写出来的审批类型有两种。

类型谁发起挡住了什么请求里带什么
hire_agent通常是 manager 或 CEO新 Agent 无法正式上岗拟招 Agent 的名字、角色、能力、适配器配置、预算
approve_ceo_strategyCEOCEO 无法开始把任务推进到 in_progresspayload 里的战略方案文本

状态机是这样的：

pending -> approved
        -> rejected
        -> revision_requested -> resubmitted -> pending

这条线里最值得记的是 revision_requested。它不是终态——你要求修改之后，球回到 Agent 手上，Agent 改完 resubmit，状态才重新回到 pending 等你再看一次。所以如果你记得自己”处理过”某条审批却发现事情没推进，先确认当时点的是不是”要求修改”：那一下并没有放行，只是把请求打了回去。同理，如果 Agent 迟迟不重新提交，这条审批就会一直停在 revision_requested，看上去像是没人管。

董事会操作者在审批页面能看到的信息，文档列了三项：谁提的、为什么提；关联的 issue（也就是这次请求的上下文）；以及完整的 payload，比如招人请求里那份拟定的 Agent 配置。三项里最容易被跳过的是关联 issue——审批本身往往只有一句话，判断依据在关联 issue 里。

“CEO 不干活”多半卡在战略门

这是新建公司时的高频现象，值得单独拎出来。

文档写得很明确：CEO 的首份战略方案需要董事会批准，批准之前 CEO 不能开始把任务推到 in_progress。也就是说，一家刚建起来的公司，如果 CEO 看起来什么都没做，第一件该查的事不是心跳、不是适配器，而是有没有一条 approve_ceo_strategy 挂在 pending 上等你。

对应的请求长这样，可以用它反过来核对你队列里那条是不是它：

POST /api/companies/{companyId}/approvals
{
  "type": "approve_ceo_strategy",
  "requestedByAgentId": "{yourAgentId}",
  "payload": { "plan": "Strategic breakdown..." }
}

如果你在排查一家刚建好的公司为什么整体不动，可以顺着建第一家公司的完整步骤回头核对一遍，看看是流程本身还差一步，还是真的卡在门上。

招人卡住：agent 建了但状态是 pending_approval

招聘这条线的卡点在于，请求发出后Agent 确实被创建了，只是没上岗。文档的说法是：如果公司策略要求审批，新 Agent 会以 pending_approval 状态创建，同时自动生成一条 hire_agent 审批。

POST /api/companies/{companyId}/agent-hires
{
  "name": "Marketing Analyst",
  "role": "researcher",
  "reportsTo": "{yourAgentId}",
  "capabilities": "Market research, competitor analysis",
  "budgetMonthlyCents": 5000
}

这就解释了一个常见的困惑：花名册上明明多了个人，可它一直不接活。此时该看的不是这个新 Agent 自身，而是那条自动生成的审批。API 文档对这个端点的描述是”创建一个草稿 Agent 和一条关联的 hire_agent 审批”，草稿这个词已经说明了状态。

还有一条权限约束容易被忽略：文档写明只有 manager 和 CEO 应该发起招聘请求，IC（一线执行）Agent 应该去找自己的 manager。所以如果某个执行层 Agent 的招人诉求一直没有变成审批，方向可能一开始就不对——先看它的 reportsTo 指向谁，把请求交给对的那一层去发。

预算字段 budgetMonthlyCents 也在招聘请求里，驳回理由里官方给的示例正是”这个角色的预算太高了”。预算这条线怎么设、超了怎么办，属于另一个话题，见预算与 token 工资超支怎么控。

批了之后还是不动：Agent 得自己去接住结果

这是第二类”审批卡住”——门开了，人没走。

按官方文档，当一条你请求的审批被裁决后，Agent 可能会被唤醒，唤醒时带上三个变量：

变量含义
PAPERCLIP_APPROVAL_ID被裁决的那条审批
PAPERCLIP_APPROVAL_STATUSapproved 或 rejected
PAPERCLIP_LINKED_ISSUE_IDS逗号分隔的关联 issue ID 列表

文档要求 Agent 在心跳一开始就处理它，处理动作是两个 GET：

GET /api/approvals/{approvalId}
GET /api/approvals/{approvalId}/issues

然后对每一条关联 issue 做出交代：如果这条审批已经把该做的事完全了结了，就关掉它；如果它还要继续，就在上面评论说明接下来会发生什么。

这套约定意味着：审批的结果落地是 Agent 侧的责任。如果一个 Agent 的实现没在心跳开头处理这几个变量，那你在董事会这边点了批准，关联 issue 也可能就一直挂着不动、既不关也没有下文。这时候该查的是 Agent 的心跳链路而不是审批本身，可以顺着Agent 不干活：心跳、看门狗、卡住怎么查往下走。

另外，Agent 侧也可以主动轮询自己公司的待处理审批：

GET /api/companies/{companyId}/approvals?status=pending

用接口把队列查清楚

排查时最省事的做法是绕开界面直接问接口。官方 API 文档给出的这一组端点，正好覆盖”看得到、看得懂、推得动”三步：

目的接口
列出公司审批（可加 status=pending 过滤）GET /api/companies/{companyId}/approvals
看单条详情（类型、状态、payload、裁决备注）GET /api/approvals/{approvalId}
看关联 issueGET /api/approvals/{approvalId}/issues
看讨论记录GET /api/approvals/{approvalId}/comments
补一条讨论POST /api/approvals/{approvalId}/comments
批准POST /api/approvals/{approvalId}/approve
驳回POST /api/approvals/{approvalId}/reject
要求修改POST /api/approvals/{approvalId}/request-revision
Agent 改完重交POST /api/approvals/{approvalId}/resubmit

前三个裁决动作都接受 decisionNote，官方示例分别是”批准，人选不错""这个角色预算太高""请降低预算并说明能力范围”。这个字段在排查时的价值不只是礼貌——GET /api/approvals/{approvalId} 返回里就包含裁决备注，几周后回头看一条被驳回的招聘请求，备注是唯一还能说明当时判断依据的东西。

resubmit 接受的是新的 payload，也就是改过的配置：

POST /api/approvals/{approvalId}/resubmit
{ "payload": { "updated": "config..." } }

实在不想等：董事会的越权手段

如果确认了流程本身有问题、又不想在审批门上耗着，文档列了董事会操作者可以直接动的几件事：

  • 随时暂停或恢复任何 Agent
  • 终止任何 Agent（不可逆）
  • 把任何任务改派给别的 Agent
  • 覆盖预算限制
  • 直接创建 Agent，绕过审批流程

最后一条是招聘卡住时的直接解法：与其等 hire_agent 走完一圈，不如自己把这个 Agent 建出来。代价也很清楚——绕过审批就等于放弃了这次决策的正式记录，而审批流程的全部意义恰恰是留下这条记录。所以它更适合”我已经知道这个人要招、只是流程堵了”的场景，不适合当成默认操作。

“终止不可逆”这五个字建议单独记一下。排查时人容易急，急起来最容易点的就是那个看上去能一了百了的按钮。

什么时候这篇不适用，以及文档没说的

先说边界：以上全部来自 Paperclip 官方文档的董事会操作者指南、Agent 开发者指南与 approvals API 三处，是机制层面的说明。

有几件事官方文档在这三处并没有交代，遇到了别按本文推：

  • 审批没有超时或自动放行机制的说明。文档没写 pending 挂多久会怎样，也没写有没有提醒。按目前写明的状态机，一条审批就是一直等着人处理。
  • “公司策略要求审批”这个开关在哪配、有哪些取值，文档在这三篇里没有说明。文档只写了”如果公司策略要求审批，新 Agent 会以 pending_approval 创建”，至于怎么把它关掉或改宽，需要另找配置来源。
  • 除 hire_agent 和 approve_ceo_strategy 之外还有没有别的审批类型，这三篇只写了这两种，虽然 Agent 侧文档提到过”支出审批、安全敏感动作”这类适用场景。把它当作类型的完整清单是不稳的。
  • 谁能裁决审批，文档的口径是董事会操作者，但多人协作时的权限细分没有展开。

还有一条判断经验：如果你已经确认队列里空空如也、Agent 也没有被 pending_approval 卡住，那问题多半根本不在审批层，而在执行层或任务流转本身——那就该换个方向查，从任务从建到关的流转重新捋一遍状态。审批门只挡住两类动作，它挡不住的事情，就别在这儿浪费时间。

延伸阅读

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

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

浏览课程 加入会员