Paperclip 的预算怎么设：给 AI 员工发「token 工资」，80% 报警、100% 自动停
让一群 Agent 自己排任务、自己派活、自己拉子任务，最先失控的通常不是代码质量，是账单。一个提示词写得不好的 CEO Agent，配上短心跳间隔，一晚上就能把一个月的量跑完——而且它自己不会觉得有什么不对，因为在它的世界里，“多想一轮”永远是划算的。
Paperclip 的做法是把这件事当成发工资来管：每个 Agent 有一份月度预算，单位是分（cents），花超了不是发个提醒就完了，是直接停掉心跳。官方文档里这句话说得很直白——追踪每个 Agent 花掉的每一个 token，并强制预算上限以防成本失控。
这篇把预算这条线从头到尾捋一遍：账是怎么记的、预算设在哪两层、80% 和 100% 各自会发生什么、Agent 自己该怎么查余额，以及在真的撞上限之前，你能从哪几个地方看出来它在烧钱。
一、Paperclip 记的账长什么样
成本记录的基本单位叫 cost event（成本事件）。每次 Agent 心跳完成，适配器解析 Agent 的输出，把这几项报回服务端：
| 字段 | 含义 |
|---|---|
| provider | 用的哪家 LLM 供应商，例如 anthropic、openai |
| model | 用的哪个模型，例如 claude-sonnet-4-20250514 |
| inputTokens | 发给模型的 token 数 |
| outputTokens | 模型生成的 token 数 |
| costCents | 这次调用的费用，单位是分（运行时能给出的话） |
这些事件按「每个 Agent、每个自然月」聚合，月份口径是 UTC 日历月，窗口在每月 1 日重置。
事件通常由适配器自动上报，但接口也开放给你直接写：
POST /api/companies/{companyId}/cost-events
{
"agentId": "{agentId}",
"provider": "anthropic",
"model": "claude-sonnet-4-20250514",
"inputTokens": 15000,
"outputTokens": 3000,
"costCents": 12
}
对 Agent 开发者，官方给的建议是：让适配器去报，别自己再补一遍，重复上报只会把账做花。
二、预算设在两层：公司和单个 Agent
预算字段叫 budgetMonthlyCents，公司和 Agent 上都有这个字段，单位统一是分。
公司层：
PATCH /api/companies/{companyId}
{ "budgetMonthlyCents": 100000 }
单个 Agent 层，可以在 Agent 配置页改，也可以走接口：
PATCH /api/agents/{agentId}
{ "budgetMonthlyCents": 5000 }
在 Agent 详情里读到的信息，同时包含预算和已花掉的数：budgetMonthlyCents 和 spentMonthlyCents 是并列的两个字段，跟角色、汇报链、状态放在一起返回。也就是说「这个 Agent 还剩多少额度」不需要另外算，取一次 Agent 记录就有。
CLI 侧对应的是 budget 这一组命令：
npx paperclipai budget overview --company-id <company-id>
npx paperclipai budget company:update --company-id <company-id> --payload-json '{...}'
npx paperclipai budget agent:update <agent-id> --payload-json '{...}'
npx paperclipai budget policy:upsert --company-id <company-id> --payload-json '{...}'
npx paperclipai budget incident:resolve <incident-id> --company-id <company-id> [--payload-json '{...}']
CLI 里出现了 policy:upsert（预算策略）和 incident:resolve（预算事件处置）两条，但这两条的 payload 结构和触发条件，抓取到的文档里只给了命令行形式，没有展开说明。要用的话得以你本机 npx paperclipai budget --help 的实际输出为准，别照着猜字段。
建公司的流程里，设预算是明确的一步：创建公司 → 定目标 → 建 CEO Agent（这一步就要填月度预算）→ 搭组织树（每个 Agent 各有自己的适配器配置、角色和预算）→ 设预算 → 开心跳。换句话说，预算不是”以后再说”的可选项，它和适配器配置是同一层的必填项。
三、80% 和 100%，两道闸的行为不一样
这是整套机制里最该记住的一张表：
| 阈值 | 行为 |
|---|---|
| 80% | 软告警——Agent 被告知只处理关键任务 |
| 100% | 硬停止——Agent 自动暂停，不再有心跳 |
两道闸的性质完全不同。80% 是行为约束，Agent 还在跑，只是被要求收敛到关键任务、跳过低优先级的活；100% 是执行层直接停，Agent 状态变成 paused。Agent 状态表里 paused 这一项的定义写得很清楚：手动暂停，或者预算导致的暂停——两种原因共用一个状态值。
被自动暂停之后，恢复只有两条路：调高它的预算，或者等到下一个自然月。没有”这次先放过”的临时豁免。
这带来一个很实际的副作用：你会先在别的地方看见症状，才想到是预算问题。 官方在委派那一篇里，把”CEO 不干活”的排查表列出来，预算是其中一行——CEO 超过月度预算 80% 时只做关键任务，可能就跳过了低优先级的派活。任务卡住不动的排查里也有同一条：先看任务评论有没有阻塞说明，再看任务是不是 blocked，然后看被指派的 Agent 状态，它可能已经被暂停或者超预算了。
所以看到”Agent 突然不接活了”，别急着查适配器和心跳配置，先看一眼预算利用率。这条排查线和心跳、看门狗那条线是并行的两回事，具体怎么区分可以对照 Agent 不干活时的心跳与看门狗排查。
四、Agent 自己也要在心跳开头查一次余额
预算不只是给人看的，它是写进 Agent 心跳协议里的动作。官方给 Agent 开发者的要求是：每次心跳开始时查一次自己的预算。
GET /api/agents/me
# 检查：spentMonthlyCents vs budgetMonthlyCents
心跳协议第一步「Identity」拿到的这条 Agent 记录里，就带着预算信息。配套的行为约定有三条：
- 利用率超过 80%，只做关键任务，跳过低优先级的；
- 到 100% 会被自动暂停，所以早点查、别把额度花在没用的探索上；
- 如果活干到一半发现快没预算了，留一条评论说明进展，然后体面地退出，而不是硬跑到被掐断。
最后一条是这套设计里比较用心的地方。被 100% 硬停的 Agent 是在任意时刻断的，如果它没有留下”我干到哪了、下一步该干什么”，那笔已经花掉的钱基本白费——下个月接着跑的时候，它还得重新读一遍上下文。心跳协议里”退出前必须在进行中的工作上留评论、必须留下明确的下一步动作”这几条硬规则，配合预算检查，才构成一个能断点续跑的循环。
五、在撞上限之前，从哪儿能看出来
仪表盘：当月花费对预算，加燃烧速率
仪表盘的成本卡片给的是当月花费 vs 预算，还有 burn rate（燃烧速率）。官方点名的三个「该盯的指标」里，预算利用率是其中之一，判断口径写得很具体：Agent 到 100% 会自动暂停，所以看到某个 Agent 接近 80% 时，就该决定是给它加预算还是重排它的工作。仪表盘各块的读法见 仪表盘与状态卡片怎么读。
同样的数据也有接口：
GET /api/companies/{companyId}/dashboard
返回里包含各状态的 Agent 数、各状态的任务数、停滞任务，以及成本汇总。文档里提到的用法有一条挺有意思——CEO Agent 在每次心跳开始时用它建立态势感知。也就是说，“公司还剩多少钱”这件事，是可以让 CEO Agent 自己看见的。
成本明细：按 Agent、按项目、按供应商切
接口层给了三个汇总口径：
GET /api/companies/{companyId}/costs/summary # 公司总计
GET /api/companies/{companyId}/costs/by-agent # 按 Agent
GET /api/companies/{companyId}/costs/by-project # 按项目
CLI 侧的切法更细一些，除了上面三个，还有 by-agent-model、by-provider、by-biller、window-spend、quota-windows，以及按单个 issue 查的 cost issue <issue-id>。这些维度怎么组合看，见 成本报表怎么看。
排查烧钱时，by-agent 通常是第一刀——多数情况是某一个 Agent 在反复空转，而不是所有人一起涨。by-agent-model 是第二刀：同一个 Agent 换到更贵的模型跑，账单曲线的形状和它多跑了几轮是不一样的。
活动日志：预算是谁改的
活动日志是仅追加、不可修改的，记录的事件类型里明确包含「预算变更」，和 Agent 的创建/配置变更/暂停/恢复/终止、审批决策、评论创建、公司配置变更并列。
这条在多人操作同一个实例时很关键：预算被谁调高了、什么时候调的，有据可查。不然”这个月怎么多花了这么多”会变成一笔糊涂账。Agent 的增删改和配置项见 Agent 增删改与配置。
六、几个会悄悄放大账单的地方
@-mention。 沟通那一篇里写得很直接：每一次 @ 提及都会触发一次消耗预算的心跳。所以官方的规则是别滥用提及，也别用提及来派活——要派活就建任务、指派任务。一个习惯性 @ 所有人的 Agent，等于在替全公司烧钱。
心跳节奏。 Agent 配置里能改的心跳设置包括间隔、冷却、最大并发运行数和唤醒触发条件。这四项直接决定了单位时间里能产生多少次调用。预算是结果侧的闸，心跳设置是源头侧的阀，只关一头是不够的。
活跃度续跑（liveness continuation）。 心跳运行会记录一个运行活跃度状态，其中 plan_only（只出了计划没动手）和 empty_response（空响应）这两种会触发有限次数的续跑唤醒，把同一个 Agent 在同一个任务上再叫醒一次。文档里写明，续跑的前提之一是预算和执行策略允许。所以一个总是”只给计划不动手”的 Agent，账单会比你按心跳次数估的高——它每次都会被多叫醒一轮。
状态卡片（实验特性）。 状态卡片需要在实例设置的 Experimental 里打开 enableStatusCards 才有，它是一块会自动刷新的公司级摘要板。它的省钱设计值得单说：刷新前先用 SQL 做变更检测，指纹没变就不花模型 token，官方给的变更检测成本是 $0。它还带每日 token 上限，卡片跑到上限就暂停自动更新，手动刷新仍然可用。
官方给了一张规划用的成本估算表，前提写得很清楚——按 v1 Summarizer 默认的 haiku 级模型算，供应商定价和你选的模型都会改变实际数字：
| 工作类型 | 预估用量 | 预估成本 |
|---|---|---|
| 增量更新 | 输入 1–2k、输出约 0.3k token | $0.003–0.006 |
| 繁忙的 15 分钟卡片跑 9 小时 | 约 10–18 次受变更门控的更新 | $0.03–0.10/天 |
| Reactive 模式最坏情况 | 每小时 6 次、跑 9 小时 | $0.15–0.35/天/卡 |
| 全量重建 | 输入 5–8k、输出约 1k token | $0.01–0.02 |
| 变更检测 | 只走 SQL | $0 |
这张表的用法不是拿来算你的账单，而是拿来体会一件事：同一块卡片，刷新策略从 Manual 换成 Reactive，量级差出一个数量级。状态卡片产生的每次生成也走正常的成本账本，会被计入总账。
七、这套机制没解决什么
粒度只到月。 预算是月度的，UTC 自然月，每月 1 日重置。它挡得住”这个月烧穿”，挡不住”今天下午三小时烧掉半个月的量”——真烧起来，你依然是靠仪表盘的燃烧速率和自己盯着才能提前发现。想要更细的窗口，CLI 里有 cost window-spend 和 cost quota-windows 这两条，但文档没说明它们的窗口定义和返回结构。
撞线后的恢复动作很硬。 只有加预算或者等下个月两种。如果你在月底最后几天撞线，加预算基本是唯一选择，而加多少全凭判断——文档没提供任何”临时额度”或”借支下月”的机制。
账准不准取决于适配器。 成本事件是适配器解析 Agent 输出得到的，费用一项文档写的是「运行时能给出的话」。也就是说，接自建 Agent 的时候，成本上报要你自己保证；不上报不会报错，只会让预算这道闸失去依据——额度看着永远够用，钱照花。
预算策略与预算事件没有文档。 CLI 里有 budget policy:upsert 和 budget incident:resolve，说明系统里存在比”两个阈值”更复杂的策略层和事件处置流程，但抓到的文档没有展开。要用这两条命令，得以你实际安装版本的帮助输出为准。
内置 Agent 的默认预算可能是 0。 内置 Agent 的定义里有 defaultBudgetMonthlyCents 这个字段，示例中 Learning、Digest 两个内置 Agent 给的默认值都是 0，新增内置 Agent 的步骤里也专门有一条”决定这个内置 Agent 是否需要非零的默认预算”。启用内置 Agent 之后发现它一动不动，检查预算是不是 0，比检查适配器配置来得快。
预算这套东西的价值不在于省了多少钱，而在于给了你一个能睡着觉的上界。上界设得保守一点，先看它跑出什么结果，再往上加——这也是官方最佳实践里的第一条。
延伸阅读
- 从头读起：Paperclip 是什么：一个自己不跑 Agent 的控制平面，怎么管住一整家 AI 公司
- 本专题共 40 篇，完整分组目录见专题页
- Paperclip 成本报表怎么看：适配器怎么上报、字段有哪些、三个查询口径分别答什么
- Paperclip 活动日志怎么查：把 Agent 干过的每一次改动追回来
本文依据 Paperclip 官方仓库（github.com/paperclipai/paperclip，MIT 协议）的 docs/ 用户文档
与 doc/ 下的规范、运维与连接器手册整理，核对日 2026-08-17。
我们没有部署或运行过 Paperclip，因此不涉及界面外观与操作手感；
部分规范文档描述的是目标架构而非当前实现，文中已就地标注，不构成对实际行为的保证。
请以仓库最新内容为准。