Claude Code 가이드

Claude Code 가이드 #9 — 트러블슈팅 & 팁

Q: 응답 없이 Claude Code가 멈췄습니다.

Ctrl+C로 현재 실행을 중단하세요. 네트워크 문제일 수 있으니 status.anthropic.com 에서 서비스 상태를 확인하세요. 재시작 후 /resume 으로 이전 세션을 복원할 수 있습니다.

Q: 인증이 자꾸 만료됩니다. 왜 그런가요?

세션 토큰 유효 기간 때문입니다. claude auth status 로 상태를 확인하고, 만료 시 claude auth login 으로 재인증하세요. 기업 VPN이나 방화벽 환경에서는 더 자주 만료되는 경향이 있습니다.

Q: MCP 서버 연결이 실패합니다. 어디서 시작해야 하나요?

/mcp 명령어로 현재 MCP 서버 상태를 확인하세요. OAuth 인증이 만료된 경우가 많으니 재인증부터 시도하세요. .mcp.json 파일의 경로와 설정도 확인이 필요합니다.

Q: 파일 수정 권한 오류가 발생합니다.

/permissions 에서 현재 권한 모드를 확인하세요. Auto accept 모드로 전환하거나, 특정 도구에만 허용 권한을 설정할 수 있습니다. 기업 환경이라면 파일 시스템 접근 제한도 확인하세요.

Claude Code를 실무에서 쓰다 보면 설치부터 인증, 런타임, 설정까지 다양한 문제를 만납니다. 이 편에서는 단계별 트러블슈팅 가이드 로 가장 자주 발생하는 문제와 해결법을 체계적으로 정리합니다. 🎓 유데미 강의 추천 Claude Code 실전 강의 — AI 코딩을 지금 시작하세요 설치부터 자동화·에이전트 활용까지, 실무에서 바로 쓰는 Claude Code 활용법을 단계별로 배울 수 있습니다.

by Lee발행: 2026-03-21

Claude Code를 실무에서 쓰다 보면 설치부터 인증, 런타임, 설정까지 다양한 문제를 만납니다. 이 편에서는 단계별 트러블슈팅 가이드로 가장 자주 발생하는 문제와 해결법을 체계적으로 정리합니다. 2026년 3월 기준 최신 정보입니다.

🎓 유데미 강의 추천

Claude Code 실전 강의 — AI 코딩을 지금 시작하세요

설치부터 자동화·에이전트 활용까지, 실무에서 바로 쓰는 Claude Code 활용법을 단계별로 배울 수 있습니다.

강의 보러가기 →

설치 단계 트러블슈팅

설치에서 가장 흔한 문제와 해결법입니다.

command not found: claude — PATH가 설정되지 않았습니다. native installer를 사용했다면 터미널을 재시작하세요. npm 설치라면 npm bin -g의 경로가 PATH에 포함되어 있는지 확인합니다.
npm install 권한 에러 — 글로벌 npm 디렉토리 권한 문제. sudo chown -R $(whoami) ~/.npm으로 해결하거나, native installer 사용을 권장합니다.
curl 설치 중 끊김 — 방화벽이 storage.googleapis.com을 차단할 수 있습니다. 네트워크 설정을 확인하세요.
Illegal instruction (CPU) — CPU 아키텍처와 바이너리가 불일치합니다. uname -m으로 확인 후 맞는 버전을 다운로드하세요.
glibc/musl 오류 (Linux) — Alpine 등 musl 기반 배포판에서 glibc 바이너리 실행 시 발생. ldd /bin/ls로 시스템 확인 후 맞는 바이너리를 설치하세요.

설치 단계 트러블슈팅 — CLI 실행 화면과 출력 결과 — Claude Code 가이드 #9 — 트러블슈팅 & 팁 — CLI 실행 화면과 출력 결과 (출처: 공식 문서 및 벤치마크 데이터 기반)

설치 문제 진단 명령어
# PATH 확인
which claude || echo "claude not found in PATH"
echo $PATH

# Node.js 버전 확인 (18+ 필요)
node --version

# npm 글로벌 경로 확인
npm bin -g

# CPU 아키텍처 확인
uname -m

# Linux: glibc vs musl 확인
ldd /bin/ls 2>&1 | head -1

💡 팁: 2026년 기준 native installer가 권장 설치 방법입니다. 자동 업데이트가 포함되어 있어 버전 관리가 편하고, PATH 설정도 자동으로 처리됩니다.

인증 단계 트러블슈팅

로그인과 API 키 관련 문제입니다.

로그인 실패 — Claude Code는 Pro/Max/Teams/Enterprise 구독이 필요합니다. 무료 플랜에서는 사용할 수 없습니다.
API Key 에러 — API 키는 sk-ant- 접두사로 시작하며 108자입니다. Console(api.anthropic.com)에서 발급받은 키를 사용하세요.
토큰 갱신 실패 — 캐시된 인증이 만료된 경우입니다. 로그아웃 후 재로그인하세요.
Console vs 구독 혼동 — Console은 API 크레딧(사용량 기반), 구독은 claude.ai 월정액입니다. Claude Code는 두 방식 모두 지원합니다.

인증 문제 해결
# 인증 상태 확인
claude auth status

# 로그아웃 후 재로그인
claude auth logout
claude auth login

# API 키로 직접 인증 (Console 사용자)
export ANTHROPIC_API_KEY=sk-ant-...

⚠️ 막히는 케이스: 회사 VPN/프록시 환경에서 인증이 실패할 수 있습니다. HTTPS_PROXY 환경 변수를 설정하거나, IT 팀에 api.anthropic.com 도메인 허용을 요청하세요.

런타임 에러 트러블슈팅

실행 중 발생하는 문제입니다.

컨텍스트 초과 (200K 토큰) — /compact로 대화 압축, 불필요한 파일 제외, 세션 분리
API 타임아웃 — 서버 부하 시 발생. 간단한 요청으로 연결 테스트 후, 잠시 후 재시도
500 에러 반복 — Anthropic 서비스 장애. status.anthropic.com에서 상태 확인
느린 응답 — 모델 변경(Haiku로 전환), 요청 분할, /compact로 컨텍스트 줄이기
sandbox 에러 (Linux) — bubblewrap과 socat이 필요합니다
CJK 정렬 깨짐 — 한글/중국어/일본어 와이드 문자 레이아웃 문제. v2.1.69 이상으로 업데이트

인증 단계 트러블슈팅 — 설정 구조와 워크플로우 다이어그램 — Claude Code 가이드 #9 — 트러블슈팅 & 팁 — 설정 구조와 워크플로우 다이어그램 (출처: 공식 문서 및 벤치마크 데이터 기반)

런타임 문제 진단
# 컨텍스트 사용량 확인
/context

# 컨텍스트 압축
/compact

# 서비스 상태 확인
curl -s https://status.anthropic.com/api/v2/status.json | python3 -c "import sys,json; print(json.load(sys.stdin)['status']['description'])"

# Linux: sandbox 의존성 설치
sudo apt install bubblewrap socat

# 버전 확인 및 업데이트
claude --version
npm update -g @anthropic-ai/claude-code

⚠️ 막히는 케이스: "컨텍스트 초과"가 반복된다면 작업 방식을 재검토하세요. "전체 프로젝트를 봐줘" 대신 구체적 파일을 지정하고, 주제별로 세션을 분리하면 토큰 사용이 크게 줄어듭니다.

토큰 최적화 & 비용 관리

Claude Code 비용을 효과적으로 관리하는 전략입니다.

effort 레벨 조절: 간단한 작업은 low effort로 실행하여 비용 절감
모델 선택: 복잡한 작업만 Opus, 일반 작업은 Sonnet, 단순 작업은 Haiku
project-state.md 활용: 프로젝트 상태를 압축 문서로 관리하면 80~95% 토큰 절약
세션 분리: 주제별로 세션을 나누어 컨텍스트 오염 방지
/compact 주기적 실행: 장시간 세션에서는 30분마다 한 번씩 권장
status line 모니터링: 실시간 토큰 사용량을 확인하며 작업

⚠️ 막히는 케이스: AGENTS.md를 자동 생성하면 오히려 비용이 약 20% 증가한다는 보고가 있습니다. 에이전트 파일은 실제 필요한 역할만 수동으로 정의하세요.

설정 & 확장 트러블슈팅

CLAUDE.md, MCP, Hooks 등 설정 관련 문제입니다.

CLAUDE.md가 무시됨 — 파일이 500줄을 넘으면 규칙이 묻힙니다. 핵심 규칙에 IMPORTANT: 접두어를 붙이고, 길이를 500줄 이하로 유지하세요.
MCP 서버 연결 실패 — OAuth 인증이 만료된 경우가 많습니다. /mcp로 상태 확인 후 재인증하세요. .mcp.json 파일의 보안도 점검하세요.
Hook이 실행되지 않음 — settings.json의 스코프 우선순위를 확인하세요: Managed > CLI > Local > Project > User
파일 수정이 안 됨 — /permissions에서 권한 모드를 확인하세요. Auto accept로 전환하거나, 특정 도구만 허용할 수 있습니다.
Watchman 충돌 — Facebook Watchman이 설치된 환경에서 충돌할 수 있습니다. Watchman을 비활성화하거나 제거하세요.