Node.js 환경 설정하기

새로운 도구를 설치할 때 가장 먼저 마주하는 난관은 역시 환경 설정이죠. 가이드대로 명령어를 입력했는데 “command not found” 메시지가 뜨거나, 설치된 줄 알았던 프로그램의 버전이 낮아 오류가 나면 정말 당혹스러워요. 특히 여러 프로젝트를 관리하다 보면 Node.js 버전이 꼬여서 개발을 시작하기도 전에 힘이 빠지곤 합니다.

OpenClaw를 원활하게 사용하기 위해 Node.js를 올바르게 설정하는 방법을 정리해 드릴게요.

필요한 것

Node 22 이상: OpenClaw는 Node 22 버전 이상의 환경이 꼭 필요해요.

설치 스크립트를 사용하면 Node.js를 자동으로 감지하고 설치해 주지만, 직접 설치하거나 PATH 설정을 확인하고 싶다면 아래 내용을 따라와 주세요.

빠른 시작

먼저 터미널에서 현재 설치된 버전을 확인해 보세요.

node -v

만약 v22.x.x 이상의 숫자가 출력된다면 준비 완료예요. Node.js가 설치되어 있지 않거나 버전이 낮다면, 운영체제에 맞는 설치 방법을 선택해 보세요.

macOS:

Homebrew (추천):

brew install node

또는 nodejs.org에서 macOS 설치 파일을 직접 다운로드할 수 있어요.

Linux:

Ubuntu / Debian:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Fedora / RHEL:

sudo dnf install nodejs

버전 관리 도구를 사용하는 방법도 있어요.

Windows:

winget (추천):

winget install OpenJS.NodeJS.LTS

Chocolatey:

choco install nodejs-lts

또는 nodejs.org에서 Windows 설치 파일을 다운로드하세요.

버전 관리 도구 사용하기 (fnm, nvm, mise, asdf)

버전 관리 도구를 쓰면 여러 Node.js 버전을 쉽게 바꿀 수 있어 편리해요.

fnm: 빠르고 다양한 플랫폼을 지원해요.
nvm: macOS와 Linux에서 가장 많이 쓰여요.
mise: Node.js 외에도 Python, Ruby 등을 함께 관리할 수 있어요.
asdf: 여러 언어의 버전을 관리하는 전통적인 도구예요.

fnm을 사용한 예시예요:

fnm install 22
fnm use 22

문제 해결

`openclaw: command not found`

npm의 글로벌 bin 디렉토리가 시스템 PATH에 등록되지 않았을 때 발생하는 문제예요.

1. 글로벌 npm prefix 찾기

    npm prefix -g

2. PATH 등록 여부 확인

    echo "$PATH"

출력 내용 중에 <npm-prefix>/bin (macOS/Linux) 또는 <npm-prefix> (Windows) 경로가 포함되어 있는지 찾아보세요.

3. 쉘 설정 파일에 경로 추가

macOS / Linux:

~/.zshrc 또는 ~/.bashrc 파일에 아래 내용을 추가하세요.

export PATH="$(npm prefix -g)/bin:$PATH"

그 다음 새 터미널을 열거나, zsh는 rehash, bash는 hash -r 명령어를 실행하세요.

Windows:

npm prefix -g 결과로 나온 경로를 설정 → 시스템 → 환경 변수 메뉴를 통해 시스템 PATH에 직접 추가해 주세요.

Linux에서 `npm install -g` 시 권한 에러가 나는 경우

EACCES 에러가 발생한다면 npm의 글로벌 prefix를 사용자 권한으로 수정할 수 있는 디렉토리로 변경해야 해요.

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"

이 설정을 유지하려면 export PATH=... 줄을 ~/.bashrc 또는 ~/.zshrc 파일에 추가해 주세요.

설정 과정에서 도움이 더 필요하다면 AI Setup Assistant에게 물어보세요.

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.