Аккаунты и квоты

Несколько аккаунтов

Вместо ручного редактирования .env при каждой смене ключа, один раз зарегистрируйте именованные аккаунты и переключайтесь между ними:

go-z-ai accounts add personal --api-key sk-...          # тип определяется автоматически
go-z-ai accounts add work --api-key sk-... --type coding_plan

go-z-ai accounts list
go-z-ai accounts use personal        # задаёт значение по умолчанию для будущих команд
go-z-ai accounts show                # показывает активный аккаунт
go-z-ai accounts remove work --yes

Аккаунты хранятся в $XDG_CONFIG_HOME/go-z-ai/accounts.json (или ~/.config/go-z-ai/accounts.json), запись выполняется атомарно с правами 0600.

Автоопределение типа: accounts add опрашивает monitor/quota-эндпоинт, применимый только к coding plan, одним бесплатным (без расхода token) вызовом. Успешный, корректно сформированный ответ означает coding_plan; в остальных случаях выполняется откат к pay_as_you_go — это вывод методом исключения, а не положительное подтверждение, поскольку неизвестно о существовании эндпоинта, специфичного для ключей pay-as-you-go. Передайте --type явно, чтобы пропустить опрос. Опрос учитывает --region: ключ glm_coding_plan_china опрашивает coding-эндпоинт open.bigmodel.cn вместо эндпоинта api.z.ai, поэтому классификация выполняется относительно нужной платформы (см. раздел Региональные шлюзы ниже).

Порядок разрешения — полный список приоритетов для --api-key, --account, переменных окружения и активного сохранённого аккаунта см. в разделe Начало работы.

Мониторинг квоты и использования

У аккаунтов GLM Coding Plan есть три независимых окна квоты:

go-z-ai accounts quota                    # по всем сохранённым аккаунтам
go-z-ai accounts usage --days 14          # тепловая карта использования token/инструментов
go-z-ai accounts usage --today            # сокращение для --days 1
go-z-ai usage quota                       # одиночный активный аккаунт
go-z-ai usage check --watch               # предупреждение, когда использование превышает 80%

Пример вывода accounts quota:

📊 GLM Coding Plan Usage (PRO tier)

• 5-hour rolling token window
  Usage: 62%
  Resets: 2026-07-11 09:30:00 CEST (in 2h 14m)
  Pace: 62% used at 55% of window elapsed — on pace to run out ~24m before reset

• weekly token window
  Usage: 41%
  Resets: 2026-07-17 09:17:18 CEST (in 5d 22h)
  Pace: 41% used at 15% of window elapsed — on pace to run out ~4d before reset

• monthly MCP tools quota
  Usage: 574/1000 (57%) — 426 remaining
  Resets: 2026-07-26 09:17:18 CEST (in 18d 6h)
  By tool:
    - search-prime: 470
    - web-reader: 97
    - zread: 7

Строка Pace (только для окон token) отвечает на вопрос «тратим ли слишком быстро?» — она экстраполирует собственное сообщённое окном использование на долю истекшего времени окна, так что вы узнаёте о риске преждевременного исчерпания до того, как упрётесь в стену. Это линейная математика по числам, возвращаемым API (никаких допущений о пиковых/внепиковых тарифах).

Не каждый аккаунт отображает все окна — на то, какие окна применимы, влияют и уровень тарифа, и тип аккаунта (accounts show <name> сообщает тип аккаунта; аккаунты pay_as_you_go полностью пропускаются командами accounts quota / accounts usage, поскольку coding-plan monitor-эндпоинт к ним неприменим).

Почему утверждение «использование не существует» неверно

Если вы встретите старые заметки в интернете (или в истории git этого репозитория), утверждающие, что у Z.AI нет API использования/квоты — это было справедливо только для общей поверхности /api/paas/v4, проверенной изолированно. Monitor-эндпоинты coding plan (/monitor/usage/quota/limit, /monitor/usage/model-usage, /monitor/usage/tool-usage) реальны, задокументированы и именно на них построены QuotaService/UsageService из pkg/client. Если accounts quota ничего не возвращает для аккаунта, сначала проверьте его тип (у аккаунтов pay_as_you_go действительно нет этих данных), прежде чем предполагать, что API сломан.

Региональные шлюзы (api.z.ai / open.bigmodel.cn)

Z.AI обслуживает одно и то же семейство моделей GLM с двух региональных шлюзов: международный хост api.z.ai (по умолчанию) и материковый китайский зеркальный open.bigmodel.cn. То, на какой хост попадёт конкретный вызов, решают два независимых фактора:

1. Embeddings и Moderations всегда маршрутизируются на open.bigmodel.cn — это единственные сервисы, привязанные к китайскому хосту в коде (pkg/client/embeddings.go и pkg/client/moderations.go вызывают doRequestBaseKey(BigModelBaseURL, …)). --china-api-key / ZAI_CHINA_API_KEY — переключатель учётных данных здесь; он опционален, поскольку обычный ZAI_API_KEY аутентифицируется одинаково на обеих платформах (тот же каталог /models, те же ошибки биллинг-уровня — живая верификация), поэтому откат к общему ключу — частый случай. Задайте отдельный китайский ключ, только если у вас есть отдельный Credential, применимый исключительно на bigmodel.cn. Rerank и Voice используют --base-url по умолчанию (api.z.ai по умолчанию) — они задокументированы только на китайской платформе, но клиент не принудительно маршрутизирует их.

2. monitor / biz / agents / detection маршрутизируются на open.bigmodel.cn, если задано --region china (или ZAI_REGION=china); в противном случае они идут на api.z.ai. Именно этот переключатель нужен пользователю glm_coding_plan_china, чтобы квота/использование, информация об аккаунте, агенты и определение типа аккаунта попадали на нужный хост — без него эти вызовы уходят на api.z.ai, и ключ, выпущенный для Китая, может провалить аутентификацию или быть неверно классифицированным. --region не меняет базовый URL чата (для этого используйте --base-url) и хост Embeddings/Moderations. Псевдонимы: cn, bigmodel, west; неизвестное значение откатывается к global.

То, получите ли вы реальные результаты от китайских задокументированных сервисов (Embeddings, Moderations, Rerank, Voice), зависит от тарифа аккаунта, а не от того, какой ключ вы используете. Каталог моделей аккаунта GLM Coding Plan содержит только чат — вызов этих сервисов с таким аккаунтом возвращает 400 Unknown Model (код ошибки 1211) на любой из платформ. Это ожидаемое поведение, а не баг: проверьте go-z-ai models list, чтобы увидеть, что реально входит в каталог вашего аккаунта.

Хосты китайского зеркала для monitor/biz/agents/detection повторяют структуру путей api.z.ai, но здесь НЕ ВЕРИФИЦИРОВАНЫ ВЖИВУЮ — для open.bigmodel.cn живая верификация подтвердила ту же поверхность OpenAPI для /models и /chat/completions, но пути monitor/biz/agents на китайской стороне ещё не были зафиксированы в cassette. См. Дорожная карта.

Коды ошибок

APIError (см. Обработка ошибок) категоризирует каждый код ошибки Z.AI, с которым сталкивался клиентский код. Два наиболее частых, встречающихся в контексте квоты:

Полная таблица и способы ветвления по APIError.Category в собственном коде — в разделе Обработка ошибок.