ModelSwap 使用文档

01ModelSwap 桌面端（开源）

桌面端负责本地功能：加密密钥库、模型平台与 Agent 配置切换、用量查询、快照回滚。密钥只在你的机器上，无需注册。

安装与启动

npm install -g modelswap
modelswap web

浏览器扩展、自动创建密钥、CLI 速查等完整说明见开源仓库《使用手册》： user-manual.md ↗。

02账号与登录

网页右上角「登录」打开登录弹窗，支持 Google 与 GitHub；邮箱注册登录即将上线。网页与桌面端共用同一账号。

多设备

每台登录过的设备对应一个设备记录，可在账号中心查看并吊销。吊销后该设备的会话立即失效，云端数据保留。

退出

网页：右上角账号菜单 →「退出登录」；桌面端：设置页退出。

03Cloud Pro 订阅

价格 $7/月 或 $59/年（省 30%），经 Stripe 结算：国际信用卡、Apple Pay、Google Pay。

• 支付成功后权益自动开通，右上角出现账号头像即已生效；打开桌面端并登录同一账号，开始同步云端用量。
• 随时取消，权益用到到期日。
• 到期只停云端（用量历史、告警、多设备），本地功能不受影响。

04Cloud 收集什么

云端只接收用量数字，不接收密钥：每条用量事件包含平台、用量百分比 / 剩余量、窗口类型与采集时间。

• 平台白名单 37 个（订阅 17 + 预付费 20），白名单外一律拒绝；
• 字段白名单：未知字段整批拒绝；单条事件 ≤ 4KB，批量 ≤ 256KB；
• API Key 与 Cookie 永不上传。

05用量历史

桌面端上报的用量按天聚合为快照（平台账号 × 窗口类型 × 日期），跨设备查看历史曲线与余量趋势，便于发现长期用量变化。

06告警（Webhook）

为用量设置阈值规则，越线时向你的 Webhook 推送。任何接受 Webhook 的通知服务都能接。

创建规则

• 指标：用量百分比（如 5 小时窗口剩余 8%）、剩余金额、剩余数量；
• 阈值与比较符：≥ / ≤；可指定单个平台或全部平台；
• Webhook 需为公网可访问的 HTTPS 地址。

推送行为

触发与恢复各推送一次（alert.firing / alert.recovered），不重复轰炸；失败自动重试，重试携带相同幂等键，接收方可据此去重。

{
  "type": "alert.firing",
  "rule_id": "6f1e2c…",
  "rule_metric": "used_percent",
  "comparator": ">=",
  "threshold": 90,
  "value": 92.5,
  "provider_id": "anthropic",
  "window_type": "5h",
  "transition_id": "8d3a…",
  "occurred_at": "2026-08-20T04:15:00.000Z"
}

07隐私

这些数据权利不需要订阅。所有操作记录在审计日志中。

• 导出：云端全部数据打包为 gzip JSON 下载；
• 删除用量数据：清空云端用量历史；
• 注销账号：邮箱验证码二次确认 → 30 天冷静期 → 到期彻底删除；冷静期内可申请取消注销。

08常见问题

告警没有收到？

依次检查：规则已启用；Webhook 公网可达；同一次越线只推一次（触发 / 恢复），确认没有漏看；用量事件正在同步。

支付渠道与退款

经 Stripe 结算，支持国际信用卡、Apple Pay、Google Pay。取消订阅后权益用到到期日；账号注销 30 天内可反悔。

密钥会传上云吗？

不会。云端白名单限制 + 体积上限，自动化测试把关敏感字段；API Key 与 Cookie 永不上传。