【免费下载链接】codeburnFree, local tool to track AI coding token usage and cost across 37 tools and agents (Claude Code, Cursor, Codex, Gemini and more), by model, project, and task. npx codeburn项目地址https://gitcode.com/gh_mirrors/co/codeburn点击查看免费下载本文以开源项目 CodeBurn 中的 Vercel AI Gateway 数据源providers/vercel-gateway.ts为主线讲解它如何通过 Vercel Custom Reporting API 拉取 AI 网关的日级按模型聚合账单如何在默认情况下将其排除在 headline 总额之外以避免与本地工具重复计费以及如何用gateway-totals命令调整这一策略。读完本文你将掌握该 Provider 的认证方式、字段映射、去重键、缓存行为与排障流程并能结合源码与测试验证每一步的实际行为。一、数据从哪来一次远程 API 请求而非本地磁盘与大多数解析本地会话文件的 Provider 不同Vercel AI Gateway 是一个网络型数据源。从源码结构看其discoverSessions()在检测到认证凭据后返回一个合成会话源path: vercel-ai-gateway:report、project: Vercel AI Gateway并标记network: true见 src/providers/vercel-gateway.ts。CodeBurn 实际调用的是 Vercel 的 Custom Reporting 接口GET https://ai-gateway.vercel.sh/v1/report?start_date...end_date...date_partdaygroup_bymodel该 URL 与查询参数在源码中硬编码REPORT_URL见 src/providers/vercel-gateway.ts请求参数由fetchVercelGatewayReport(dateRange)构造见 src/providers/vercel-gateway.ts参数取值说明start_dateYYYY-MM-DDUTC日期范围的起始日由formatUtcDate按 UTC 生成end_dateYYYY-MM-DDUTC日期范围的结束日date_partday聚合粒度固定为“日”group_bymodel按模型聚合即每一行是一个“某天 × 某模型”的聚合记录请求携带Authorization: Bearer key与Accept: application/json响应体取body.results数组作为报告行。该能力对应 Vercel AI Gateway 的 Custom Reporting 功能需要账号开通 Pro/Enterprise 套餐。二、认证两个环境变量二选一文档规定设置以下任一环境变量即可源码见 src/providers/vercel-gateway.ts 的getVercelGatewayApiKey()AI_GATEWAY_API_KEY网关 API 密钥优先使用VERCEL_OIDC_TOKEN使用vercel dev时通过vercel env pull拉取到的 OIDC 令牌。取值逻辑为AI_GATEWAY_API_KEY ?? VERCEL_OIDC_TOKEN取到后先trim()再判空空串按“未配置”处理。两个环境变量都没有时Provider 直接静默降级discoverSessions()返回空数组不产生任何会话源fetchVercelGatewayReport()返回[]且整个过程中不会发出任何网络请求——测试emits no gateway rows at all without a credential专门验证了这一点见 tests/providers/vercel-gateway.test.ts。值得注意的是会话缓存层会记录该 Provider 的凭据依赖AI_GATEWAY_API_KEY/VERCEL_OIDC_TOKEN见 src/session-cache.ts这意味着凭据变化会影响缓存键的有效性判断。三、无缓存、单次请求、按日去重文档明确该 Provider 不做本地缓存每次 parse 针对请求的日期范围只发起一次 API 请求。这与本地文件型 Provider 形成鲜明对比。去重键为vercel-gateway:day:model见 src/providers/vercel-gateway.ts。由于报告本身就是按“天 × 模型”聚合的同一日期范围内重复 parse 时相同键的记录会被seenKeys集合拦截确保不会产生重复计数。另外无价值的行会被提前跳过当某行的total_cost、input_tokens、output_tokens全部为 0 时直接continue见 src/providers/vercel-gateway.ts避免为“零花费”的聚合行生成调用记录。四、字段映射一天一行一行代表整个模型当天的全部请求报告行结构在源码中以ReportRow类型定义见 src/providers/vercel-gateway.ts解析器将其逐字段映射为ParsedProviderCall报告字段映射目标说明daytimestamp${day}T12:00:00.000Z与sessionId${day}:${model}取 UTC 正午作为该天记录的时间戳modelmodel缺省时回退为unknowntotal_costcostUSD直接作为成本缺省为 0input_tokens/output_tokensinputTokens/outputTokens直接映射cached_input_tokenscacheReadInputTokens缓存读取 tokenscache_creation_input_tokenscacheCreationInputTokens缓存写入 tokensreasoning_tokensreasoningTokens推理 tokensrequest_countrequestCount仅当数值 1 时携带请求计数两个关键设计文档“Quirks”节的核心代码注释也写明total_cost直接作为costUSD这是网关“报告给谁的账单金额”不是由 tokens 按单价重算的估值。因此vercel-gateway被列入REPORTED_COST_PROVIDERS见 src/parser.ts其缓存成本在读取时原样返回、不会被价格表重算。request_count承载调用次数一行代表一整天某模型的多次请求但只生成一条调用记录。成本与 tokens 完整保留在这条记录上只有调用计数用于behavioralCallWeight等工作量加权读取request_count见 src/providers/vercel-gateway.ts。测试断言requestCount为 3、且端到端流程中totalApiCalls也为 3见 tests/providers/vercel-gateway.test.ts 与 tests/providers/vercel-gateway.test.ts。模型显示名modelDisplayName()会先按/拆分去掉 vendor/slug 前缀再交给全局短名表getShortModelName()归一化见 src/providers/vercel-gateway.ts。测试给出了两个可验证示例openai/gpt-5.6-terra→GPT-5.6 Terraaccounts/fireworks/models/kimi-k2p6→Kimi K2.6见 tests/providers/vercel-gateway.test.ts。五、为什么默认不计入总额双重计费的根因与排除机制这是本文档最有价值的部分。网关报告行是按天、按模型的聚合没有请求 id、时间戳或归属信息因此无法与任何本地工具记录做关联去重。而通过ANTHROPIC_BASE_URL指向网关的 Claude Code、以及 Codex、OpenCode、Cline/Roo/Kilo、Cursor 等工具都会在自己的会话文件里再次记录同一批请求。两边都计入同一笔花费就被统计了两次。因此 CodeBurn 采取如下默认策略始终单独展示网关花费永远作为独立的 provider 行显示应用中标注 “not in total”并在--format json输出中体现为overview.excludedGatewayCost见 src/main.ts默认排除不进入任何 headline 总计、按模型行、按日行与历史数据点可单独审视--provider vercel-gateway作用域下报告完整金额便于排查。排除规则的实现位置排除逻辑被集中在一个统一规则里从解析层到聚合层各司其职解析层定义AGGREGATE_ONLY_PROVIDER vercel-gateway见 src/parser.tsexcludesAggregateOnlyProviders()判定“全 Provider 读取且未开启计入”时排除见 src/parser.tsexcludeAggregateOnlyProjects()从语料中剔除聚合型 Provider 并重建所有嵌套合计见 src/parser.ts。无凭据的机器上语料为空输出与“没这条规则”的构建逐字节一致聚合层对日条目同样处理excludesGatewayFromTotals复用了同一规则excludeProviderFromDay()把网关切片从 day 级各汇总字段中扣减扣减结果做Math.max(0, ...)防负同时切片仍留在day.providers下供独立展示见 src/usage-aggregator.ts提示层文本输出时excludedGatewayNote()在 stderr 上提示“排除了 X 金额的 Vercel AI Gateway 日级总计本地工具可能已计入可用codeburn gateway-totals include纳入”见 src/format.ts由reportExcludedGatewayCost()在models、sessions、export、compare、compare-periods、spend、yield、audit、budget等独立报表入口统一触发见 src/main.ts。由于这是一条集中式规则report、交互式 dashboard、menubar 负载、models、sessions、export、compare、compare-periods、spend、yield、audit、budget以及 Teams 同步推送否则会把同一笔重复计数交给后端全部遵循同一行为。唯一的例外是缓存层session cache 与 daily cache 仍刻意保存网关切片因为某一天的聚合行永远无法再次拉取见 src/usage-aggregator.ts 的注释说明。用 gateway-totals 命令切换想要把网关计入总额使用gateway-totals命令实现见 src/main.tscodeburn gateway-totals include # 计入codeburn gateway-totals exclude 撤销 codeburn gateway-totals # 查看当前设置该命令支持--format text|jsonJSON 输出形如{includeGatewayInTotals: true}传非法模式时输出 usage 提示并置非零退出码。开关持久化在配置文件中includeGatewayInTotals字段见 src/config.ts每次命令运行前由preAction钩子同步到进程内状态见 src/main.ts。关键特性是纯读取侧read-side onlydaily cache 始终保存网关切片因此切换开关可以追溯性地作用于已封存的旧日数据无需重新拉取——这对“过去的某天永远无法重新获取”的聚合数据意义重大源码注释见 src/providers/vercel-gateway.ts 与 src/usage-aggregator.ts。六、已知限制与行为特性套餐门槛/v1/report需要 Vercel 账号开通 Pro/Enterprise 的 Custom Reporting数据延迟请求完成后报告数据可能延迟几分钟才可见聚合语义行是按天、按模型的聚合而非按对话会话chat session的明细无法做请求级归属计数语义request_count作为该行的调用次数即一行可代表多次请求但只携带一个成本与一个 token 数成本语义total_cost作为costUSDtoken 字段存在时直接映射成本不参与价格重算。七、排查与复现步骤文档“修 bug 时的清单”确认环境变量AI_GATEWAY_API_KEY或VERCEL_OIDC_TOKEN必须设置在运行codeburn的同一个 shell 中最小复现命令codeburn report --provider vercel-gateway -p week --format json在 Provider 作用域下观察完整金额对照核验将总计与 Vercel 控制台的 AI Gateway 用量视图进行比对。网络异常时fetchVercelGatewayReport()会在 stderr 输出codeburn: Vercel AI Gateway report failed (HTTP ...)或... report unreachable (...)并返回空数组而不是中断整个 parse见 src/providers/vercel-gateway.ts保证其他 Provider 的正常统计不受影响。八、源码级验证从端到端测试看完整链路tests/providers/vercel-gateway.test.ts 提供了从 mock 报告到真实聚合管线的端到端证据凭据驱动发现设置AI_GATEWAY_API_KEY后discoverSessions()恰好返回 1 个会话源未设置时返回空L24-L35行映射正确性mock 的total_cost: 1.25、request_count: 3分别落到costUSD与requestCountL37-L71合成源穿过指纹门槛回归测试专门验证了vercel-ai-gateway:report这个“磁盘上不存在文件”的合成源不会被fingerprintFile门槛丢弃网络 Provider 的费用能真实进入聚合管线并计入totalCostUSD同时requestCount在写入 session cache v9 后仍能原样读回L107-L138无凭据零请求无密钥时既不产出任何行也绝不调用fetchL140-L149。此外Provider 采用懒加载vercel-gateway列于懒加载名单仅在真正需要时才import(./vercel-gateway.js)避免无关场景的无谓开销见 src/providers/index.ts 与 src/providers/index.ts。总结Vercel AI Gateway 是 CodeBurn 中典型的网络型、聚合型、计费型数据源凭AI_GATEWAY_API_KEY/VERCEL_OIDC_TOKEN一次请求拉取日级按模型报告用vercel-gateway:day:model去重成本直接采用网关账单值并因无法与本地工具会话关联而默认排除在 headline 总额之外、只以独立行呈现。理解这套“集中式排除规则 读侧开关 缓存例外”的设计不仅能让你在接入网关时避免重复计费也能在排查金额差异时快速定位问题——需要时codeburn gateway-totals include即可一键将全部网关花费纳入统计。赞分享【免费下载链接】codeburnFree, local tool to track AI coding token usage and cost across 37 tools and agents (Claude Code, Cursor, Codex, Gemini and more), by model, project, and task. npx codeburn项目地址https://gitcode.com/gh_mirrors/co/codeburn点击查看免费下载相关推荐Awesome Flying FPV 计算机视觉篇OpenDroneMap开源航测与机器学习避障实战Awesome Flying FPV 计算机视觉篇OpenDroneMap开源航测与机器学习避障实战 Awesome Flying FPVawesome f人工智能AI Agent代码智能体Agent 工作流Agent 沙箱工具调用后端前端CodeBurn MCP Server 实现指南基于 stdio 的 codeburn mcp 用量与节省分析服务CodeBurn MCP Server 实现指南基于 stdio 的 codeburn mcp 用量与节省分析服务 CodeBurn 是一款在本机追踪 AIOpenClaw Vercel AI Gateway 插件参考用单个 API Key 接入多模型统一网关OpenClaw Vercel AI Gateway 插件参考用单个 API Key 接入多模型统一网关 本文围绕 OpenClaw 的 Vercel AIAI 应用AI Agent交互助手后端即时通讯网关创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考