문제 해결

자주 발생하는 문제와 해결 방법을 정리합니다.

문제 해결 흐름도

단계별 문제 해결 의사결정 트리

🚨

증상 확인

응답 없음 / 설치 오류 / 인증 실패 / 성능 저하 / MCP 오류

먼저 실행

🩺

로그 확인

claude doctorclaude --debug--verbose

해결됨?

YES ✓

완료!

NO ↓

🔧

일반 해결책 시도

인증 재설정 · 캐시 삭제 · 앱 재시작 · 권한 확인 · 재설치

아직 안 됨?

🔬

고급 진단

--debug 로그.mcp.json 검증worktree 정리환경변수 확인

해결 불가?

🆘

도움 요청

GitHub Issues 검색 · 로그 첨부하여 이슈 등록 · Anthropic 고객 지원

진단 도구

문제가 발생했을 때 먼저 사용해볼 수 있는 진단 도구들입니다.

claude doctor

Claude Code의 전반적인 상태를 진단합니다.

# 전체 진단 실행
claude doctor

# Code 모드 내에서
/doctor

claude doctor는 다음 항목을 자동으로 확인합니다:

인증 상태
MCP 서버 연결 상태
네트워크 연결

디버그 모드

상세한 로그를 출력하여 문제 원인을 파악합니다.

# 디버그 모드로 실행
claude --debug

# 더 상세한 로그
claude --verbose

로그 파일 위치

각 운영체제별 로그 파일 경로입니다.

운영체제	로그 경로
macOS	`~/Library/Logs/Claude Code/`
Windows	`%APPDATA%\Claude Code\logs\`
Linux	`~/.local/share/claude-code/logs/`

팁

문제를 GitHub Issues에 보고할 때 로그 파일을 함께 첨부하면 빠른 해결에 도움이 됩니다.

Claude Desktop 공통

Claude가 응답하지 않아요

인터넷 연결 확인: Claude는 온라인 서비스입니다
앱 재시작: Claude Desktop을 완전히 종료 후 다시 실행
사용량 확인: 무료 플랜은 일일 사용량 제한이 있습니다

파일을 읽지 못해요

파일 크기 제한: 너무 큰 파일은 처리할 수 없습니다
지원 형식 확인: 지원하지 않는 파일 형식일 수 있습니다
권한 확인: 파일 접근 권한이 필요할 수 있습니다

응답이 잘려요

긴 응답이 중간에 잘리는 경우:

"계속해줘" 또는 "이어서 작성해줘"라고 요청
출력 범위를 좁혀서 다시 요청

Desktop 앱 빈 화면 / 렌더링 오류

Desktop 앱이 흰 화면으로 표시되거나 UI가 깨지는 경우:

# macOS: 캐시 삭제
rm -rf ~/Library/Application\ Support/Claude\ Code/Cache
rm -rf ~/Library/Application\ Support/Claude\ Code/GPUCache

# Windows: 캐시 삭제
rd /s /q "%APPDATA%\Claude Code\Cache"
rd /s /q "%APPDATA%\Claude Code\GPUCache"

캐시 삭제 후 앱을 재시작하세요.

Desktop 앱 인증 오류

"Authentication failed" 또는 토큰 관련 오류가 발생하는 경우:

# 1. 인증 토큰 재설정
claude auth logout
claude auth login

# 2. 그래도 안 되면 인증 파일 직접 삭제
# macOS
rm ~/Library/Application\ Support/Claude\ Code/auth.json

# Windows
del "%APPDATA%\Claude Code\auth.json"

경고

인증 파일 삭제 후에는 반드시 claude auth login으로 다시 로그인해야 합니다.

Claude Code 관련

설치 오류

"npm ERR! permission denied"

# 방법 1: npx로 직접 실행
npx @anthropic-ai/claude-code

# 방법 2: nvm 사용 (권장)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts
npm install -g @anthropic-ai/claude-code

정보

npm 대신 네이티브 설치(Native Install)를 권장합니다. 설치 가이드에서 운영체제별 설치 방법을 확인하세요.

"Node.js version not supported" (npm 방식으로 설치한 경우만 해당)

네이티브 설치는 Node.js 불필요

공식 설치 스크립트나 Homebrew로 설치한 경우 Node.js가 필요하지 않습니다. 아래 내용은 구버전 npm 기반 설치(npm install -g @anthropic-ai/claude-code)를 사용하는 경우에만 해당합니다.

# Node.js 18 이상 필요 (npm 설치 방식 한정)
node --version  # 현재 버전 확인
nvm install 22  # 최신 LTS 설치
nvm use 22

인증 오류

"Invalid API key"

# API 키 확인
echo $ANTHROPIC_API_KEY

# 키 재설정
export ANTHROPIC_API_KEY="sk-ant-..."

"Authentication failed"

claude 명령어를 다시 실행하여 재인증
브라우저 캐시/쿠키 삭제 후 재시도

파일 수정 관련

"Permission denied" 에러

Claude Code가 파일을 수정할 수 없는 경우:

파일 권한 확인: ls -la 파일경로
읽기 전용 파일인지 확인
권한 모드 확인: /permissions

변경 사항이 반영되지 않아요

파일이 다른 프로세스에 의해 잠겨 있는지 확인
IDE가 파일 변경을 감지하지 못하면 수동으로 새로고침

Git 관련 문제

"index.lock" 오류

Git 작업 중 비정상 종료 시 lock 파일이 남아 있을 수 있습니다.

# index.lock 파일 삭제
rm -f .git/index.lock

# 워크트리 정리 (병렬 세션 사용 시)
git worktree prune

워크트리(Worktree) 충돌

Desktop 앱의 병렬 세션이나 /batch 사용 후 워크트리가 정리되지 않은 경우:

# 현재 워크트리 목록 확인
git worktree list

# 불필요한 워크트리 정리
git worktree prune

# 수동으로 워크트리 디렉토리 삭제
rm -rf .claude/worktrees/orphaned-worktree
git worktree prune

성능 관련

응답이 너무 느려요

/compact로 대화 컨텍스트 압축
새 세션 시작 (/clear)
빠른 모드 활성화 (/fast)

토큰 소비가 많아요

구체적인 요청으로 불필요한 탐색 줄이기
CLAUDE.md에 프로젝트 정보를 미리 작성
큰 파일은 필요한 부분만 참조하도록 안내

Claude Code가 느릴 때 최적화 체크리스트

응답이 느리거나 시작이 오래 걸릴 때 순서대로 확인하세요.

[ ] 1. 컨텍스트 크기 확인: /cost로 현재 토큰 사용량 확인
[ ] 2. 대화 압축: /compact 실행
[ ] 3. 불필요한 MCP 서버 비활성화: /mcp에서 확인
[ ] 4. CLAUDE.md 크기 점검: 200줄 이내 권장
[ ] 5. 모델 변경: /fast 또는 /model haiku로 전환
[ ] 6. 새 세션 시작: /clear로 초기화
[ ] 7. --bare 모드: CI/CD라면 --bare로 자동 탐색 건너뛰기
[ ] 8. 설치 방식 확인: npm 기반 설치라면 Node.js 최신 LTS (22+) 사용 확인
[ ] 9. 네트워크: VPN/프록시 설정 확인

네트워크 / 프록시 문제

프록시 환경에서 연결 안 됨

기업 네트워크에서 프록시를 사용하는 경우:

# HTTP 프록시 설정
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# 프록시 인증이 필요한 경우
export HTTP_PROXY=http://user:password@proxy.company.com:8080

# Node.js의 SSL 인증서 오류 시
export NODE_TLS_REJECT_UNAUTHORIZED=0  # 주의: 보안 위험

경고

NODE_TLS_REJECT_UNAUTHORIZED=0은 보안 위험이 있으므로 테스트 환경에서만 사용하세요. 프로덕션에서는 올바른 CA 인증서를 설정해야 합니다.

방화벽에서 허용해야 할 도메인

api.anthropic.com        - Claude API
claude.ai                - 인증 및 웹 인터페이스
code.claude.com          - Claude Code 서비스
*.amazonaws.com          - 파일 업로드/다운로드

MCP 서버 관련

자세한 내용은 MCP 서버 가이드를 참고하세요.

MCP 서버가 "Failed" 상태

# 진단 실행
/doctor

# 상세 상태 확인
/mcp

확인 사항:

환경변수 확인: echo $GITHUB_TOKEN 등으로 값이 설정되었는지
패키지 설치 확인: npx -y @modelcontextprotocol/server-github가 실행되는지
API 키 유효성: 토큰이 만료되지 않았는지
네트워크: HTTP/SSE 서버의 URL에 접근 가능한지

MCP 서버 연결 안 될 때 디버깅 순서

단계별로 문제를 좁혀가는 디버깅 방법입니다.

# 1단계: MCP 서버 상태 확인
/mcp
# → "failed", "connecting", "ready" 중 어떤 상태인지 확인

# 2단계: 서버를 직접 실행하여 오류 메시지 확인
npx -y @modelcontextprotocol/server-github
# → 에러 메시지가 나오면 해당 문제 해결

# 3단계: 환경변수 확인
echo $GITHUB_TOKEN
# → 빈 값이면 설정 필요

# 4단계: .mcp.json 문법 검증
cat .mcp.json | python3 -m json.tool
# → JSON 파싱 에러가 나오면 수정

# 5단계: 디버그 모드로 Claude Code 재시작
claude --debug
# → MCP 서버 초기화 로그에서 원인 파악

MCP 도구가 호출되지 않아요

도구는 있지만 Claude가 사용하지 않는 경우, 권한이 설정되지 않았을 가능성이 높습니다:

/permissions
# mcp__서버이름__* 를 allowedTools에 추가

환경변수가 적용되지 않아요

올바른 문법 사용: ${VAR_NAME} ($VAR_NAME 아님)
.mcp.json이 유효한 JSON인지 확인 (후행 쉼표 없음)
변수 설정 후 Claude Code 재시작 필요

Windows에서 MCP 서버가 안 돼요

네이티브 Windows (WSL이 아닌)에서는 cmd /c 래퍼가 필요합니다:

{
  "mcpServers": {
    "server": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-name"]
    }
  }
}

정보

WSL 환경에서는 cmd /c 래퍼 없이 Linux와 동일하게 설정할 수 있습니다.

스킬 관련

자세한 내용은 스킬 가이드를 참고하세요.

스킬이 자동으로 호출되지 않아요

description에 사용자가 쓸 법한 키워드가 포함되어 있는지 확인
disable-model-invocation: true가 설정되어 있지 않은지 확인
/스킬이름으로 직접 호출하여 스킬 자체가 작동하는지 확인

스킬이 너무 자주 호출돼요

description을 더 구체적으로 수정
또는 disable-model-invocation: true로 수동 호출만 허용

커스텀 스킬이 나타나지 않아요

SKILL.md 파일이 올바른 위치에 있는지 확인:
- 개인 스킬: ~/.claude/skills/스킬이름/SKILL.md
- 프로젝트 스킬: .claude/skills/스킬이름/SKILL.md
YAML 프론트매터 형식이 올바른지 확인
user-invocable: false로 설정되어 있으면 직접 호출 불가

원격 제어 관련

"Remote Control requires a claude.ai subscription"

claude.ai 계정으로 인증되지 않은 경우입니다:

claude auth login
# → claude.ai 옵션 선택

API 키(ANTHROPIC_API_KEY)는 원격 제어를 지원하지 않습니다. 반드시 claude.ai 전체 범위 로그인(Full-scope Login)이 필요합니다.

원격 제어 연결이 끊겨요

터미널이 열려 있는지 확인 (터미널 닫으면 세션 종료)
네트워크 연결 확인 (10분 이상 끊기면 타임아웃)
claude remote-control --verbose로 상세 로그 확인

CLAUDE.md 관련

CLAUDE.md가 적용되지 않아요

파일 이름이 정확한지 확인: CLAUDE.md (대문자, 확장자 .md)
파일 위치가 프로젝트 루트인지 확인
Claude Code를 새로 시작해서 다시 확인
파일 크기가 너무 크지 않은지 확인 (200줄 이내 권장)

팀원마다 다른 설정을 쓰고 싶어요

팀 공유 규칙: CLAUDE.md (Git에 커밋)
개인 규칙: CLAUDE.local.md (.gitignore에 추가)

echo "CLAUDE.local.md" >> .gitignore

디스패치 관련

디스패치가 작동하지 않아요

플랜 확인: Pro 또는 Max 플랜이 필요합니다 (Team/Enterprise 미지원)
앱 페어링 확인: Claude 모바일 앱과 데스크탑 앱이 페어링되어 있는지 확인
Claude Desktop 실행 확인: 데스크탑 앱이 실행 중이어야 합니다

스케줄 관련

/loop이 동작하지 않아요

CLAUDE_CODE_DISABLE_CRON=1 환경변수가 설정되어 있지 않은지 확인
Claude Code 세션이 유휴 상태인지 확인 (응답 중에는 실행되지 않음)
세션당 최대 50개 작업 제한을 초과하지 않았는지 확인

문제 해결의 한계

Claude Code로 해결할 수 없는 문제

모든 문제가 Claude Code의 자가 진단으로 해결되는 것은 아닙니다. 다음 유형의 문제는 별도의 접근이 필요합니다.

문제 유형	이유	권장 대응
하드웨어 장애	디스크 오류, 메모리 불량 등은 소프트웨어로 진단 불가	시스템 진단 유틸리티 또는 하드웨어 점검
OS 수준 문제	커널 패닉, 드라이버 충돌, 시스템 파일 손상	OS 재설치 또는 시스템 복원
네트워크 인프라	ISP 장애, 방화벽 정책, DNS 문제	네트워크 관리자 또는 ISP에 문의
계정/결제 문제	구독 상태, 결제 실패, 계정 정지	Anthropic 고객 지원에 문의
서드파티 서비스 장애	GitHub, npm, Docker Registry 등의 다운타임	해당 서비스의 상태 페이지 확인

자가 진단 vs 공식 지원

상황	자가 진단 가능	공식 지원 필요
MCP 서버 연결 실패	✅ `claude doctor`	-
Node.js 버전 호환성 (npm 설치 한정)	✅ `node --version`	-
인증 토큰 만료	✅ `claude auth login`	-
API Rate Limit 초과	✅ 대기 후 재시도	-
지속적인 500 에러	-	✅ Anthropic 서버 문제 가능
계정 접근 불가	-	✅ 계정 복구 필요
알 수 없는 크래시 반복	✅ 로그 확인 후	✅ 해결 안 되면 이슈 등록

디버깅 도구의 한계점

claude doctor: 기본적인 환경 점검만 수행하며, 프로젝트별 복잡한 설정 오류나 MCP 서버 간 충돌은 감지하지 못합니다
--debug / --verbose: 로그 양이 방대하여 핵심 원인을 찾기 어려울 수 있고, 민감한 정보(토큰, 경로 등)가 로그에 포함될 수 있습니다
로그 파일: 로그 파일이 커지면 저장 공간을 차지하며, 오래된 로그는 자동 정리되지 않아 수동 관리가 필요합니다

활용 팁

문제 해결이 막히면 다음 순서로 접근하세요: (1) claude doctor로 기본 진단 (2) --debug로 상세 로그 확인 (3) GitHub Issues에서 유사 사례 검색 (4) 로그 파일을 첨부하여 이슈 등록. 디버그 로그를 공유할 때는 API 키나 토큰 등 민감 정보를 반드시 제거하세요.

연계 기능

문제 해결 과정에서 함께 참고하면 도움이 되는 페이지입니다.

📦설치 문제 해결

"npm ERR! permission denied"나 Node.js 버전 오류가 발생한다면 설치 가이드의 운영체제별 설치 방법을 확인하세요.

nvm을 통한 Node.js 설치
네이티브 설치 방법
OS별 권한 설정

설치 가이드 →

⚙️설정 오류 점검

CLAUDE.md가 적용되지 않거나 .mcp.json 파싱 오류가 발생한다면 설정 가이드에서 올바른 형식을 확인하세요.

CLAUDE.md 위치 및 크기 제한
.mcp.json 문법 검증
환경변수 설정 방법

설정 가이드 →

📟CLI 명령어 확인

claude doctor, --debug, --verbose 등 진단에 활용하는 모든 CLI 플래그와 슬래시 명령어의 전체 목록을 확인하세요.

/doctor, /mcp, /permissions
--debug, --verbose 플래그
로그 파일 위치별 경로

CLI 레퍼런스 →

도움 받기

문제가 해결되지 않으면:

claude doctor로 전체 진단 실행
claude --debug로 상세 로그 확인
Anthropic 공식 문서 확인
Claude Code GitHub Issues에서 유사 이슈 검색
로그 파일을 첨부하여 이슈 등록

문제 해결 흐름도​

진단 도구​

claude doctor​

디버그 모드​

로그 파일 위치​

Claude Desktop 공통​

Claude가 응답하지 않아요​

파일을 읽지 못해요​

응답이 잘려요​

Desktop 앱 빈 화면 / 렌더링 오류​

Desktop 앱 인증 오류​

Claude Code 관련​

설치 오류​

인증 오류​

파일 수정 관련​

Git 관련 문제​

성능 관련​

Claude Code가 느릴 때 최적화 체크리스트​

네트워크 / 프록시 문제​

프록시 환경에서 연결 안 됨​

방화벽에서 허용해야 할 도메인​

MCP 서버 관련​

MCP 서버가 "Failed" 상태​

MCP 서버 연결 안 될 때 디버깅 순서​

MCP 도구가 호출되지 않아요​

환경변수가 적용되지 않아요​

Windows에서 MCP 서버가 안 돼요​

스킬 관련​

스킬이 자동으로 호출되지 않아요​

스킬이 너무 자주 호출돼요​

커스텀 스킬이 나타나지 않아요​

원격 제어 관련​

"Remote Control requires a claude.ai subscription"​

원격 제어 연결이 끊겨요​

CLAUDE.md 관련​

CLAUDE.md가 적용되지 않아요​

팀원마다 다른 설정을 쓰고 싶어요​

디스패치 관련​

디스패치가 작동하지 않아요​

스케줄 관련​

/loop이 동작하지 않아요​

문제 해결의 한계​

Claude Code로 해결할 수 없는 문제​

자가 진단 vs 공식 지원​

디버깅 도구의 한계점​

연계 기능​

도움 받기​