support@routerai.ru

Загрузка...

Вайб-кодинг в zerostack: настройка Rust-агента через RouterAI (Claude, GLM, DeepSeek)

zerostack

zerostack — терминальный coding-агент с открытым исходным кодом на Rust (репозиторий gi-dellav/zerostack, лицензия GPL-3.0). Автор описывает его как минимальный агент, вдохновлённый pi и opencode: он читает и правит файлы, запускает команды, читает AGENTS.md и CLAUDE.md, работает в интерактивном TUI и в режиме ACP — как агент-бэкенд для редакторов, поддерживающих Agent Client Protocol (например, Zed).

Главная особенность — расход памяти. В README проекта указано: бинарник около 26 МБ, потребление RAM в среднем ~16 МБ с пиками до ~24 МБ, тогда как JS-агенты занимают сотни мегабайт. Это делает zerostack удобным для слабых машин, контейнеров и работы в нескольких параллельных сессиях.

RouterAI подключается как кастомный OpenAI-совместимый провайдер: в одном агенте доступны Claude, GLM и DeepSeek из каталога моделей, работа из России без VPN и оплата в рублях. Важная деталь: по умолчанию zerostack настроен на OpenRouter, поэтому провайдера нужно переопределить явно — об этом ниже.

Требования

  • Linux или macOS. Windows в README помечен как непроверенный — запуск в WSL или контейнере надёжнее.
  • Для установки из релизов ничего, кроме терминала, не нужно. Для cargo install — свежий Rust (rustup).
  • API-ключ из личного кабинета.
  • Для ACP-режима — редактор с поддержкой Agent Client Protocol (например, Zed).

Установка

Самый быстрый способ — скрипт из репозитория:

curl -fsSL https://raw.githubusercontent.com/gi-dellav/zerostack/main/install.sh | bash
zerostack --version

Либо готовый архив с GitHub Releases. Для x86_64 Linux берите zerostack-x86_64-unknown-linux-musl.tar.gz: сборка на glibc требует библиотеку 2.39 и на Debian 12 / Ubuntu 22.04 не запустится, а musl-сборка статическая и работает везде.

tar xzf zerostack-x86_64-unknown-linux-musl.tar.gz
install -m755 zerostack-x86_64-unknown-linux-musl /usr/local/bin/zerostack
zerostack --version

Через Cargo — с набором функций на выбор. По умолчанию собираются git-worktree, mcp, subagents, archmd, status-signals и logging; ACP, память, hooks, advisor и мультимодальный ввод включаются флагами:

cargo install zerostack                    # базовый набор
cargo install zerostack --features acp,memory,hooks,advisor

Есть также Homebrew (brew tap gi-dellav/tap && brew install zerostack) и Nix. Команда zerostack --version должна вывести версию — на момент написания это zerostack 1.8.5.

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

Настройки zerostack читает из файла config.toml, config.yaml или config.json. Порядок поиска: $ZS_CONFIG_DIR, затем ~/.config/zerostack/, затем ~/.local/share/zerostack/. На практике удобнее всего ~/.config/zerostack/config.toml. Файл settings.json в zerostack — это конфигурация hooks, а не провайдеров; не путайте.

RouterAI подключается через секцию custom_providers: тип провайдера openai (Chat Completions, https://routerai.ru/api/v1), ключ — из переменной окружения, чтобы он не лежал в файле.

  1. Создайте каталог и файл конфигурации:
mkdir -p ~/.config/zerostack

# ~/.config/zerostack/config.toml
provider = "routerai"
model = "anthropic/claude-sonnet-5.5"
context_window = 1000000
enable-exa-mcp = false

[custom_providers.routerai]
provider_type = "openai"
base_url = "https://routerai.ru/api/v1"
api_key_env = "ROUTERAI_API_KEY"

Файл ~/.config/zerostack/config.toml с провайдером RouterAI: provider, model и секция custom_providers с base_url и api_key_env

  1. Положите ключ в переменную окружения — в ~/.bashrc, ~/.zshrc или в файл, который подключаете перед запуском:
export ROUTERAI_API_KEY="sk-xxxxxxxxxxxxxxxx"
  1. Проверьте, что zerostack видит провайдера и модель: zerostack --print-config показывает путь к загруженному файлу, провайдера, модель и лимиты контекста.

Вывод zerostack --print-config: config file /root/.config/zerostack/config.toml, провайдер routerai и модель anthropic/claude-sonnet-5.5

Поля секции custom_providers:

Поле Что задаёт
provider_type Базовый тип транспорта: для RouterAI — openai
base_url Адрес API: https://routerai.ru/api/v1
api_key_env Имя переменной окружения с ключом
api_style completions (по умолчанию при заданном base_url) или responses
model Модель по умолчанию для этого провайдера
headers, timeout_secs Дополнительные заголовки и таймаут запроса

Помимо файла, провайдера можно указать флагами командной строки. Это удобно для разового запроса или для проверки:

zerostack --provider routerai --model deepseek/deepseek-v4.1-flash -p "Объясни, что делает invoices.js"

Флаги --provider и --model (а также переменные ZS_PROVIDER и ZS_MODEL) имеют приоритет над файлом конфигурации.

Почему важно явно задать провайдера

Провайдер по умолчанию в zerostack — OpenRouter, и если ключ RouterAI лежит в окружении, а провайдер не переопределён, агент всё равно попытается уйти в OpenRouter. Признак этого — ошибка при старте:

No API key found. Set the OPENROUTER_API_KEY environment variable, add it to
config.api_keys under 'openrouter' ...

Значит, секция custom_providers не загрузилась или provider не переключён. Если ключ OpenRouter у вас тоже есть в окружении, уберите его из сессии (unset OPENROUTER_API_KEY) — так ошибки конфигурации видны сразу, а не маскируются чужим ключом.

Как проверить, какой эндпоинт реально используется

Самый надёжный способ — включить отладочный вывод и посмотреть, к какому хосту идёт соединение:

zerostack -p --no-session --log-level debug "скажи OK" 2>&1 | grep -i routerai

В выводе будут строки вида starting new connection: routerai.ru и connecting to ... :443. Полный подробный лог с трассировкой запросов пишется в файл ~/.local/share/zerostack/logs/ при флаге -v; путь можно переопределить через --log-file.

Ещё два признака: команда /provider внутри агента показывает текущего провайдера, а заведомо неверный ключ при правильно заданном base_url даёт ответ 401 Unauthorized от RouterAI — это и подтверждает, куда уходит запрос.

ROUTERAI_API_KEY=sk-invalid zerostack -p --provider routerai --model z-ai/glm-5.3-flash "hi"

ACP-режим

ACP — протокол на JSON-RPC, по которому редактор запускает агента отдельным процессом и общается с ним. В README zerostack он назван Agent Communication Protocol, а в Zed — Agent Client Protocol; стороны совместимы, что проверяется уже на рукопожатии. С включённой функцией acp zerostack становится ACP-сервером, и редактор может открывать в нём треды.

# stdio: редактор запускает процесс сам
zerostack --acp

# TCP: слушает на порту (по умолчанию 7243)
zerostack --acp --acp-host 0.0.0.0 --acp-port 7243

В Zed добавьте агента через Agent Settings → External Agents → Add Agent → Add Custom Agent и укажите в настройках:

{
  "agent_servers": {
    "zerostack": {
      "type": "custom",
      "command": "zerostack",
      "args": ["--acp"],
      "env": {
        "ROUTERAI_API_KEY": "sk-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Режим stdio подходит для редакторов, которые запускают агента подпроцессом; TCP-вариант нужен, если редактор подключается к уже запущенному серверу.

Ответ на запрос initialize по stdio выглядит так:

Ответ ACP-сервера zerostack на JSON-RPC initialize: версия агента и поддерживаемые возможности

Ключевой момент: ACP не заменяет настройку провайдера. Zed в треде внешнего агента не подставляет свои модели и ключи — провайдер, ключ и выбор модели остаются за zerostack. Поэтому перед подключением к редактору убедитесь, что custom_providers и provider = "routerai" работают в терминале: в ACP-режиме без настроенного провайдера агент просто не обработает запрос.

Выбор модели

Идентификаторы взяты из каталога RouterAI на момент написания; актуальные цены и список смотрите там же. Для агента важно уверенное вызывание инструментов (tool calling) — от него зависит, сможет ли модель править файлы и запускать команды.

Модель Контекст Для чего
anthropic/claude-sonnet-5.5 1M Основная модель: фичи, отладка, рефакторинг среднего размера
anthropic/claude-opus-5 1M Сложные рефакторинги и архитектурные изменения
anthropic/claude-haiku-5.5 1M Быстрые мелкие задачи, массовые правки
z-ai/glm-5.3-flash 1M Рутина: дешёвые правки, переименования, шаблонный код
deepseek/deepseek-v4.1-flash 1M Рутина и длинные файлы: дешёвый ввод, контекст 1M
openai/gpt-5.5 1M Альтернатива Claude от OpenAI для тех же задач

У zerostack есть механизм быстрых моделей (quick_models). Они задаются в том же config.toml и переключаются командой /models <имя>, флагом --quick-model или по Alt+M:

[quick_models.fast]
provider = "routerai"
model = "z-ai/glm-5.3-flash"

[quick_models.cheap]
provider = "routerai"
model = "deepseek/deepseek-v4.1-flash"

zerostack --quick-model=fast

Рабочая схема — держать Sonnet для сложных задач и переключаться на GLM Flash или DeepSeek Flash для рутины. Для разового запуска с другой моделью достаточно /model <id> или --model в командной строке.

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

Быстрая проверка без интерактивного интерфейса — один запрос флагом -p (--print):

zerostack -p --no-session "Ответь одним словом: OK"

Ответ OK означает, что конфигурация верна. Дальше проверьте агента в работе: запустите zerostack в папке проекта и дайте небольшую задачу — например, добавить функцию и тест к ней, а затем прогнать тесты.

На первом запуске в новом проекте zerostack спросит, создать ли ARCHITECTURE.md — файл с описанием архитектуры для агентов. Ответьте n, если не хотите добавлять его в репозиторий; отказ ни на что не влияет.

TUI zerostack в демо-проекте Invoices: заголовок с моделью anthropic/claude-sonnet-5.5 и строка ввода

В строке статуса видно рабочую папку, модель, занятый контекст (~3k/1.0M) и активный prompt (code). Для примера ниже агент получил задачу добавить в демо-проект функцию pendingInvoices() и тест к ней.

Задача в zerostack: агент прочитал файлы проекта, внёс правки в invoices.js и invoices.test.js и запустил npm test

В конце агент отвечает, что сделал: функция фильтрует счета со статусом pending, тест проверяет состав, статусы и что выборка не равна полному списку, npm test — 2 из 2. В строке статуса — израсходованные токены (⇡38k ⇣2k).

Дифф изменений в invoices.js после задачи и успешный прогон npm test

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

No API key found. Set the OPENROUTER_API_KEY ...

Провайдер остался по умолчанию. Проверьте, что config.toml лежит в ~/.config/zerostack/, что в нём есть provider = "routerai" и секция [custom_providers.routerai], а переменная из api_key_env экспортирована в том же терминале. Быстрая диагностика — zerostack --print-config.

401 Unauthorized

Ключ не найден или неверен, но запрос уже уходит на RouterAI. Проверьте значение в переменной из api_key_env и что ключ скопирован из личного кабинета целиком. Если 401 приходит от другого сервиса — значит, base_url указывает не туда.

404 или «модель не найдена»

base_url должен быть https://routerai.ru/api/v1 — с /v1. Идентификатор модели пишется целиком, с префиксом производителя: anthropic/claude-sonnet-5.5, z-ai/glm-5.3-flash. Сверьтесь с каталогом.

402 Payment Required

Недостаточно средств на балансе — пополните его в разделе Биллинг.

Сборка из релиза не запускается: GLIBC_2.39 not found

Возьмите zerostack-x86_64-unknown-linux-musl.tar.gz вместо варианта с gnu в имени: он статический и не зависит от версии системной glibc.

В логах WARN про error sending request при старте

Повторяющиеся предупреждения в начале сессии относятся к служебному запросу списка моделей для автоопределения контекста. Если указать context_window в конфигурации явно (например, 1000000 для моделей из таблицы выше), автозапрос не нужен и предупреждения пропадают.

Ошибка подключения к mcp.exa.ai

В новой установке zerostack сам подключает MCP-сервер Exa для веб-поиска, и он может быть недоступен из вашей сети. На работу агента это не влияет; чтобы не видеть ошибку, добавьте в конфигурацию enable-exa-mcp = false.

zerostack, Cline, OpenCode и Aider: чем отличается

zerostack — молодой проект: репозиторий появился в мае 2026 года, на Hacker News его представили постом «Zerostack – A Unix-inspired coding agent written in pure Rust» — 575 баллов. Для сравнения, у OpenCode, Cline и Aider аудитория и экосистема заметно больше, и это честное ограничение: меньше готовых рецептов, меньше ответов на форумах, API может меняться между версиями.

Зато по расходу ресурсов он в другой категории. OpenCode и другие JS-агенты, по данным README zerostack, занимают ~300 МБ RAM с пиками до ~700 МБ против ~16–24 МБ у zerostack, а CPU в простое — ~2 % против 0 %. Если вы держите два-три агента одновременно или работаете на ноутбуке с 8 ГБ, разница заметна. Плюс zerostack не требует Node.js: это один бинарник, который запускается сразу.

По возможностям набор стандартный для 2026 года: правка файлов, bash, MCP, субагенты, сессии, режимы разрешений (readonly, guarded, standard, yolo), песочница через bubblewrap, system prompts для разных фаз работы (code, plan, review, debug). Cline — расширение VS Code, Aider — CLI-агент с фокусом на git-коммиты и историю правок; zerostack ближе к минималистичным TUI-агентам вроде Crush и Pi.

Что дальше