项目介绍

zcode2api 是一个面向 ZCode（BigModel / Z.ai）账号的自托管网关。它把上游模型能力通过 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 三种协议暴露给客户端，重点解决免费账号使用中的重试、并发排队、自动换号和多账号管理问题。

它适合已经持有 ZCode 账号、希望用 OpenAI 或 Anthropic 兼容客户端调用模型，又不想把账号凭据直接配置到每个客户端的人。项目使用 Go 编写，提供源码、Release 二进制和 Docker Compose 三种运行方式。

主要能力包括：

• 账号管理：BigModel / Z.ai、本机导入、OAuth、分组与会话亲和。
• 调度与重试：自动换号、并发排队、限流重试；单账号最多 3 个并发请求。
• 自动领卡：默认每 240 分钟巡检，支持验证取票、领取记录与待生效额度。
• 网络配置：HTTP/HTTPS 出站代理、节点订阅、Mihomo 与上游安全验证。

快速使用

项目支持 Windows、Linux 和 macOS。源码构建需要 Go 1.26+，后台安全验证需要 Node.js 18+ 和 jsdom。

运行 Release

1. 从 Releases 下载对应系统与架构的压缩包，完整解压。
2. 在解压目录运行。

Windows PowerShell 使用后台启动，停止用 .\scripts\stop.ps1：

.\scripts\start.ps1

Linux / macOS 前台运行，按 Ctrl+C 停止：

chmod +x ./zcode2api
./zcode2api --root .

首次登录与接入客户端

启动后：

用途	默认地址 / 文件
Web 控制台	http://127.0.0.1:6789
推理网关	http://127.0.0.1:6780
首次管理密码	data/admin-password.txt
实际端口与进程信息	data/ports.json

登录控制台后，在「账号」中通过本机导入或 OAuth 添加账号，确认账号状态、模型能力和余额，然后在「密钥」中创建网关密钥。本机导入读取的是服务所在机器的 ~/.zcode/v2/credentials.json，Docker 不会自动读取宿主机凭据。

把网关密钥和对应 Base URL 填入客户端：

协议	Base URL	请求端点
OpenAI Chat Completions	http://127.0.0.1:6780/v1	POST /v1/chat/completions
OpenAI Responses	http://127.0.0.1:6780/v1	POST /v1/responses
Anthropic Messages	http://127.0.0.1:6780	POST /v1/messages

模型列表通过 GET /v1/models 获取，默认别名包括 glm-flash → GLM-5.3-Flash、glm-5.3 → GLM-5.3。原始步骤见接入客户端。

源码构建与 Docker

在项目根目录执行：

go build -trimpath -o bin/zcode2api .
./bin/zcode2api --root .

或者在源码根目录运行 Docker Compose：

docker compose up -d --build

Docker 方式会把数据持久化到宿主机 ./data，端口只映射到宿主机回环地址。停止并移除容器用 docker compose down，数据目录会保留。

配置说明

优先在控制台「设置」中修改，保存后会持久化并覆盖同名文件配置；监听地址和端口变更需要重启。示例配置文件见 config.example.json。常用配置项：

配置项	默认值	用途
host	127.0.0.1	本机监听地址
web_port / gateway_port	6789 / 6780	控制台 / 网关端口
claim_auto_enabled / claim_auto_min	true / 240	自动领卡开关 / 周期（分钟）
http.captcha.mode	off	推理请求的验证策略
outbound_proxy.enabled	false	全局出站代理

常用环境变量包括 ZCODE2API_DATA_DIR、ZCODE2API_HOST、ZCODE2API_WEB_PORT、ZCODE2API_GATEWAY_PORT、ZCODE2API_ADMIN_PASSWORD。重试规则和更多配置见配置说明；代理订阅与验证见网络配置。

使用约束

• 账号授权和上游 ZCode 服务的使用受该服务提供方条款约束，部署前应阅读安全说明。
• 本机导入依赖服务所在机器的凭据文件；Docker 需要把凭据放进容器，不能直接读取宿主机文件。
• 部分功能有额外依赖：订阅代理需要 Mihomo，后台验证需要 Node.js 18+ 和 jsdom。
• 网关默认监听回环地址，暴露到 localhost 之外会改变安全边界，需要有意配置。
• 项目采用 Apache License 2.0（许可证）。

HotRepo 点评

项目在 2026 年 11 月 4 日进入 Go 新项目榜，记录到 106 Stars、3 Forks，在采集到的一小时窗口内新增 4 Stars。这个记录说明项目获得了早期关注，但它没有进入全部语言日榜，站内也只有相邻的两个采样点，尚不足以判断持续热度。更具体的信号来自设计本身：用 Go 实现兼容 OpenAI 与 Anthropic 的网关，并提供账号池、重试调度和自动领卡，对已经使用 ZCode 免费账号的人有实际用途；同时，自动领卡和第三方账号规则也是采用前需要重点评估的部分。