Начало работы
Здесь вы за пару минут пройдёте путь от нуля до своей первой команды
go-z-ai.
1. Установка
Предварительные требования: Go 1.26.4+, API-ключ Z.AI (создайте его здесь).
go install github.com/SamyRai/go-z-ai@latest
Бинарник устанавливается как go-z-ai. Необязательный короткий псевдоним:
ln -s "$(go env GOPATH)/bin/go-z-ai" "$(go env GOPATH)/bin/zai"
Либо соберите из исходников сразу с нужным именем:
git clone https://github.com/SamyRai/go-z-ai.git
cd go-z-ai
go build -o go-z-ai .
Каким бы путём вы ни пошли, убедитесь, что go-z-ai разрешается и лежит в
вашем PATH:
go-z-ai --version
Далее предполагается, что бинарник называется go-z-ai.
2. Аутентификация
Выберите то, что подходит под ваш стиль работы. Методы разрешаются в следующем порядке приоритета (высший побеждает):
| Метод | Когда использовать |
|---|---|
Флаг --api-key |
Разовые вызовы, скрипты, CI |
Флаг --account <name> |
Зарегистрировано несколько аккаунтов (см. Аккаунты и квоты) |
Переменная окружения ZAI_API_KEY (или файл .env) |
Повседневная работа в локальной оболочке — типичный случай |
| Активный аккаунт из хранилища аккаунтов | Вы выполнили accounts use <name> и хотите, чтобы он применялся по умолчанию |
Для единственного ключа самый быстрый путь:
export ZAI_API_KEY=your_api_key_here
go-z-ai validate
validate выполняет один реальный вызов API и подтверждает, что ключ
работает, прежде чем двигаться дальше.
Если ваш ключ был выпущен на китайской платформе Z.AI (open.bigmodel.cn),
укажите --region china (или ZAI_REGION=china), чтобы вызовы квоты /
использования, информации об аккаунте, агентов и определения типа аккаунта
шли на правильный хост — без этого они попадают на api.z.ai, и ключ,
выпущенный в Китае, может не пройти аутентификацию. Полная картина — в разделе
Аккаунты и квоты § Региональные шлюзы;
для большинства задач чата / эмбеддингов / модерации ничего дополнительно не
нужно (обычный ZAI_API_KEY аутентифицируется на обеих платформах).
3. Ваши первые команды
# Посмотреть, к каким моделям у вас есть доступ
go-z-ai models list
# Отправить завершение чата
go-z-ai chat create "Объясни горутины одним абзацем"
# Выводить ответ потоком token за token
go-z-ai chat create "Напиши хайку про Go" --stream
# Проверить свою квоту (аккаунты GLM Coding Plan)
go-z-ai usage quota
Дальше:
- Полный справочник по командам: Справочник по CLI
- Несколько аккаунтов / мониторинг квоты: Аккаунты и квоты
- Подключение Claude Code / OpenCode / Crush / Factory Droid / Cursor к вашему GLM Coding Plan: Инструменты для кода
- Использование проекта как библиотеки Go вместо CLI: Руководство по библиотеке
- Полноэкранный терминальный интерфейс (вкладки чата, моделей, использования, аккаунтов, кодинга, медиа и инструментов в одном месте):
go-z-ai tui
Устранение неполадок
"API key is required" — ни один из четырёх методов выше не дал ключа.
Перепроверьте echo $ZAI_API_KEY или явно укажите --api-key, чтобы
убедиться.
"invalid API key" / HTTP 401 — ключ найден, но Z.AI его отклонил. Перевыпустите его на z.ai/manage-apikey.
"Unknown Model" (error 1211) на embeddings/moderations/rerank/voice —
почти всегда это ограничение по тарифу аккаунта, а не баг: в каталоге тарифа
вашего аккаунта нет этой модели. Выполните go-z-ai models list, чтобы
посмотреть, что реально доступно вашему ключу. Полное объяснение — в
Аккаунты и квоты.
Что-то другое — откройте issue с точной командой и выводом ошибки (удалите ключ из текста).