Почему OpenClaw требует Node.js 22
OpenClaw написан на TypeScript и выполняется в среде Node.js. Версия 22 — не произвольный выбор: агент использует ряд возможностей, которые появились именно в этом релизе.
Ключевые зависимости от Node.js 22+:
- Native fetch API — встроенный fetch без полифиллов для работы с LLM API.
- Web Streams API — потоковая обработка ответов языковых моделей.
- V8 12.4 — улучшенная производительность работы с JSON и регулярными выражениями.
- Node Test Runner — используется во внутренних тестах агента.
- ESM по умолчанию — вся кодовая база OpenClaw использует ES-модули.
Запуск на Node.js 18 или 20 приведёт к ошибкам при старте. Node.js 21 не является LTS и не поддерживается официально.
Таблица совместимости версий
| Node.js | Статус | Примечание |
|---|---|---|
| 16.x | Не поддерживается | Слишком старая, нет fetch |
| 18.x | Не поддерживается | Нет нужных Web Streams API |
| 20.x | Не поддерживается | Несовместим с модульной системой |
| 21.x | Не поддерживается | Не LTS, нестабильная |
| 22.x | Рекомендуется | Полная поддержка |
| 23.x | Экспериментально | Может работать, не тестируется |
Подробнее о системных требованиях — в статье про установку OpenClaw.
Установка через nvm (рекомендуется)
nvm (Node Version Manager) — лучший способ управлять версиями Node.js. Он позволяет устанавливать несколько версий и переключаться между ними без конфликтов.
macOS и Linux
- Установите nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash- Активируйте nvm в текущей сессии:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"Либо перезапустите терминал — nvm добавит себя в ~/.bashrc или ~/.zshrc автоматически.
- Установите Node.js 22 LTS:
nvm install 22
nvm use 22
nvm alias default 22- Проверьте установку:
node --version # v22.x.x
npm --version # 10.x.xWindows (nvm-windows)
На Windows используется отдельная утилита — nvm-windows:
- Скачайте установщик с github.com/coreybutler/nvm-windows/releases.
- Запустите
nvm-setup.exeи следуйте инструкциям мастера. - Откройте PowerShell от имени администратора:
nvm install 22
nvm use 22- Проверьте:
node --version
npm --versionУстановка без nvm
Если вы предпочитаете прямую установку:
macOS через Homebrew
brew install node@22
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcLinux (Ubuntu/Debian) через NodeSource
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejsWindows через официальный установщик
Скачайте LTS-версию с nodejs.org и запустите .msi-установщик. Убедитесь, что в мастере отмечена галочка Add to PATH.
Проверка корректной установки
После установки выполните диагностику:
node --version # ожидается v22.x.x
npm --version # ожидается 10.x.x или выше
npx --version # должна быть установлена автоматическиЕсли команды не найдены — проблема с PATH (смотрите раздел ниже).
Частые ошибки и их решение
Ошибка: «node: command not found»
Причина: Node.js не добавлен в PATH.
Решение на macOS/Linux:
echo $PATH # проверьте, есть ли путь к node
which node # должно вернуть путь, например /usr/local/bin/nodeЕсли путь отсутствует, добавьте его вручную. Для nvm:
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc
source ~/.zshrcРешение на Windows: Зайдите в Параметры системы → Переменные среды, найдите переменную PATH и убедитесь, что путь к Node.js присутствует.
Ошибка: «ENGINE: node >= 22 required»
OpenClaw явно проверяет версию при старте. Если видите эту ошибку:
node --version # проверьте текущую версию
nvm use 22 # переключитесь на нужнуюЕсли используете nvm, убедитесь, что в .nvmrc файле проекта указана версия 22.
Конфликт нескольких версий Node.js
Симптом: node --version показывает правильную версию, но при запуске OpenClaw используется другая.
Решение:
which node # покажет путь к активной версии
nvm current # покажет активную версию nvm
nvm alias default 22 # установите 22 как версию по умолчаниюnpm install зависает или падает с ошибкой сети
- Проверьте соединение с интернетом.
- Смените npm-реестр:
npm config set registry https://registry.npmjs.org/ - Очистите кеш:
npm cache clean --force - Повторите установку.
Использование .nvmrc в проекте OpenClaw
Репозиторий OpenClaw содержит файл .nvmrc с нужной версией Node.js. Если вы используете nvm, достаточно выполнить в папке проекта:
nvm usenvm автоматически прочитает файл и переключится на нужную версию. Это исключает ошибки при обновлении проекта.
Следующие шаги
После успешной установки Node.js 22:
- Перейдите к установке OpenClaw — клонирование репозитория и сборка.
- Ознакомьтесь с полным гидом по OpenClaw, чтобы понять возможности агента.
- После установки изучите интеграции OpenClaw для подключения внешних сервисов.
Дальше по установке: на Linux и на macOS. Если при установке навыка ломается brew — разбор этой ошибки.