클로드 코드 설치 오류, command not found와 중복 설치 해결

command not found: claude가 나오면 새 터미널에서 한 번 더 확인하세요. 같은 오류가 나오면 설치 파일이 있는지부터 본 뒤 PATH 문제를 좁힙니다. 설치가 실패한 상태에서 PATH만 바꿔도 프로그램이 생기지는 않습니다.

이 글은 클로드 코드 설치 오류를 설치 경로, 중복 설치, 인증 방식 순서로 확인합니다. 명령 예시는 macOS의 zsh 기준입니다. Windows의 경로·PowerShell 명령은 다르므로 공식 Windows 설치 경로 안내를 사용하세요.

보이는 증상	먼저 확인할 부분
command not found: claude	새 터미널 → 설치 파일·PATH
설치했는데 다른 버전이 실행됨	현재 실행 경로와 중복 설치
구독 중인데 API 사용으로 표시됨	현재 인증 방식과 API 키 설정
어디에 물어봐야 할지 모르겠음	오류 복사와 도움 요청 예시

command not found가 뜰 때, 새 터미널부터 확인하기

macOS에서 터미널을 여는 방법은 Command + Space → “터미널” 검색 → Enter입니다. 아래 셸 명령은 Claude Code 대화창이 아닌 터미널에 입력합니다. /status처럼 슬래시로 시작하는 명령은 Claude Code 안에서 입력한다는 점을 구분하세요.

방금 설치를 끝냈다면 새 터미널을 열고 claude --version을 다시 실행하세요. 설치 과정에서 PATH가 추가됐더라도, 이미 열려 있던 셸은 그 변경을 아직 읽지 않았을 수 있습니다.

새 터미널에서도 같은 오류가 나올 때만 아래의 설치 파일과 PATH를 확인합니다. 재설치나 설정 파일 수정을 먼저 하지 않으면 어디서 막혔는지 쉽게 구분할 수 있습니다.

공식 기본 설치 프로그램으로 설치했다면 다음처럼 파일을 직접 실행해 보세요.

~/.local/bin/claude --version

• 버전 숫자가 나옵니다: 설치 파일은 실행됩니다. 아래 PATH 확인으로 넘어갑니다.
• No such file or directory가 나옵니다: 기본 설치 위치에 파일이 없습니다. 설치 실패 또는 다른 설치 방식인지 확인하고 맥 설치 안내의 설치 단계로 돌아갑니다.
• Permission denied 등 다른 오류가 나옵니다: PATH 문제로 단정하지 말고 그 오류 문구를 따로 확인합니다.

PATH는 명령어를 찾을 때 살펴보는 폴더 목록입니다. 설치 파일이 실행된다면 현재 터미널에만 경로를 추가해 확인합니다. 기존 설정 파일은 이 단계에서 바꾸지 않습니다.

export PATH="$HOME/.local/bin:$PATH"
claude --version

확인 환경에서는 PATH에서 설치 폴더를 제외한 셸에 command not found: claude가 발생했고, 설치 파일을 직접 실행하면 버전이 나왔습니다. 2026년 9월 14일 재확인 값은 2.1.268 (Claude Code)였습니다. 독자의 버전 숫자는 달라도 됩니다. 같은 터미널에서 claude --version이 성공하는지로 판단하세요.

새 터미널을 열 때마다 문제가 돌아오면 시작 설정에 경로가 저장되지 않은 것입니다. zsh는 ~/.zshrc, bash는 사용하는 시작 파일이 다를 수 있습니다. 파일을 백업한 뒤 중복되지 않게 경로를 추가하는 공식 PATH 설정 절차로 이어가세요.

버전이 다르거나 중복 설치가 의심될 때

현재 실행되는 경로와 설치 상태를 확인합니다. 아래 명령은 파일을 삭제하지 않습니다.

which -a claude
claude doctor

여러 경로가 나온다는 사실만으로 충돌이 확정되지는 않습니다. 연결된 파일이 같을 수도 있으니, 실제 실행 경로·버전과 진단 결과를 함께 보세요. npm 설치 여부는 npm이 있는 환경에서만 다음 명령으로 확인합니다.

npm -g ls @anthropic-ai/claude-code

기본 설치본으로 옮기기로 했다면 그 설치본이 직접 실행되는지 먼저 확인하고 기존 설치 방식의 제거 절차를 따릅니다. 예전 ~/.claude/local 폴더를 원인 확인 없이 통째로 지우거나, ~/.claude 전체를 삭제하는 방식은 피하세요. 설정과 작업 기록까지 잃을 수 있습니다. 공식 설치 충돌 점검에서 자신의 설치 방식에 해당하는 부분만 적용하면 됩니다.

구독 중인데 API로 실행될 때

Claude Code 안에서 /status를 열어 현재 인증 방식을 확인합니다. 대화형 실행은 API 키 사용을 승인한 뒤 사용하며, claude -p 같은 비대화형 실행은 환경에 API 키가 있으면 그 키를 사용할 수 있습니다. ANTHROPIC_API_KEY 외에 다른 인증 설정도 있으므로 키 하나만 지웠다고 구독으로 바뀌었다고 단정하지 않습니다.

현재 터미널의 API 키 설정 여부는 아래처럼 확인할 수 있습니다. 실제 키 값은 출력하지 않습니다.

if [ -n "${ANTHROPIC_API_KEY:-}" ]; then
  printf '%s\n' '현재 셸에 API 키가 설정되어 있습니다'
else
  printf '%s\n' '현재 셸에는 API 키가 없습니다'
fi

개인 구독으로 실행하려고 했는데 예전 키가 남아 있었다면, 현재 셸에서 해제한 뒤 다시 실행하고 로그인·상태를 확인합니다. 회사가 관리하는 인증 설정은 담당자에게 확인하세요.

unset ANTHROPIC_API_KEY
claude

unset은 현재 셸에만 적용됩니다. 새 터미널에서 다시 나타난다면 셸 시작 파일이나 프로젝트 설정에서 주입되는지 확인해야 합니다. 이 작업이 이미 발생한 API 사용 비용을 취소하지는 않습니다.

해결되지 않으면 오류를 어떻게 전달하나요?

“안 돼요” 대신 실행한 명령과 실패한 결과를 함께 전달합니다. 오류가 시작된 줄부터 끝까지 복사하되 API 키·토큰·비밀번호·고객정보는 가립니다. 모든 터미널 기록을 통째로 붙일 필요는 없습니다. 화면 배치나 입력 문제가 있다면 해당 부분을 캡처하고 오류 텍스트도 함께 적습니다.

하려던 작업: 클로드 코드를 처음 실행하려고 했습니다.
환경: macOS / 터미널 앱 / zsh
입력한 명령: claude --version
오류 전문: zsh: command not found: claude
이미 확인한 것: ~/.local/bin/claude --version은 버전이 나옵니다.

설치 문제와 PATH 문제를 구분해서 설명해 주세요.
먼저 파일을 지우거나 설정을 덮어쓰지 않는 확인 명령 하나를 알려 주세요.
그 결과가 무엇이면 해결된 것인지도 알려 주세요.

이 예시는 기본 설치 파일이 실행되는 경우입니다. 독자의 실제 결과로 바꿔서 전달하세요. 수정 후에는 처음 실패한 명령을 다시 실행해 성공 여부를 확인합니다.

자주 묻는 질문

VS Code 확장을 설치했는데 터미널에서는 claude가 없다고 합니다.

확장이 사용하는 CLI와 터미널에서 실행할 CLI 설치는 구분됩니다. 확장을 설치했다고 기본 설치 경로에 claude 명령이 생기는 것은 아닙니다. 터미널에서도 쓰려면 CLI 설치를 확인하세요.

설치는 되는데 한글 입력만 이상하면 이 글을 따라 하나요?

설치를 지우기보다 답변 언어·한글 입력·글자 깨짐을 구분하는 안내로 넘어가세요. 설치 문제와 입력 문제는 원인이 다를 수 있습니다.

정상 실행을 확인했다면 첫 체크리스트 앱 실습으로 이어갈 수 있습니다. 전체 학습 순서는 클로드 코드 시작 가이드에 있습니다.

검증 기준

• 마지막 업데이트일: 2026-09-15
• 확인 환경: macOS zsh, Claude Code CLI 2.1.268. PATH에서 설치 폴더를 제외한 별도 셸의 오류와 설치 파일 직접 실행을 2026년 9월 14일 재확인했습니다. 사용자 설정·설치본·인증 값은 변경하지 않았으며 Windows·중복 설치·과금 장애는 이번에 재현하지 않았습니다.
• 주요 근거: 설치·로그인 오류 · 인증 방식