​
일반적인 설치 문제

​
Linux 권한 문제

npm으로 Claude Code를 설치할 때, npm 전역 접두사가 사용자가 쓸 수 있는 상태가 아닌 경우(예: /usr 또는 /usr/local) 권한 오류가 발생할 수 있습니다.

​
권장 해결책: 사용자가 쓸 수 있는 npm 접두사 생성

가장 안전한 방법은 홈 폴더 내의 디렉토리를 사용하도록 npm을 구성하는 것입니다:

# 먼저 나중에 마이그레이션하기 위해 기존 전역 패키지 목록을 저장합니다
npm list -g --depth=0 > ~/npm-global-packages.txt

# 전역 패키지를 위한 디렉토리를 생성합니다
mkdir -p ~/.npm-global

# 새 디렉토리 경로를 사용하도록 npm을 구성합니다
npm config set prefix ~/.npm-global

# 참고: ~/.bashrc를 셸에 맞는 ~/.zshrc, ~/.profile 또는 다른 적절한 파일로 바꾸세요
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# 새 PATH 설정을 적용합니다
source ~/.bashrc

# 이제 새 위치에 Claude Code를 재설치합니다
npm install -g @anthropic-ai/claude-code

# 선택사항: 새 위치에 이전 전역 패키지를 재설치합니다
# ~/npm-global-packages.txt를 보고 유지하고 싶은 패키지를 설치하세요

이 해결책이 권장되는 이유:

  • 시스템 디렉토리 권한 수정을 피합니다
  • 전역 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 복구 방법:

  1. 재부팅하는 동안 SHIFT를 눌러 GRUB 메뉴에 액세스합니다

  2. “Advanced options for Ubuntu/Debian”을 선택합니다

  3. 복구 모드 옵션을 선택합니다

  4. “Drop to root shell prompt”를 선택합니다

  5. 파일시스템을 쓰기 가능하도록 다시 마운트합니다:

    mount -o remount,rw /

  6. 권한을 수정합니다:

    # root 소유권 복원
chown -R root:root /usr
chmod -R 755 /usr

# npm 패키지를 위해 /usr/local이 사용자 소유인지 확인
chown -R YOUR_USERNAME:YOUR_USERNAME /usr/local

# 중요한 바이너리에 setuid 비트 설정
chmod u+s /usr/bin/sudo
chmod 4755 /usr/bin/sudo
chmod u+s /usr/bin/su
chmod u+s /usr/bin/passwd
chmod u+s /usr/bin/newgrp
chmod u+s /usr/bin/gpasswd
chmod u+s /usr/bin/chsh
chmod u+s /usr/bin/chfn

# sudo 구성 수정
chown root:root /usr/libexec/sudo/sudoers.so
chmod 4755 /usr/libexec/sudo/sudoers.so
chown root:root /etc/sudo.conf
chmod 644 /etc/sudo.conf

  7. 영향받은 패키지 재설치 (선택사항이지만 권장):

    # 설치된 패키지 목록 저장
dpkg --get-selections > /tmp/installed_packages.txt

# 재설치
awk '{print $1}' /tmp/installed_packages.txt | xargs -r apt-get install --reinstall -y

  8. 재부팅:

    reboot
대안 Live USB 복구 방법:

복구 모드가 작동하지 않는 경우, live USB를 사용할 수 있습니다:

  1. live USB(Ubuntu, Debian 또는 임의의 Linux 배포판)로 부팅합니다

  2. 시스템 파티션을 찾습니다:

    lsblk

  3. 시스템 파티션을 마운트합니다:

    sudo mount /dev/sdXY /mnt  # sdXY를 실제 시스템 파티션으로 바꾸세요

  4. 별도의 부트 파티션이 있는 경우, 그것도 마운트합니다:

    sudo mount /dev/sdXZ /mnt/boot  # 필요한 경우

  5. 시스템으로 chroot합니다:

    # Ubuntu/Debian의 경우:
sudo chroot /mnt

# Arch 기반 시스템의 경우:
sudo arch-chroot /mnt

  6. 위의 Ubuntu/Debian 복구 방법에서 6-8단계를 따릅니다

시스템을 복원한 후, 위의 권장 해결책을 따라 사용자가 쓸 수 있는 npm 접두사를 설정하세요.

​
자동 업데이터 문제

Claude Code가 자동으로 업데이트할 수 없는 경우, npm 전역 접두사 디렉토리의 권한 문제 때문일 수 있습니다. 이를 해결하려면 위의 권장 해결책을 따르세요.

대신 자동 업데이터를 비활성화하려면 다음을 사용할 수 있습니다: 대신 자동 업데이터를 비활성화하려면 DISABLE_AUTOUPDATER 환경 변수를 1로 설정할 수 있습니다

​
권한 및 인증

​
반복되는 권한 프롬프트

동일한 명령을 반복적으로 승인하고 있다면, /permissions 명령을 사용하여 특정 도구가 승인 없이 실행되도록 허용할 수 있습니다. 권한 문서를 참조하세요.

​
인증 문제

인증 문제가 발생하는 경우:

  1. /logout을 실행하여 완전히 로그아웃합니다
  2. Claude Code를 닫습니다
  3. claude로 다시 시작하고 인증 과정을 다시 완료합니다

문제가 지속되면 다음을 시도하세요:

rm -rf ~/.config/claude-code/auth.json
claude

이는 저장된 인증 정보를 제거하고 깨끗한 로그인을 강제합니다.

​
성능 및 안정성

​
높은 CPU 또는 메모리 사용량

Claude Code는 대부분의 개발 환경에서 작동하도록 설계되었지만, 대규모 코드베이스를 처리할 때 상당한 리소스를 소비할 수 있습니다. 성능 문제가 발생하는 경우:

  1. 컨텍스트 크기를 줄이기 위해 /compact를 정기적으로 사용하세요
  2. 주요 작업 사이에 Claude Code를 닫고 다시 시작하세요
  3. 대규모 빌드 디렉토리를 .gitignore 파일에 추가하는 것을 고려하세요

​
명령이 멈추거나 정지됨

Claude Code가 응답하지 않는 것 같으면:

  1. Ctrl+C를 눌러 현재 작업을 취소하려고 시도하세요
  2. 응답하지 않으면 터미널을 닫고 다시 시작해야 할 수 있습니다

​
JetBrains (IntelliJ, PyCharm 등) 터미널에서 ESC 키가 작동하지 않음

JetBrains 터미널에서 Claude Code를 사용하고 있고 ESC 키가 예상대로 에이전트를 중단하지 않는 경우, 이는 JetBrains의 기본 단축키와의 키바인딩 충돌 때문일 가능성이 높습니다.

이 문제를 해결하려면:

  1. Settings → Tools → Terminal로 이동합니다
  2. “Override IDE Shortcuts” 옆의 “Configure terminal keybindings” 하이퍼링크를 클릭합니다
  3. 터미널 키바인딩 내에서 “Switch focus to Editor”까지 스크롤하고 해당 단축키를 삭제합니다

이렇게 하면 ESC 키가 PyCharm의 “Switch focus to Editor” 액션에 의해 캡처되는 대신 Claude Code 작업을 취소하는 데 제대로 작동할 수 있습니다.

​
추가 도움 받기

여기에서 다루지 않은 문제가 발생하는 경우:

  1. Claude Code 내에서 /bug 명령을 사용하여 Anthropic에 직접 문제를 보고하세요
  2. 알려진 문제에 대해 GitHub 저장소를 확인하세요
  3. /doctor를 실행하여 Claude Code 설치 상태를 확인하세요