Claude Code 공식문서 리뷰-Build with Claude Code[8] : Troubleshooting

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> Build with Claude Code 섹션의 내용 중 [Connect Claude Code to tools via MCP]를 살펴 보려고 합니다.

https://code.claude.com/docs/en/troubleshooting

Troubleshooting - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다. 

 

문제 해결 가이드

• 목적: Claude Code 사용 중 발생하는 일반적인 문제 해결
• 범위: 설치, 인증, 성능, IDE 통합, 포매팅 문제
• 빠른 진단: /doctor 명령으로 설치 상태 자동 진단
• 원본: code.claude.com/docs/en/troubleshooting

 

설치 문제

Windows (WSL) 설치 오류

WSL 환경에서 Claude Code를 설치할 때 발생하는 일반적인 문제들이다.

 

OS/플랫폼 감지 문제

Windows에서 WSL을 사용할 때 플랫폼 감지가 잘못될 수 있다.

# 설치 전에 실행
npm config set os linux

# 강제 설치 (sudo 사용 금지)
npm install -g @anthropic-ai/claude-code --force --no-os-check

주의
sudo를 사용하면 권한 문제가 발생할 수 있다. 반드시 일반 사용자로 설치한다.

 

Node를 찾을 수 없음 (exec: node: not found)

WSL이 Linux Node.js 대신 Windows Node.js를 참조하는 경우 발생한다.

문제 확인:

which npm
which node

상태	경로
잘못된 경로	/mnt/c/Program Files/... (Windows 경로)
올바른 경로	/usr/bin/node 또는 ~/.nvm/... (Linux 경로)

 

해결 방법:

1. Linux 패키지 관리자로 설치:

# Ubuntu/Debian
sudo apt install nodejs npm

2. nvm으로 설치 (권장):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install --lts

 

nvm 버전 충돌

Windows와 WSL에 각각 nvm이 설치된 경우 충돌이 발생할 수 있다.

 

해결 방법 - 셸 설정에 추가:

# ~/.bashrc 또는 ~/.zshrc에 추가
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 순서 조정:

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

 

Linux/macOS 설치 오류

권한 오류나 "command not found" 에러가 발생하는 경우 네이티브 설치를 권장한다.

 

권장 설치 방법

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 doctor  # 설치 상태 진단

팁
claude doctor 명령은 설치 문제를 자동으로 진단해준다. 문제가 발생하면 가장 먼저 실행해보자.

 

권한 및 인증

반복되는 권한 요청

같은 도구에 대해 반복적으로 권한을 요청받는다면 /permissions 명령으로 허용 목록을 설정할 수 있다.

# 권한 설정 열기
/permissions

 

인증 문제

로그인이 제대로 되지 않거나 인증 오류가 발생하는 경우:

1. /logout으로 로그아웃
2. Claude Code 종료
3. claude 명령으로 재시작 후 다시 인증

 

문제가 지속되면:

# 인증 파일 삭제 후 재인증
rm -rf ~/.config/claude-code/auth.json
claude

흔한 에러: 토큰 만료
"Authentication expired" 또는 "Invalid token" 메시지가 나타나면 위 단계를 따라 재인증한다.

 

설정 파일 위치

Claude Code는 여러 설정 파일을 사용한다. 문제 해결 시 이 파일들의 위치를 알아두면 유용하다.

 

설정 파일 목록

파일	용도	공유
~/.claude/settings.json	사용자 설정 (권한, 훅, 모델)	개인용
.claude/settings.json	프로젝트 설정	버전 관리 O
.claude/settings.local.json	로컬 프로젝트 설정	버전 관리 X
~/.claude.json	전역 상태 (테마, OAuth, MCP)	개인용
.mcp.json	프로젝트 MCP 서버	버전 관리 O

 

기업 관리형 설정 파일 위치

플랫폼	경로
macOS	/Library/Application Support/ClaudeCode/
Linux/WSL	/etc/claude-code/
Windows	C:\ProgramData\ClaudeCode\

참고
Windows에서 ~는 사용자 홈 디렉토리를 의미한다 (예: C:\Users\YourName).

 

설정 초기화

모든 설정을 초기 상태로 되돌리려면:

# 모든 사용자 설정 초기화
rm ~/.claude.json
rm -rf ~/.claude/

# 프로젝트별 설정 초기화
rm -rf .claude/
rm .mcp.json

주의
설정 초기화는 모든 커스텀 설정, 권한, 훅을 삭제한다. 필요하다면 먼저 백업하자.

 

성능 및 안정성

높은 CPU/메모리 사용량

Claude Code는 대부분의 개발 환경에서 잘 작동하지만, 대규모 코드베이스에서는 리소스를 많이 사용할 수 있다.

해결 방법:

1. /compact 명령으로 정기적으로 컨텍스트 크기 줄이기
2. 큰 작업 사이에 Claude Code 재시작
3. 빌드 디렉토리를 .gitignore에 추가

실전 팁
/compact 명령은 대화 컨텍스트를 압축하여 메모리 사용량을 줄인다. 긴 대화 후에 사용하면 효과적이다.

 

명령 멈춤 또는 프리징

Claude Code가 응답하지 않는 경우:

1. Ctrl+C로 현재 작업 취소
2. 응답이 없으면 터미널을 닫고 재시작

 

검색 및 탐색 문제

Search 도구, @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

 

설치 후 환경 변수 설정:

export USE_BUILTIN_RIPGREP=0

초보자 팁
ripgrep은 매우 빠른 코드 검색 도구다. 설치하면 Claude Code의 검색 성능이 크게 향상된다.

 

WSL에서 느린 검색 결과

WSL에서 파일 시스템 간 작업 시 디스크 읽기 성능 저하로 검색 결과가 적거나 느릴 수 있다.

방법	설명
구체적인 검색	"auth-service 패키지에서 JWT 검증 로직 찾기"
Linux 파일시스템 사용	프로젝트를 /mnt/c/ 대신 /home/에 배치
네이티브 Windows 사용	WSL 대신 Windows에서 직접 Claude Code 실행

 

IDE 통합 문제

WSL2에서 JetBrains IDE 감지 안됨

WSL2의 네트워킹 설정이나 Windows 방화벽이 연결을 차단할 수 있다.

 

방법 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

 

3. IDE와 Claude Code 재시작

 

방법 2: 미러링 네트워킹 모드

Windows 사용자 디렉토리의 .wslconfig 파일에 추가:

[wsl2]
networkingMode=mirrored

 

WSL 재시작:

wsl --shutdown

 

Windows IDE 통합 문제 보고 시 필요한 정보

항목	예시
환경 유형	네이티브 Windows (Git Bash) 또는 WSL1/WSL2
WSL 네트워킹 모드	NAT 또는 mirrored
IDE 이름/버전	IntelliJ IDEA 2024.1
Claude Code 확장 버전	1.0.58
셸 유형	Bash, Zsh, PowerShell 등

 

JetBrains 터미널에서 Esc 키 동작 안함

해결 방법:

1. Settings → Tools → Terminal 이동
2. 다음 중 하나 수행:
   • "Move focus to the editor with Escape" 체크 해제
   • "Configure terminal keybindings" 클릭 → "Switch focus to Editor" 단축키 삭제
3. 변경 적용

 

마크다운 포매팅 문제

코드 블록에 언어 태그 누락

Claude가 생성한 마크다운에서 코드 블록에 언어 태그가 없는 경우가 있다.

 

잘못된 예:

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

 

올바른 예:

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

 

해결 방법:

1. 직접 요청: "이 마크다운 파일의 모든 코드 블록에 적절한 언어 태그를 추가해줘"
2. 훅으로 자동화: PostToolUse 훅을 사용해 자동으로 언어 태그를 추가할 수 있다.
3. 수동 검토: 생성된 문서를 검토하고 수정 요청

 

일관성 없는 포매팅

방법	설명
명시적 요청	"언어 태그가 있는 코드 블록을 포함한 적절한 마크다운 형식으로"
프로젝트 규칙	CLAUDE.md에 마크다운 스타일 가이드 문서화
검증 훅	PostToolUse 훅으로 자동 검증 및 수정

실전 팁
CLAUDE.md 파일에 마크다운 포매팅 규칙을 명시하면 Claude가 일관된 형식으로 문서를 생성한다.

 

추가 도움 얻기

문제 보고

Claude Code 내에서 /bug 명령을 사용하면 Anthropic에 직접 문제를 보고할 수 있다.

/bug

 

유용한 리소스

리소스	용도
/doctor	설치 상태 진단
/bug	문제 보고
GitHub Issues	알려진 문제 확인
Claude에게 직접 질문	기능 및 사용법 문의

초보자 팁
Claude Code에게 직접 기능에 대해 물어볼 수 있다. Claude는 자체 문서에 접근할 수 있으므로 "어떻게 하면..."이라고 질문하면 된다.

 

문제 해결 체크리스트

문제가 발생했을 때 순서대로 확인:

1. /doctor 실행해서 설치 상태 확인
2. Claude Code 최신 버전인지 확인 (claude --version)
3. 설정 파일이 올바른 위치에 있는지 확인
4. WSL 사용 시 Linux 경로에 프로젝트가 있는지 확인
5. IDE 통합 문제 시 방화벽 설정 확인
6. 문제 지속 시 설정 초기화 고려
7. 해결되지 않으면 /bug로 문제 보고

참고 자료

• 공식 문서: Troubleshooting
• 설정 가이드
• GitHub Issues