ZCode 额度反代网关 (ZCode Quota Reverse-Proxy Gateway)

2026-09-25 暂无评论

遭遇场景

2026-09-24，想把 ZCode（zcode.z.ai）的 Coding Plan 额度接成标准 API 给 Claude Code 之类的客户端用。
GitHub 上叫 zcode2api 的仓库有几十个（同一份代码被反复 fork），质量差异极大，随便挑一个会踩满坑。

一句话结论：主仓库 liu5269/zcode2api（244⭐）已经打不过上游风控；要装就装 dengyie/zcode2api。

选型：同名仓库里哪个能用

仓库	星	结论
`liu5269/zcode2api`	244	废。验证码求解器被阿里云风控判死，且缺设备身份头
`dengyie/zcode2api`	58	可用。happy-dom 深度指纹 + 成套桌面设备仿真 + 首启安装序仿真
`SQMY-dor/zcode2api`	0	已 archive；它的 README 最早记录了 jsdom 被识破一事
`gakiyukr/zcode2api-plus` 等	十几	未实测

判断方法：看 captcha_node/solver.js 的大小。5~6 KB 的是早期 jsdom 版（死）；60 KB 上下的是加固版。

请求链路 (Request Path)

客户端 (Claude Code / Cline / 任意 Anthropic 客户端)
  │ POST /v1/messages
  ▼
zcode2api (:3000, 本机 Python)
  │ 取一枚验证码（池内有现成的直接用）
  │ POST https://zcode.z.ai/api/v1/zcode-plan/anthropic/v1/messages
  │   Authorization: Bearer <Coding Plan JWT>
  │   X-Aliyun-Captcha-Verify-Param: <每请求一枚，用完即废>
  ▼
zcode.z.ai（控制面）→ 真实 AI 端点 api.z.ai

上游协议（实测）

ZCode 官方只有两条渠道（见官方 zai-org/ZCode 源码 oauth/providers/）：

渠道	登录入口	AI 端点	备注
`zai`	`chat.z.ai/api/oauth/authorize`	`api.z.ai/api/anthropic`	即"国际"线，下游是 `api.z.ai`
`bigmodel`	`bigmodel.cn/login`	`open.bigmodel.cn/api/anthropic`	国内线

Plan 通道（吃套餐额度）——需要验证码：

POST https://zcode.z.ai/api/v1/zcode-plan/anthropic/v1/messages
Authorization: Bearer <Coding Plan JWT>
X-Aliyun-Captcha-Verify-Param: <verifyParam>
X-Aliyun-Captcha-Region: cn
X-Device-Mid: <稳定 UUIDv4，永不逐请求随机>
X-ZCode-App-Version: 3.14.0
X-ZCode-Agent: glm
User-Agent: ZCode/3.14.0
HTTP-Referer: https://zcode.z.ai/

API Key 通道——免验证码，但不吃套餐额度：

POST https://api.z.ai/api/anthropic/v1/messages
x-api-key: <apiKey>.<secret>

实测拿 OAuth 顺手换来的 API Key 打这个端点，返回 1113 Insufficient balance——
API Key 是平台按量账户，跟 Coding Plan 是两本账。"用 API Key 绕过验证码"这条路在额度上是死的。

性能：慢的根因是验证码，不是网络

这是最反直觉的一点。上游每个请求都要求一枚全新的验证码，用完立刻作废。

场景	实测
池内有现成验证码	2~3 秒（TTFT ≈ 2.3 秒）
池子空了要现场解	6~20 秒
原生 ZCode 应用	1~2 秒 TTFT

原生应用快，是因为它用真实浏览器解，一秒出结果；模拟环境的求解器要 2~8 秒。

默认验证码池只预备 3 枚，一冲就空。调到 8 枚后：

连打 6 次    前: 2.1 / 19.2 / 2.7 / 7.8 / 3.0 / 9.4 秒
             后: 3.0 /  2.2 / 2.2 / 2.9 / 2.7 / 2.1 秒

.env 里改：

CAPTCHA_POOL_MIN=8      # 默认 3，太小
CAPTCHA_POOL_MAX=24
ZCODE_CAPTCHA_RETRIES=6 # 风控会随机判失败，重试给足

代价：启动后要 30~60 秒预热（串行解 8 枚）。之后池子稳态运行就顺了。

坑清单

现象	根因	处理
`{"code":3007,"msg":"captcha verify failed"}`	验证码无效/被风控判 F001	见阿里云无痕验证无浏览器求解 (Headless Aliyun Traceless Captcha Solving)
`{"code":3012,"msg":"...unusual activity"}`	设备身份缺失，风控拦截	换 dengyie 版（它伪造成套桌面设备）
`{"code":1113,"msg":"Insufficient balance"}`	用了 API Key 通道	Plan 额度只走 JWT 通道
OAuth 登录页只有 +86 手机号	本来如此，不是 bug	国际 z.ai 账号进不去；凭证可在工具间搬
点「开始登录」什么都不弹	`window.open` 写在 `await` 之后，浏览器不认用户手势	改成点击当下先同步开 `about:blank`，拿到 URL 再填
`client/configs` 返回 `3001 parameter error`	多带了 `platform=win32`	改用 `app_version=3.14.0&os=win32`，或不带参数
求解器首次运行超时（退出码 2 + `[pe-stall]`）	要下载阿里云 CDN 资源到 `~/.zcode-captcha-cdn-cache`	预热一次，别误判成坏了
pip 装依赖 GBK `UnicodeDecodeError`	Windows 中文环境	`export PYTHONUTF8=1 PYTHONIOENCODING=utf-8`

关于"国际站登录"的澄清

不存在这种东西。 ZCode 官方源码里就 zai 和 bigmodel 两个 provider，
所有 zcode2api 家族走的是同一个 OAuth 入口、同一个公开 client_id
（client_P8X5CMWmlaRO9gyO-KSqtg，公开标识不是密钥）。

授权页只提供 +86 手机号登录，用 Google/邮箱注册的国际 z.ai 账号进不去——
这是账号体系的问题，换仓库解决不了。

但凭证可以搬：JWT 是纯字符串，从 A 工具的 data/accounts.db 抄到 B 工具
（cli.py add-account zai <名字> <jwt>）即可，不必重新授权。