用量查询

Olenro 的配额/余额展示分为两大类：自动查询（官方订阅类，开箱即用）和手动启用（内置模板 + 自定义脚本，需要用户配置后再显示）。

自动查询（官方订阅类）

v3.13.0 起，以下三类供应商在启用后会自动在卡片底部显示配额，用户无需任何额外配置：

这三类的共同特点是数据来源唯一且语义明确（官方订阅的使用率），不存在歧义，因此 Olenro 直接调用对应的官方或 OAuth 查询接口。

自动查询的交互

• 卡片底部显示：使用百分比 + 重置倒计时，颜色随使用率变化（< 70% 绿 / 70–89% 橙 / ≥ 90% 红）
• 手动刷新：点击卡片上的刷新图标按钮重新查询
• 卡片简化：对这三类供应商，健康检查和用量查询配置按钮会被自动隐藏，避免干扰内置展示
• 会话过期提示：如果 Token 无法刷新，卡片会显示「会话已过期」警告（Copilot / Codex OAuth）

手动启用（内置模板 + 自定义脚本）

除了上述三类自动查询的供应商，所有其他供应商（包括 Token Plan、第三方余额查询、以及各类中转服务）都需要在供应商卡片上手动打开「用量查询」开关后才会显示配额。

为什么需要手动启用？

一个重要原因是：同一个请求地址（同一家供应商）可能同时提供多种查询模式 —— 既可能有按套餐的配额查询，也可能有按账户余额的查询。Olenro 无法自动推断你想查哪一种，所以这类供应商的内置查询默认关闭，由你选择合适的模板后启用。

覆盖的内置模板

v3.13.0 为以下类别提供了开箱即用的内置模板，启用后无需手写脚本：

💡 除了以上内置模板外，对未被覆盖的供应商，你可以使用自定义脚本方式（见下文）编写自己的查询逻辑。

启用步骤

1. 鼠标悬停在供应商卡片上，显示操作按钮
2. 点击 用量查询 按钮（📊 图标）
3. 在配置面板顶部打开 启用用量查询 开关
4. 选择合适的内置模板（例如 Token Plan、第三方余额）或选择「自定义」
5. 按需填入 API Key / Base URL / Access Token 等参数（大多数情况可留空，使用供应商本身的凭据）
6. 点击「测试脚本」确认能正常返回
7. 保存配置 —— 下次激活该供应商时，配额将显示在卡片底部

⚠️ 注意：启用后的自动刷新间隔通过「自动查询间隔」字段控制（设为 0 禁用自动刷新），仅当供应商处于「当前启用」状态时才会触发后台查询。

自定义脚本查询（高级）

功能说明

当供应商不在内置模板覆盖范围内时，你可以用 JavaScript 编写自定义查询脚本。适用于中转服务、私有部署、特殊格式 API 等。

使用场景：

• 查看 API 账户剩余余额
• 监控套餐使用情况
• 多套餐额度汇总显示

打开配置

1. 鼠标悬停在供应商卡片上，显示操作按钮
2. 点击「用量查询」按钮（📊 图标）
3. 打开用量查询配置面板

启用用量查询

在配置面板顶部，开启「启用用量查询」开关。

预设模板

Olenro 提供三种预设模板：

自定义模板

完全自定义请求和提取逻辑，适用于特殊 API 格式。

通用模板

适用于大多数标准 API 格式的供应商：

({
  request: {
    url: "{{baseUrl}}/user/balance",
    method: "GET",
    headers: {
      "Authorization": "Bearer {{apiKey}}",
      "User-Agent": "olenro/1.0"
    }
  },
  extractor: function(response) {
    return {
      isValid: response.is_active || true,
      remaining: response.balance,
      unit: "USD"
    };
  }
})

配置参数：

New API 模板

专为 New API 类型的中转服务设计：

({
  request: {
    url: "{{baseUrl}}/api/user/self",
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer {{accessToken}}",
      "New-Api-User": "{{userId}}"
    },
  },
  extractor: function (response) {
    if (response.success && response.data) {
      return {
        planName: response.data.group || "默认套餐",
        remaining: response.data.quota / 500000,
        used: response.data.used_quota / 500000,
        total: (response.data.quota + response.data.used_quota) / 500000,
        unit: "USD",
      };
    }
    return {
      isValid: false,
      invalidMessage: response.message || "查询失败"
    };
  },
})

配置参数：

通用配置

超时时间

请求超时时间（秒），默认 10 秒。

自动查询间隔

自动刷新用量数据的间隔（分钟）：

• 设为 0 表示禁用自动查询
• 范围：0-1440 分钟（最长 24 小时）
• 仅当供应商处于「当前启用」状态时生效

提取器返回格式

提取器函数返回包含以下字段的对象，所有字段均可选：

测试脚本

配置完成后，点击「测试脚本」按钮验证：

1. 发送请求到配置的 URL
2. 执行提取器函数
3. 显示返回结果或错误信息

显示效果

配置成功后，供应商卡片上会显示：

• 单套餐：直接显示剩余额度
• 多套餐：显示套餐数量，点击展开查看详情

变量占位符

脚本中可使用以下占位符，运行时自动替换：

常见供应商配置示例

故障排除

自动查询未显示配额（官方订阅类）

检查：

1. 确认供应商是官方订阅类 —— Claude / Codex / Gemini 官方登录、GitHub Copilot、Codex OAuth 反向代理
2. 供应商是否处于「当前启用」状态（非激活时不会触发查询）
3. 对于 OAuth 类型（Copilot / Codex OAuth），检查 Token 是否仍在有效期内；如果卡片显示「会话已过期」，请到 OAuth 认证中心重新登录
4. 网络是否可访问官方配额接口

手动启用后仍未显示配额

检查：

1. 供应商卡片的「用量查询」面板顶部启用用量查询开关是否已打开
2. 是否选择了合适的内置模板（Token Plan / 第三方余额 / 自定义）
3. 点击「测试脚本」查看返回的具体错误信息
4. API Key / Base URL 等必要字段是否填写正确
5. 网络是否可访问供应商的配额端点
6. 仅当供应商处于「当前启用」状态时，后台自动查询才会生效

查询失败

检查：

1. API Key 是否正确
2. Base URL 是否正确
3. 网络是否可访问
4. 超时时间是否足够

返回数据为空

检查：

1. 提取器函数是否有 return 语句
2. 响应数据结构是否与提取器匹配
3. 使用「测试脚本」查看原始响应

格式化失败

脚本语法错误时，点击「格式化」按钮会提示错误位置。

注意事项

• 用量查询会消耗少量 API 请求配额
• 建议设置合理的自动查询间隔，避免频繁请求
• 敏感信息（API Key、Token）会安全存储在本地