​
일반적인 설치 문제

​
Linux 권한 문제

npm으로 Claude Code를 설치할 때, npm 전역 접두사가 사용자가 쓸 수 없는 경우(예: /usr 또는 /use/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 전역 접두사 디렉토리의 권한 문제 때문일 수 있습니다. 이를 해결하려면 위의 권장 해결책을 따르세요.

대신 자동 업데이터를 비활성화하려면 다음을 사용하세요:

claude config set -g autoUpdaterStatus disabled

​
권한 및 인증

​
반복되는 권한 프롬프트

동일한 명령을 반복적으로 승인해야 하는 경우, 특정 도구가 승인 없이 실행되도록 허용할 수 있습니다:

# npm test가 승인 없이 실행되도록 허용
claude config add allowedTools "Bash(npm test)"

# npm test와 모든 하위 명령이 승인 없이 실행되도록 허용
claude config add allowedTools "Bash(npm test:*)"

​
인증 문제

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

  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와 .claudeignore 파일에 추가하는 것을 고려

​
명령이 멈추거나 정지

Claude Code가 응답하지 않는 것처럼 보이는 경우:

  1. Ctrl+C를 눌러 현재 작업 취소 시도
  2. 응답이 없는 경우 터미널을 닫고 다시 시작해야 할 수 있음
  3. 지속적인 문제의 경우 자세한 로깅으로 Claude 실행: claude --verbose

​
추가 도움 받기

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

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

Was this page helpful?

Claude Code 튜토리얼컴퓨터 사용 (베타)