문제 해결 (Troubleshooting)

읽는 시간: 15분 | 난이도: 초급자

Claude Code 사용 시 발생할 수 있는 일반적인 문제들과 그 해결 방법을 배웁니다.

개요

이 가이드는 Claude Code 사용 중 마주할 수 있는 문제들을 진단하고 해결하는 방법을 다룹니다. 빠른 문제 해결을 위한 체계적인 접근 방식을 제공합니다.

1. 일반적인 문제 (Common Issues)

1.1 설치 문제

문제: 명령을 찾을 수 없음

$ claude
command not found: claude

해결 방법:

1. 설치 확인

# npm으로 설치된 경우
npm list -g @anthropic-ai/claude-code

# 전역 경로 확인
npm config get prefix

2. PATH에 추가

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

# ~/.zshrc 또는 ~/.bashrc에 추가
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3. 재설치

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

문제: 권한 오류

npm ERR! code EACCES

해결 방법:

# sudo 사용 (macOS/Linux)
sudo npm install -g @anthropic-ai/claude-code

# 또는 npm 권한 수정
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

1.2 인증 문제

문제: API 키 오류

Error: Invalid API key

해결 방법:

1. API 키 확인

# 환경 변수 확인
echo $ANTHROPIC_API_KEY

# API 키 설정
export ANTHROPIC_API_KEY="your_api_key_here"

# ~/.zshrc 또는 ~/.bashrc에 영구 추가
echo 'export ANTHROPIC_API_KEY="your_api_key_here"' >> ~/.zshrc

2. API 키 재발급

• Anthropic Console에서 새 키 발급
• 기존 키 삭제 및 새 키로 교체

문제: 인증 만료

Error: Token expired

해결 방법:

# 토큰 새로고침
claude auth refresh

# 또는 수동으로 API 키 업데이트
export ANTHROPIC_API_KEY="new_api_key_here"

1.3 연결 문제

문제: 네트워크 오류

Error: Network timeout
Error: Connection refused

해결 방법:

1. 인터넷 연결 확인

# 연결 테스트
ping api.anthropic.com

# DNS 확인
nslookup api.anthropic.com

2. 프록시 설정

# 프록시 환경 변수 설정
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# 또는 npm 설정
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

3. 방화벽 확인

• 포트 443 (HTTPS)가 열려 있는지 확인
• 방화벽 설정에서 api.anthropic.com 도메인 허용

2. 파일 작업 문제 (File Operation Issues)

2.1 파일 읽기 오류

문제: 권한 거부

Error: Permission denied to read file

해결 방법:

# 파일 권한 확인
ls -la <file>

# 읽기 권한 추가
chmod +r <file>

# 또한 .claudeignore에서 파일 제외 확인
cat .claudeignore | grep <file>

문제: 파일 너무 큼

Error: File too large to read

해결 방법:

# 파일 크기 확인
ls -lh <file>

# 특정 부분만 읽기
claude read <file> --lines 100

# 또는 파일 분할
split -l 1000 <file> output_

2.2 파일 쓰기 오류

문제: 잠금 오류

Error: File is locked

해결 방법:

# 파일 사용 프로세스 확인
lsof <file>

# 프로세스 종료
kill -9 <PID>

# 또는 잠시 후 다시 시도

3. 명령 실행 문제 (Command Execution Issues)

3.1 명령 실패

문제: 명령을 찾을 수 없음

Error: Command not found: npm

해결 방법:

# Node.js/npm 설치 확인
which node
which npm

# 설치되지 않은 경우 설치
# macOS
brew install node

# Ubuntu
sudo apt install nodejs npm

문제: 권한 거부

Error: Permission denied

해결 방법:

# 권한 있는 명령인지 확인
claude --allow-dangerous "sudo npm install"

# 또는 CLAUDE.md에서 명령 화이트리스트 설정

4. 성능 문제 (Performance Issues)

4.1 느린 응답

문제: 응답 시간이 느림

해결 방법:

1. 인터넷 속도 확인

# 속도 테스트
speedtest-cli

# 또는
ping -c 5 api.anthropic.com

2. 캐시 활성화

# 캐시 설정
claude config set cache.enabled true
claude config set cache.ttl 3600

3. 모델 변경

# 더 빠른 모델 사용
claude config set ai.model claude-haiku

4.2 메모리 사용량

문제: 메모리 부족

Error: Out of memory

해결 방법:

# Node.js 메모리 제한 증가
export NODE_OPTIONS="--max-old-space-size=4096"

# 또는
claude --max-memory 4GB

5. Git 문제 (Git Issues)

5.1 커밋 실패

문제: 커밋 오류

Error: Git commit failed

해결 방법:

# Git 상태 확인
git status

# 충돌 해결
git merge --abort

# 또는 수동 커밋
git add .
git commit -m "message"

5.2 푸시 실패

문제: 푸시 거부

Error: Push rejected

해결 방법:

# 원격 변경사항 가져오기
git pull --rebase

# 충돌 해결 후 푸시
git push

6. 디버깅 도구 (Debugging Tools)

6.1 로그 확인

# 로그 레벨 설정
claude --log-level debug

# 로그 파일 지정
claude --log-file /path/to/log.txt

# 로그 위치 확인
claude config get logging.file

6.2 진단 모드

# 진단 모드 실행
claude --diagnostic

# 상세 정보 표시
claude --verbose

# 추적 모드
claude --trace

6.3 상태 확인

# 상태 확인
claude status

# 설정 확인
claude config list

# 버전 확인
claude --version

7. 자주 묻는 질문 (FAQ)

Q: Claude Code가 오프라인에서 작동하나요?

A: 아니요. Claude Code는 인터넷 연결이 필수입니다. 모든 AI 처리는 클라우드에서 이루어집니다.

Q: 여러 프로젝트에서 동시에 사용할 수 있나요?

A: 네. 각 프로젝트 디렉터리에서 별도의 Claude Code 세션을 실행할 수 있습니다.

Q: 코드를 Claude 서버로 전송하나요?

A: 네. 코드 분석을 위해 Anthropic 서버로 전송됩니다. 자세한 내용은 개인정보 처리방침을 확인하세요.

Q: .claudeignore 파일은 무엇인가요?

A: .gitignore와 유사하게 Claude Code가 읽지 않을 파일/폴더를 지정합니다.

요약

이 문제 해결 가이드는 가장 흔한 문제들을 다룹니다.

문제 해결 단계

1. 문제 식별: 정확한 에러 메시지 확인
2. 원인 파악: 가능한 원인 목록 확인
3. 해결 시도: 제안된 해결 방법 순서대로 시도
4. 검증: 문제가 해결되었는지 확인

추가 지원

이 가이드에서 해결되지 않는 문제는 다음을 통해 지원받으세요:

• 공식 포럼
• GitHub Issues
• 공식 문서

이 가이드가 도움이 되셨나요?

추가 문제 해결이 필요하시면 언제든지 물어보세요!