Claude Code 설치 오류 원인과 단계별 해결법

Claude Code 설치 전 필수 환경을 확인하는 방법

Claude Code를 설치하려면 먼저 몇 가지 환경이 갖춰져 있어야 합니다. 가장 중요한 것은 Node.js 버전입니다. Claude Code는 Node.js 18 이상을 요구하는데, 오래된 버전이 설치되어 있으면 설치 자체가 실패하거나 실행 중 예상치 못한 오류가 발생합니다. Node.js는 자바스크립트를 컴퓨터에서 직접 실행할 수 있게 해주는 도구인데, Claude Code가 이 위에서 동작하기 때문에 반드시 필요합니다.

터미널을 열고 아래 명령어를 입력하면 현재 설치된 버전을 확인할 수 있습니다.

node -v
npm -v

node -v 결과가 v16이나 v14처럼 낮은 버전이 나온다면, Node.js 공식 사이트에서 최신 LTS(장기 지원) 버전을 다운로드해서 업데이트해야 합니다. LTS 버전은 안정성이 검증된 버전이므로 최신 버전보다 LTS를 선택하는 것이 좋습니다. npm도 함께 확인해야 합니다. npm -v를 입력해서 npm 버전이 9 이상인지 체크하는 것을 권장합니다. npm은 Node.js의 패키지 관리자로, Claude Code를 설치할 때 사용하는 도구입니다.

 

 

 

운영체제별로도 주의할 점이 있습니다. Windows에서는 PowerShell이나 명령 프롬프트 대신 Git Bash나 WSL(Windows Subsystem for Linux)을 사용하는 것을 권장합니다. PowerShell에서는 일부 명령어가 다르게 동작하거나, 경로 구분자 문제로 예상치 못한 오류가 발생할 수 있기 때문입니다. macOS에서는 Xcode Command Line Tools가 설치되어 있어야 일부 네이티브 모듈이 정상적으로 빌드됩니다. 아래 명령어로 간단히 설치할 수 있습니다.

xcode-select --install

설치 환경을 먼저 점검하는 것이 번거롭게 느껴질 수 있지만, 이 단계를 건너뛰면 이후에 훨씬 더 복잡한 오류를 만나게 됩니다. 5분 투자로 수십 분의 삽질을 아낄 수 있으니, 반드시 먼저 확인하는 것이 좋습니다.

 

npm 글로벌 패키지 설치 오류를 해결하는 방법

환경이 준비됐는데도 npm install -g @anthropic-ai/claude-code 명령어에서 오류가 발생하는 경우가 있습니다. 가장 흔한 원인은 글로벌 설치 권한 문제입니다. 특히 macOS나 Linux에서 sudo 없이 글로벌 패키지를 설치하면 EACCES 권한 오류가 나타납니다. 이 오류는 npm이 패키지를 저장하려는 폴더에 쓰기 권한이 없다는 뜻입니다.

이 경우 두 가지 방법으로 해결할 수 있습니다. 첫 번째는 npm의 글로벌 디렉토리를 사용자 폴더로 변경하는 것입니다.

# 글로벌 디렉토리를 사용자 폴더로 변경
npm config set prefix ~/.npm-global

# PATH에 새 경로 추가 (bash 사용자)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# zsh 사용자라면
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

두 번째는 nvm(Node Version Manager)을 사용하는 방법입니다. nvm으로 Node.js를 설치하면 글로벌 패키지 설치 시 권한 문제가 발생하지 않습니다. nvm은 여러 Node.js 버전을 동시에 관리할 수 있는 도구여서, 나중에 버전을 전환해야 할 때도 유용합니다.

 

 

네트워크 관련 오류도 자주 발생합니다. 회사나 학교 네트워크에서 프록시(proxy, 인터넷 연결을 중계하는 서버)를 사용하는 경우 npm이 패키지를 다운로드하지 못할 수 있습니다. 이런 환경에서는 npm에 프록시 정보를 알려줘야 합니다.

# 프록시 설정
npm config set proxy http://프록시주소:포트
npm config set https-proxy http://프록시주소:포트

# 프록시 설정 확인
npm config get proxy

프록시 설정이 필요 없는 환경인데도 다운로드가 안 되는 경우에는, npm 캐시가 손상되었을 가능성이 있습니다. npm cache clean --force로 캐시를 정리한 뒤 다시 시도해 보는 것도 좋은 방법입니다. 그래도 안 된다면 npm 레지스트리를 미러 서버로 변경해볼 수 있습니다. npm config set registry https://registry.npmmirror.com으로 변경하면 국내에서 더 빠르고 안정적인 다운로드가 가능합니다. 다만 설치가 완료된 후에는 원래 레지스트리(https://registry.npmjs.org)로 되돌려 놓는 것이 좋습니다.

 

 

Claude Code 실행 시 command not found 오류를 해결하는 방법

설치는 성공했는데 claude 명령어를 입력하면 "command not found"가 나오는 경우가 있습니다. 이것은 대부분 PATH 환경 변수 설정 문제입니다. PATH란 운영체제가 명령어를 찾을 때 탐색하는 폴더 목록인데, npm 글로벌 패키지가 설치된 경로가 이 목록에 포함되어 있지 않으면 터미널이 claude 명령어를 찾지 못합니다.

먼저 npm 글로벌 패키지가 어디에 설치되어 있는지 확인해야 합니다.

# 글로벌 패키지 경로 확인
npm config get prefix

# Windows에서는 보통 이 경로
# C:\Users\사용자이름\AppData\Roaming\npm

# macOS/Linux에서는 보통 이 경로
# /usr/local 또는 ~/.npm-global

출력된 경로 뒤에 /bin(Windows는 그대로)을 붙인 경로가 PATH에 있는지 살펴보면 됩니다. Windows에서는 시스템 환경 변수 설정에서 Path 항목을 편집합니다. 설정 → 시스템 → 정보 → 고급 시스템 설정 → 환경 변수 순서로 접근할 수 있습니다. macOS나 Linux에서는 셸 설정 파일에 경로를 추가합니다.

# PATH에 npm 글로벌 경로 추가
export PATH="$(npm config get prefix)/bin:$PATH"

변경 후에는 터미널을 새로 열어야 적용됩니다. 이 과정이 번거롭다면, 터미널에서 npx @anthropic-ai/claude-code를 사용하는 방법도 있습니다. npx는 글로벌 설치 없이 패키지를 바로 실행하는 도구인데, PATH 설정을 건드리지 않아도 됩니다. 다만 매번 실행할 때마다 약간의 로딩 시간이 추가됩니다.

 

 

 

또 다른 흔한 문제는 API 키 설정입니다. Claude Code를 처음 실행하면 Anthropic API 키를 입력하라는 안내가 나옵니다. 키를 아직 발급받지 않았다면 Anthropic 콘솔에서 먼저 API 키를 생성해야 합니다. API 키는 sk-ant-로 시작하는 긴 문자열인데, 복사·붙여넣기 과정에서 공백이나 줄바꿈 문자가 포함되는 경우가 종종 있습니다. 키를 붙여넣을 때 앞뒤 공백이 없는지 꼭 확인해야 합니다. 환경 변수로 미리 설정해두면 매번 입력하지 않아도 됩니다.

# 환경 변수로 API 키 설정
export ANTHROPIC_API_KEY="sk-ant-여기에키입력"

제가 처음 설치할 때 command not found 오류로 30분 넘게 헤맸는데, 결국 PATH 설정 한 줄 추가로 해결됐습니다. 대부분의 설치 문제는 환경 설정 누락이 원인이므로, 오류 메시지를 차분히 읽고 하나씩 점검하면 반드시 해결할 수 있습니다.

 

 

Claude Code 설치 완료 후 정상 동작을 최종 점검하는 방법

모든 과정을 마쳤다면 Claude Code가 제대로 작동하는지 최종 점검이 필요합니다. 점검은 3단계로 진행합니다.

1단계는 버전 확인입니다. 터미널에서 claude --version을 입력하면 설치된 버전 정보가 출력됩니다. 버전 번호가 정상적으로 나온다면 Claude Code 바이너리 설치 자체는 성공한 것입니다. 버전 번호 대신 오류가 나온다면 앞의 PATH 설정 단계를 다시 확인해야 합니다.

2단계는 대화 모드 진입입니다. claude 명령어를 입력해서 대화 모드로 들어가 봅니다. 정상적으로 프롬프트(prompt, 입력을 기다리는 표시)가 나타나고 질문에 응답한다면 모든 설정이 완료된 것입니다. "안녕하세요"처럼 간단한 메시지를 보내서 응답이 돌아오는지 테스트해 보는 것을 권장합니다.

# 1단계: 버전 확인
claude --version

# 2단계: 대화 모드 진입
claude

# 3단계: 간단한 테스트 명령
claude -p "Hello, Claude!"

3단계는 프로젝트 폴더에서의 동작 확인입니다. Claude Code의 진가는 프로젝트 폴더 안에서 발휘됩니다. 아무 프로젝트 폴더로 이동한 뒤 claude를 실행해 보면, Claude가 해당 폴더의 파일 구조를 인식하고 코드에 대해 질문에 답할 수 있는 상태가 됩니다. 프로젝트 루트에 CLAUDE.md 파일이 있다면 자동으로 참고하여 더 정확한 답변을 제공합니다.

 

 

 

만약 여기까지 왔는데도 문제가 해결되지 않았다면 Claude Code GitHub 저장소의 Issues 탭을 확인해 보는 것을 추천합니다. 다른 사용자들이 비슷한 문제를 겪고 해결한 사례를 찾을 수 있습니다. 이슈를 검색할 때는 오류 메시지의 핵심 키워드를 그대로 입력하면 관련 이슈를 빠르게 찾을 수 있습니다.

 

설치 과정에서 가장 많이 하는 실수를 정리하면 이렇습니다.

• 첫째, Node.js 버전을 확인하지 않고 바로 설치를 시도하는 것입니다.
• 둘째, 권한 오류를 sudo로 무작정 해결하려는 것입니다. sudo로 npm을 실행하면 당장은 설치가 되지만, 이후에 파일 소유권 문제가 꼬여서 더 복잡한 상황이 됩니다.
• 셋째, PATH 설정을 변경한 후 터미널을 새로 열지 않는 것입니다. 이 세 가지만 주의하면 대부분의 설치 오류는 피할 수 있습니다. 설치 과정이 다소 복잡해 보이지만, 한 번 제대로 설정해두면 이후에는 업데이트도 npm update -g @anthropic-ai/claude-code 한 줄로 간단히 처리할 수 있습니다.