> 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`.

### 套餐

提供三档方案，每档都有按月和按年的周期：

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

更高档位解锁的功能并不多，主要是降低相对于 **单次调用边际成本** 的按量付费基线。所有档位都“可访问全部内容”；你购买的是更便宜的推理，而不是受限的能力。

### 支付提供方

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

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

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

### 额度、充值与自动充值

除了订阅之外，你还拥有一个 **美元额度余额**。你可以查看余额、翻阅交易历史，并通过任一网关充值。 **自动充值** （仅 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 使用量和计算出的美元成本记录到一个仅追加的 JSONL 文件（`<workspace>/state/costs.jsonl`）中，保留内存中的日/月聚合，执行预算限制，并通过 JSON-RPC 提供一个 7 天仪表板。代理回合循环与仪表板处理器共享一个进程全局的单例跟踪器（回合循环会在每次提供方调用后记录遥测），因此每次调用都只会被持久化一次。

### 实时 token 与成本跟踪

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

### 预算与执行

预算执行在 `[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 秒轮询一次，并显示“已于 Ns 前更新”的新鲜度标记。当全局跟踪器尚未初始化时，会使用共享同一 JSONL 文件的只读回退跟踪器来提供 UI。

### RPC 接口

命名空间 `成本`，暴露为 `openhuman.cost_*`:

| 方法                       | 输入                            | 输出                        |
| ------------------------ | ----------------------------- | ------------------------- |
| `cost_get_dashboard`     | 无                             | 7 天分桶、汇总指标、预算利用率/状态、按模型明细 |
| `cost_get_daily_history` | `days?` （默认 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)