메인 콘텐츠로 건너뛰기

​
일반적인 설치 문제

​
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/로 시작하는 Windows 경로가 아닌 /usr/로 시작하는 Linux 경로를 가리켜야 합니다. 이를 해결하려면 Linux 배포판의 패키지 관리자 또는 nvm을 통해 Node를 설치해보세요. nvm 버전 충돌: WSL과 Windows 모두에 nvm이 설치되어 있으면 WSL에서 Node 버전을 전환할 때 버전 충돌이 발생할 수 있습니다. 이는 WSL이 기본적으로 Windows PATH를 가져오기 때문에 WSL 설치보다 Windows nvm/npm이 우선순위를 갖기 때문입니다. 다음과 같은 방법으로 이 문제를 식별할 수 있습니다:
  • which npm과 which node 실행 - Windows 경로(/mnt/c/로 시작)를 가리키면 Windows 버전이 사용 중입니다
  • WSL에서 nvm으로 Node 버전을 전환한 후 기능이 손상됨
이 문제를 해결하려면 Linux PATH를 수정하여 Linux node/npm 버전이 우선순위를 갖도록 하세요: 주요 해결책: nvm이 셸에 제대로 로드되었는지 확인 가장 일반적인 원인은 nvm이 비대화형 셸에 로드되지 않는 것입니다. 셸 구성 파일(~/.bashrc, ~/.zshrc 등)에 다음을 추가하세요: 
# Load nvm if it exists
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: 
# Install stable version (default)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version number
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
Windows PowerShell: 
# Install stable version (default)
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Install specific version number
& ([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  # Should show an alias to ~/.claude/local/claude
Windows에서: 
where claude  # Should show path to claude executable
설치 확인: 
claude doctor # Check installation health

​
권한 및 인증

​
반복되는 권한 프롬프트

동일한 명령을 반복적으로 승인해야 하는 경우 /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. 응답이 없으면 터미널을 닫고 다시 시작해야 할 수 있습니다

​
검색 및 발견 문제

검색 도구, @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의 파일 시스템 간 작업할 때 디스크 읽기 성능 저하로 인해 Claude Code를 WSL에서 사용할 때 예상보다 적은 일치 항목(완전한 검색 기능 부족은 아님)이 발생할 수 있습니다.
이 경우 /doctor는 검색을 OK로 표시합니다.
해결책:
  1. 더 구체적인 검색 제출: 디렉토리 또는 파일 유형을 지정하여 검색할 파일 수를 줄이세요: “auth-service 패키지에서 JWT 검증 로직 검색” 또는 “JS 파일에서 md5 해시 사용 찾기”.
  2. 프로젝트를 Linux 파일 시스템으로 이동: 가능하면 프로젝트가 Windows 파일 시스템(/mnt/c/)이 아닌 Linux 파일 시스템(/home/)에 위치하도록 하세요.
  3. 네이티브 Windows 사용: 더 나은 파일 시스템 성능을 위해 WSL 대신 Windows에서 Claude Code를 네이티브로 실행하는 것을 고려하세요.

​
IDE 통합 문제

​
WSL2에서 JetBrains IDE가 감지되지 않음

WSL2에서 Claude Code를 JetBrains IDE와 함께 사용 중이고 “사용 가능한 IDE가 감지되지 않음” 오류가 발생하면 이는 WSL2의 네트워킹 구성 또는 Windows 방화벽이 연결을 차단하기 때문일 가능성이 높습니다.

​
WSL2 네트워킹 모드

WSL2는 기본적으로 NAT 네트워킹을 사용하므로 IDE 감지를 방해할 수 있습니다. 두 가지 옵션이 있습니다: 옵션 1: Windows 방화벽 구성 (권장)
  1. WSL2 IP 주소 찾기: 
    wsl hostname -I
# Example output: 172.21.123.456
  2. PowerShell을 관리자로 열고 방화벽 규칙 생성: 
    New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
    (1단계의 WSL2 서브넷을 기반으로 IP 범위 조정)
  3. IDE와 Claude Code 모두 다시 시작
옵션 2: 미러링된 네트워킹으로 전환 Windows 사용자 디렉토리의 .wslconfig에 추가: 
[wsl2]
networkingMode=mirrored
그런 다음 PowerShell에서 wsl --shutdown으로 WSL을 다시 시작하세요.
이러한 네트워킹 문제는 WSL2에만 영향을 줍니다. WSL1은 호스트의 네트워크를 직접 사용하며 이러한 구성이 필요하지 않습니다.
추가 JetBrains 구성 팁은 IDE 통합 가이드를 참조하세요.

​
Windows IDE 통합 문제 보고 (네이티브 및 WSL 모두)

Windows에서 IDE 통합 문제가 발생하는 경우 다음 정보와 함께 문제를 생성하세요: 네이티브(git bash) 또는 WSL1/WSL2 여부, WSL 네트워킹 모드(NAT 또는 미러링), IDE 이름/버전, Claude Code 확장/플러그인 버전 및 셸 유형(bash/zsh/등)

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

JetBrains 터미널에서 Claude Code를 사용 중이고 ESC 키가 예상대로 에이전트를 중단하지 않으면 이는 JetBrains의 기본 단축키와 키 바인딩이 충돌하기 때문일 가능성이 높습니다. 이 문제를 해결하려면:
  1. 설정 → 도구 → 터미널로 이동
  2. 다음 중 하나를 수행하세요:
    • “Escape로 편집기에 포커스 이동” 선택 해제, 또는
    • “터미널 키 바인딩 구성”을 클릭하고 “편집기로 포커스 전환” 단축키 삭제
  3. 변경 사항 적용
이를 통해 ESC 키가 Claude Code 작업을 제대로 중단할 수 있습니다.

​
Markdown 형식 문제

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

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

생성된 markdown에서 다음과 같은 코드 블록을 발견하면: 
```
function example() {
  return "hello";
}
```
다음과 같이 적절히 태그된 블록 대신: 
```javascript
function example() {
  return "hello";
}
```
해결책:
  1. Claude에 언어 태그 추가 요청: 단순히 “이 markdown 파일의 모든 코드 블록에 적절한 언어 태그를 추가해주세요.”라고 요청하세요.
  2. 사후 처리 훅 사용: 누락된 언어 태그를 감지하고 추가하는 자동 형식 지정 훅을 설정하세요. 구현 세부 사항은 markdown 형식 지정 훅 예제를 참조하세요.
  3. 수동 확인: markdown 파일을 생성한 후 적절한 코드 블록 형식을 검토하고 필요한 경우 수정을 요청하세요.

​
일관성 없는 간격 및 형식

생성된 markdown에 과도한 빈 줄이나 일관성 없는 간격이 있는 경우: 해결책:
  1. 형식 지정 수정 요청: Claude에 “이 markdown 파일의 간격 및 형식 문제를 수정해주세요.”라고 요청하세요.
  2. 형식 지정 도구 사용: prettier 또는 사용자 정의 형식 지정 스크립트와 같은 markdown 포매터를 실행하는 훅을 설정하세요.
  3. 형식 지정 기본 설정 지정: 프롬프트 또는 프로젝트 메모리 파일에 형식 지정 요구 사항을 포함하세요.

​
Markdown 생성을 위한 모범 사례

형식 지정 문제를 최소화하려면:
  • 요청에서 명시적으로: “언어 태그가 있는 코드 블록이 포함된 적절히 형식화된 markdown”을 요청하세요
  • 프로젝트 규칙 사용: CLAUDE.md에서 선호하는 markdown 스타일을 문서화하세요
  • 검증 훅 설정: 사후 처리 훅을 사용하여 일반적인 형식 지정 문제를 자동으로 확인하고 수정하세요

​
추가 도움 받기

여기에 다루지 않은 문제가 발생하는 경우:
  1. Claude Code 내에서 /bug 명령을 사용하여 Anthropic에 문제를 직접 보고하세요
  2. GitHub 저장소에서 알려진 문제를 확인하세요
  3. /doctor를 실행하여 Claude Code 설치 상태를 확인하세요
  4. Claude에 직접 기능 및 특징에 대해 물어보세요 - Claude는 문서에 대한 기본 제공 액세스 권한이 있습니다