Node 환경 먼저 맞추기
OpenClaw npm 설치 방법은 설치 명령보다 Node 런타임 조건을 먼저 맞추는 데서 시작됩니다. 공식 설치 문서는 Node 24를 권장하고 Node 22.14 이상을 지원 대상으로 안내합니다. 이미 nvm, fnm, Volta 같은 도구로 Node를 관리한다면 설치 스크립트보다 npm 전역 설치가 더 예측 가능합니다. Windows 사용자는 네이티브 Windows도 가능하지만 WSL2가 더 안정적인 선택입니다. 먼저 현재 터미널에서 Node와 npm 버전을 확인하고, 전역 설치 후 `openclaw` 명령이 잡히도록 npm global bin 경로가 PATH에 포함되어 있는지 확인합니다.
node -v
npm -v
npm prefix -g
echo "$PATH"npm 전역 설치 실행
Node 조건이 맞으면 OpenClaw CLI를 전역 패키지로 설치합니다. 공식 문서는 npm, pnpm, bun 경로를 함께 안내하지만 이 글에서는 이미 Node를 관리하는 사용자를 위한 npm 방식을 기준으로 합니다. `@latest`를 붙이면 현재 배포판을 가져오므로 이전 실험 설치와 혼동을 줄일 수 있습니다. 설치 뒤에는 온보딩 명령으로 모델 설정, API 키, Gateway 구성을 진행합니다. 데몬까지 함께 설치하려면 공식 npm 예시처럼 `--install-daemon` 옵션을 붙입니다. macOS에서 sharp 빌드 오류가 발생하면 libvips 충돌을 의심하고 환경 변수를 붙인 재설치를 검토합니다.
npm install -g openclaw@latest
openclaw onboard --install-daemon
# sharp 빌드 오류가 있을 때
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest설치 후 상태 확인
온보딩이 끝났다면 성공 화면만 보지 말고 CLI와 Gateway 상태를 각각 확인해야 합니다. `openclaw --version`은 명령이 전역 PATH에서 잡히는지 확인하는 최소 기준입니다. `openclaw doctor`는 설정 누락이나 환경 문제를 찾아 주며, `openclaw gateway status`는 Gateway 실행 여부를 확인합니다. 명령을 찾지 못한다면 재설치보다 npm 전역 prefix와 셸 PATH를 먼저 확인해야 합니다. API 키를 넣은 뒤에는 짧은 요청으로 실제 모델 호출이 되는지까지 확인해야 설치가 끝났다고 볼 수 있습니다.
openclaw --version
openclaw doctor
openclaw gateway status
export PATH="$(npm prefix -g)/bin:$PATH"맺음말
OpenClaw npm 설치 방법의 핵심은 Node 조건, 전역 CLI 설치, 온보딩, 상태 점검을 한 흐름으로 묶는 것입니다. Node를 직접 관리하는 환경에서는 `npm install -g openclaw@latest`가 단순할 수 있지만, Node 버전과 PATH가 맞지 않으면 설치가 끝나도 명령을 실행할 수 없습니다. 따라서 설치 전에는 Node 24 또는 Node 22.14 이상인지 확인하고, 설치 후에는 `openclaw --version`, `openclaw doctor`, `openclaw gateway status`를 차례로 실행해야 합니다. 문제가 생기면 패키지를 반복 삭제하기보다 PATH, npm prefix, sharp 빌드 오류, Gateway 실행 상태를 분리해 보는 편이 빠릅니다. 이 순서로 정리하면 OpenClaw를 개인 AI 도구나 개발 보조 환경에 안정적으로 붙일 수 있습니다.
댓글
댓글 쓰기