Claude Code 설치 후 명령어가 인식 안 될 때 PATH 오류 해결법

Claude Code를 분명히 설치했는데 막상 터미널을 열고 claude를 입력하면 "'claude'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램 또는 배치 파일이 아닙니다"라는 문구가 뜨는 경우가 있습니다. 처음 접하면 굉장히 당혹스럽습니다. 설치가 잘못된 건지, 다시 설치해야 하는 건지 판단이 서지 않습니다. 이 문제는 대부분 PATH 오류(운영체제가 프로그램을 찾는 경로 설정 문제)에서 비롯됩니다. 원인을 세 가지로 나눌 수 있고, 각각 해결 방법이 다릅니다.

 

 

'claude' 명령어 오류가 생기는 이유 — PATH란 무엇인가

터미널에서 명령어를 입력하면 Windows는 PATH(패스)라는 목록을 보고 해당 프로그램을 찾습니다. PATH는 쉽게 말해 "이 폴더들을 뒤져서 실행 파일을 찾아라"라는 주소 목록입니다. 예를 들어 notepad라고 치면 Windows가 PATH에 등록된 폴더들을 순서대로 확인하고 notepad.exe를 찾아서 실행합니다.

 

Claude Code는 Node.js 패키지 매니저인 npm(Node Package Manager)을 통해 전역 설치됩니다. npm으로 설치된 프로그램들은 특정 폴더에 모입니다. 그런데 이 폴더가 PATH에 등록되어 있지 않으면 Windows는 claude를 실행하려고 해도 어디에 있는지를 모릅니다. 결국 "모르겠어, 없는 거 아니야?"라는 식으로 오류 메시지를 출력하는 겁니다.

 

이 상황은 Claude Code가 설치 자체는 정상적으로 된 경우가 많습니다. 단지 운영체제가 그 위치를 모르는 것뿐입니다. 다시 설치한다고 해결되지 않습니다. PATH를 고쳐야 합니다.

 

아래 화면처럼 터미널에서 오류 메시지가 출력된다면 이 글의 해결 방법을 순서대로 따라가시면 됩니다.

 

 

 

 

npm 전역 설치 경로를 PATH에 등록하는 방법

가장 흔한 원인입니다. npm은 전역으로 설치한 패키지를 특정 폴더에 저장하는데, Windows에서는 이 폴더가 자동으로 PATH에 추가되지 않는 경우가 있습니다. 우선 현재 npm이 전역 패키지를 어느 폴더에 저장하고 있는지 확인해야 합니다.

PowerShell 또는 명령 프롬프트를 열고 다음 명령어를 실행합니다.

npm config get prefix

 

출력 결과는 C:\Users\사용자명\AppData\Roaming\npm 형태의 경로입니다. 이 경로를 복사해 둡니다.

이제 이 경로를 PATH에 등록합니다. 순서는 다음과 같습니다.

 

1. 키보드에서 Win + S를 누르고 "환경 변수"를 검색합니다.

2. "시스템 환경 변수 편집"을 클릭합니다.

3. 하단의 "환경 변수" 버튼을 누릅니다.

4. "사용자 변수" 목록에서 Path를 선택하고 "편집"을 누릅니다.

5. "새로 만들기"를 클릭하고 아까 복사한 npm 경로를 붙여넣습니다.

6. "확인"을 눌러 창을 닫습니다.

 

이 과정이 익숙하지 않다면 시스템 속성 창이 낯설게 느껴질 수 있습니다. 하지만 순서를 그대로 따라가면 어렵지 않습니다. 경로 하나를 목록에 추가하는 단순한 작업입니다.

 

제가 보기에는 이 원인이 전체 오류의 절반 이상을 차지합니다. npm을 처음 설치할 때 PATH 자동 등록 여부는 설치 환경마다 달라서, 특히 Node.js를 공식 설치 파일이 아닌 다른 방법으로 설치한 경우 이 문제가 자주 발생합니다.

아래 화면처럼 시스템 환경 변수 편집 창에서 Path 항목에 npm 경로가 추가된 상태를 확인할 수 있습니다.

 

 

 

 

PowerShell 실행 정책이 Claude Code를 차단하는 경우

PATH를 등록했는데도 claude 명령어 실행 시 다른 오류가 나타나는 경우가 있습니다. "이 시스템에서 스크립트를 실행할 수 없으므로..."라는 문구가 보인다면 PowerShell 실행 정책(Execution Policy)이 원인입니다.

 

실행 정책이란 PowerShell이 스크립트 파일(.ps1)을 실행할 수 있는지를 제어하는 보안 설정입니다. Windows는 기본적으로 이 정책을 Restricted(제한됨)으로 설정해 외부에서 내려받은 스크립트가 실행되지 않도록 막습니다. npm으로 설치된 Claude Code는 .ps1 스크립트를 포함하고 있어서, 이 정책에 걸리면 실행이 차단됩니다.

 

해결 방법은 실행 정책을 현재 사용자에 한해 변경하는 것입니다. PowerShell을 열고 아래 명령어를 입력합니다.

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

명령어의 의미는 다음과 같습니다. RemoteSigned는 인터넷에서 내려받은 스크립트는 서명된 것만 허용하고, 로컬에서 만든 스크립트는 자유롭게 실행한다는 정책입니다. Scope CurrentUser는 이 변경을 현재 사용자 계정에만 적용한다는 뜻입니다. 컴퓨터 전체 설정을 바꾸는 게 아니라 내 계정만 바꾸는 것이므로 부담이 적습니다.

 

실행 후 확인 메시지가 나오면 Y를 입력하고 엔터를 누릅니다.

아래 화면처럼 명령어가 정상 실행되면 실행 정책 변경이 완료된 것입니다.

 

 

실행 정책 변경은 한 번만 하면 됩니다. 이후에는 별도 작업 없이 PowerShell에서 npm 스크립트가 정상 실행됩니다. PATH를 올바르게 등록했는데도 해결이 안 된다며 포기하는 경우를 자주 봤습니다. PATH 등록 후에도 오류가 계속된다면 실행 정책을 먼저 의심해 봐야 합니다.

 

 

터미널 재시작 후 claude 명령어 작동 확인

PATH를 등록하고 실행 정책도 바꿨는데 여전히 claude가 인식되지 않는다면, 열려 있는 터미널 창을 닫고 새로 열지 않은 경우일 가능성이 높습니다.

PATH는 터미널이 처음 실행될 때 읽어오는 정보입니다. 이미 열려 있는 터미널에서는 새로 등록한 PATH가 반영되지 않습니다. 즉 환경 변수를 수정하기 전에 열었던 PowerShell이나 명령 프롬프트 창은 변경 이전의 PATH를 그대로 사용하고 있습니다.

해결 방법은 간단합니다.

 

1. 현재 열려 있는 모든 터미널 창을 닫습니다.

2. 새로운 PowerShell 또는 명령 프롬프트 창을 엽니다.

3. claude --version을 입력하여 버전 정보가 출력되는지 확인합니다.

버전 정보가 출력된다면 PATH가 정상 반영된 것입니다. 이 단계에서 처음으로 claude 명령어가 작동하는 경험을 하게 됩니다.

추가로, Windows 터미널(Windows Terminal) 앱을 사용하고 있다면 탭을 닫는 것만으로는 부족한 경우가 있습니다. 앱 자체를 완전히 종료한 뒤 다시 실행해야 새 환경 변수가 적용됩니다. VS Code의 내장 터미널을 사용하고 있다면 VS Code 전체를 재시작해야 합니다.

 

세 가지 원인을 한 번에 점검할 수 있는 순서를 정리합니다. 이 순서대로 진행하면 대부분의 경우 해결됩니다.

 

1단계 — npm 전역 경로 확인 및 PATH 등록

npm config get prefix

출력된 경로를 복사하고, 시스템 환경 변수 → Path 편집에서 해당 경로를 추가합니다.

 

2단계 — PowerShell 실행 정책 확인

Get-ExecutionPolicy -Scope CurrentUser

출력이 Restricted라면 앞서 안내한 Set-ExecutionPolicy 명령어로 RemoteSigned로 변경합니다.

 

3단계 — 터미널 재시작 후 작동 확인

모든 터미널 창을 닫고 새 창을 열어 다음 명령어를 실행합니다.

claude --version

버전 정보가 나오면 설치와 PATH 설정이 모두 정상입니다. 이 세 단계를 순서대로 밟아도 해결되지 않는다면 Node.js 설치 자체가 불완전한 경우입니다. Node.js 공식 웹사이트(nodejs.org)에서 LTS 버전을 내려받아 재설치한 뒤 위 단계를 다시 진행하면 됩니다.