Claude Code 설치·삭제·인증 오류 해결 — 초보자도 5분 안에 끝내는 실용 가이드
Claude Code 설치 오류 해결이 막막하다면 이 글 하나로 끝납니다. command not found·인증 실패·설치 안 됨까지 원인별 해결법과 깔끔한 삭제 방법을 초보자도 따라할 수 있게 정리했습니다.
결론 먼저 — 오류 유형별 해결법 한눈에
Claude Code를 설치하다 막히는 지점은 대부분 세 가지입니다.
| 오류 | 원인 | 해결 시간 |
|---|---|---|
claude: command not found | npm 경로가 PATH에 없음 | 약 2분 |
Authentication failed | 인증 토큰 만료·충돌 | 약 1~3분 |
| 설치 자체가 안 됨 | Node.js 버전 미달 | 약 5분 |
어떤 오류가 떴는지 확인하고 해당 섹션으로 바로 이동하세요.
Claude Code가 뭔지 모르는 분께 — 30초 요약
Claude Code는 터미널(명령 프롬프트)에서 실행하는 AI 코딩 도구입니다. ChatGPT처럼 대화창에 질문하는 방식이 아니라, 내 컴퓨터 파일을 직접 읽고 수정할 수 있다는 점이 다릅니다.
쉽게 말하면 “파일을 직접 건드릴 수 있는 AI 조수”입니다. 설치는 딱 한 줄이지만, 환경에 따라 오류가 생기는 경우가 있어 처음 접하는 분이 당황하기 쉽습니다.
설치 전 확인 — Node.js 버전부터 체크하세요
Claude Code는 Node.js 18 이상이 필요합니다. 먼저 터미널에서 버전을 확인하세요.
node -vv18.0.0 이상이 출력되면 바로 설치로 넘어가도 됩니다. 버전이 낮거나 command not found가 뜬다면 Node.js 공식 사이트에서 LTS 버전을 먼저 설치하세요.
설치 명령어 (단 한 줄)
npm install -g @anthropic-ai/claude-code설치가 완료되면 claude 명령어로 실행할 수 있습니다. 여기서 아무 반응이 없거나 오류가 뜬다면 아래 해결법을 따라가세요.
오류 1: claude: command not found
왜 이 오류가 뜨나요?
설치는 됐지만 내 컴퓨터가 claude라는 명령어가 어디 있는지 모르는 상태입니다. npm이 패키지를 설치하는 폴더가 터미널 실행 경로(PATH)에 등록되지 않았기 때문입니다.
집 주소를 모르면 택배가 안 오는 것과 같습니다. PATH에 주소를 등록해줘야 합니다.
해결 방법 (macOS · Linux)
# 1단계: npm이 패키지를 설치한 위치 확인
npm config get prefix
# 결과 예시: /usr/local 또는 /Users/내이름/.npm-global
# 2단계: .zshrc 또는 .bashrc 파일에 아래 줄 추가
# (터미널이 zsh이면 .zshrc, bash이면 .bashrc)
export PATH="$PATH:$(npm config get prefix)/bin"
# 3단계: 변경 사항 즉시 적용
source ~/.zshrc이후 다시 claude 를 입력하면 정상 실행됩니다.
Windows 사용자라면
Windows에서는 WSL(Windows Subsystem for Linux) 환경에서 사용하는 것을 권장합니다. 일반 명령 프롬프트나 PowerShell보다 안정적으로 동작합니다.
오류 2: Authentication failed — 인증 오류 해결
Soft Reset — 먼저 이것부터 시도하세요
claude auth logout
claude auth login로그아웃 후 재로그인하는 방법입니다. 인증 토큰이 만료됐거나 일시적으로 꼬인 경우 대부분 해결됩니다. 1분도 안 걸립니다.
Hard Reset — Soft Reset이 안 됐을 때
# macOS · Linux: Claude 관련 설정 파일 전체 삭제
rm -rf ~/.claude
# 삭제 후 재로그인
claude auth login~/.claude 폴더에는 인증 토큰과 설정 파일이 저장돼 있습니다. 이 폴더를 통째로 삭제하면 깨끗한 상태에서 다시 시작할 수 있습니다.
걱정하지 마세요 — 이 폴더를 삭제해도 Anthropic 계정, 구독 정보, 크레딧은 전혀 영향받지 않습니다. 로컬 캐시만 지워지는 것입니다.
Claude Code 삭제 방법
더 이상 사용하지 않거나, 완전히 초기화하고 싶을 때는 두 단계로 삭제합니다.
# 1단계: 패키지 제거
npm uninstall -g @anthropic-ai/claude-code
# 2단계: 설정 파일 완전 삭제 (선택 사항)
rm -rf ~/.claude2단계는 선택입니다. 나중에 다시 설치할 예정이라면 건너뛰어도 됩니다.
설치 후 바로 쓸 수 있는 핵심 팁 3가지
Claude Code 설치 오류 해결을 마쳤다면, 처음 사용할 때 알아두면 도움이 되는 팁입니다.
1. 반드시 프로젝트 폴더 안에서 실행하세요cd 내프로젝트폴더 로 이동한 뒤 claude 를 실행해야 합니다. 폴더 맥락 없이 실행하면 AI가 무엇을 도와야 할지 파악하기 어렵습니다.
2. ESC 두 번 = 즉시 중단
AI가 원하지 않는 방향으로 작업을 진행할 때 ESC를 두 번 누르면 바로 멈춥니다.
3. 컨텍스트가 60~70% 차면 새 대화를 시작하세요
대화가 길어질수록 응답 품질이 떨어질 수 있습니다. /context 명령어로 현재 사용량을 확인하고, 여유 있게 새 대화를 여는 습관을 들이면 훨씬 안정적으로 사용할 수 있습니다.
마무리
Claude Code 설치 오류 해결의 핵심은 단순합니다. command not found는 PATH 등록, 인증 오류는 Soft → Hard Reset 순서로 시도하면 대부분 해결됩니다. 설치 자체가 안 된다면 Node.js 버전부터 확인하세요.
설치가 끝났다면 다음 단계로 토큰 비용을 아끼는 방법을 알아두는 것을 추천합니다. Claude Code는 사용량에 따라 요금이 발생하는 구조라, 처음부터 절약 습관을 들이면 부담 없이 오래 쓸 수 있습니다.
