Node.js 버전의 중요성
OpenClaw은 Node.js 22 이상을 요구합니다. 이것은 선택 사항이 아닌 필수 요구사항입니다. 22 미만의 버전은 OpenClaw이 시작되지 않거나 예기치 못한 오류를 일으킵니다. Node.js 22에는 개선된 ESM 지원, 네이티브 WebSocket API, 성능 최적화 등 OpenClaw이 의존하는 많은 기능이 도입되었습니다.
또한 특별히 주의할 점이 있습니다: Bun이 Node.js 대안으로 최근 빠르게 발전하고 있지만, WhatsApp과 Telegram의 WebSocket 연결 처리 시 알려진 호환성 문제가 있어 OpenClaw 공식적으로는 Bun 사용을 권장하지 않습니다.
nvm(Node Version Manager)은 여러 Node.js 버전을 관리하는 최적의 도구로, 시스템 전역 환경에 영향을 주지 않으면서 다른 버전 간에 자유롭게 전환할 수 있습니다.
nvm 설치
macOS와 Linux
macOS와 Linux에서 nvm 설치는 매우 간단합니다:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
설치 스크립트는 자동으로 nvm 로드 명령을 셸 설정 파일(~/.bashrc, ~/.zshrc 등)에 추가합니다. 설치 완료 후 셸을 다시 로드합니다:
source ~/.bashrc
zsh(macOS 기본 셸)를 사용하는 경우:
source ~/.zshrc
nvm 설치 성공 확인:
nvm --version
Windows (WSL2)
OpenClaw은 Windows에서 WSL2를 통해 실행하는 것을 권장합니다. WSL2의 Ubuntu 환경에서는 nvm 설치 방법이 Linux와 동일합니다:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
네이티브 Windows 환경을 사용하는 경우 nvm-windows(https://github.com/coreybutler/nvm-windows)를 고려할 수 있지만, 최상의 호환성을 위해 WSL2 사용을 강력히 권장합니다.
Node.js 22 설치
nvm으로 최신 Node.js 22 LTS 버전을 설치합니다:
nvm install 22
nvm이 자동으로 지정된 버전을 다운로드, 컴파일(필요한 경우)하고 설치합니다. 설치 완료 후 자동으로 해당 버전으로 전환됩니다:
node --version
출력이 v22.x.x인지 확인합니다.
기본 버전으로 설정
Node.js 22를 nvm의 기본 버전으로 설정하면 새 터미널을 열 때마다 자동으로 사용됩니다:
nvm alias default 22
기본 버전 설정 확인:
nvm current
OpenClaw 설치
Node.js 환경이 준비되었으면 OpenClaw을 설치할 수 있습니다.
방법 1: npm 전역 설치
npm install -g openclaw@latest
방법 2: 공식 설치 스크립트
curl -fsSL https://openclaw.ai/install.sh | bash
두 가지 방법 모두 OpenClaw을 전역 커맨드 라인 도구로 설치합니다. 설치 확인:
openclaw --version
OpenClaw 초기화
최초 설치 후 가이드 프로그램을 실행하여 설정을 완료합니다:
openclaw onboard --install-daemon
가이드 프로그램이 다음 단계를 안내합니다:
- AI 모델 공급자(OpenAI, Anthropic 등)의 API 키 설정
- 채팅 플랫폼 선택 및 연결(WhatsApp, Telegram, Discord 등)
- 백그라운드 데몬 프로세스 설치(macOS에서는 LaunchAgent, Linux에서는 systemd 서비스)
모든 설정은 ~/.openclaw/openclaw.json 파일에 저장됩니다.
설치 후 검증
OpenClaw 내장 진단 도구를 실행하여 환경이 올바르게 설정되었는지 확인합니다:
openclaw doctor
이 명령은 다음을 검사합니다:
- Node.js 버전이 22+ 요구사항을 충족하는지
- OpenClaw 설정 파일이 완전한지
- 각 채팅 플랫폼 연결이 정상인지
- 네트워크 연결성
모든 검사 항목을 통과한 후 OpenClaw을 시작합니다:
openclaw start
또는 관리 패널을 엽니다:
openclaw dashboard
nvm 일상 사용 팁
설치된 버전 확인
nvm ls
사용 가능한 원격 버전 확인
nvm ls-remote --lts
버전 전환
nvm use 22
프로젝트 단위 버전 고정
프로젝트 디렉토리에 .nvmrc 파일을 생성하여 Node.js 버전을 고정합니다:
echo "22" > .nvmrc
이후 프로젝트 디렉토리에서 nvm use만 실행하면 nvm이 자동으로 .nvmrc를 읽고 지정된 버전으로 전환합니다.
자동 버전 전환
~/.bashrc 또는 ~/.zshrc에 다음 스크립트를 추가하면 프로젝트 디렉토리에 진입할 때 자동으로 Node.js 버전이 전환됩니다:
autoload -U add-zsh-hook
load-nvmrc() {
local nvmrc_path="$(nvm_find_nvmrc)"
if [ -n "$nvmrc_path" ]; then
local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")
if [ "$nvmrc_node_version" = "N/A" ]; then
nvm install
elif [ "$nvmrc_node_version" != "$(nvm version)" ]; then
nvm use
fi
fi
}
add-zsh-hook chdir load-nvmrc
load-nvmrc
Node.js 버전 업그레이드
Node.js 새 버전이 출시되면 nvm을 통해 쉽게 업그레이드할 수 있습니다:
nvm install 22 --reinstall-packages-from=current
--reinstall-packages-from=current 매개변수는 현재 버전에 전역 설치된 npm 패키지(OpenClaw 포함)를 새 버전으로 자동 마이그레이션합니다.
업그레이드 후 OpenClaw이 여전히 정상적으로 작동하는지 확인합니다:
openclaw --version
openclaw doctor
이전 버전 제거
업그레이드 후 더 이상 필요하지 않은 이전 버전을 정리할 수 있습니다:
nvm uninstall 20
자주 묻는 질문
nvm 명령을 찾을 수 없음
셸 설정 파일에 nvm 로드 스크립트가 포함되어 있는지 확인하세요. ~/.bashrc 또는 ~/.zshrc에 다음 내용이 있는지 확인합니다:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
전역 npm 패키지가 버전 전환 후 사라짐
nvm의 각 Node.js 버전에는 독립적인 전역 패키지 디렉토리가 있습니다. 버전 전환 후에는 전역 패키지를 다시 설치해야 하며, 또는 --reinstall-packages-from 매개변수를 사용하여 설치 시 자동으로 마이그레이션할 수 있습니다.
sudo npm install 실패
nvm으로 관리하는 Node.js는 sudo를 사용할 필요가 없으며 사용해서도 안 됩니다. 권한 문제가 발생하면 시스템 수준의 Node.js를 잘못 사용하고 있는지 확인하세요. which node를 실행하여 경로가 nvm 디렉토리(~/.nvm/versions/node/v22.x.x/bin/node와 유사)를 가리키는지 확인합니다.
요약
nvm은 OpenClaw의 실행 환경 관리를 위해 유연하고 안정적인 방안을 제공합니다. nvm을 통해 Node.js 버전을 쉽게 설치, 전환, 관리하여 OpenClaw이 항상 호환되는 Node.js 22+ 환경에서 실행되도록 할 수 있습니다. 개발 디버깅이든 프로덕션 배포든 nvm은 Node.js 버전 관리의 모범 사례입니다.