클로드 코드를 설치했는데 claude를 쳐도 반응이 없거나, 이상한 메시지만 뜨는 경우가 있습니다.
검색해보면 사람마다 증상이 다 달라서 뭐가 내 문제인지 헷갈립니다.
이 글은 유튜브에 올라온 설치 후기 3편에서 실제로 자주 언급되는 문제를 추리고, 제 컴퓨터에서 직접 같은 상황을 재현해서 해결까지 확인한 것만 정리했습니다. 재현이 안 되는 건 넣지 않았습니다.
설치 자체가 아직이라면 클로드 코드 맥 설치 방법부터 보고 오면 됩니다.
지금 확인할 것
command not found가 뜬다면 → PATH 문제, 원인과 고치는 명령어 한 줄- 설치를 두 번 이상 했다면 → 충돌 확인하는 법
- 구독인데 요금이 이상하게 나간다면 → 예전 API 키가 남아있는지 확인하는 법
증상별로 먼저 확인하세요
| 증상 | 원인 | 해결 |
|---|---|---|
command not found: claude |
설치 폴더가 PATH에 없음 | PATH에 ~/.local/bin 추가 |
| 버전이 이상하거나 업데이트가 안 먹음 | 설치가 여러 개 겹침 | 충돌 확인 후 하나만 남기기 |
| 구독 중인데 API 요금이 따로 청구됨 | 예전 ANTHROPIC_API_KEY가 남아있음 |
환경변수 확인 후 제거 |
1. command not found: claude — PATH 문제
설치는 끝났다고 나왔는데 claude를 치면 이렇게 뜨는 경우입니다.
실제로 PATH를 제한한 상태로 제 컴퓨터에서 재현해봤습니다.
$ claude --version
zsh:1: command not found: claude원인은 설치 프로그램이 claude를 넣어둔 ~/.local/bin 폴더가, 터미널이 프로그램을 찾는 경로(PATH) 목록에 없기 때문입니다. 설치가 잘못된 게 아니라 터미널이 어디를 봐야 할지 모르는 것입니다.
먼저 PATH에 이미 들어있는지 확인합니다.
echo $PATH | tr ':' 'n' | grep -Fx "$HOME/.local/bin"아무것도 안 뜨면 없는 겁니다. 아래 명령어로 추가합니다 (맥 기본 셸인 zsh 기준).
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc다시 확인하면 이번엔 버전이 뜹니다.
$ claude --version
2.1.233 (Claude Code)터미널을 새로 열어도 됩니다. 껐다 켜면 ~/.zshrc가 자동으로 다시 읽힙니다.
2. 설치가 여러 개 겹쳐서 충돌하는 경우
클로드 코드를 예전에 npm으로 설치했다가, 나중에 공식 설치 스크립트로 다시 설치한 경우 두 개가 같이 남아있을 수 있습니다. 버전이 안 올라가거나 이상하게 동작하면 이걸 의심해야 합니다.
확인하는 방법은 세 가지입니다. 제 컴퓨터에서 직접 돌려본 결과입니다.
$ which -a claude
/Users/seo/.local/bin/claude
$ ls -la ~/.claude/local/
ls: /Users/seo/.claude/local/: No such file or directory
$ npm -g ls @anthropic-ai/claude-code
/opt/homebrew/lib
└── (empty)이 컴퓨터는 네이티브 설치 하나만 깔끔하게 있는 상태입니다. which -a claude에 경로가 두 개 이상 뜨거나, ~/.claude/local/이 실제로 존재하거나, npm 목록에 뭔가 나온다면 그게 충돌 후보입니다.
충돌이 있으면 공식 문서 기준 정리 방법은 이렇습니다.
# npm 전역 설치 제거
npm uninstall -g @anthropic-ai/claude-code
# 예전 로컬 설치 제거
rm -rf ~/.claude/local~/.local/bin/claude로 된 네이티브 설치 하나만 남기는 게 공식 권장 방식입니다.
3. 구독 중인데 API 요금이 따로 나가는 경우
Pro나 Max를 구독하고 있는데 이상하게 API 요금이 따로 청구된다면, ANTHROPIC_API_KEY 환경변수가 셸 설정 파일에 남아있을 가능성이 있습니다. 예전 회사나 프로젝트에서 쓰던 키가 남아있으면, 클로드 코드가 구독 대신 그 키를 우선 사용합니다.
확인 방법입니다.
$ echo "현재 값: '${ANTHROPIC_API_KEY:-<설정안됨>}'"
현재 값: '<설정안됨>'
$ grep -n "ANTHROPIC_API_KEY" ~/.zshrc ~/.bashrc ~/.profile이 컴퓨터는 둘 다 깨끗해서 해당 없습니다. 만약 export ANTHROPIC_API_KEY=... 같은 줄이 나온다면, 그 파일에서 지우고 터미널을 다시 열면 됩니다. 지금 세션에서만 임시로 없애려면 이렇게 합니다.
unset ANTHROPIC_API_KEY
claude그래도 안 되면
여기 세 가지로도 안 풀리면, 증상이 더 다양하게 갈립니다. 이럴 땐 claude doctor를 실행하면 자동으로 진단 보고서를 만들어줍니다. 그래도 안 되면 공식 설치·로그인 문제 해결 문서에서 정확한 에러 메시지로 찾는 게 가장 빠릅니다. 에러 메시지 표가 잘 정리돼 있어서, 그대로 검색하면 거의 다 나옵니다.
자주 묻는 질문
PATH를 추가했는데도 안 되면 어떻게 하나요?
source ~/.zshrc를 안 했거나, 다른 셸(bash 등)을 쓰고 있을 수 있습니다. 터미널을 완전히 껐다가 다시 열어보고, 그래도 안 되면 echo $SHELL로 지금 쓰는 셸이 뭔지 먼저 확인하는 게 순서입니다.
npm으로 설치했는데 공식 방법으로 다시 설치해야 하나요?
권장합니다. 네이티브 설치가 자동 업데이트도 되고 공식 권장 방식입니다. 다만 바꾸기 전에 npm 설치본을 먼저 제거해야 충돌이 안 생깁니다.
이 세 가지 말고 다른 에러가 뜨면요?
이 글은 유튜브 설치 후기에서 자주 나오는 것 위주로 재현한 것이라 전부는 아닙니다. 공식 문서의 에러 메시지 표에 웬만한 증상이 다 정리돼 있으니, 뜬 메시지를 그대로 검색해보는 게 가장 빠릅니다.
정리
command not found는 대부분 PATH 문제 —~/.local/bin을 PATH에 추가하면 해결됩니다.- 설치를 여러 번 했다면
which -a claude로 충돌부터 확인하세요. - 구독인데 API 요금이 따로 나가면
ANTHROPIC_API_KEY환경변수부터 의심하세요. - 여기 없는 증상은
claude doctor나 공식 문서의 에러 메시지 표로 찾는 게 가장 빠릅니다.
설치까지 끝났다면 다음은 클로드 코드 사용법에서 이어집니다. 전체 순서는 바이브코딩 시작 가이드에서 확인할 수 있습니다.
참고 자료:
– Claude Code 공식 설치·로그인 문제 해결 문서