문제 설명
npm install -g openclaw로 설치를 성공적으로 완료한 후, 터미널에서 openclaw 명령을 실행하면 시스템에서 해당 명령을 찾을 수 없다고 표시됩니다:
$ openclaw --version
bash: openclaw: command not found
또는 Windows에서:
'openclaw' 은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다.
또는 PowerShell에서:
openclaw: The term 'openclaw' is not recognized as the name of a cmdlet, function, script file, or operable program.
npm 전역 설치 패키지는 특정 전역 디렉토리에 배치되며 해당 디렉토리에 실행 파일의 심볼릭 링크가 생성됩니다. 이 디렉토리가 시스템의 PATH 환경 변수에 포함되어 있지 않으면 터미널에서 openclaw 명령을 찾을 수 없습니다.
진단 단계
1단계: npm 전역 설치 경로 확인
다음 명령을 실행하여 npm 전역 패키지의 설치 접두사를 확인합니다:
npm prefix -g
다음과 유사한 경로가 출력됩니다:
- Linux / macOS:
/usr/local또는/home/사용자명/.nvm/versions/node/v22.x.x - Windows:
C:\Users\사용자명\AppData\Roaming\npm
전역 실행 파일은 해당 경로의 bin(Linux/macOS) 또는 루트 디렉토리(Windows)에 있습니다.
2단계: openclaw 바이너리 파일 존재 확인
# Linux / macOS
ls -la $(npm prefix -g)/bin/openclaw
# Windows (Git Bash)
ls -la "$(npm prefix -g)/openclaw.cmd"
파일이 존재하면 설치 자체에는 문제가 없으며 PATH 설정만 올바르지 않은 것입니다. 파일이 없다면 설치 과정에서 오류가 발생했을 수 있으므로 재설치가 필요합니다.
3단계: PATH 환경 변수 확인
echo $PATH
출력에서 npm 전역 경로를 검색합니다. 찾을 수 없다면 수동으로 추가해야 합니다.
npm이 제공하는 경로 확인 도구를 직접 사용할 수도 있습니다:
npm bin -g
이 명령은 전역 실행 파일이 위치한 디렉토리 경로를 직접 출력합니다.
해결 방법
Linux / macOS 사용자
npm 전역 bin 디렉토리를 PATH에 추가합니다. 사용하는 Shell에 따라 해당 설정 파일을 편집합니다:
# Bash 사용자
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Zsh 사용자
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
nvm으로 Node.js를 관리하는 경우, 일반적으로 nvm의 초기화 스크립트가 자동으로 PATH를 설정합니다. Shell 설정 파일에 nvm 초기화 코드가 포함되어 있는지 확인하세요:
grep -n "nvm" ~/.bashrc
다음과 유사한 줄이 보여야 합니다:
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
이 줄이 없거나 주석 처리되어 있다면 주석을 해제하거나 다시 추가하세요.
Windows 사용자
Windows의 npm 전역 경로는 일반적으로 %APPDATA%\npm입니다. 시스템 환경 변수 PATH에 추가해야 합니다:
Win + R을 누르고sysdm.cpl을 입력한 후 Enter- "고급" 탭으로 전환하고 "환경 변수"를 클릭
- "사용자 변수"에서
Path를 찾아 더블 클릭하여 편집 - 새 항목 추가:
%APPDATA%\npm - 확인을 클릭하여 저장한 후 터미널을 다시 엽니다
또는 PowerShell로 빠르게 추가할 수 있습니다:
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:APPDATA\npm", "User")
추가 후 터미널을 다시 시작해야 변경 사항이 적용됩니다.
npx를 임시 대안으로 사용
PATH를 수정하기 어려운 상황에서 급하게 OpenClaw을 사용해야 한다면 npx를 통해 직접 실행할 수 있습니다:
npx openclaw --version
npx openclaw start
npx는 전역 설치된 패키지를 자동으로 찾거나 임시로 다운로드하여 실행합니다. 하지만 이것은 장기적인 해결책이 아니므로 가능한 빨리 PATH 설정을 수정하는 것이 좋습니다.
pnpm 또는 yarn 전역 설치 사용
pnpm 또는 yarn을 패키지 관리자로 사용하는 경우 전역 설치 경로가 다를 수 있습니다:
# pnpm
pnpm add -g openclaw
pnpm bin -g # 전역 bin 경로 확인
# yarn
yarn global add openclaw
yarn global bin # 전역 bin 경로 확인
마찬가지로 해당 bin 경로가 PATH에 포함되어 있는지 확인해야 합니다.
수정 확인
PATH를 수정한 후, 새 터미널 창을 엽니다(이것이 중요합니다. 이전 창은 업데이트된 환경 변수를 로드하지 않을 수 있습니다). 다음을 실행합니다:
openclaw --version
which openclaw # Linux / macOS
where openclaw # Windows
명령이 버전 번호와 실행 파일 경로를 출력하면 문제가 해결된 것입니다. 이어서 설정을 초기화할 수 있습니다:
openclaw init
이 명령은 ~/.openclaw/ 디렉토리에 기본 openclaw.json 설정 파일을 생성합니다.