# ZCode через RouterAI: настройка десктопного coding-агента

ZCode — десктопная среда для кодинга (Agentic Development Environment, ADE) от Z.ai со встроенным ZCode Agent: вы ставите задачу в чате, агент читает проект, запускает команды и правит файлы, а вы подтверждаете его действия. Приложение есть для macOS, Windows и Linux, бесплатное, а исходный код открыт под лицензией Apache-2.0 ([репозиторий zai-org/ZCode](https://github.com/zai-org/ZCode), около 8,4 тысячи звёзд на GitHub). Через RouterAI в ZCode подключаются GLM, Claude, GPT, DeepSeek и другие модели из [каталога](/models): работа из России без VPN, оплата в рублях, один ключ на все модели. Подписка GLM Coding Plan и аккаунт Z.ai для этого не нужны. Статья проверена на ZCode 3.16.3 (Linux).

## Требования

* ZCode для macOS (Apple Silicon или Intel), Windows (x64 или ARM64) или Linux (x64 или ARM64; AppImage, DEB, RPM).
* Ключ RouterAI: [создайте его в личном кабинете](https://routerai.ru/settings/keys) и пополните баланс. Ключ показывается один раз.

## Установка

Скачайте сборку для своей системы на странице [Install в документации ZCode](https://zcode.z.ai/en/docs/install).

* **macOS:** откройте `.dmg` и перетащите `ZCode.app` в папку «Программы».
* **Windows:** запустите установщик `.exe` и следуйте мастеру.
* **Linux:** для AppImage сделайте файл исполняемым (`chmod +x ZCode-*.AppImage`) и запустите его; `.deb` и `.rpm` ставятся менеджером пакетов. Если в системе нет FUSE (например, в контейнере), распакуйте образ командой `./ZCode-*.AppImage --appimage-extract` и запустите `squashfs-root/zcode`.

## Первый запуск без аккаунта Z.ai

Войти в аккаунт Z.ai или BigModel не обязательно: приложение работает и с чужим провайдером.

1. На экране Welcome to ZCode есть кнопки Connect to Z.ai, Connect to BigModel и Use API key. Они нужны для аккаунтов и ключей самой Z.ai. Нажмите Use API key, затем Skip for now.
2. Пройдите мастер первого запуска: What do you do? → Next, Choose your UI mode (Coding mode или Office mode) → Next, Personalize your work assistant → Get started.
3. На рабочем экране в поле чата будет надпись No model available и ссылка Manage models. Это нормально: модель появится после подключения провайдера.

![Экран Welcome to ZCode: кнопки Connect to Z.ai, Connect to BigModel и Use API key](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/503c12a453bae8c43f7bc77dd3c01220.png)

## Подключение к RouterAI

Нажмите Manage models в чате (или откройте настройки и пункт Model settings). Откроется панель Model settings с провайдерами.

![Панель Model settings со списком провайдеров и кнопкой Add provider](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/104cb418f9a2f329d3e09231542e0cd2.png)

1. Нажмите Add provider и в списке выберите **Create custom provider**: готовые плитки ведут на Z.ai, Kimi, MiniMax и другие сервисы, а RouterAI подключается как свой провайдер.
2. **Base URL** — `https://routerai.ru/api/v1`.
3. **API format** — Chat completions (/chat/completions). По умолчанию выбран Anthropic messages (/v1/messages), поэтому формат нужно переключить.
4. **API key** — ваш ключ RouterAI вида `sk-xxxxxxxxxxxxxxxx` (на кадрах показана заглушка).
5. Имя провайдера по умолчанию New provider. Откройте меню «⋯» справа вверху, выберите Rename и введите `RouterAI`.

Провайдер сохраняется сам: внизу появляется уведомление New provider saved, а переключатель справа вверху остаётся включённым.

![Список Add provider с пунктом Create custom provider](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/ec1ef74206369595c2e9727e0e954006.png)

![Выпадающий список API format: Anthropic messages, Chat completions и Responses](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/38c9249f8b6b132ba9d4021bf3799d6a.png)

![Провайдер RouterAI: Base URL, формат Chat completions и ключ-заглушка](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/51e6a4f2468b2d191ee92d7bfc05ff07.png)

### Добавление моделей

Список моделей RouterAI в ZCode не подтягивает: id нужно добавить вручную из [каталога](/models). Нажмите Add model в блоке Model list. В форме есть переключатель Smart configuration, поля Model ID, Context window и Max output tokens и раздел Advanced settings.

Впишите id, например `z-ai/glm-5.3`. Smart configuration узнала модель, сама подставила контекст 1000000 и лимит вывода 128000 (это совпадает с каталогом) и показала сообщение Smart configuration matched for this model. Нажмите Save и повторите для остальных моделей. Если подсказки для id нет, заполните Context window и Max output tokens по каталогу.

![Форма Add model: Model ID z-ai/glm-5.3 и подставленные значения Smart configuration](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/4f08321a3a9a18c525fcb7ca42337f53.png)

После добавления `z-ai/glm-5.3`, `z-ai/glm-5.3-flash`, `deepseek/deepseek-v4.1-flash` и `anthropic/claude-sonnet-5.5` в списке видны все четыре модели с бейджем контекста 1M (у части ещё Vision) и переключателем включения.

![Провайдер RouterAI с четырьмя добавленными моделями](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/2dda5f4e6dd2215b67d9dde5c0a79448.png)

### Chat completions или Anthropic messages

ZCode поддерживает у пользовательского провайдера три формата: Anthropic messages, Chat completions и Responses. Для RouterAI основной путь — **Chat completions** с Base URL `https://routerai.ru/api/v1`: RouterAI — OpenAI-совместимый API, и этот формат подходит для моделей любых семейств каталога. В интерфейсе ZCode мы проверили именно его (на моделях GLM).

Если нужен Anthropic Messages API, выберите формат Anthropic messages и укажите Base URL `https://routerai.ru/api`. Формат подписан как `/v1/messages`, поэтому `/v1` в Base URL не повторяйте: запрос `https://routerai.ru/api/v1/messages` RouterAI обрабатывает.

### GLM без подписки Coding Plan

По [документации ZCode](https://zcode.z.ai/en/docs/configuration), при подключении аккаунта Z.ai с тарифом Coding Plan приложение использует его квоту напрямую. Через RouterAI подписка не нужна: GLM подключаются как обычные модели по id из каталога (`z-ai/glm-5.3`, `z-ai/glm-5.3-flash`, ускоренный `z-ai/glm-5.3-prime`), а расходы списываются с баланса RouterAI в рублях.

## Выбор модели

Модель выбирается в поле чата: нажмите на её название, и откроется список провайдера RouterAI. Там же ползунок Effort (глубина рассуждений, переключается по Ctrl+T).

![Выбор модели в чате: провайдер RouterAI, четыре модели и ползунок Effort](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/5aa201ba8c91484afd44e2f5996ee0cf.png)

| Модель | Для чего |
| --- | --- |
| `z-ai/glm-5.3` | Сложные задачи по программной инженерии и агентные сценарии на много шагов; режим рассуждений всегда включён, по умолчанию max |
| `z-ai/glm-5.3-flash` | Более лёгкое кодирование и долгие агентные задачи, принимает изображения |
| `deepseek/deepseek-v4.1-flash` | Экономичный вариант для кодинга и длинных агентных цепочек |
| `anthropic/claude-sonnet-5.5` | Повседневная разработка: новые функции и исправление ошибок |
| `anthropic/claude-haiku-5.5` | Быстрые и недорогие задачи, субагенты |

Контекст у всех моделей из таблицы в каталоге — около 1 млн токенов. Цены в рублях — в [каталоге моделей](/models).

## Проверка подключения

Проверим связку на демо-проекте с одним тестом.

1. В поле чата откройте Select project → Create project, введите имя проекта и нажмите Choose folder. На Linux откроется системный диалог выбора папки.
2. ZCode спросит Trust this folder?: агент сможет читать и править файлы и запускать команды в выбранной папке. Подтвердите кнопкой Trust folders and create.
3. Убедитесь, что в чате выбрана модель RouterAI, и отправьте задачу: «Запусти npm test и кратко объясни, что проверяет тест в invoices.test.js».
4. В режиме Ask before changes агент попросит разрешение на команду `npm test`. Выберите Allow (только в этот раз) и нажмите Confirm.

![Рабочий экран ZCode с проектом invoices и моделью z-ai/glm-5.3](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/6d10c67cb4d2c970d750fc35e4903cbd.png)

![Запрос разрешения на команду npm test: Allow, Always allow this command, Full access, Deny](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/258d9f33f58dffb43c113f2fdb3e5dd8.png)

Модель `z-ai/glm-5.3` через RouterAI прогнала тест (1 passed, 0 failed) и объяснила, что он проверяет. Ответ занял около полутора минут: на уровне Effort Max модель долго рассуждает, для коротких задач уровень можно снизить.

![Ответ агента после запуска npm test: тест прошёл, разбор invoices.test.js](https://b51bc417-3ee0-451a-a83b-8a681d027a96.selstorage.ru/public/0664dbadf632e8d426877aa0d643af82.png)

Проверить ключ без интерфейса можно запросом:

```bash
curl https://routerai.ru/api/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"z-ai/glm-5.3","messages":[{"role":"user","content":"Привет"}]}'
```

## Чем ZCode отличается от Claude Code и Cline

* **ZCode** — отдельное десктопное приложение с собственным агентом ZCode Agent, встроенными терминалом, Git и просмотром результата. Модели настраиваются в самом приложении: в [FAQ ZCode](https://zcode.z.ai/en/docs/qa) сказано, что переменные окружения терминала и настройки ZCode независимы и не синхронизируются. Если в терминале у вас уже настроен `ANTHROPIC_BASE_URL` или другой ключ, в ZCode их нужно ввести заново. То же касается прокси: ZCode не читает `HTTP_PROXY`, адрес задаётся в Settings → General.
* **Claude Code** — агент для терминала, см. [настройку через RouterAI](/pages/vibe-coding-claude-code). Мастер миграции ZCode умеет импортировать из него историю разговоров.
* **Cline** — расширение для VS Code, см. [настройку через RouterAI](/pages/vibe-coding-vscode-cline). ZCode ставится отдельно и не требует редактора.

## Решение проблем

* **В чате No model available.** Провайдер RouterAI не добавлен, в нём нет моделей или выключен переключатель провайдера либо модели. Проверьте панель Model settings.
* **Ошибка авторизации (401).** Неверный ключ или нулевой баланс: проверьте их в личном кабинете RouterAI.
* **Запрос идёт, но модель не отвечает или приходит 404.** Проверьте Base URL: для Chat completions это `https://routerai.ru/api/v1` без `/chat/completions` на конце, а id модели должен совпадать с каталогом вместе с префиксом (`z-ai/glm-5.3`, не `glm-5.3`).
* **Контекст и лимит вывода пустые.** Для id, которых нет в подсказках Smart configuration, впишите Context window и Max output tokens вручную по каталогу.
* **Подключение бесконечно загружается (Loading).** По FAQ ZCode, проверьте доступ к сервису из вашей сети и то, что у ключа есть баланс и доступ к модели.

## Что дальше

* [Каталог моделей RouterAI](/models) — id, контекст и цены.
* [Claude Code через RouterAI](/pages/vibe-coding-claude-code) и [Cline через RouterAI](/pages/vibe-coding-vscode-cline) — другие способы вайб-кодинга.
* [OpenHands через RouterAI](/pages/openhands-routerai) и [Oh My Pi через RouterAI](/pages/oh-my-pi-routerai) — другие coding-агенты.
* [Документация ZCode](https://zcode.z.ai/en/docs/configuration) и [репозиторий zai-org/ZCode](https://github.com/zai-org/ZCode).