클로드 코드 쓰다가 막혀본 적 있으신가요?
“설치했는데 claude 명령어를 못 찾겠어요.”
“API 키를 분명히 넣었는데 인증 오류가 뜨네요.”
“어제까지 잘 됐는데 오늘 갑자기 안 돼요.”
클로드 코드(Claude Code)를 처음 쓰는 분들이 공통적으로 겪는 고민들입니다. 사실 저도 이 목록의 절반은 직접 걸려서 헤맸습니다. 저는 개발자가 아니라 커머스 MD인데요, 명령어가 안 먹혀서(1번), 인증 오류가 떠서(4번), 대화가 갑자기 느려지고 앞 내용을 까먹어서(7번) 각각 한참을 붙잡고 있었어요. 그때마다 “내가 뭘 잘못했지?” 자책했는데, 알고 보면 대부분 몇 가지 정해진 원인이더군요.
이 글에서는 입문자가 가장 많이 하는 실수 10가지를 원인과 해결법 세트로 깔끔하게 정리해 드립니다. 해당 오류가 뜨면 바로 찾아보세요.
실수 1~5: 설치·인증 단계에서 막히는 경우
실수 1. claude: command not found — 설치했는데 명령어를 못 찾는다
원인: npm으로 전역 설치했지만 npm 글로벌 경로가 시스템 PATH에 등록되지 않은 경우입니다.
해결법:
# npm 글로벌 경로 확인
npm config get prefix
# 해당 경로의 bin 폴더를 PATH에 추가 (예: ~/.npm-global/bin)
export PATH="$HOME/.npm-global/bin:$PATH"
# 터미널 재시작 또는 설정 파일에 영구 저장 (~/.zshrc 또는 ~/.bashrc에 위 줄 추가)
Windows라면 명령 프롬프트를 관리자 권한으로 열고 재설치하세요.
🙋 제 경우: 저는 윈도우에서 이 1번에 막혔었어요. 설치는 분명 됐다는데
claude를 치면 “명령을 찾을 수 없다”고만 뜨더라고요. 해결은 허무할 만큼 간단했습니다 — 터미널을 완전히 닫고 다시 여니 PATH가 새로 인식돼 바로 실행됐습니다.
실수 2. npm 설치 시 권한(Permission) 오류가 난다
원인: npm 글로벌 폴더가 관리자 소유로 되어 있어 일반 사용자 계정으로는 쓰기 권한이 없는 상황입니다.
해결법 (sudo 없이):
# 사용자 쓰기 가능 경로로 npm prefix 변경
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH="~/.npm-global/bin:$PATH"
# 이후 다시 설치
npm install -g @anthropic-ai/claude-code
⚠️
sudo npm install -g는 보안상 권장하지 않습니다. 위 방법으로 우회하세요.
실수 3. WSL(윈도우 리눅스 환경)에서 설치 오류가 난다
원인: WSL 내부에서 npm이 Windows 쪽 npm을 참조해 OS 불일치 오류가 발생합니다.
해결법:
# 방법 A: os 설정 우선 변경
npm config set os linux
npm install -g @anthropic-ai/claude-code
# 방법 B: 강제 설치 옵션 사용
npm install -g @anthropic-ai/claude-code --force --no-os-check
실수 4. API 키를 넣었는데 “Invalid API Key” 오류가 뜬다
원인: 키 앞뒤에 공백이 포함됐거나, 환경 변수가 현재 세션에만 적용되고 다음 터미널 실행 시 사라지는 경우, 또는 키 자체가 만료·비활성 상태인 경우입니다.
해결법:
# 현재 키 확인 (값이 비어 있으면 설정 안 된 것)
echo $ANTHROPIC_API_KEY
# 올바른 설정 방법 (공백 없이)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxx..."
# 영구 저장 (재시작 후에도 유지)
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxx..."' >> ~/.zshrc
source ~/.zshrc
설정 후 claude /status를 입력해 현재 인증 상태를 확인하세요.
🙋 제 경우: 저는 키를 제대로 넣었는데도 인증 오류가 떴는데, 원인은 엉뚱하게도 Anthropic Console에 결제 수단(카드)을 등록하지 않은 것이었습니다. 카드를 등록하고 5달러만 충전하니 바로 풀렸어요. 키 문제처럼 보여도 결제 설정을 함께 확인해 보세요.
실수 5. VS Code에서 Claude Code가 API 키를 인식 못 한다
원인: VS Code 익스텐션은 내부에 저장된 토큰이 있는데, 이 토큰이 손상되거나 만료됐을 때 새 키를 입력해도 반영이 안 됩니다.
해결법: VS Code 설정에서 키를 다시 입력하는 것보다 CLI에서 먼저 로그인해 전역 세션을 만들어주는 게 더 확실합니다.
# 터미널에서 실행 (VS Code 내부 터미널 아님)
claude /login
# 또는
claude config
이후 VS Code를 완전히 종료하고 다시 시작하면 익스텐션이 CLI 세션을 물려받습니다.
실수 6~10: 사용 중에 생기는 문제들
실수 6. 파일 경로를 물어봤는데 “파일을 찾을 수 없다”고 한다
원인: 클로드 코드는 현재 터미널이 위치한 폴더를 기준으로 파일을 탐색합니다. 다른 드라이브나 폴더에 파일이 있으면 찾지 못합니다.
해결법:
# 작업 전 반드시 프로젝트 폴더로 이동
cd C:\Users\사용자명\프로젝트폴더
# 이동 후 claude 실행
claude
또는 클로드 코드에 절대 경로를 포함해 요청하세요.
예: “C:\Users\홍길동\projects\myapp\main.py 파일을 읽어줘”
실수 7. 대화 맥락이 갑자기 초기화됐다 / 이전 내용을 모른다
원인: 클로드 코드는 하나의 대화 세션(context window) 내에서만 이전 내용을 기억합니다. /clear 명령이 실행됐거나, 세션이 만료된 경우 맥락이 사라집니다. 또한 대화가 너무 길어져도 앞부분을 잊기 시작합니다.
해결법:
– CLAUDE.md 파일을 프로젝트 폴더에 만들어두세요. 클로드는 매 세션마다 이 파일을 자동으로 읽어 규칙과 맥락을 이어갑니다.
– 긴 작업 전에는 “이번 작업의 전제는 ~이야”라고 먼저 요약해 주세요.
– 대화가 길어져 느려졌다면 /compact로 이전 대화를 요약·압축해 맥락을 유지하세요.
🙋 제 경우: 저는 이 7번을
/compact라는 명령어가 있는지도 모른 채 겪었습니다. 대화가 길어지니 응답이 점점 느려지고 아까 정리한 내용을 자꾸 까먹길래 “AI가 원래 이런가?” 했는데,/compact한 번이면 해결되는 문제였어요. 지금은 작업이 길어진다 싶으면 습관적으로 눌러 줍니다.
실수 8. 같은 오류를 고쳐달라고 했는데 계속 안 고쳐진다
원인: 문제를 너무 뭉뚱그려 전달하거나, 에러 메시지를 요약해서 넘기는 경우입니다. 클로드는 정확한 정보 없이 추측으로 수정하다 실패를 반복합니다.
해결법: 에러 메시지를 전체 복사해서 붙여넣기 하세요.
❌ “오류 났어요”
✅ “아래 오류가 발생했어요:TypeError: Cannot read properties of undefined (reading 'map') at App.js:23“
에러 메시지 전문 + 발생 파일명 + 어떤 동작을 했을 때 나타났는지를 함께 전달하면 해결 속도가 크게 빨라집니다. 저도 이 방법을 알고 나서는 같은 오류를 몇 번씩 되묻는 일이 확 줄었습니다.
실수 9. 너무 많은 파일을 한 번에 넘겼더니 응답이 이상하다
원인: 클로드 코드의 컨텍스트 창(한 번에 처리할 수 있는 정보량)에는 한계가 있습니다. 너무 많은 코드를 한 번에 넣으면 앞 내용을 잊거나 응답 품질이 떨어질 수 있습니다.
해결법:
– 작업을 작게 나눠 한 번에 하나씩 요청하세요.
– 핵심 파일만 지정해서 읽히거나, “이 파일의 A 함수만 봐줘” 처럼 범위를 좁혀주세요.
– /clear로 맥락을 초기화한 후 새로 시작하는 것도 방법입니다.
실수 10. 갑자기 “사용 한도 초과” 또는 속도 제한 오류가 뜬다
원인: Anthropic API에는 분당 요청 수(RPM)와 일일 토큰 한도(TPD)가 있습니다. 특히 무료/기본 플랜은 한도가 낮습니다. 빠르게 많은 요청을 보내거나 긴 코드를 여러 번 처리하면 제한에 걸립니다.
해결법:
| 상황 | 해결책 |
|---|---|
| 잠시 후 다시 시도 | 보통 60초~수 분 기다리면 풀립니다 |
| 반복적으로 걸린다 | Anthropic Console에서 플랜/한도 확인 |
| 비용 절약이 필요하다 | Haiku 모델로 전환 (비용 절약편 참고) |
| 급하지 않은 작업 | 여러 세션으로 나눠 처리 |
진단 명령어 claude doctor를 실행하면 현재 설정 상태와 인증 이슈를 한 번에 점검할 수 있습니다.
claude doctor 한 줄이면 설치·인증·설정을 한 번에 점검해 준다.빠른 자가 진단 체크리스트
막혔을 때 이 순서대로 확인해 보세요.
claude --version— 설치 확인echo $ANTHROPIC_API_KEY— API 키 환경 변수 확인claude doctor— 전반적인 설정 진단claude /status— 현재 인증 상태 확인/clear후 재시도 — 맥락 초기화
자주 묻는 질문 (FAQ)
Q. 설치는 됐는데 업데이트 후 또 오류가 나요. 왜 그런가요?
A. 버전 업데이트 시 일부 설정 파일 구조가 바뀌어 충돌이 생길 수 있습니다. npm update -g @anthropic-ai/claude-code로 최신 버전으로 올린 후 claude doctor를 실행해 설정 파일 유효성을 점검하세요. 그래도 안 되면 ~/.claude 폴더를 백업 후 삭제하고 /login부터 다시 진행하면 깨끗이 해결됩니다.
Q. API 키는 맞는데 “401 인증 오류”가 계속 뜹니다.
A. Anthropic Console(console.anthropic.com)에서 해당 키의 상태가 “Active”인지 먼저 확인하세요. 키가 활성화됐는데도 오류가 지속되면, 키를 새로 발급받아 교체해 보세요. 기존 키가 손상된 경우 재발급이 가장 빠른 해결법입니다.
Q. 회사 네트워크(VPN)에서 Claude Code가 안 돼요.
A. 일부 기업 방화벽이나 VPN이 Anthropic API 서버(api.anthropic.com)로의 연결을 차단하는 경우가 있습니다. IT 팀에 해당 도메인 허용을 요청하거나, VPN을 끈 상태에서 테스트해 보세요. Anthropic 공식 지원 페이지에서도 API 연결 오류 해결 가이드를 제공합니다.
한 줄 요약: 클로드 코드 오류 대부분은 경로·API 키·환경 변수 세 가지만 점검해도 절반 이상 해결됩니다. 막히면 claude doctor부터 돌려보세요.
참고 자료
– Claude Code 공식 문제 해결 가이드 (Anthropic 한국어)
– Claude Code 설치 및 인증 문제 해결 — Claude Help Center
– 오류 참조 — Claude Code Docs 한국어