Claude Code 문제 해결
Claude Code 설치 및 사용 시 발생하는 일반적인 문제에 대한 해결책
일반적인 설치 문제
Linux 권한 문제
npm으로 Claude Code를 설치할 때, npm 전역 접두사가 사용자가 쓸 수 없는 경우(예: /usr
또는 /use/local
) 권한 오류가 발생할 수 있습니다.
권장 해결책: 사용자가 쓸 수 있는 npm 접두사 생성
가장 안전한 접근 방식은 홈 폴더 내의 디렉토리를 사용하도록 npm을 구성하는 것입니다:
이 해결책이 권장되는 이유는 다음과 같습니다:
- 시스템 디렉토리 권한을 수정하지 않음
- 전역 npm 패키지를 위한 깨끗하고 전용 위치 생성
- 보안 모범 사례 준수
시스템 복구: 시스템 파일의 소유권과 권한을 변경하는 명령을 실행한 경우
시스템 디렉토리 권한을 변경하는 명령(예: sudo chown -R $USER:$(id -gn) /usr && sudo chmod -R u+w /usr
)을 이미 실행했고 시스템이 손상된 경우(예: sudo: /usr/bin/sudo must be owned by uid 0 and have the setuid bit set
메시지가 표시되는 경우), 복구 단계를 수행해야 합니다.
Ubuntu/Debian 복구 방법:
-
재부팅하는 동안 SHIFT를 눌러 GRUB 메뉴에 접근
-
“Advanced options for Ubuntu/Debian” 선택
-
복구 모드 옵션 선택
-
“Drop to root shell prompt” 선택
-
파일시스템을 쓰기 가능하게 다시 마운트:
-
권한 수정:
-
영향을 받은 패키지 재설치(선택사항이지만 권장):
-
재부팅:
대체 Live USB 복구 방법:
복구 모드가 작동하지 않는 경우 live USB를 사용할 수 있습니다:
-
live USB로 부팅(Ubuntu, Debian 또는 다른 Linux 배포판)
-
시스템 파티션 찾기:
-
시스템 파티션 마운트:
-
별도의 부트 파티션이 있는 경우 마운트:
-
시스템으로 chroot:
-
위의 Ubuntu/Debian 복구 방법의 6-8단계 수행
시스템을 복구한 후, 위의 권장 해결책을 따라 사용자가 쓸 수 있는 npm 접두사를 설정하세요.
자동 업데이터 문제
Claude Code가 자동으로 업데이트되지 않는 경우, npm 전역 접두사 디렉토리의 권한 문제 때문일 수 있습니다. 이를 해결하려면 위의 권장 해결책을 따르세요.
대신 자동 업데이터를 비활성화하려면 다음을 사용하세요:
권한 및 인증
반복되는 권한 프롬프트
동일한 명령을 반복적으로 승인해야 하는 경우, 특정 도구가 승인 없이 실행되도록 허용할 수 있습니다:
인증 문제
인증 문제가 발생하는 경우:
/logout
을 실행하여 완전히 로그아웃- Claude Code 종료
claude
로 다시 시작하고 인증 프로세스 다시 완료
문제가 지속되는 경우 다음을 시도하세요:
이렇게 하면 저장된 인증 정보가 제거되고 새로운 로그인이 강제됩니다.
성능 및 안정성
높은 CPU 또는 메모리 사용량
Claude Code는 대부분의 개발 환경에서 작동하도록 설계되었지만, 큰 코드베이스를 처리할 때 상당한 리소스를 소비할 수 있습니다. 성능 문제가 발생하는 경우:
/compact
를 정기적으로 사용하여 컨텍스트 크기 줄이기- 주요 작업 사이에 Claude Code를 종료하고 다시 시작
- 큰 빌드 디렉토리를
.gitignore
와.claudeignore
파일에 추가하는 것을 고려
명령이 멈추거나 정지
Claude Code가 응답하지 않는 것처럼 보이는 경우:
- Ctrl+C를 눌러 현재 작업 취소 시도
- 응답이 없는 경우 터미널을 닫고 다시 시작해야 할 수 있음
- 지속적인 문제의 경우 자세한 로깅으로 Claude 실행:
claude --verbose
추가 도움 받기
여기서 다루지 않은 문제가 발생하는 경우:
- Claude Code 내에서
/bug
명령을 사용하여 Anthropic에 직접 문제 보고 - 알려진 문제에 대해 GitHub 저장소 확인
/doctor
를 실행하여 Claude Code 설치 상태 확인
Was this page helpful?