> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/gong-neng/billing-and-usage.md).

# 计费、成本与用量

OpenHuman 维护两本相关但彼此分开的账本。 **计费** 是你支付给托管后端的部分：套餐、信用充值、已保存的卡和优惠券，全部通过 Stripe 或 Coinbase 结算。 **成本与用量** 是代理代表你花费的部分，按每次提供方调用在本地跟踪，因此你可以在账单到来之前看到（并限制）真实的 token 支出。

第一本在云端；第二本从不离开你的工作区。

***

## 第 1 部分：计费与支付

这个 `计费` 域是一个薄 RPC 适配器。它只包含 **没有自己的支付逻辑或状态**。每个操作都会把经过身份验证的 HTTPS 调用转发到托管后端（`/payments/*`, `/coupons/*`）并使用你存储的应用会话 JWT，且原样返回 JSON 响应。授权、套餐归属和支付策略都由后端强制执行。缺失或无效的会话会返回后端的 `401`/`403` ；JWT 和卡数据绝不会被记录。

在 HTTP 之前，适配器只做轻量输入校验：非空的套餐/优惠券/支付方式 id，有限且为正的 `amountUsd`金额，以及网关白名单仅限 `stripe` / `coinbase`.

### 套餐

提供三种层级，每种都有月度和年度周期：

| 级别      | 月付      | 年付        | 相较按量付费的每次调用折扣 |
| ------- | ------- | --------- | ------------- |
| **免费**  | $0      | $0        | 无（按量付费基线）     |
| **基础版** | $19.99  | $199      | 每次调用便宜 50%    |
| **专业版** | $199.99 | $1,799.99 | 每次调用便宜 90%    |

更高层级并不是解锁功能，而是降低 **每次调用的差额** 相较按量付费基线。所有层级都拥有“全部访问权限”；你购买的是更便宜的推理，而不是受限功能。

### 支付提供方

只接入了两个网关，而且仅有这两个：

* **Stripe**：套餐购买（Checkout 会话）、客户账单门户、信用充值、已保存卡管理（SetupIntents）以及自动充值。
* **Coinbase Commerce**：加密货币支付，用于信用充值和年度计费。

`top_up_credits` 以及 `create_coinbase_charge` 默认使用 `stripe` 该网关和 `年度` 周期；空网关或仅空白的网关会归一化为 Stripe。

### 信用、充值与自动充值

除了订阅之外，你还持有一个 **USD 信用余额**。你可以查看余额、分页浏览交易历史，并通过任一网关进行充值。 **自动充值** （仅 Stripe）会在余额不足时从已保存的卡中补充信用；你可以读取和更新其设置，并列出 / 添加 / 更新 / 删除已保存的卡。添加卡会创建一个 Stripe SetupIntent；删除卡会被视为危险操作。

### 优惠券

优惠券代码会在后端兑换（`POST /coupons/redeem`），并且你可以列出当前已在账户中兑换的优惠券（`GET /coupons/me`).

### 应用中的计费位置

桌面端 **设置 → 计费** 面板刻意不内嵌支付 UI。它会跳转到托管的网页 **计费仪表板**，这是管理套餐、卡和发票的唯一地方。代理也可以通过默认开启的工具读取计费状态（套餐、余额、交易、卡片、优惠券、Stripe 门户链接）；所有涉及资金流动或支付方式变更的操作都默认关闭，并由 **默认关闭** 通过 `billing_writes` 开关控制，且卡片删除被标记为危险。

### RPC 接口

命名空间 `计费`，公开为 `openhuman.billing_*` （15 个方法），例如 `billing_get_current_plan`, `billing_get_balance`, `billing_get_transactions`, `billing_purchase_plan`, `billing_top_up`, `billing_create_coinbase_charge`, `billing_get_cards`, `billing_create_setup_intent`, `billing_update_auto_recharge`, `billing_redeem_coupon`.

***

## 第 2 部分：成本与用量仪表板

这个 `成本` 域完全在本地。它会将每次提供方调用的 token 用量和计算出的 USD 成本记录到一个只追加的 JSONL 文件（`<workspace>/state/costs.jsonl`），维护内存中的日/月聚合，执行预算限制，并通过 JSON-RPC 提供一个 7 天仪表板。一个进程级单例跟踪器由代理轮询循环（它在每次提供方调用后记录遥测）和仪表板处理器共享，因此每次调用都只持久化一次。

### 实时 token 与成本跟踪

对于每次调用，每次调用成本会根据 token 数量和每百万 token 的价格计算得出（将非有限或负数价格截断为 `0.0`）。当提供方回显一个权威的 `charged_amount_usd` 时，该值优先生效；否则 OpenHuman 会回退到已知模型的静态定价目录。用量按 UTC 分桶，以模型为键，提供方则从 **提供方** 派生自 `提供方/模型` 前缀。全为零的用量载荷会被跳过，因此不报告用量的提供方不会抬高请求计数。

### 预算与强制执行

预算强制执行在 `[cost]` 配置块下配置：

| 设置项                 | 默认       | 角色                  |
| ------------------- | -------- | ------------------- |
| `启用`                | `true`   | 门控 **仅强制执行**，不是遥测   |
| `daily_limit_usd`   | `10.00`  | 每日硬上限               |
| `monthly_limit_usd` | `100.00` | 每月硬上限               |
| `warn_at_percent`   | `80`     | 警告阈值 `check_budget` |

`check_budget` 返回 `允许`, `警告` （已达到警告阈值）或 `超出` （超过每日或每月上限）。一个关键细节： **`启用` 它控制的是强制执行，而不是记录。** 当它为 `false`, `check_budget` 始终返回 `允许` 并且硬上限关闭。代理仍会无条件记录用量，因此你的消费历史会不断累积，你可以在 *之前* 决定启用硬上限。 `dashboard.enabled = false`；要清除历史记录，请删除该 JSONL 文件（它是本地文件，永远不会离开工作区）。

### 7 天仪表板

设置 → **用量与限制** 承载成本仪表板（以及后台活动控制）。它呈现 7 天每日历史（间隔天补零，最旧在前）、token 用量图表、月度进度预测、预算利用率以及按模型划分的成本明细。仪表板的颜色编码使用月度预算的比例：当达到 `warn_threshold` （默认 `0.8`）时，条形会变成琥珀色，在 `alert_threshold` （默认 `0.95`). `budget_utilization` 会被截断为 `1.0` 以便显示，而状态则根据原始值计算。面板大约每 10 秒轮询一次，并显示 “Updated Ns ago” 新鲜度标签。当全局跟踪器尚未初始化时，一个只读的回退跟踪器（共享同一个 JSONL 文件）会提供 UI。

### RPC 接口

命名空间 `成本`，公开为 `openhuman.cost_*`:

| 方法                       | 输入                          | 输出                          |
| ------------------------ | --------------------------- | --------------------------- |
| `cost_get_dashboard`     | 无                           | 7 天分桶、摘要指标、预算利用率/状态、按模型划分明细 |
| `cost_get_daily_history` | `天数？` （默认 7，限制在 1 到 366 之间） | 按顺序排列的每日条目，最旧在前，间隔已补零       |
| `cost_get_summary`       | 无                           | 实时会话 / 每日 / 每月成本摘要          |

这些也作为只读、默认开启的代理工具公开，因此代理可以检查自己的支出。

***

## 成本与 token 压缩

因为成本跟踪的是 **实际 token 数量**，所以任何缩短提示词的做法都会直接降低支出。OpenHuman 的 [TokenJuice token 压缩](/openhuman/zh/gong-neng/token-compression.md) 会减少每次调用发送的 token，而 [模型路由](/openhuman/zh/gong-neng/model-routing.md) 会把任务发送给能处理它的最便宜模型。两者都会在仪表板中表现为更低的条形和更慢的预算消耗。

***

## 另请参阅

* [Token 压缩（TokenJuice）](/openhuman/zh/gong-neng/token-compression.md)
* [模型路由](/openhuman/zh/gong-neng/model-routing.md)