Paperclip 成本报表怎么看：适配器怎么上报、字段有哪些、三个查询口径分别答什么

2026-08-17

站内工具大模型 API 价格对比表 → 豆包 / GLM / Kimi / 千问 / DeepSeek 等 9 家厂商单价并排看，可按币种筛选、按价格排序，每行链到官方定价页。

一堆 Agent 跑了一个月，账单出来了，接下来的问题永远是同一个：钱到底花在谁身上、花在哪个项目上。

如果你只在面板上看到一个总数，那这笔账是查不下去的。要能查下去，前提是每一次模型调用都在某个地方留下过一条结构化记录，而不是事后拿账单反推。Paperclip 的做法就是前者：它把「花了多少」拆成上报、记录、聚合三段，每段都有明确的产出物。

这篇不讲预算阈值怎么设、超了怎么办（那是预算与「token 工资」超支怎么控那篇的事），只讲数据本身——谁产生它、它长什么样、你能用什么姿势把它查出来。

成本数据不是 Agent 自己写的，是适配器代劳的

第一个容易搞反的点：在 Paperclip 里，上报成本这件事默认不由 Agent 的业务逻辑负责，而是发生在适配器（adapter）这一层。

官方文档写得很直白：成本上报是通过适配器自动完成的。触发时机是一次 Agent 心跳完成之后——适配器去解析这次 Agent 的输出，从里面把用量信息抽出来。抽完之后，服务端把它记为一条成本事件（cost event），供后续的预算跟踪使用。

这个设计决定了两件事。

一是你换执行层不用重写记账。不管底下接的是哪一类适配器，记账动作都收敛在适配器里，上层的公司、项目、预算逻辑看到的都是统一格式的成本事件。适配器分几类、各自怎么接，见五类适配器分别怎么接。

二是账的颗粒度天然跟心跳绑定。心跳是 Paperclip 驱动 Agent 干活的基本节拍，成本事件也就挂在这个节拍上。所以当你发现某个 Agent 的成本记录长时间不增长，先别急着怀疑记账链路，很可能是它压根没在跑——这时该查的是心跳和看门狗，参见Agent 不干活：心跳、看门狗、卡住怎么查。

一条成本事件里到底有什么

适配器解析出来的字段，官方文档列了五项：

字段	含义	文档给的示例
Provider	用的是哪家 LLM 供应商	`anthropic`、`openai`
Model	用的是哪个模型	`claude-sonnet-4-20250514`
Input tokens	发给模型的 token 数	—
Output tokens	模型生成的 token 数	—
Cost	这次调用的美元成本	—

注意最后一行的限定条件，原文写的是「if available from the runtime」——这次调用的金额，只在运行时能提供的时候才有。

这句话的分量比看上去重。它意味着 provider、model、输入输出 token 数这几项是解析输出就能拿到的，而金额是个可能缺席的字段。如果你接的执行层本身不回吐费用信息，那么这条成本事件里有 token 数、未必有钱数。做对账的时候，这是第一个要确认的地方：你看到的金额到底是运行时给的，还是压根没有。至于缺失时系统会不会按某套价目表折算、折算规则是什么，官方文档没有说明，别自己假设。

也可以绕过适配器直接上报

自动上报之外，成本事件是可以直接 POST 的：

POST /api/companies/{companyId}/cost-events
{
  "agentId": "{agentId}",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "inputTokens": 15000,
  "outputTokens": 3000,
  "costCents": 12
}

请求体的字段名值得逐个记一下，因为它跟前面那张概念表不是一一对应的写法：agentId 指明这笔账算谁头上，provider 和 model 是字符串，token 数是 inputTokens / outputTokens，金额字段叫 costCents——单位是「分」，不是美元。示例里的 12 是 12 美分，不是 12 美元。这个单位如果搞错，报表会直接差两个数量级。

顺带说一句，预算侧用的也是同一套单位习惯，公司预算和 Agent 预算都写作 budgetMonthlyCents。整条成本链路上，钱一律以分为整数单位流转，没有小数。

什么时候需要手工 POST？文档给的口径是「通常由适配器在每次心跳后自动上报」，也就是说手工上报属于补充路径而非主路径。同时它在最佳实践里给了一条明确的反面提醒：让适配器负责成本上报，不要重复上报。你在 Agent 逻辑里再 POST 一遍，得到的不是双保险，是把同一笔花销记了两次。

查账的三个口径，各答各的问题

聚合查询这边，官方给了三个接口，是三个不同的切面，别混着用：

接口	回答的问题	返回内容
`GET /api/companies/{companyId}/costs/summary`	这家公司这个月一共花了多少、还剩多少	当月总支出、预算、使用率
`GET /api/companies/{companyId}/costs/by-agent`	钱花在哪些 Agent 身上	当月按 Agent 拆分的明细
`GET /api/companies/{companyId}/costs/by-project`	钱花在哪些项目上	当月按项目拆分的明细

三个接口有一个共同的隐含前提：返回的都是「当月」（current month）数据。这是理解 Paperclip 成本视图的关键——它默认是一个月度视图，而不是任意时间段的查询工具。

配套的规则是预算窗口的重置时间：每月 1 日（UTC）重置。注意是 UTC，不是你所在时区的月初。对国内团队来说，UTC 月初对应的是北京时间当月 1 日 8:00，也就是说月初那几个小时里，你看到的当月数字和你直觉里的「这个月」会错开一段。做月度复盘、或者写脚本定时抓数的时候，这个八小时的错位值得先算清楚。

至于超出当月范围的历史数据能不能查、有没有按时间段过滤的参数、明细返回多少条、要不要分页，这三个接口的文档都没有写。需要长期趋势的话，稳妥做法是自己定期把 summary 的结果落到外部存储里，而不是指望接口能回溯。

想把这些数字摆到界面上看，可以配合仪表盘与状态卡片怎么读那篇一起看。

Agent 自己怎么读自己的账

上面三个是给「查账的人」用的。Agent 本身还有一个自查入口：

GET /api/agents/me
# Check: spentMonthlyCents vs budgetMonthlyCents

两个字段的名字直接说明了用法——spentMonthlyCents 是本月已花，budgetMonthlyCents 是本月预算，都是分。文档建议 Agent 在每次心跳的开头就查一次，理由很实在：早点知道额度状况，才不会把工作做到一半才发现没钱了，白干一场。

具体的行为建议是：使用率超过 80% 时，只做关键任务，低优先级的先跳过；到 100% 会被自动暂停。如果是在任务执行中途发现额度快见底，文档给的动作是留一条评论说明情况，然后体面退出，而不是硬撑到被强制中断。

这几条严格来说属于「Agent 开发者应当写进自己 Agent 逻辑里的约定」，而不是平台替你做的事——平台负责的是暂停这个硬动作，80% 之后要不要收着干，得你自己在代码里判断。

账对不上的时候，按这个顺序排查

把上面的机制串起来，出问题时的排查顺序其实是固定的：

成本事件有没有产生——Agent 这段时间跑过心跳吗？没有心跳就没有上报，这是源头。
事件里有没有金额——costCents 依赖运行时能不能提供，token 数在、钱数缺是可能的正常状态。
是不是重复记了——检查自己的 Agent 代码里有没有在适配器之外又 POST 了一次 cost-events。
口径对不对——summary 是公司总账，by-agent 和 by-project 是两个不同维度的拆分，拿其中一个的数字去核另一个的总和之前，先确认你比的是同一个维度。
月份边界对不对——所有接口都是当月视图，重置点是 UTC 月初。

想追到具体是哪次操作产生的花销，得配合活动日志一起看，成本接口本身返回的是聚合结果，不是逐笔流水。

这套机制没覆盖的部分

说几个官方文档里明确没有的东西，免得你按错误的预期去设计流程。

没有跨月的历史查询接口。 三个聚合接口一律是当月。要做同比环比、要看某个项目三个月的曲线，得自己在外面攒数据。

没有说明成本事件的保留期限。 数据存多久、会不会被清理，文档没写。

金额不保证一定有。 前面说过，costCents 取决于运行时能不能提供。以「金额一定存在」为前提写的告警逻辑，换个执行层就可能失效，用 token 数做兜底指标更稳。

成本归属只在事件层面确定。 一条成本事件带的是 agentId，项目维度的拆分由系统聚合给出，具体是按什么关系归属到项目的，文档没有展开。

这是记账，不是限流。 成本事件是事后记录，它记的是已经花掉的钱。真正拦住花销的是预算侧的 80%/100% 两道线，那套机制的具体行为和配置，还是回到预算那篇看。

如果你现在要做的事是「把这个月的钱花在哪讲清楚」，那 summary 加 by-agent、by-project 三个接口足够；如果要做的是「建一套能看半年趋势的成本看板」，那第一步不是找接口，而是先搭一个定时抓取和落库的活儿。

延伸阅读

从头读起：Paperclip 是什么：一个自己不跑 Agent 的控制平面，怎么管住一整家 AI 公司
本专题共 40 篇，完整分组目录见专题页
Paperclip 活动日志怎么查：把 Agent 干过的每一次改动追回来
Paperclip 仪表盘与状态卡片怎么读：五组指标的口径、数据来源与刷新机制

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