1. Mac 전용 OpenClaw 가이드가 필요한 이유
OpenClaw는 여러 플랫폼에서 동작하지만, Mac(특히 Apple Silicon)에서는 환경 경로, Homebrew·npm 전역 prefix, Gatekeeper·권한, 프로세스 백그라운드 유지 방식이 Linux/Windows와 다릅니다. "명령을 찾을 수 없음", EACCES, 포트 사용 중에서 막히는 분이 많습니다. 본 가이드는 재현 가능한 Mac 단계와 트러블슈팅 표를 제공합니다.
2. Mac 환경 준비(Xcode CLI, Homebrew, Node)
1단계: Xcode Command Line Tools 설치. 터미널에서 xcode-select --install 실행.
2단계: Homebrew를 공식 원라이너로 설치. Apple Silicon인 경우 PATH에 Homebrew 추가: echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile 후 source ~/.zprofile.
3단계: Node.js 22+ 설치. 권장: brew install nvm, 셸 설정 후 nvm install 22, nvm use 22. 또는 brew install node@22 및 brew link node@22 --force. node -v, npm -v로 확인.
3. 설치 방식 비교
| 방식 | 명령 / 참고 | 용도 |
|---|---|---|
| npm 전역 | npm install -g openclaw@latest | 기존 Node 환경, 빠른 체험 |
| 공식 스크립트 | curl -fsSL https://openclaw.ai/install.sh | bash | 의존성·PATH 일괄 설정 |
| Docker | 공식 또는 커뮤니티 OpenClaw 이미지 사용 | 격리 환경 |
4. 5단계 설치와 첫 실행
1단계: 선택한 방식으로 설치 실행(예: npm install -g openclaw@latest). EACCES: permission denied가 나오면 npm 전역 디렉터리 권한 수정: sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}.
2단계: CLI 확인. 새 터미널에서 openclaw --version 실행. "명령을 찾을 수 없음"이면 PATH에 npm 전역 bin(npm config get prefix + /bin)이 포함되는지 확인.
3단계: 문서대로 초기화(예: openclaw onboard) 후 API 키 설정. 기본 콘솔 포트는 18789 또는 3000인 경우가 많으니 방화벽·보안 그룹에서 허용.
4단계: 게이트웨이/서비스 시작(예: openclaw gateway 또는 openclaw start). 브라우저에서 해당 포트로 접속해 콘솔 확인.
5단계: 최소 테스트(콘솔 또는 CLI로 요청 1회) 후 필요 시 LaunchAgent 또는 백그라운드 유지 설정.
5. Apple Silicon 참고사항
（1）Homebrew 경로: Apple Silicon에서는 Homebrew가 /opt/homebrew에 있음. /opt/homebrew/bin을 PATH에 추가. （2）Rosetta 2: 일부 npm 네이티브 모듈이 Rosetta 설치를 요청할 수 있음. 요청 시 설치. （3）Gatekeeper: 바이너리가 차단되면 시스템 설정 → 개인 정보 보호 및 보안 → "그래도 열기" 선택.
6. Mac 트러블슈팅 표
| 증상 | 가능한 원인 | 조치 |
|---|---|---|
| 명령을 찾을 수 없음(openclaw / node) | PATH에 Homebrew 또는 npm 전역 bin 없음 | ~/.zprofile 또는 ~/.bash_profile에 경로 추가 후 source |
| EACCES | npm 전역 디렉터리 소유자가 현재 사용자가 아님 | chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share} |
| 포트 사용 중 | 기본 포트 선점 | 설정에서 포트 변경 또는 lsof로 프로세스 확인 후 종료 |
| 콘솔 접속 불가 | 방화벽 또는 보안 그룹 | macOS 방화벽에서 앱 허용; 원격 Mac이면 18789/3000 개방 |
| 덮개 닫으면 프로세스 종료 | 유지 설정 없음 | LaunchAgent 또는 nohup/screen 사용; 또는 원격 Mac에서 24/7 실행 |
7. 마무리: 원격 Mac에서 OpenClaw 24/7 실행
로컬에서 OpenClaw가 동작하면, 24/7 가동이 필요하거나 본인 PC를 쓰지 않거나 슬립·덮개 문제를 피하려면 원격 Mac 노드에 배포하세요. 동일한 macOS와 위 단계로 전용·안정 가동이 가능합니다. 로컬 유지·운영 부담을 줄이려면 MACGPU 원격 Mac을 임대해 그곳에 OpenClaw를 설치하면 한 번 설정으로 장기 안정 운영이 가능합니다.