零依赖的 Node.js 本地/服务器代理 + 网页控制台，用于 Cline Pass 订阅：

• 🔍 上游枚举与校验 —— 列出订阅模型背后每一条上游渠道，并一键实测哪些「✔可用 / ⏳限流 / ✘不可钉」
• 🎯 精确钉住上游 —— 严格钉住 / 优先+回退两种模式，支持按最低成本、最快首字、最高吞吐排序
• 🧬 多上游优先级故障转移（2026-09-06 新增） —— 勾选多个上游即按勾选顺序逐个尝试：第一个异常（报错 / 网络失败 / 超时）自动顺切下一个，全部失败才透传错误；每次尝试有独立 120s 超时与逐次尝试明细（请求头 X-Cline-Target-Upstream: a>b 与 X-Cline-Attempts，历史与测试台展示逐次尝试路径 upstream(502) 到 upstream(200)）
• 🚫 上游排除 —— 勾「排除」的渠道永不被使用：勾选模式下从候选中剔除；自动模式与优先+回退模式下把排除换算成 only 白名单（已知上游 - 排除项）注入，两类管道均实测生效；网关侧渠道清单更新导致白名单过期时，报错中附带的最新渠道清单会被自动学习合并
• 👥 账号池 —— 多账号管理、手动切换、轮询均衡、逐账号连通性测试与用量统计
• 📊 观测 —— 每条请求自动记录实际命中的渠道、背后模型、耗时（含流式）
• 🔑 代理密钥 —— 给下游客户端发一把独立密钥，可随时在页面轮换
• 🌐 OpenAI 兼容 —— 任何 OpenAI 客户端 / Cline 扩展把 Base URL 指向代理即可，无侵入

git clone https://github.com/<你的用户名>/cline-pass-switcher.git
cd cline-pass-switcher
node server.js        # 仅需 Node ≥ 18，无需 npm install

打开 http://127.0.0.1:3123/，在「账号管理」里添加你的 Cline Pass 账号（sk_ 开头的 key）并保存即可。 没有 key 也能启动：页面会提示配置入口。

Cline Pass key 从哪里来？购买 Cline Pass 订阅后，在 Cline 的账户设置里创建 API Key。 订阅模型 ID 均为 cline-pass/* 前缀（如 cline-pass/glm-5.2）。

客户端接入（任何 OpenAI 兼容工具）：

Base URL: http://127.0.0.1:3123/v1
API Key:  （在控制台「访问与安全」里设置代理密钥；本地留空 = 不鉴权）
Model:    cline-pass/glm-5.2 等

mkdir -p data && cp config.example.json data/config.json
# 编辑 data/config.json，或在启动时用环境变量注入 key

# 有域名（A 记录指向服务器，自动签发 Let's Encrypt 受信证书）：
CPASS_DOMAIN=pass.example.com docker compose -f deploy/docker-compose.all-in-one.yml up -d --build

# 只有 IP（自签证书，浏览器需手动信任一次）：
docker compose -f deploy/docker-compose.all-in-one.yml up -d --build

访问 https://你的域名/（或 https://服务器IP/），控制台里设置代理密钥即可对外提供服务。

根目录的 docker-compose.yml 只启动应用并绑定 127.0.0.1:3123，由你现有的 nginx/Caddy 做 TLS：

location / {
    proxy_pass http://127.0.0.1:3123;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_buffering off;            # 流式响应必须
    proxy_read_timeout 600s;
}

环境变量在启动时覆盖 config.json；此后通过控制台保存设置，会以当前生效值写回文件。

Cline Pass 订阅模型在 Cline 网关之后分成两条管道，钉住上游的写法完全不同：

关键发现：规划器管道的请求由 Vercel AI Gateway 执行，请求体里的顶层 provider.only/order 会被 Cline 丢弃 （这也是官方 API 上"换上游不生效"的原因），但 providerOptions.gateway 嵌套形式会原样透传：

{
  "model": "cline-pass/glm-5.2",
  "messages": [],
  "providerOptions": { "gateway": { "only": ["alibaba"] } }
}

实测响应：finalProvider: "alibaba"，规划器理由变为 Provider set restricted to: alibaba。 参考：Vercel AI Gateway — Provider Filtering, Ordering & Sorting

1. 响应元数据回读：规划器管道带 canonicalSlug / fallbacksAvailable / finalProvider；直连管道顶层 provider 即实际上游；
2. 假上游探测（零 token）：带不存在的 only:["__probe__"] 让网关在路由层报错并列出精确的可用渠道清单（两条管道的清单不一致，要分别取）；
3. OpenRouter 公开接口 GET /api/v1/models/{slug}/endpoints：补充上下文长度/在线率（对直连管道有直接参考意义）。

管道归属由 Cline 侧决定、可能随时间变化，控制台的「探测」会刷新每个模型的管道类型与渠道清单。

代理同时做了兼容性标准化：解包 Cline 的 {"data":...} 包装为标准 OpenAI 格式、错误统一为 {"error":{"message":...}}、附加 X-Cline-Target-Upstream / X-Cline-Actual-Upstream / X-Cline-Account 等响应头。

Q：为什么选了某个渠道会报 invalid_request_error？ 部分渠道被单独钉住时会因模型 ID 映射失败，还有渠道处于共享池限流（429）状态。点该模型行的「校验」， 把所有渠道实测一遍，下拉框会标注 ✔可用 / ⏳限流 / ✘不可钉。钉住失败的渠道会被自动学习标记。

Q：限流的渠道还能用吗？ 能。限流是共享池的临时状态，过段时间重新「校验」即可；或改用「优先+回退」模式，限流时自动跳到其他渠道。

Q：直接用官方 API 写 provider.only 为什么不生效？ 对规划器管道（走 Vercel AI Gateway 的模型）会被 Cline 网关丢弃，请改用 providerOptions.gateway，见上文。

Q：两条管道的渠道清单为什么不一样？ 钉住发生在不同后端（OpenRouter vs Vercel AI Gateway），各自支持的渠道池不同，要以对应清单为准。

Q：订阅额度怎么计？ 经代理的请求与直连官方 API 计费一致；「探测/测试/校验」会产生极小额的真实请求（每次约 0.0002 美元级）。

• config.json / data/ 含明文密钥，已在 .gitignore 排除，不要提交或分享；
• 对外部署务必设置 proxyKey（控制台可随时轮换）；
• 「重试博弈」maxRetries > 0 时会放大请求量，注意额度消耗。

MIT