​
일반적인 설치 문제

​
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 등)에 다음을 추가하세요: 
# 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: 
# 안정 버전 설치 (기본값)
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. 응답하지 않으면 터미널을 닫고 다시 시작해야 할 수 있습니다

​
검색 및 발견 문제

검색 도구, @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를 실행하는 것을 고려하세요.

​
IDE 통합 문제

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

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

​
WSL2 네트워킹 모드

WSL2는 기본적으로 NAT 네트워킹을 사용하며, 이는 IDE 감지를 방해할 수 있습니다. 두 가지 옵션이 있습니다: 옵션 1: Windows 방화벽 구성 (권장)
  1. WSL2 IP 주소 찾기: 
    wsl hostname -I
# 예시 출력: 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 작업을 제대로 중단할 수 있습니다.

​
마크다운 형식 문제

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는 자체 문서에 대한 내장 액세스 권한이 있습니다