​
일반적인 설치 문제

​
Windows 설치 문제: WSL에서의 오류

WSL에서 다음과 같은 문제가 발생할 수 있습니다:

OS/플랫폼 감지 문제: 설치 중 오류가 발생하면 WSL이 Windows npm을 사용하고 있을 수 있습니다. 다음을 시도해보세요:

  • 설치 전에 npm config set os linux 실행
  • npm install -g @anthropic-ai/claude-code --force --no-os-check로 설치 (sudo 사용하지 마세요)

Node를 찾을 수 없음 오류: claude를 실행할 때 exec: node: not found 오류가 표시되면 WSL 환경이 Windows의 Node.js 설치를 사용하고 있을 수 있습니다. which npm과 which node로 확인할 수 있으며, 이는 /mnt/c/가 아닌 /usr/로 시작하는 Linux 경로를 가리켜야 합니다. 이를 해결하려면 Linux 배포판의 패키지 매니저나 nvm을 통해 Node를 설치해보세요.

nvm 버전 충돌: WSL과 Windows 모두에 nvm이 설치되어 있으면 WSL에서 Node 버전을 전환할 때 버전 충돌이 발생할 수 있습니다. 이는 WSL이 기본적으로 Windows PATH를 가져와서 Windows nvm/npm이 WSL 설치보다 우선순위를 갖기 때문입니다.

다음과 같은 방법으로 이 문제를 식별할 수 있습니다:

  • which npm과 which node 실행 - Windows 경로(/mnt/c/로 시작)를 가리키면 Windows 버전이 사용되고 있습니다
  • WSL에서 nvm으로 Node 버전을 전환한 후 기능이 작동하지 않는 경우

이 문제를 해결하려면 Linux PATH를 수정하여 Linux node/npm 버전이 우선순위를 갖도록 하세요:

주요 해결책: 셸에서 nvm이 제대로 로드되도록 확인

가장 일반적인 원인은 nvm이 비대화형 셸에서 로드되지 않는 것입니다. 셸 구성 파일(~/.bashrc, ~/.zshrc 등)에 다음을 추가하세요:

# nvm이 존재하면 로드
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

또는 현재 세션에서 직접 실행:

source ~/.nvm/nvm.sh

대안: PATH 순서 조정

nvm이 제대로 로드되었지만 Windows 경로가 여전히 우선순위를 갖는 경우, 셸 구성에서 Linux 경로를 PATH에 명시적으로 앞에 추가할 수 있습니다:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

Windows PATH 가져오기를 비활성화(appendWindowsPath = false)하는 것은 WSL에서 Windows 실행 파일을 쉽게 호출하는 기능을 손상시키므로 피하세요. 마찬가지로 Windows 개발에 사용하는 경우 Windows에서 Node.js를 제거하는 것도 피하세요.

​
Linux 및 Mac 설치 문제: 권한 또는 명령을 찾을 수 없음 오류

npm으로 Claude Code를 설치할 때 PATH 문제로 인해 claude에 액세스하지 못할 수 있습니다. npm 전역 접두사가 사용자 쓰기 가능하지 않은 경우(예: /usr 또는 /usr/local) 권한 오류가 발생할 수도 있습니다.

​
권장 해결책: 네이티브 Claude Code 설치

Claude Code에는 npm이나 Node.js에 의존하지 않는 네이티브 설치가 있습니다.

네이티브 Claude Code 설치 프로그램은 현재 베타 버전입니다.

다음 명령을 사용하여 네이티브 설치 프로그램을 실행하세요.

macOS, Linux, WSL:

# 안정 버전 설치 (기본값)
curl -fsSL https://claude.ai/install.sh | bash

# 최신 버전 설치
curl -fsSL https://claude.ai/install.sh | bash -s latest

# 특정 버전 번호 설치
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell:

# 안정 버전 설치 (기본값)
irm https://claude.ai/install.ps1 | iex

# 최신 버전 설치
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# 특정 버전 번호 설치
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

이 명령은 운영 체제와 아키텍처에 적합한 Claude Code 빌드를 설치하고 ~/.local/bin/claude에 설치에 대한 심볼릭 링크를 추가합니다.

시스템 PATH에 설치 디렉토리가 있는지 확인하세요.

​
대안 해결책: 로컬 설치로 마이그레이션

또는 Claude Code가 실행되는 경우 로컬 설치로 마이그레이션할 수 있습니다:

claude migrate-installer

이는 Claude Code를 ~/.claude/local/로 이동하고 셸 구성에서 별칭을 설정합니다. 향후 업데이트에는 sudo가 필요하지 않습니다.

마이그레이션 후 셸을 다시 시작한 다음 설치를 확인하세요:

macOS/Linux/WSL에서:

which claude  # ~/.claude/local/claude에 대한 별칭을 표시해야 함

Windows에서:

where claude  # claude 실행 파일 경로를 표시해야 함

설치 확인:

claude doctor # 설치 상태 확인

​
권한 및 인증

​
반복되는 권한 프롬프트

동일한 명령을 반복적으로 승인하는 경우 /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. 설정 → 도구 → 터미널로 이동
  2. “IDE 단축키 재정의” 옆의 “터미널 키바인딩 구성” 하이퍼링크 클릭
  3. 터미널 키바인딩 내에서 “편집기로 포커스 전환”까지 스크롤하고 해당 단축키 삭제

이렇게 하면 ESC 키가 PyCharm의 “편집기로 포커스 전환” 작업에 의해 캡처되는 대신 Claude Code 작업을 취소하는 데 제대로 작동할 수 있습니다.

​
검색 및 발견 문제

검색 도구, @file 언급, 사용자 정의 에이전트 및 사용자 정의 슬래시 명령이 작동하지 않는 경우 시스템 ripgrep을 설치하세요:

# macOS (Homebrew)  
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep

그런 다음 환경에서 USE_BUILTIN_RIPGREP=0을 설정하세요.

​
WSL에서 느리거나 불완전한 검색 결과

WSL에서 파일 시스템 간 작업 시 디스크 읽기 성능 저하로 인해 WSL에서 Claude Code를 사용할 때 예상보다 적은 일치 항목이 나타날 수 있습니다(하지만 검색 기능이 완전히 없어지지는 않음).

이 경우 /doctor는 검색을 OK로 표시합니다.

해결책:

  1. 더 구체적인 검색 제출: 디렉토리나 파일 유형을 지정하여 검색할 파일 수를 줄이세요: “auth-service 패키지에서 JWT 유효성 검사 로직 검색” 또는 “JS 파일에서 md5 해시 사용 찾기”.

  2. 프로젝트를 Linux 파일 시스템으로 이동: 가능하면 프로젝트가 Windows 파일 시스템(/mnt/c/)이 아닌 Linux 파일 시스템(/home/)에 위치하도록 하세요.

  3. 네이티브 Windows 사용: 더 나은 파일 시스템 성능을 위해 WSL을 통하지 않고 Windows에서 네이티브로 Claude Code를 실행하는 것을 고려하세요.

​
마크다운 형식 문제

Claude Code는 때때로 코드 펜스에 언어 태그가 누락된 마크다운 파일을 생성하여 GitHub, 편집기 및 문서 도구에서 구문 강조 표시 및 가독성에 영향을 줄 수 있습니다.

​
코드 블록의 언어 태그 누락

생성된 마크다운에서 다음과 같은 코드 블록을 발견하는 경우:

```
function example() {
  return "hello";
}
```

다음과 같이 제대로 태그된 블록 대신:

```javascript
function example() {
  return "hello";
}
```

해결책:

  1. Claude에게 언어 태그 추가 요청: 단순히 “이 마크다운 파일의 모든 코드 블록에 적절한 언어 태그를 추가해주세요.”라고 요청하세요.

  2. 후처리 훅 사용: 누락된 언어 태그를 감지하고 추가하는 자동 형식 지정 훅을 설정하세요. 구현 세부 사항은 마크다운 형식 지정 훅 예제를 참조하세요.

  3. 수동 확인: 마크다운 파일을 생성한 후 적절한 코드 블록 형식을 검토하고 필요한 경우 수정을 요청하세요.

​
일관성 없는 간격 및 형식

생성된 마크다운에 과도한 빈 줄이나 일관성 없는 간격이 있는 경우:

해결책:

  1. 형식 수정 요청: Claude에게 “이 마크다운 파일의 간격 및 형식 문제를 수정해주세요.”라고 요청하세요.

  2. 형식 지정 도구 사용: 생성된 마크다운 파일에서 prettier나 사용자 정의 형식 지정 스크립트와 같은 마크다운 포매터를 실행하는 훅을 설정하세요.

  3. 형식 기본 설정 지정: 프롬프트나 프로젝트 메모리 파일에 형식 요구 사항을 포함하세요.

​
마크다운 생성 모범 사례

형식 문제를 최소화하려면:

  • 요청에서 명시적으로 표현: “언어 태그가 있는 코드 블록으로 적절히 형식화된 마크다운” 요청
  • 프로젝트 규칙 사용: CLAUDE.md에서 선호하는 마크다운 스타일 문서화
  • 유효성 검사 훅 설정: 일반적인 형식 문제를 자동으로 확인하고 수정하는 후처리 훅 사용

​
추가 도움 받기

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

  1. Claude Code 내에서 /bug 명령을 사용하여 Anthropic에 직접 문제 보고
  2. 알려진 문제에 대해 GitHub 저장소 확인
  3. /doctor를 실행하여 Claude Code 설치 상태 확인
  4. Claude의 기능과 특징에 대해 Claude에게 직접 문의 - Claude는 자체 문서에 대한 내장 액세스 권한이 있습니다