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

ZCode — десктопная среда для кодинга (Agentic Development Environment, ADE) от Z.ai со встроенным ZCode Agent: вы ставите задачу в чате, агент читает проект, запускает команды и правит файлы, а вы подтверждаете его действия. Приложение есть для macOS, Windows и Linux, бесплатное, а исходный код открыт под лицензией Apache-2.0 (репозиторий zai-org/ZCode, около 8,4 тысячи звёзд на GitHub). Через RouterAI в ZCode подключаются GLM, Claude, GPT, DeepSeek и другие модели из каталога: работа из России без 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: создайте его в личном кабинете и пополните баланс. Ключ показывается один раз.

Установка

Скачайте сборку для своей системы на странице Install в документации ZCode.

• 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. Это нормально: модель появится после подключения провайдера.

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

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

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, а переключатель справа вверху остаётся включённым.

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

Список моделей RouterAI в ZCode не подтягивает: id нужно добавить вручную из каталога. Нажмите 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 по каталогу.

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

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, при подключении аккаунта 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).

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

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

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

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.

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

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

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 сказано, что переменные окружения терминала и настройки ZCode независимы и не синхронизируются. Если в терминале у вас уже настроен ANTHROPIC_BASE_URL или другой ключ, в ZCode их нужно ввести заново. То же касается прокси: ZCode не читает HTTP_PROXY, адрес задаётся в Settings → General.
• Claude Code — агент для терминала, см. настройку через RouterAI. Мастер миграции ZCode умеет импортировать из него историю разговоров.
• Cline — расширение для VS Code, см. настройку через RouterAI. 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 — id, контекст и цены.
• Claude Code через RouterAI и Cline через RouterAI — другие способы вайб-кодинга.
• OpenHands через RouterAI и Oh My Pi через RouterAI — другие coding-агенты.
• Документация ZCode и репозиторий zai-org/ZCode.