헤드리스 NodeMac Mac mini M4 호스트에 OpenClaw를 설치할 때 CLI는 성공하는데 Homebrew Node 업그레이드 후 게이트웨이 LaunchAgent가 종료되는 경우가 많습니다. 본 2026-05-21 매트릭스는 설치 실패 증상을 근본 원인에 매핑하고, 번들과 Homebrew Node 런타임을 비교하며, 8단계 재현 가능한 정렬 절차와 인시던트 티켓에 붙일 FAQ 답변을 제공합니다.
업스트림 설치기는 Node.js를 ~/.openclaw/tools/node/bin/node에 둘 수 있는데, SSH 세션은 /opt/homebrew/bin/node를 먼저 해석할 수 있습니다. launchd 라벨 ai.openclaw.gateway로 시작하는 게이트웨이 데몬은 또 다른 PATH를 상속합니다. 이 세 바이너리가 어긋나면 CLI에서는 네이티브 애드온이 로드되지만 데몬에서는 실패합니다—2026년 깨끗한 macOS 호스트에서 게이트웨이 설치가 번들 Node를 무시한다고 보고된 바로 그 유형의 버그입니다.
「OpenClaw가 고장」처럼 보이지만 실은 PATH 드리프트인 설치 실패
- CLI 정상, 게이트웨이 다운: SSH에서
openclaw doctor는 통과하지만brew upgrade node후launchctl print gui/$(id -u)/ai.openclaw.gateway가 종료 코드 78을 표시. - 버전 삼중 불일치: SSH의
node -v가 v24.x, plist는 v22.19, 번들 도구는 다른 패치 수준 보고. - 설치 시 npm EACCES:
npm i -g openclaw가 전역 prefix가 서비스 사용자에게 쓰기 불가라 권한 오류. - 깨끗한 macOS에 git 없음: 의존성 fetch에 git이 필요해 npm install 중단—베이스라인 패키지 적용 전 신규 NodeMac 이미지에서 흔함.
첫 설치라면 헤드리스 onboard 및 데몬 수용 체크리스트부터 시작하세요. 리전과 SSH/VNC 배치는 2026-05-19 리전·SSH/VNC 런북 참조. 심층 진단은 OpenClaw doctor 및 헬스 진단. 계정 설정: 도움말 센터와 요금.
증상 → 원인 → 수정 매트릭스(runbook에 복사)
임대 Mac mini M4 노드에서 라이브 인시던트 시 본 표를 사용하세요. 각 행 끝은 VNC 없이 SSH로 실행할 수 있는 명령입니다.
| 증상 | 가능 원인 | 1차 수정(SSH) | 검증 |
|---|---|---|---|
| npm EACCES | 전역 prefix 쓰기 불가 | npm config set prefix ~/.npm-global |
which openclaw |
| 게이트웨이 종료 78 | Plist node ≠ CLI node | ~/Library/LaunchAgents/ai.openclaw.gateway.plist ProgramArguments node 경로 편집 |
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway |
| doctor Node 경고 | 22.19 미만 | 설치기로 Node 22 설치 또는 번들 경로 고정 | node -v ≥ 22.19 |
| npm install 실패 | git 없음 | xcode-select --install 또는 brew install git |
git --version |
| 헬스 타임아웃 | 소켓 up, 플러그인 크래시 | ~/.openclaw/logs/gateway.log tail |
헬스 호출 3000 ms OK |
런타임 소스 비교: 어떤 Node가 게이트웨이를 소유해야 하나
호스트당 하나의 주 런타임을 선택하고 플릿 레지스트리에 기록하세요. plist 경로 없이 소스를 혼합하는 것이 2026년 헤드리스 Mac mini M4 임대에서 지배적인 실패 모드입니다.
| 런타임 소스 | 일반 경로 | NodeMac 장점 | 단점 |
|---|---|---|---|
| 번들(install-cli) | ~/.openclaw/tools/node/bin/node |
업스트림 테스트 매트릭스와 일치; brew 변동에 강함 | plist가 Homebrew를 가리키면 무시되기 쉬움 |
| Homebrew node@22 | /opt/homebrew/opt/node@22/bin/node |
macOS 관리자에게 친숙; 보안 패치 빠름 | brew upgrade가 게이트웨이 동기화 깨뜨림 |
| 사용자 npm-global | ~/.npm-global/bin/openclaw |
sudo 없이 EACCES 수정 | launchd가 PATH export를 명시 상속해야 함 |
8단계 정렬 절차(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 설치 또는 선택; 우발적 메이저 다운그레이드 차단.
- npm prefix 수정: EACCES 시
npm config set prefix ~/.npm-global및 서비스 사용자~/.zprofile에서 PATH export. - plist node 경로 정렬: ProgramArguments 첫 항목을 선택한 node 바이너리로;
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.gateway.plist후 재 bootstrap. - 데몬 재 onboard: 유지할 shell PATH와 동일 환경에서
openclaw onboard --install-daemon실행. - 헬스 프로브: 3000 ms 타임아웃으로 루프백 health 호출; 출력을 호스트 시리얼과 함께 아카이브.
- CMDB 가드레일: 선택한 런타임 소스(번들 / brew / npm-global) 기록; 게이트웨이 스모크 테스트 없는 brew upgrade 창 금지.
업무 워크플로 참고: 싱가포르 Mac mini M4의 OpenClaw로 Slack 티켓을 라우팅하는 지원팀도 Node 경로가 어긋나면 실패합니다—모델 프롬프트 튜닝 전에 런타임 정렬을 먼저 고치세요. 크래시한 데몬 뒤에 메시지가 큐에 쌓일 때 추론에서 50 ms 줄이는 것보다 안정적인 게이트웨이 가동 시간이 더 중요합니다.
FAQ: Mac mini M4에서 OpenClaw Node.js PATH
번들 Node와 Homebrew 중 무엇을 우선?
install-cli와 launchd를 동일 바이너리로 유지하려면 프로덕션 게이트웨이에 번들 Node 우선. Homebrew는 매 brew upgrade 후 plist 경로를 명시 고정할 때만.
VNC가 npm 설치 오류에 도움이 되나?
거의 없음. PATH와 권한 수정은 SSH 작업. macOS 프라이버시 프롬프트가 자동화 헬퍼를 막을 때만 VNC—npm EACCES에는 불필요.
runbook 부록에 기록할 숫자는?
Node semver, npm prefix 경로, plist node 절대 경로, 헬스 타임아웃 3000 ms, 마지막 성공 openclaw doctor 해시를 기록해 다음 온콜이 버전 논쟁을 반복하지 않게.
NodeMac에서 OpenClaw 설치 경로를 고치려면 Mac mini M4를 일회용 노트북이 아니라 장기 게이트웨이 어플라이언스로 다루는 편이 빠릅니다. Apple Silicon M4 통합 메모리는 Node 집약적 툴체인에 적합하고, 네이티브 macOS는 OpenClaw 플랫폼 가정과 맞습니다. SSH와 VNC로 하드웨어 배송 없이 plist와 셸 환경을 맞출 수 있습니다. 홍콩·일본·한국·싱가포르·미국에서 임대하면 Slack과 LLM API 가까이 게이트웨이를 두며 capex를 피합니다. 전용 메탈은 이웃 노이즈가 「무작위 npm 실패」로 위장하는 것도 막습니다. Node 바이너리 불일치로 하루 더 낭비하기 전 요금 페이지에서 월간 노드 비용을 비교하세요.