config.example.yaml

server:
  port: 8080
  host: "0.0.0.0"

auth:
  # Key that clients must provide to use the proxy.
  # Set to null/omit to disable client auth.
  proxyApiKey: "your-proxy-secret"

  # Upstream credentials come from the OAuth login flow — run this first:
  #   bun run src/index.ts auth login <zai|bigmodel>
  # Parsed but currently not honored — the credential store path is fixed at
  # ~/.zcode-proxy/credentials.json:
  # oauthCredentialsPath: "~/.zcode-proxy/credentials.json"

# Which upstream provider to use: "zai" or "bigmodel"
provider: zai

# Which plan tier to use:
#   "coding-plan" (default) — direct upstream endpoints, permanent API key
#   "start-plan"            — routes through zcode.z.ai with JWT auth (requires `auth login`)
plan: coding-plan

# Start-plan captcha controls (environment variables only, milliseconds):
# CAPTCHA_ACQUIRE_BUDGET_MS=45000 bounds initial acquisition and retry backoff.
# Expiry returns 503 without forwarding; client abort stops waiting immediately.
# CAPTCHA_CONFIG_TIMEOUT_MS=15000 covers config headers AND the complete body.
# CAPTCHA_CONFIG_TTL_MS=3600000 caches successful snapshots only. Expired snapshots
# refresh in the background while requests use the last successful config.
# Completed refreshes apply to subsequent requests; failures preserve that config,
# including disabled or absent captcha settings. Cold starts await the first fetch.
# Non-numeric, non-finite, or non-positive values use the defaults above.

providers:
  zai:
    anthropicBase: "https://api.z.ai/api/anthropic"
    openaiBase: "https://api.z.ai/api/coding/paas/v4"
  bigmodel:
    anthropicBase: "https://open.bigmodel.cn/api/anthropic"
    openaiBase: "https://open.bigmodel.cn/api/coding/paas/v4"

# Default model used when a client request omits `model`.
defaultModel: glm-5.3

# Informational model list surfaced in the TUI / startup output; any other
# model id still forwards upstream (no whitelist enforcement).
models:
  - glm-5.3
  - glm-5.3-flash

# Multi-account pool
accounts:
  # Account pick strategy: "round-robin" (default, even distribution — safest
  # for free tier) or "most-remaining-quota" (drench traffic into the account
  # with the most quota; compares the REQUESTED MODEL's bucket per-model and
  # falls back to round-robin for accounts with unreliable/missing numbers).
  pickStrategy: round-robin
  # Max concurrent in-flight requests per account (free-tier accounts 429 with
  # ~3 concurrent streams).
  maxInFlightPerAccount: 2
  # Queue wait when all accounts are at cap (ms). 0 disables queueing.
  queueTimeoutMs: 5000
  # Fallback cooling for a 429 without Retry-After (ms).
  rateLimitCooldownMs: 30000
  # Reservation watchdog: force-release slots held longer than this (ms).
  reservationTimeoutMs: 900000

# Configurable identity headers injected on every upstream request to mimic the
# ZCode desktop client (User-Agent, X-Title, X-ZCode-Agent, HTTP-Referer).
# X-ZCode-App-Version is not configurable: the app version is pinned in code
# (DEFAULT_APP_VERSION in src/config/loader.ts) and auto-bumps with mirror
# snapshot updates. Runtime platform headers (X-Platform, X-Os-Category,
# X-Os-Version) are detected dynamically and are not configured here. All
# fields below are optional; env vars override YAML, which overrides defaults.
identity:
  # X-Title suffix → "Z Code@{sourceTitle}". Default "cli".
  sourceTitle: "cli"
  # HTTP-Referer URL. Default "https://zcode.z.ai".
  refererOrigin: "https://zcode.z.ai"
  # Device identity (X-Device-Mid) — random UUIDv4, generated ONCE and reused
  # forever (mirrors ZCode's telemetry deviceMid; no hardware values involved).
  # Auto-generated into this file at first `auth login` or config creation.
  # Leave empty on Android — the app injects ZCODE_IDENTITY_DEVICE_MID instead.
  deviceMid: ""

# Local client-session inference for upstream session affinity.
# "enforce" (default) forwards a stable x-session-id for inferred sessions
# (cache affinity + closer to the official client, whose signing template
# always carries a session id). "observe" logs inferred sessions in debug
# mode without changing upstream x-session-id. "off" disables inference.
clientIdentity:
  mode: enforce
  ttlSeconds: 900
  maxSessions: 1024

# Responses API (/v1/responses) — Codex CLI / OpenAI Agents SDK endpoint.
# Translates Responses requests through Chat Completions to the Anthropic-format
# upstream (both plans post Anthropic upstream).
# State (previous_response_id) is held in-memory (cleared on restart, 24h TTL).
responses:
  enabled: true
  store:
    maxEntries: 1000
    ttlMs: 86400000

# Official plugin-MCP aggregate (tianyancha / Wind / 同花顺 iFinD ...).
# ONE /mcp endpoint exposes every plugin's tools, namespaced {plugin}__{tool}
# (streamable HTTP JSON-RPC: initialize / ping / tools list & call). GET /mcp
# returns a human-readable catalogue; DELETE /mcp closes the cached upstream
# plugin sessions. Outbound calls hit Z.AI's official gateway with your
# OAuth login injected — inbound callers authenticate with the same
# proxyApiKey as the LLM routes.
# Requires a coding-plan credential: the upstream gateway rejects
# identity-only auth (JSON-RPC 3101), so start-plan requests fail with 400
# `mcp_plan_unsupported`.
# The server table ships with the build (scripts/regen-mcp-catalogue.ts).
# The relay spends your paid data entitlements, so setting auth.proxyApiKey
# is strongly recommended (CORS headers are only emitted when a key is set).
# Legacy `mcp.enabled`/`webSearch`/`webReader`/`zread` keys are still parsed
# but ignored (the GLM hosted-tool client they fed has been removed).
# Env overrides: ZCODE_MCP_GATEWAY, ZCODE_MCP_GATEWAY_ORIGIN.
mcp:
  gateway:
    enabled: true
    # `${ZCODE_BASE_URL}` substituted into plugin .mcp.json URLs.
    # Production default per the desktop bundle (`jee`); the
    # chatglm.site variant is the TEST env origin.
    upstreamOrigin: https://zcode.z.ai

# Async (off-peak / "idle plan") bridge.
# When enabled, exposes POST /async/v1/messages and /async/v1/chat/completions
# that route through ZCode's off-peak ticket-queue backend — free compute when
# the GLM cluster has idle capacity. The proxy holds the connection open with
# SSE keepalives during queue wait, forwards the LLM stream once a ticket is
# ready, and auto-retries on ticket-expired (up to maxRetries).
#
# IMPORTANT: off-peak needs the JWT captured by `auth login`. A credential
# without a JWT makes the route return 400 `async_credentials_unavailable`.
# Off-peak is a coding-plan feature: when `plan: start-plan`, the /async/*
# routes return 400 `async_plan_unsupported` even when enabled: true.
#
# Env overrides: ZCODE_ASYNC_ENABLED, ZCODE_ASYNC_ORIGIN,
# ZCODE_ASYNC_MAX_RETRIES, ZCODE_ASYNC_MAX_WAIT_MS.
async:
  enabled: false
  origin: "https://zcode.z.ai"
  pollIntervalMs: 5000
  keepAliveIntervalMs: 3000
  # Maximum total wait for ticket to become ready, in ms. 0 = unlimited.
  maxWaitMs: 0
  maxRetries: 3
  settleTimeoutMs: 8000
  controlTimeoutMs: 15000
  # Optional model override; empty uses the request's `model`.
  defaultModel: ""

# Manual claim ("weekend plan") — mirrors the ZCode 3.10 desktop client's
# manualClaimPlan feature. When enabled, the proxy periodically lists claimable
# trial plans from both faces — {origin}/api/v1/zcode-plan/billing/preview
# merged with marketing-banner plans ({origin}/api/v1/marketing/touch; deduped
# by planId, preview wins) — and auto-claims the highest-priority one
# ({origin}/api/v1/zcode-plan/billing/claim) using the OAuth JWT plus an
# Aliyun captcha token when the campaign config requires one (same solver as
# start-plan). Weekend
# campaigns are quota-limited first-come-first-served; claimed plans activate
# at the campaign's `starts_at` and land as Start-Plan quota.
#
# IMPORTANT: requires a logged-in credential (claim uses the JWT from
# `auth login`), and identity.appVersion must be >= the campaign's minimum
# client version or the server rejects with `ineligible` — an app_version
# below the floor can also surface as a silently empty preview list
# (measured floor 3.14.0 for the 2026-09 campaign; the built-in appVersion
# "3.17.1" satisfies it).
#
# Env overrides: ZCODE_CLAIM_ENABLED, ZCODE_CLAIM_AUTO, ZCODE_CLAIM_ORIGIN,
# ZCODE_CLAIM_POLL_INTERVAL_MS.
claim:
  # On by default: the scheduler polls the merged plan list (billing preview +
  # marketing banner) every 5 min and idles until a campaign goes live
  # (404 preview = nothing to claim).
  # `false` = CLI-only (`zcode-proxy claim [list|now]` still works).
  enabled: true
  # Auto-claim in the background while serving. `false` = CLI-only
  # (`zcode-proxy claim` still works when `enabled: true`).
  auto: true
  origin: "https://zcode.z.ai"
  # Preview poll cadence (5 min default).
  pollIntervalMs: 300000
  # Backoff after failed attempts (10 min default); quota_exhausted /
  # already_claimed back off to the server-provided next window instead.
  cooldownMs: 600000
  # Optional: claim a specific plan_id. Empty = highest-priority preview.
  planId: ""

# Server-controlled upstream URL remapping (mirrors the ZCode client's
# ProviderEndpointRoutingService). The proxy periodically fetches
# {origin}/api/v1/agent/configs and rewrites matching upstream URLs per the
# returned proxyEndpoint.mapping table (currently the coding-plan Anthropic
# endpoints -> zcode.z.ai ultra endpoints). Fail-open: any fetch/parse error
# keeps the original URLs. Env override: ZCODE_ENDPOINT_ROUTING=false.
endpointRouting:
  enabled: true
  origin: "https://zcode.z.ai"

# Client request signing V4 (mirrors the ZCode 3.15.1 static signing rule).
# When enabled, coding-plan requests are always signed: handshake against
# {provider}/api/paas/c1f3a7e2/v2/client, Ed25519 signature + proof-of-work
# headers on every request, fail-open retry ladder (two 401 VERIFY rejections
# -> permanent unsigned bypass). Start-plan and off-peak paths are never
# signed (the old agent/configs codingPlanSignature gate is gone on both
# sides). Env override: ZCODE_CLIENT_SIGNING=false.
clientSigning:
  enabled: true

# HighSpeed 加速卡 (mirrors the ZCode 3.15.1 HighspeedCardService — Coding Plan
# subscriber benefit, server-side random draw). Enabled by default, matching the
# official client (which has no toggle): the first eligible coding-plan request
# ignites a background draw loop (POST {origin}/api/v1/highspeed/draw at ~1/s —
# the measured token-bucket refill rate; server next_draw_at is ignored on a
# miss); on a hit, requests inside the card window are rewritten to the card
# model with the highspeed auth set (X-Highspeed-Card-ID), rerouted to the
# dedicated inference endpoint ({origin}/api/v1/highspeed/anthropic/v1/messages
# — pinned by the official zcode-builtin provider rules, NOT the coding-plan
# URL) and stay unsigned, exactly like the official client. The loop
# self-extinguishes 5 minutes after
# the last eligible request; account unavailability (503/3404) is
# negative-cached 10min, HTTP 429 backs off 5s. task_id reuses the local
# client-session affinity inference. Env override: ZCODE_HIGHSPEED_ENABLED=false.
highspeed:
  enabled: true
  origin: "https://zcode.z.ai"
  models: ["glm-5.3", "glm-5.2", "glm-5.1"]

logging:
  level: info