Overview

zcode2api is a self-hosted gateway for ZCode (BigModel / Z.ai) accounts. It exposes upstream model access through three client protocols: OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. Its main purpose is to make free-account usage more manageable: it handles automatic account switching, concurrent request queuing, rate-limit retries, session affinity, and scheduled free-card claiming.

It targets people who already have ZCode accounts and want to use them from OpenAI- or Anthropic-compatible clients, without wiring account credentials into each client. It is written in Go and ships as source, release binaries, and a Docker Compose setup.

Key capabilities include:

• Account management: BigModel / Z.ai, local credential import, OAuth, grouping, and session affinity.
• Scheduling and retries: automatic account switching, concurrent queuing, and rate-limit retries; a single account supports up to 3 concurrent requests.
• Automatic card claiming: a default 240-minute inspection cycle with verification, claim records, and pending quota.
• Network configuration: HTTP/HTTPS outbound proxy, node subscriptions, Mihomo, and upstream security verification.

Quick start

The project supports Windows, Linux, and macOS. Building from source requires Go 1.26+. Background security verification requires Node.js 18+ and jsdom.

Run a release binary

1. Download the archive for your OS and architecture from Releases and fully extract it.
2. Run from the extracted directory.

On Windows PowerShell, start in the background (stop with .\scripts\stop.ps1):

.\scripts\start.ps1

On Linux or macOS, run in the foreground and stop with Ctrl+C:

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

First login and client setup

After startup:

Purpose	Default address / file
Web console	http://127.0.0.1:6789
Inference gateway	http://127.0.0.1:6780
Initial admin password	data/admin-password.txt
Actual ports and process information	data/ports.json

Sign in to the console, add an account via local import or OAuth, confirm account status, model capability, and balance, then create a gateway key under Keys. Local import reads ~/.zcode/v2/credentials.json on the machine running the service; Docker does not automatically read host credentials.

Point your client at the gateway with the gateway key:

Protocol	Base URL	Endpoint
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

Model aliases are available via GET /v1/models; defaults include glm-flash → GLM-5.3-Flash and glm-5.3 → GLM-5.3. See client integration for the original steps.

Build from source or use Docker

From the project root, build and run:

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

Or run Docker Compose from the source root:

docker compose up -d --build

Docker persists data to ./data and maps ports only to the host loopback address. Stop with docker compose down; the data directory is retained.

Configuration

Prefer changing settings in the console unter Settings. Saved console settings override same-name file configuration, and listen address or port changes require a restart. The sample config is config.example.json. Common settings:

Setting	Default	Purpose
host	127.0.0.1	Local listen address
web_port / gateway_port	6789 / 6780	Console / gateway ports
claim_auto_enabled / claim_auto_min	true / 240	Automatic card claiming on/off and interval in minutes
http.captcha.mode	off	Verification policy for inference requests
outbound_proxy.enabled	false	Global outbound proxy

Environment variables include ZCODE2API_DATA_DIR, ZCODE2API_HOST, ZCODE2API_WEB_PORT, ZCODE2API_GATEWAY_PORT, and ZCODE2API_ADMIN_PASSWORD. Retry rules and further settings are in the configuration guide; proxy subscriptions and verification are covered in the network guide.

Constraints

• Account authorization and use of the upstream ZCode service remain subject to that provider's terms. Review the security notes before deploying.
• Local credential import depends on the machine running the service; Docker needs credentials inside the container, not on the host.
• Some features have extra dependencies: Mihomo is needed for subscription proxies, and Node.js 18+ with jsdom is needed for background verification.
• The gateway defaults to loopback binding. Exposing it beyond localhost changes the security boundary and requires deliberate configuration.
• The project is licensed under Apache License 2.0 (license).

HotRepo's take

The project entered the Go new-project list on November 4, 2026 with 106 stars and 3 forks, gaining 4 stars in the recorded one-hour window. That record shows early attention, but the repository has no daily all-language rank and only two nearby star samples, so it is not enough to judge sustained momentum. The more concrete signal is the design itself: a Go gateway that offers OpenAI and Anthropic-compatible endpoints, account pools, retry scheduling, and automatic claiming. That fills a practical gap for people already using ZCode free accounts, while the reliance on free-quota claiming and third-party account rules remains the main thing to evaluate before adopting it.