1. 从订阅额度到统一出口Sub2API 到底解决什么问题如果你手上有 Claude Code、Codex CLI、Gemini CLI 这几个订阅大概率遇到过同一个尴尬每个工具都能在官方客户端里跑但一旦想让自己的脚本、内部小工具或者团队里其他人调用就发现订阅凭证根本不是标准 API Key。OAuth 授权、刷新令牌、账号轮换、并发限制、用量统计这些东西官方客户端帮你藏起来了可你自己搭服务时全得重新面对。Sub2API 这类项目的价值就在这里。它做的事情可以一句话概括把多个上游 AI 订阅账号抽象成一个带鉴权、调度、计量能力的统一 API 网关对外只暴露一个 Base URL 和一个 Key。你不再关心背后是哪个账号、哪个平台、哪个协议网关帮你把请求路由到合适的资源上再把用量记清楚。适合谁用三类人最典型。第一类是个人开发者手里攒了好几个订阅想用一个统一入口调用第二类是小团队几个人共享账号池需要按 Key 分配权限和额度第三类是做内部工具的想把 AI 能力封装成标准接口给其他系统调用。如果你只是自己一个人用一个订阅其实没必要上这么重的架构官方客户端就够了。但要注意一个前提订阅产品的授权范围通常不等于 API 服务共享和转售往往有额外限制。所以这套架构更适合个人实验和可信内部团队真要对外提供付费服务得先确认上游条款是否允许。这一点后面还会展开。我试过把几个订阅账号接进自建网关最深的体会是难点从来不是能不能转发请求而是转发之后怎么保证账算得清、账号不出事、会话不漂移。Sub2API 的架构设计基本都围绕这三个问题展开下面拆开讲。2. TaoToken 统一 Key 通道前置准备与接入定位在讲具体配置之前先理清 TaoToken 在这套架构里的位置。TaoToken 提供的是统一 Key 和 API 通道能力官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你可以把它理解为一个已经帮你处理好鉴权和通道管理的上游入口你的自建网关或者客户端只需要对接这一个 Base URL。为什么要在 Sub2API 的语境里提 TaoToken因为很多人在自建网关时会卡在上游凭证怎么管这一步。自己维护一堆 OAuth 账号刷新、冷却、隔离都得写而通过统一 Key 通道你可以先把上游这一层收敛掉把精力放在网关的路由、计量和回退逻辑上。两者是互补关系TaoToken 负责统一出口Sub2API 负责把出口包装成多用户、可计费的服务。前置准备清单如下。你需要一个可用的 TaoToken Key在控制台创建即可地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Key 的创建和管理在 API Keys 页面入口是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你还没确定用哪个模型可以先去模型对话页面试一下地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 确认通道通了再往下走。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面会说明 Base URL 的拼接规则和鉴权头格式。如果你打算长期跑编码类 Agent可以关注 Coding Plan入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它更适合持续性的编码任务场景。这里要强调一个工程习惯无论你后面接的是 Sub2API 还是别的网关上游凭证都不要硬编码在代码里。用环境变量或者密钥管理服务注入日志里绝对不能打印 Authorization 头。我见过太多因为日志脱敏没做好导致 Key 泄露的案例排查起来非常痛苦。3. 可复制的网关路由与配额映射配置这一节给可直接复制的配置片段。先说明目录约定假设你的网关项目根目录是gateway/配置文件放在gateway/config/下。下面用 JSON 和 TOML 两种格式各给一份你可以按自己技术栈选。先看上游通道定义用 JSON 写文件路径gateway/config/upstreams.json{ upstreams: [ { name: taotoken-primary, base_url: https://taotoken.net/api, auth_type: bearer, api_key_env: TAOTOKEN_API_KEY, timeout_ms: 120000, max_retries: 2, models: [claude-*, gpt-*, gemini-*] } ] }注意api_key_env指向的是环境变量名不是 Key 本身。启动网关前先export TAOTOKEN_API_KEY你的Key这样配置文件可以进版本库而不会泄露凭证。再看路由与配额映射用 TOML 写文件路径gateway/config/routes.toml[gateway] listen 0.0.0.0:8080 default_upstream taotoken-primary [[route]] match_model claude-* upstream taotoken-primary quota_group claude-pool sticky_session true cooldown_on_429_sec 60 [[route]] match_model gpt-* upstream taotoken-primary quota_group openai-pool sticky_session true cooldown_on_429_sec 45 [[route]] match_model gemini-* upstream taotoken-primary quota_group gemini-pool sticky_session false cooldown_on_429_sec 30 [quota] [[quota.group]] name claude-pool rpm_limit 60 tpm_limit 200000 concurrent_limit 8 [[quota.group]] name openai-pool rpm_limit 120 tpm_limit 300000 concurrent_limit 12 [[quota.group]] name gemini-pool rpm_limit 90 tpm_limit 250000 concurrent_limit 10这份配置里几个关键点值得解释。match_model用的是通配符网关在收到请求后先做模型名归一化再匹配路由这样claude-3-5-sonnet和claude-sonnet-4都能落到同一个池子。sticky_session控制会话粘性编程类 Agent 建议开启避免长对话在账号间漂移导致缓存失效。cooldown_on_429_sec是收到限流后的冷却时间不同平台的风控节奏不一样需要按实测调整。如果你用的是 Claude Code 这类客户端还需要一份客户端侧的 settings 片段。以~/.claude/settings.json为例{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:8080, ANTHROPIC_AUTH_TOKEN: sk-your-gateway-key } }这里的sk-your-gateway-key是你网关自己签发的 Key不是上游 Key。网关收到后先鉴权再换成上游凭证转发。这一层隔离很重要客户端永远拿不到真实上游凭证。如果你用 Codex CLI配置在~/.codex/auth.json需要写全三件套{ base_url: http://127.0.0.1:8080/v1, api_key: sk-your-gateway-key, model: gpt-5-codex }Base URL、Key、Model ID 三个字段缺一不可尤其是 Model ID写错会导致路由匹配失败直接返回 404。Cline 的 MCP 配置同理在 MCP 服务器配置里填 Base URL 和 KeyModel ID 按你实际要用的填。4. 验证请求与成功结果确认配置写完先别急着接客户端用 curl 做最小验证。第一步确认网关活着curl -s http://127.0.0.1:8080/health正常返回应该是{status:ok}之类的结构。如果连不上先查端口监听和防火墙别往下走。第二步发一个最小对话请求验证路由和上游通道curl -s http://127.0.0.1:8080/v1/chat/completions \ -H Authorization: Bearer sk-your-gateway-key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}], max_tokens: 16 }成功的话你会拿到标准 OpenAI 格式的响应choices[0].message.content里有内容usage字段里有 token 统计。重点看usage这是后面计费和对账的依据。如果usage缺失说明网关没有正确解析上游返回需要检查响应解析逻辑。第三步验证流式因为编程 Agent 几乎都用流式curl -N http://127.0.0.1:8080/v1/chat/completions \ -H Authorization: Bearer sk-your-gateway-key \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: count to 5}], stream: true }-N关闭 curl 缓冲你应该能看到一串data: {...}事件最后以data: [DONE]结束。如果卡住不动八成是反向代理开了缓冲需要关掉 SSE 缓冲并延长读取超时。第四步验证配额计量。连续发 10 个请求然后查网关的用量记录接口或者数据库curl -s http://127.0.0.1:8080/admin/usage?keysk-your-gateway-key你应该看到 10 条记录每条有模型名、输入输出 token 数、时间戳。如果记录数不对检查计量写入是不是异步的、有没有丢。这一步是很多自建网关的薄弱环节请求成功了但账没记上时间一长就对不上。第五步验证失败回退。手动把上游 Key 改错再发请求观察网关行为export TAOTOKEN_API_KEYinvalid-key # 重启网关后发请求 curl -s http://127.0.0.1:8080/v1/chat/completions \ -H Authorization: Bearer sk-your-gateway-key \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:ping}]}预期是网关返回 401 或 502并且把该上游标记为异常。如果你配了多个上游应该能看到自动切换到备用通道。这一步验证的是回退逻辑生产环境必备。5. 常见报错排查401、local proxy failed 与 reading choices这一节按真实报错来。第一个高频错误是 401 Unauthorized。分两种情况客户端到网关的 401说明网关 Key 不对或者没带 Authorization 头网关到上游的 401说明上游 Key 失效或者格式不对。排查方法是在网关日志里找upstream_auth_failed关键字看是哪个环节。如果是 TaoToken 通道去控制台确认 Key 状态地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。第二个错误是local proxy failed。这个通常出现在客户端侧意思是客户端连不上你配置的 Base URL。检查三件事网关进程是否在跑、端口是否对、Base URL 有没有多写或少写/v1。Claude Code 的ANTHROPIC_BASE_URL不要带/v1SDK 会自己拼而 Codex 的base_url通常要带/v1。这个差异坑过很多人。第三个错误是reading choices相关完整报错类似error reading choices: unexpected end of JSON input。这几乎都是流式响应被截断导致的。原因可能是反向代理缓冲、超时太短、或者上游断流。排查顺序先看 Nginx 配置有没有proxy_buffering off再看proxy_read_timeout是不是够长最后看网关的timeout_ms设置。如果用的是 Nginx记得加underscores_in_headers on;否则带下划线的请求头会被丢掉粘性会话直接失效。第四个错误是 OAuth 相关的token refresh failed。如果你用的是 OAuth 类上游刷新令牌过期或者被撤销都会报这个。处理方式是重新授权并且在网关里把该账号标记为待刷新不要让它继续参与调度。Sub2API 这类系统会把账号状态做成状态机冷却、隔离、待刷新各有各的转移条件自己实现时也要有类似设计。第五个错误是模型路由 404报错类似no route matched for model xxx。这是模型名归一化没做好。上游返回的模型名可能带日期后缀、带版本号你的路由规则如果写死了精确匹配就会漏。建议用前缀通配并且在网关里维护一张别名映射表。排障时有个通用技巧把日志级别临时调到 debug但记得排查完调回去debug 日志会打印请求体有泄露风险。另外所有排障动作都要在测试环境先做一遍别直接在生产上改配置。6. 语义一致收尾把统一出口跑稳的几个实用习惯最后说几个把网关跑稳的习惯都是踩过坑总结的。第一版本固定。自建网关依赖的上游协议会变模型名会变计费字段会变。生产环境不要用latest标签固定版本号升级前先读变更说明在测试环境验证流式、工具调用、计费三个环节再灰度。第二对账。每周拉一次网关用量记录和上游账单做比对差异超过阈值就查。Token 计费最容易出问题的地方是缓存 token 的重复计算输入、输出、缓存读取、缓存写入四个字段要分开记。第三凭证轮换。上游 Key 定期换网关自己的 Key 也要能吊销和重建。控制台里给每个用户或每个应用发独立 Key出问题能精确定位到来源。第四监控首字节延迟和流式中断率。这两个指标比平均响应时间更能反映真实体验。一个请求最终成功但中间等了 40 秒对 Agent 来说就是失败。第五备份。PostgreSQL 和配置文件定期备份并且要验证恢复流程。只备份不验证等于没备份。如果你还在选型阶段可以先从模型对话页面确认通道可用再决定是自建网关还是直接用统一 Key 通道。长期跑编码任务的话Coding Plan 的入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。把上游这层收敛好你的网关只需要专注路由、计量和回退整体复杂度会降一大截。
绿色便携版：离线专业术语查取引擎)
