Операторы, устанавливающие OpenClaw на headless-хостах Mac mini M4 NodeMac, часто видят успешную CLI, пока LaunchAgent шлюза завершается после обновления Node через Homebrew. Эта матрица от 2026-05-21 сопоставляет симптомы сбоев установки с корневыми причинами, сравнивает bundled и Homebrew runtime Node, перечисляет восемь воспроизводимых шагов выравнивания и включает ответы FAQ для инцидентных тикетов.
Установщики апстрима могут разместить Node.js в ~/.openclaw/tools/node/bin/node, тогда как SSH-сессия сначала разрешает /opt/homebrew/bin/node. Демон шлюза, запущенный launchd с меткой ai.openclaw.gateway, наследует ещё один PATH. Когда эти три бинарника расходятся, нативные add-on загружаются в CLI, но падают под демоном—именно класс багов, о которых в 2026 сообщают против установки шлюза, игнорирующей bundled Node на чистых хостах macOS.
Сбои установки, похожие на «OpenClaw сломан», но это дрейф PATH
- CLI здорова, шлюз down:
openclaw doctorпроходит по SSH, ноlaunchctl print gui/$(id -u)/ai.openclaw.gatewayпоказывает код выхода 78 послеbrew upgrade node. - Тройное несовпадение версий:
node -vвыводит v24.x по SSH, plist указывает на v22.19, bundled-инструменты сообщают другой patch-уровень. - npm EACCES при установке:
npm i -g openclawпадает с ошибками прав, потому что глобальный префикс недоступен для записи сервисному пользователю. - Нет git на чистом macOS: npm install прерывается, так как git нужен для зависимостей—типично на свежих образах NodeMac до установки базовых пакетов.
Начните с чеклиста headless onboard и приёмки демона, если это первая установка. По региону и размещению SSH/VNC см. руководство по регионам и SSH/VNC от 2026-05-19. Глубокая диагностика: OpenClaw doctor и диагностика здоровья. Настройка аккаунта: центр помощи и цены.
Матрица симптом → причина → исправление (копировать в runbook)
Используйте эту таблицу при живых инцидентах на арендованных узлах Mac mini M4. Каждая строка заканчивается командой, которую можно выполнить по SSH без VNC.
| Симптом | Вероятная причина | Первое исправление (SSH) | Проверка |
|---|---|---|---|
| npm EACCES | Глобальный префикс недоступен для записи | npm config set prefix ~/.npm-global |
which openclaw |
| Шлюз exit 78 | Node в plist ≠ node в CLI | Изменить путь node в ProgramArguments в ~/Library/LaunchAgents/ai.openclaw.gateway.plist |
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway |
| doctor предупреждает Node | Ниже 22.19 | Установить Node 22 через установщик или закрепить bundled-путь | node -v ≥ 22.19 |
| npm install failed | Нет git | xcode-select --install или brew install git |
git --version |
| Таймаут health | Сокет up, плагины падают | Смотреть ~/.openclaw/logs/gateway.log |
Health-вызов 3000 мс OK |
Сравнение источников runtime: какой Node должен владеть шлюзом?
Выберите один основной runtime на хост и задокументируйте его в реестре флота. Смешение источников без явных путей в plist — доминирующий режим сбоя на headless-аренде Mac mini M4 в 2026 году.
| Источник runtime | Типичный путь | Плюсы на NodeMac | Минусы |
|---|---|---|---|
| Bundled (install-cli) | ~/.openclaw/tools/node/bin/node |
Соответствует тестовой матрице апстрима; переживает churn brew | Легко игнорировать, если plist всё ещё указывает на Homebrew |
| Homebrew node@22 | /opt/homebrew/opt/node@22/bin/node |
Привычно админам macOS; быстрые security-патчи | brew upgrade может рассинхронизировать шлюз |
| Пользовательский npm-global | ~/.npm-global/bin/openclaw |
Исправляет EACCES без sudo | launchd должен явно наследовать экспорты PATH |
Процедура выравнивания в восемь шагов (воспроизводимо по SSH)
- Снимок трёх путей Node: выполнить
which node; node -v; plutil -extract ProgramArguments xml1 -o - ~/Library/LaunchAgents/ai.openclaw.gateway.plist 2>/dev/null | headи вставить в тикет. - Сначала doctor: выполнить
openclaw doctor(флаги fix только после чтения отчёта). - Закрепить Node ≥ 22.19: установить или выбрать Node, соответствующий минимуму апстрима; блокировать случайные major-downgrade.
- Исправить префикс npm: при EACCES задать
npm config set prefix ~/.npm-globalи экспортировать PATH в~/.zprofileсервисного пользователя. - Выровнять путь node в plist: указать первую запись ProgramArguments на выбранный бинарник node; выполнить
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist, затем снова bootstrap. - Повторный onboard демона: выполнить
openclaw onboard --install-daemonиз того же shell PATH, который планируете сохранить. - Health-проба: вызвать loopback health с таймаутом 3000 мс; архивировать вывод рядом с серийным номером хоста.
- Ограничение CMDB: записать выбранный источник runtime (bundled / brew / npm-global) и запретить окна brew upgrade без дымового теста шлюза.
Заметка о бизнес-процессе: команды поддержки, маршрутизирующие тикеты Slack через OpenClaw на Mac mini M4 в Сингапуре, всё равно терпят неудачу при дрейфе путей Node—сначала выровняйте runtime, потом настраивайте промпты моделей. Стабильный аптайм шлюза важнее экономии 50 мс на инференсе, когда сообщения стоят в очереди за упавшим демоном.
FAQ: PATH Node.js OpenClaw на Mac mini M4
Предпочитать bundled Node или Homebrew?
Предпочитайте bundled Node на продакшен-шлюзах, если хотите, чтобы install-cli и launchd оставались на одном бинарнике. Homebrew — только если явно закрепляете путь plist после каждого brew upgrade.
Поможет ли VNC при ошибках npm install?
Редко. Исправления PATH и прав — задачи SSH. Используйте VNC только для диалогов конфиденциальности macOS, блокирующих помощников автоматизации, а не для npm EACCES.
Какие числа нужны в приложении runbook?
Зафиксируйте semver Node, путь префикса npm, абсолютный путь node в plist, таймаут health 3000 мс и последний успешный хеш openclaw doctor, чтобы следующая смена не спорила о версиях заново.
Исправление путей установки OpenClaw на NodeMac идёт быстрее, если относиться к Mac mini M4 как к долгоживущему шлюзовому appliance, а не к одноразовому ноутбуку. Apple Silicon M4 даёт unified memory для Node-тяжёлых цепочек инструментов; нативный macOS соответствует допущениям платформы OpenClaw; SSH и VNC позволяют выровнять plist и shell без отправки железа. Аренда в Гонконге, Японии, Корее, Сингапуре или США размещает шлюзы рядом с API Slack и LLM без CAPEX, а выделенный металл не даёт шуму соседей выглядеть как «случайные сбои npm». Сравните месячную стоимость узла на странице цен, прежде чем сжечь ещё один день на несовпадающих бинарниках Node.