Openclaw Membership Billing Spec

# OpenClaw 会员与付费体系方案（Web + Client）

Status: Proposed  
Audience: Product, design, web, desktop/client, backend, operations  
Companions: [openclaw-web-platform-spec.md](openclaw-web-platform-spec.md), [openclaw-api-contract.md](openclaw-api-contract.md)

## 1. 背景

当前系统已经有工作区套餐字段 `planTier`，但该字段更偏向工作区形态与团队版本，不足以承载面向 C 端会员订阅、年度付费、充值钱包、模型可用范围、每日请求额度、模型倍率消耗等能力。

本方案用于在现有 OpenClaw Web 控制平面与本地客户端基础上，新增一套完整的会员与付费体系，目标是：

- 支持 `VIP`、`VIP 年度`、`VIP S`、`VIP S 年度`、`SVIP`、`SVIP 年度`
- 参考 GPT / Cursor 的“订阅 + 高级请求倍率 + 超额充值”机制
- 按会员等级控制每日请求量、可用模型范围、模型消耗倍率上限
- 让 Web 端成为会员、充值、账单、模型权限、配额管理中心
- 让客户端根据会员权益动态控制模型选择、请求发起、消耗统计与降级策略

---

## 2. 设计原则

### 2.1 核心原则

1. **订阅与算力分离**  
   订阅负责“身份、权益、每日基础额度、优先级”；充值负责“超额使用、突发使用、重度模型”。

2. **统一按标准请求折算**  
   用户界面展示“今日可用请求次数”，后端统一换算为 `quotaPoints`，避免不同模型价格差异直接暴露给用户。

3. **模型按倍率消耗**  
   类似 Cursor 的 premium request 思路，不同模型与不同运行方式使用不同倍率。

4. **Web 控制、客户端执行**  
   Web 负责发放权益与计费规则；客户端负责请求前校验、请求后上报、模型选择限制。

5. **可渐进演进到团队版**  
   当前先覆盖个人会员与小团队工作区，后续可叠加 Team / Business / Enterprise。

### 2.2 不建议直接复用现有 `planTier`

当前 [web/prisma/schema.prisma](web/prisma/schema.prisma) 中已有 `PlanTier = FREE | PRO | TEAM | BUSINESS | ENTERPRISE`，建议继续保留其“工作区/组织计划”语义；新增一套独立的会员订阅字段承载个人会员与充值逻辑，避免把 C 端会员和 B 端组织套餐混在一起。

---

## 3. 产品定义

## 3.1 会员层级

建议将“等级”和“计费周期”拆开建模：

- `MembershipTier`
  - `FREE`
  - `VIP`
  - `VIP_S`
  - `SVIP`
- `BillingCycle`
  - `MONTHLY`
  - `YEARLY`

对外售卖 SKU：

- `VIP_MONTHLY`
- `VIP_YEARLY`
- `VIP_S_MONTHLY`
- `VIP_S_YEARLY`
- `SVIP_MONTHLY`
- `SVIP_YEARLY`

> 这样既满足你要的 `VIP / VIP年度 / VIP S / VIP S年度 / SVIP / SVIP年度`，也便于后续价格后台配置。

## 3.2 核心计量单位

建议统一使用以下 3 个单位：

- `quotaPoints`：后端内部计费单位
- `standardRequests`：前端展示单位，`1 standardRequest = 10 quotaPoints`
- `walletCredits`：充值钱包余额，1:1 对应 `quotaPoints`

### 3.3 扣减顺序

每次请求按以下顺序扣减：

1. 当日会员额度 `dailyQuotaPoints`
2. 充值钱包 `walletCredits`
3. 若两者都不足，则提示升级会员或充值

---

## 4. 建议售价与 SKU

以下为首版建议价，已参考 GPT / Cursor 常见定价区间与年度折扣习惯，币种建议先用人民币，后台保留多币种能力。

| SKU | 建议售价 | 折算月价 | 年付优惠 | 目标人群 |
| --- | --- | --- | --- | --- |
| FREE | ¥0 | ¥0 | - | 试用用户 |
| VIP_MONTHLY | ¥39 / 月 | ¥39 | - | 日常轻中度用户 |
| VIP_YEARLY | ¥399 / 年 | ¥33.25 | 约 15% | 稳定个人用户 |
| VIP_S_MONTHLY | ¥99 / 月 | ¥99 | - | 高频生产用户 |
| VIP_S_YEARLY | ¥999 / 年 | ¥83.25 | 约 16% | 稳定高频用户 |
| SVIP_MONTHLY | ¥199 / 月 | ¥199 | - | 重度/专业用户 |
| SVIP_YEARLY | ¥1,999 / 年 | ¥166.58 | 约 16% | 专业工作流用户 |

### 4.1 定价逻辑

- `VIP` 对标大众可接受的订阅门槛，用于建立付费转化
- `VIP S` 对标“主力用户套餐”，承担大多数高频请求
- `SVIP` 对标“重度模型使用者 + 云任务 + Browser Operator”
- 年付统一保留约 15% - 18% 折扣，降低流失率

---

## 5. 权益矩阵

## 5.1 每日基础额度

| 会员等级 | 每日标准请求 | 对应 `dailyQuotaPoints` | 最大允许模型倍率 | 客户端可登录设备数 | 并发任务数 |
| --- | --- | --- | --- | --- | --- |
| FREE | 20 次/天 | 200 | 1x | 1 | 1 |
| VIP | 100 次/天 | 1000 | 2x | 2 | 2 |
| VIP S | 300 次/天 | 3000 | 4x | 3 | 3 |
| SVIP | 800 次/天 | 8000 | 6x | 5 | 5 |

> 年付与月付的每日额度一致，差异只在价格、活动权益、续费激励。

## 5.2 可用能力矩阵

| 能力 | FREE | VIP | VIP S | SVIP |
| --- | --- | --- | --- | --- |
| 基础对话模型 | ✅ | ✅ | ✅ | ✅ |
| 标准代码模型 | ✅ | ✅ | ✅ | ✅ |
| 高级推理模型 | ❌ | 部分 | ✅ | ✅ |
| 顶级重推理模型 | ❌ | ❌ | 部分 | ✅ |
| Browser Operator | ❌ | 试用额度 | ✅ | ✅ |
| 云端远程任务 | ❌ | 限量 | ✅ | ✅ |
| 批量自动化 | ❌ | ❌ | ✅ | ✅ |
| 优先队列 | ❌ | ✅ | ✅ | ✅+ |
| 专属活动赠点 | ❌ | ✅ | ✅ | ✅ |
| 充值加油包 | ✅ | ✅ | ✅ | ✅ |

### 5.3 首版建议的模型访问策略

建议不要直接按“具体模型名称”写死会员规则，而是先抽象为模型等级：

- `Lite`
- `Standard`
- `Advanced`
- `Max`
- `Research`

模型可由后台映射到等级，例如：

| 模型等级 | 示例模型 | 默认倍率 | 可用会员 |
| --- | --- | --- | --- |
| Lite | `gpt-4.1-mini`、`gemini-flash`、`claude-haiku` | 0.5x | FREE+ |
| Standard | `gpt-4.1`、`claude-sonnet`、`gemini-pro` | 1x | FREE+ |
| Advanced | `gpt-5`、`claude-opus`、高质量代码模型 | 2x | VIP+ |
| Max | 超长上下文/高推理预算模型 | 4x | VIP S+ |
| Research | 深度研究、复杂多步、重型代理模型 | 6x | SVIP |

---

## 6. 消耗倍率规则

## 6.1 基础公式

每次调用实际消耗：

$$
actualCostPoints = baseRequestPoints \times modelMultiplier \times toolMultiplier \times executionMultiplier
$$

默认取值：

- `baseRequestPoints = 10`
- `modelMultiplier`：由模型等级决定
- `toolMultiplier`：由工具链复杂度决定
- `executionMultiplier`：由执行位置决定

### 6.2 建议倍率

#### 模型倍率 `modelMultiplier`

| 模型等级 | 倍率 |
| --- | --- |
| Lite | 0.5 |
| Standard | 1 |
| Advanced | 2 |
| Max | 4 |
| Research | 6 |

#### 工具倍率 `toolMultiplier`

| 场景 | 倍率 | 说明 |
| --- | --- | --- |
| 纯对话 | 1.0 | 不调用额外工具 |
| 代码生成/文件编辑 | 1.2 | 常规开发任务 |
| Web 搜索/抓取 | 1.3 | 包含搜索和抓取成本 |
| Browser Operator | 2.0 | 浏览器自动化成本更高 |
| 图像/多模态处理 | 2.0 | 图片理解或生成 |

#### 执行倍率 `executionMultiplier`

| 执行方式 | 倍率 | 说明 |
| --- | --- | --- |
| Local | 1.0 | 本地执行 |
| Hybrid | 1.2 | 本地 + 云协同 |
| Cloud | 1.5 | 云端托管或远程运行 |

### 6.3 示例

- `Standard` 模型 + 本地纯对话  
  `10 × 1 × 1 × 1 = 10 points`，即 1 次标准请求
- `Advanced` 模型 + 代码生成 + 本地执行  
  `10 × 2 × 1.2 × 1 = 24 points`
- `Research` 模型 + Browser Operator + Cloud  
  `10 × 6 × 2 × 1.5 = 180 points`

> 前端展示时可同步显示“本次约消耗 18 次标准请求的 18%”或“预计消耗 180 点”。

---

## 7. 充值体系（加油包 / 钱包）

为避免高阶用户只靠订阅额度就消耗过大，建议增加充值包。

## 7.1 充值包建议

| 商品 | 售价 | 到账 `walletCredits` | 适用场景 |
| --- | --- | --- | --- |
| Starter Pack | ¥29 | 300 | 轻度补量 |
| Growth Pack | ¥99 | 1200 | 月中补量 |
| Power Pack | ¥199 | 2600 | 高级模型突发使用 |
| Pro Pack | ¥399 | 5600 | 重度任务周期 |

### 7.2 充值规则

- 钱包额度优先用于超出每日会员额度后的请求
- 钱包额度建议 **365 天有效**
- 可设置首充赠送 10%
- 活动赠点、邀请码奖励、售后补偿均统一进入 `walletCredits`
- 钱包流水必须可审计、可追溯、可退款回滚

### 7.3 推荐策略

- 免费用户可直接充值，但高级模型仍需会员门槛解锁
- `VIP` 可购买所有充值包，但最高只能用到 2x 倍率模型
- `VIP S` 可使用 4x 以内模型
- `SVIP` 可使用全模型池

---

## 8. 会员状态机

### 8.1 订阅状态

- `TRIAL`
- `ACTIVE`
- `PAST_DUE`
- `GRACE_PERIOD`
- `PAUSED`
- `CANCELED`
- `EXPIRED`

### 8.2 关键规则

1. 付款成功后立即生效
2. 到期未续费，进入 `GRACE_PERIOD`（建议 3 天）
3. 宽限期结束后降为 `FREE`
4. 降级时不清空钱包余额，只调整每日额度与模型权限
5. 年付取消后，权益保留到当前周期结束

---

## 9. Web 端产品需求

## 9.1 页面结构

建议新增或完善以下页面：

- `/pricing`：套餐页
- `/checkout`：下单页
- `/app/billing`：账单总览
- `/app/billing/subscription`：订阅管理
- `/app/billing/usage`：今日/近 7 天/近 30 天用量
- `/app/billing/wallet`：充值与钱包流水
- `/app/billing/invoices`：发票与订单
- `/app/settings/models`：模型可用范围与倍率说明
- `/admin/pricing`：运营后台价格配置
- `/admin/entitlements`：会员权益配置后台

### 9.2 套餐页必须展示的信息

每个套餐卡片必须展示：

- 月付 / 年付切换
- 每日标准请求数
- 支持的模型等级
- 最大倍率
- Browser Operator 是否可用
- 云端任务是否可用
- 优先级说明
- 是否支持充值叠加
- 推荐标签（如“最受欢迎”）

### 9.3 Billing 页核心模块

`/app/billing` 应包含：

1. 当前会员卡片
2. 今日剩余额度
3. 钱包余额
4. 最近 7 天用量趋势
5. 按模型等级统计消耗
6. 订单/发票入口
7. 升级会员入口
8. 充值入口
9. 风险提示（即将耗尽 / 即将续费 / 支付失败）

### 9.4 运营后台能力

后台需要支持：

- 配置套餐价格
- 配置每个 tier 的每日额度
- 配置模型等级与倍率
- 配置模型到等级的映射
- 配置充值商品
- 赠送钱包额度
- 人工冻结/解冻会员
- 人工调整配额
- 查看用户消费与异常行为

---

## 10. 客户端产品需求

客户端是会员权益执行层，必须从 Web 控制平面拉取实时权益。

## 10.1 客户端必须支持的能力

1. 登录后拉取当前用户/工作区的 `entitlements`
2. 在模型选择器中隐藏无权限模型
3. 显示每个模型的倍率标签，如 `1x`、`2x`、`4x`
4. 发起请求前先做额度预检
5. 请求完成后回传实际 `usage` 与 `cost`
6. 额度不足时提示升级或充值
7. 在离线模式下使用最近一次缓存权益，并限制高风险模型

### 10.2 客户端模型选择规则

基于现有模型选择和成本结构，可直接在客户端接入：

- 模型元数据：参考 [pi_agent_rust/src/provider.rs](../pi_agent_rust/src/provider.rs)
- 实际使用量结构：参考 [pi_agent_rust/src/model.rs](../pi_agent_rust/src/model.rs)
- 模型列表/选择器：参考 [pi_agent_rust/src/models.rs](../pi_agent_rust/src/models.rs) 与 [pi_agent_rust/src/model_selector.rs](../pi_agent_rust/src/model_selector.rs)

### 10.3 客户端交互建议

#### 模型选择器

每个模型显示：

- 模型名
- 模型等级（Lite / Standard / Advanced / Max / Research）
- 当前消耗倍率
- 当前用户是否可用
- 预计单次消耗区间

#### 输入框上方提示

显示：

- `今日剩余：86 次标准请求`
- `当前模型：Advanced · 2x`
- `本次任务预计：24 points`

#### 降级提示

当用户额度不足时：

- 优先推荐降级到低一档模型
- 若仍不足，提示去充值包页面
- 若会员门槛不足，提示升级会员

---

## 11. 后端 API 合同建议

建议新增以下接口。

## 11.1 套餐与权益

### `GET /api/billing/plans`

返回公开套餐矩阵。

### `GET /api/billing/entitlements`

返回当前用户在当前工作区下的权益快照：

```json
{
  "workspaceId": "ws_xxx",
  "membershipTier": "VIP_S",
  "billingCycle": "MONTHLY",
  "subscriptionStatus": "ACTIVE",
  "dailyQuotaPoints": 3000,
  "remainingDailyQuotaPoints": 1840,
  "walletCredits": 960,
  "maxModelMultiplier": 4,
  "allowedModelClasses": ["Lite", "Standard", "Advanced", "Max"],
  "allowedExecutionTargets": ["local", "hybrid", "cloud"],
  "featureFlags": {
    "browserOperator": true,
    "batchAutomation": true,
    "priorityQueue": true
  },
  "resetAt": "2026-03-11T00:00:00+08:00"
}
```

## 11.2 请求预检

### `POST /api/usage/preflight`

作用：客户端在真正发请求前，先检查当前模型和工具链是否可用、预计消耗多少。

请求：

```json
{
  "workspaceId": "ws_xxx",
  "model": "gpt-5",
  "modelClass": "Advanced",
  "executionTarget": "local",
  "toolKinds": ["code_edit"],
  "estimatedInputTokens": 12000,
  "estimatedOutputTokens": 4000
}
```

响应：

```json
{
  "allowed": true,
  "estimatedCostPoints": 24,
  "remainingDailyQuotaPoints": 1840,
  "walletCredits": 960,
  "fallbackModels": ["gpt-4.1", "claude-sonnet"]
}
```

## 11.3 请求完成回传

### `POST /api/usage/report`

客户端在任务结束后上报真实消耗。底层字段可直接复用现有 `Usage`/`Cost` 结构。

### `GET /api/billing/usage-summary?range=7d`

返回近 7 天、30 天、账期内用量。

## 11.4 支付与充值

- `POST /api/billing/checkout/session`
- `POST /api/billing/topup/session`
- `POST /api/billing/webhooks/provider`
- `GET /api/billing/invoices`
- `POST /api/billing/subscription/cancel`
- `POST /api/billing/subscription/resume`

---

## 12. 数据模型建议

## 12.1 建议新增枚举

- `MembershipTier`
- `BillingCycle`
- `SubscriptionStatus`
- `ModelClass`
- `WalletLedgerType`
- `PaymentProvider`
- `RechargeOrderStatus`

## 12.2 建议新增实体

### `BillingAccount`

- 归属 `workspaceId`
- 当前会员信息
- 默认支付方式
- 税务与发票信息

### `Subscription`

- `membershipTier`
- `billingCycle`
- `status`
- `periodStartAt`
- `periodEndAt`
- `cancelAtPeriodEnd`
- `providerSubscriptionId`

### `Wallet`

- `workspaceId`
- `balanceCredits`
- `currency`

### `WalletLedger`

记录所有变动：

- 充值
- 消费
- 退款
- 补偿
- 活动赠送
- 过期回收

### `UsageEvent`

记录每次请求真实消耗：

- `workspaceId`
- `userId`
- `taskRunId`
- `model`
- `modelClass`
- `executionTarget`
- `toolKinds`
- `usagePayload`
- `estimatedCostPoints`
- `actualCostPoints`
- `settledFrom`（daily quota / wallet / mixed）

### `DailyQuotaSnapshot`

用于高效计算每日剩余：

- `workspaceId`
- `date`
- `quotaPoints`
- `usedPoints`
- `remainingPoints`

### `ModelAccessPolicy`

用于后台配置：

- `modelId`
- `modelClass`
- `multiplier`
- `minTier`
- `enabled`

## 12.3 与现有 schema 的关系

当前 [web/prisma/schema.prisma](web/prisma/schema.prisma) 里的 `Workspace.planTier` 建议保留；会员付费能力新增在 `BillingAccount` / `Subscription` / `Wallet` 等实体，不要直接把 `VIP`、`SVIP` 写进现有 `PlanTier`。

---

## 13. 权限与风控

### 13.1 风控规则

- 短时间高频高倍率请求需限流
- Browser Operator、Cloud 模式需单独风控阈值
- 支付失败时暂停高成本能力
- 对异常账户可强制降为 `Lite/Standard only`

### 13.2 安全要求

- 所有账单流水要可审计
- 支付回调要幂等
- 额度扣减要防并发超扣
- 客户端本地只缓存权益快照，不缓存支付敏感信息

---

## 14. 首版落地建议

## Phase 1：基础可售卖

目标：先跑通会员和充值闭环。

- 套餐页 `/pricing`
- 订阅支付
- 充值包支付
- Billing 页面总览
- `GET /api/billing/entitlements`
- 客户端模型权限控制
- 客户端请求前预检 / 请求后上报

## Phase 2：增强体验

- 用量图表
- 自动降级推荐
- 到量提醒
- 年付续费提醒
- 优惠券、邀请码、首充赠点

## Phase 3：精细化运营

- 模型精细倍率策略
- 不同活动价格版本
- A/B 测试套餐页
- 团队共享配额池
- BYOK 降费策略

---

## 15. 最终建议（便于决策）

如果要尽快上线，建议首版直接采用以下组合：

### 套餐

- `FREE`：20 次/天
- `VIP`：¥39/月，100 次/天，最高 2x
- `VIP S`：¥99/月，300 次/天，最高 4x
- `SVIP`：¥199/月，800 次/天，最高 6x
- 年付统一 15% - 16% 折扣

### 充值

- ¥29 / 300 点
- ¥99 / 1200 点
- ¥199 / 2600 点
- ¥399 / 5600 点

### 展示口径

- 面向用户：展示“今日请求次数”“模型倍率”“钱包余额”
- 面向系统：统一按 `quotaPoints` 结算

### 控制逻辑

- Web 控制会员、支付、账单、套餐配置、模型权限
- 客户端执行模型过滤、额度预检、真实消耗上报
- 后端统一结算每日额度与钱包余额

该方案能较好兼容你当前的 Web 控制平面方向，也能直接指导客户端实现会员限制、模型选择控制和消耗指数管理。