用量与账单 | JoyToken

JoyToken 会在模型调用成功后记录 tokens、Credits、模型、tier 和 API Key 归因。

你需要看什么

问题	看哪里
使用了哪个模型设置	`metadata.model`
消耗多少 Credits	`metadata.billing.credits_used`
输入 / 输出 token	`metadata.billing.input_tokens` / `metadata.billing.output_tokens`
哪把 Key 产生用量	JoyToken Console 日志和用量
使用哪个 tier	`metadata.tier`

响应账单字段

metadata 始终是数组。单模型响应只有一条；编排响应每个任务一条。总费用应将所有条目的 billing.credits_used 相加。

{
  "metadata": [
    {
      "model": "auto",
      "tier": "standard",
      "billing": {
        "credits_used": "0.2288",
        "input_tokens": 54,
        "output_tokens": 545
      }
    }
  ]
}

流式会在 [DONE] 前追加独立 metadata 事件：单模型响应发出一个事件，值为单元素数组；编排响应每个任务发出一个事件，值为单个对象。

用量归因

建议每个环境和 workflow 使用独立 API Key：

Workflow	推荐 Key
本地开发	`dev-chat-api`
集成接口	`integration-api`
OpenClaw / Hermes / IDE	`agent-key`
后台任务	`worker-summary`

控制成本

目标	做法
防止测试消耗过高	给测试 Key 设置较小预算
控制 Agent 成本	Agent / IDE 使用独立 Key 和预算
降低默认成本	使用 `model: "auto"` + `tier: "economy"`
稳定实验成本	固定 tier 或 Key 预算
排查单次调用	每次服务端请求带 `X-Request-ID`

余额不足

402 insufficient_quota 通常来自钱包余额、Key 预算或 tier 余额不足。处理顺序：

检查个人或组织钱包余额。
检查请求使用的 tier 是否有余额。
检查 API Key 的每日/每周预算。
如果自动路由没有候选模型，检查 tier、策略、钱包和 Key 预算。
premium 成本过高时，尝试 standard 或 economy。