문제 설명
OpenClaw을 설치할 때 다음과 같은 오류 메시지를 만날 수 있습니다:
npm ERR! engine Unsupported engine
npm ERR! notsup Not compatible with your version of node/npm: openclaw@latest
npm ERR! notsup Required: {"node":">=22.0.0"}
npm ERR! notsup Actual: {"node":"18.17.1","npm":"9.6.7"}
또는 실행 시 다음과 같은 오류가 발생합니다:
SyntaxError: Unexpected token '??='
at wrapSafe (internal/modules/cjs/loader.js:915:16)
이러한 오류는 모두 동일한 근본 원인을 가리킵니다: Node.js 버전이 OpenClaw이 요구하는 최소 버전 22.0.0보다 낮습니다. OpenClaw은 네이티브 WebSocket, import attributes, 새로운 모듈 해석 알고리즘 등 Node.js 22+ 에서만 지원되는 다수의 언어 기능을 사용하므로 이전 버전에서는 실행할 수 없습니다.
진단 단계
먼저 현재 설치된 Node.js 버전을 확인합니다:
node -v
출력이 v22.0.0 미만인 경우(예: v18.17.1 또는 v20.11.0) 업그레이드가 필요합니다.
동시에 npm 버전도 확인하여 Node.js 22와 호환되는지 확인합니다:
npm -v
Node.js 22에 기본 포함된 npm 버전은 10.x 이상입니다. npm 버전이 10 미만인 경우에도 설치 과정에서 문제가 발생할 수 있습니다.
해결 방법
방법 1: nvm으로 버전 전환 (권장)
nvm(Node Version Manager)은 여러 Node.js 버전을 관리하는 최적의 도구입니다. 아직 nvm을 설치하지 않았다면 먼저 설치하세요.
Linux / macOS:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
Windows:
Windows 사용자는 nvm-windows를 사용해야 하며, GitHub Releases 페이지에서 설치 패키지를 다운로드하세요.
nvm 설치 후 Node.js 22를 설치하고 전환합니다:
nvm install 22
nvm use 22
nvm alias default 22
버전이 전환되었는지 확인합니다:
node -v
# v22.x.x가 출력되어야 합니다
npm -v
# 10.x.x가 출력되어야 합니다
그런 다음 OpenClaw을 다시 설치합니다:
npm install -g openclaw
방법 2: fnm을 nvm 대안으로 사용
fnm(Fast Node Manager)은 Rust로 작성된 더 빠른 Node.js 버전 관리 도구입니다:
# macOS / Linux
curl -fsSL https://fnm.vercel.app/install | bash
# Windows (PowerShell)
winget install Schniz.fnm
설치 후:
fnm install 22
fnm use 22
fnm default 22
방법 3: 최신 LTS 직접 다운로드 설치
여러 Node.js 버전을 관리할 필요가 없다면 Node.js 공식 사이트에서 22.x LTS 버전의 설치 패키지를 직접 다운로드하여 덮어쓰기 설치할 수 있습니다.
설치 완료 후 새 터미널 창을 열고 버전을 확인합니다:
node -v
자주 발생하는 함정
시스템에 여러 Node.js 설치가 존재하는 경우
시스템에 여러 Node.js 설치 경로가 존재할 수 있습니다. 다음 명령으로 실제로 사용 중인 것이 어떤 것인지 확인하세요:
# Linux / macOS
which node
# Windows
where node
출력된 경로가 예상하는 nvm 관리 경로가 아닌 경우, PATH 환경 변수를 확인하여 nvm 경로가 시스템 기본 Node.js 경로보다 앞에 위치하도록 합니다.
Docker 환경에서의 버전 문제
Docker에서 OpenClaw을 배포하는 경우 Dockerfile의 기본 이미지가 Node.js 22를 사용하는지 확인하세요:
FROM node:22-alpine
node:lts 태그는 가리키는 버전이 시간이 지나면 변할 수 있으므로 사용하지 마세요. 메이저 버전 번호를 명확히 지정하면 빌드 불일치를 방지할 수 있습니다.
CI/CD 파이프라인에서의 버전 설정
GitHub Actions에서 setup-node 단계에 올바른 버전이 지정되어 있는지 확인하세요:
- uses: actions/setup-node@v4
with:
node-version: '22'
설치 성공 확인
Node.js 업그레이드 후 다음 명령을 실행하여 OpenClaw이 정상적으로 작동하는지 확인합니다:
npm install -g openclaw
openclaw --version
openclaw doctor
openclaw doctor 명령은 Node.js 버전, 필수 시스템 의존성, 설정 파일 ~/.openclaw/openclaw.json 존재 여부 등 실행 환경을 자동으로 검사합니다. 모든 검사를 통과하면 녹색 확인 메시지가 표시됩니다.
업그레이드 후에도 여전히 문제가 발생하면 npm 캐시를 정리한 후 다시 설치해 보세요:
npm cache clean --force
npm install -g openclaw