CC Switch 接入、线路探活与余额查询

RootFlowAI 账户中心可以把 API Key、余额查询和备用线路一次导入 CC Switch，无需另外生成系统访问令牌或填写用户 UID。

不使用 CC Switch 也可以通过本文的 HTTP 接口和 Python 脚本查询账户余额，适用于其他桌面客户端、个人脚本和服务端集成。

一键导入

1. 登录 RootFlowAI 账户中心。
2. 找到需要使用的 API Key，点击「导入 CC Switch」。
3. 选择应用、主线路和模型。模型列表按当前令牌的分组与模型限制加载，默认选择版本数字最大的模型，也可以下拉切换；版本相同时保留列表顺序。
4. 检查名称，默认包含令牌名和所选模型，也可以自行修改。
5. 点击「打开 CC Switch」，在客户端确认导入并启用。

导入内容包括：

• 当前模型 API Key。
• 用户选中的默认主模型。每次导入一个模型，所有分组共用同一选择方式。
• 用户选中的主线路。
• 其余 RootFlowAI 备用线路。
• 每 5 分钟自动刷新的账户余额查询。

余额查询使用同一个模型 API Key，不保存门户登录状态，也不会发起模型请求或产生模型推理费用。

例如，国模特惠令牌可以选择 Codex，再选择 glm-5.3 或其他当前可用模型导入。模型列表表示令牌的可用范围，不代表所有模型都兼容所选客户端：Codex 需要 Responses 接口与工具调用支持。导入后仍使用旧默认模型时，请重启 Codex。

重复导入可能在 CC Switch 中新增配置；也可以直接在 CC Switch 编辑已有配置。此功能设置单个默认模型，不会一次向 Codex APP 的模型菜单添加全部模型。

国产模型导入 Claude Code

选择 Claude 后，可从当前令牌的可用模型中选择 deepseek-v4-pro、deepseek-v4.1-flash、glm-5.3、glm-5.3-flash、kimi-k3 或 qwen3.8-max。导入时，默认模型及 Opus、Sonnet、Haiku 三个别名均映射为所选模型，例如选择 glm-5.3 后四个位置都使用 glm-5.3。这些别名不代表模型具备原生 Claude 的全部能力。

Claude 使用所选线路的根地址，通过 /v1/messages 请求模型；无需手动给 Base URL 追加 /v1。实际使用需要该模型支持 Messages 协议及工具调用，导入成功本身不代表调用兼容性已经验证。启用配置后重新启动 Claude Code；若仍使用其他模型，检查启动参数、项目配置及已有环境变量是否覆盖了导入设置。

每次导入一个模型配置，换模型可再次导入并在 CC Switch 中选择对应配置；不会自动向 Claude 的模型菜单添加全部六个模型。门户更新或回滚不会自动修改已经导入的本地配置，需要时在 CC Switch 切回旧配置或重新导入。

2026-09-21 验证：上述六款模型均通过 Messages 流式文本、强制工具调用及工具结果续接测试。Claude Code 2.1.258 的实际文件读取测试中，DeepSeek 两款、GLM 两款和 Kimi 通过；Qwen 的一次自动工具选择测试未调用读取工具而直接生成了文件内容，强制调用 Read 则成功。因此暂不建议依赖 Qwen 自动完成文件操作，不能仅凭模型的文字描述判断操作已经执行。

该版本 Claude Code 可能提示这些模型不在内置模型目录中，并默认按 200K 上下文处理。此提示不代表模型 ID 导入失败，也不代表服务端实际支持 200K；长上下文能力需以所用模型和服务限制为准。

线路探活与测速

CC Switch 会把选中的线路作为主线路，其余线路作为测速候选。Codex 和 OpenCode 自动使用各线路的 /v1 地址。

线路测试表示目标地址能够返回 HTTP 响应，用于判断网络可达性和延迟；它不代表特定模型一定可用。余额查询成功可以验证 API Key 当前有效，但不验证该 Key 的模型权限。

不使用 CC Switch 时如何探活

可以向对应线路的 /api/status 发送不带 Key 的 GET 请求：

以主线路为例：

curl --silent --show-error --fail \
  --connect-timeout 5 --max-time 10 \
  --write-out '\nHTTP %{http_code}; total %{time_total}s\n' \
  https://api.rootflowai.com/api/status

预期为 HTTP 200，JSON 中的 success 为 true。time_total 是本次 HTTP 请求总耗时，包含连接与服务响应，并非模型首字延迟或生成速度。替换域名即可检查其他线路。

探活地址不需要追加 /v1，也不要用登录页、/v1/chat/completions 或 /v1/responses 代替探活。探活成功不代表某个模型或上游渠道一定可用。自行设置定时探活时建议至少间隔 60 秒，失败后退避重试。

CC Switch 余额检查脚本

新导入的 Provider 会自动携带余额配置。已有 Provider 可以打开「配置用量查询」，启用查询并选择「自定义」，填写：

将下面的完整脚本填入「提取器代码」，点击「测试脚本」，成功后保存配置：

({
  request: {
    url: "{{baseUrl}}/api/integrations/usage",
    method: "GET",
    headers: {
      "Authorization": "Bearer {{apiKey}}",
      "Accept": "application/json"
    }
  },
  extractor: function(response) {
    if (response.success && response.data) {
      return response.data;
    }
    return {
      isValid: false,
      invalidMessage: response.message || "用量查询失败"
    };
  }
})

{{baseUrl}} 和 {{apiKey}} 由 CC Switch 替换，保留占位符即可。这里的请求地址是门户域名 https://rootflowai.com，与模型请求使用的主线路、香港线路、美国线路地址不同。不要在请求地址后追加 /v1。

其他客户端与脚本查询余额

HTTP 接口

GET https://rootflowai.com/api/integrations/usage
Authorization: Bearer <你的 RootFlowAI 模型 API Key>
Accept: application/json

• 使用账户中心创建的模型 API Key，包含 sk- 前缀。无需系统访问令牌、用户 UID、Cookie 或门户登录状态。
• 只支持 GET；不要附加查询参数或请求体，也不要使用 HEAD。
• Key 仅通过 Authorization 请求头传递，不要放在 URL 中。
• 所有模型线路共用这个余额地址，不能将其域名替换成 api.rootflowai.com、hk.rootflowai.com 或 us.rootflowai.com。
• 查询成功不调用模型、不消耗模型推理额度。建议每 5 分钟查询一次，无需每次模型调用后都查询。
• 接口不提供浏览器跨域访问（CORS）。其他客户端应从桌面应用、本地脚本或自己的服务端发起请求；不要把 Key 写进公开网页代码。

curl 示例

下面的 Bash 示例交互读取 Key，不会把 Key 明文写入命令历史。运行时不要启用 set -x 或将带鉴权的请求输出到日志。

read -r -s -p 'RootFlowAI API Key: ' ROOTFLOWAI_API_KEY
printf '\n'
export ROOTFLOWAI_API_KEY

curl --silent --show-error --fail-with-body \
  --connect-timeout 5 --max-time 15 \
  --header "Authorization: Bearer ${ROOTFLOWAI_API_KEY}" \
  --header 'Accept: application/json' \
  https://rootflowai.com/api/integrations/usage

unset ROOTFLOWAI_API_KEY

Python 示例

下面的 Python 3 脚本仅使用标准库。它优先读取环境变量 ROOTFLOWAI_API_KEY，没有配置时会交互输入；每次运行只查询一次余额。

import getpass
import json
import os
import sys
import urllib.error
import urllib.request

key = os.environ.get("ROOTFLOWAI_API_KEY") or getpass.getpass("RootFlowAI API Key: ")
if not key.strip():
    sys.exit("API Key is required")

request = urllib.request.Request(
    "https://rootflowai.com/api/integrations/usage",
    headers={"Authorization": f"Bearer {key}", "Accept": "application/json"},
    method="GET",
)

try:
    with urllib.request.urlopen(request, timeout=15) as response:
        payload = json.load(response)
    if payload.get("success") is not True:
        sys.exit("Balance query failed")
    data = payload["data"]
    print(f"Remaining: {data['remaining']} {data['unit']}")
    print(f"Used: {data['used']} {data['unit']}")
    print(f"Total: {data['total']} {data['unit']}")
except urllib.error.HTTPError as error:
    print(f"Balance query failed: HTTP {error.code}", file=sys.stderr)
    if error.code == 429:
        print(f"Retry after {error.headers.get('Retry-After', '60')} seconds", file=sys.stderr)
    sys.exit(1)
except (urllib.error.URLError, TimeoutError):
    sys.exit("Network error or timeout; retry later")
except (ValueError, KeyError, TypeError):
    sys.exit("Unexpected balance response")

服务端集成时，通过部署环境或密钥管理工具注入 ROOTFLOWAI_API_KEY。不要将真实 Key 写入脚本、仓库、工单或监控标签。

返回数据与余额口径

成功响应示例，以下金额仅为演示：

{
  "success": true,
  "data": {
    "planName": "RootFlowAI",
    "remaining": 12.5,
    "used": 2.5,
    "total": 15,
    "unit": "USD"
  }
}

为什么显示 USD 或美元符号

接口为兼容客户端返回 unit: "USD"，CC Switch 因此可能显示 USD 或 $。这些数值代表 RootFlowAI 站内额度，不表示账户中持有真实美元；接口不会进行外汇换算。

例如，上面的 remaining: 12.5 表示剩余 12.5 站内额度。按当前充值规则，充值 1 元人民币获得 1 站内额度；赠送额度等因素还会影响实际资金成本，不能把客户端显示值当作可提现金额。价格单位与费用核对见计费说明。集成时保留接口字段，面向用户的说明应明确站内额度含义。

额度向下保留两位小数；各字段分别换算，展示值相加可能有 0.01 站内额度的尾差。响应带有 Cache-Control: no-store，集成时不要缓存并持续展示为实时余额。

返回的是账户额度，不是单个 API Key 的独立限额。即使 Key 配置为无限额度，也能查询账户余额；有限额 Key 还需保有可用额度。Key 的模型权限仍以账户中心配置为准。

错误处理与查询频率

错误响应通常包含 success: false 和 message；网络故障或中间代理异常也可能返回非 JSON 内容，应先判断 HTTP 状态再解析数据。不要将查询失败视为余额为零。

同一个 Key 的应用层限制为每分钟 12 次，此外还有按出口 IP 和全局执行的限流；共享出口或并发请求可能更早收到 429。推荐间隔 5 分钟，遇到 429 遵守 Retry-After，其他临时故障也应退避，避免立即循环重试。

常见问题

导入后没有余额查询

请升级到支持 deep link 用量配置的 CC Switch 新版本，然后从账户中心重新导入 Provider；也可以按本文的「CC Switch 余额检查脚本」为已有 Provider 手动配置。

提示 API Key 无效或不可用

检查该 Key 是否已禁用、过期、删除或耗尽。设置了 IP 白名单的 Key 还需要允许当前网络出口地址。

余额暂时不可用

余额服务异常或请求过于频繁时，CC Switch 会保留 Provider 的模型配置。稍后刷新余额即可，不需要重新导入 API Key。

余额与账户中心短暂不一致

充值或消费后，余额数据可能有秒级同步延迟。CC Switch 默认每 5 分钟自动刷新，也可以手动刷新。核对时还需注意，接口返回的是整个账户的累计用量，而非单个 Key 或当天用量。

::: warning 安全提示 API Key 可以调用模型并查询余额。不要把导入链接、API Key 或 CC Switch 配置文件发送给他人。