토큰 최적화, 에러 대응, 비용 관리 방법을 총정리한다. rate limit 우회, 컨텍스트 초과 대응, 느린 응답 해결, API 키 문제까지 자주 발생하는 이슈별 해결책을 정리한다.
Claude Code를 실무에서 쓰다 보면 설치부터 인증, 런타임, 설정까지 다양한 문제를 만납니다. 이 편에서는 단계별 트러블슈팅 가이드로 가장 자주 발생하는 문제와 해결법을 체계적으로 정리합니다. 2026년 3월 기준 최신 정보입니다.
설치 단계 트러블슈팅
설치에서 가장 흔한 문제와 해결법입니다.
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로 시스템 확인 후 맞는 바이너리를 설치하세요.
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을 비활성화하거나 제거하세요.
Claude Code 가이드 #9 — 트러블슈팅 & 팁 — 에러 해결 프로세스 흐름도 (출처: 공식 문서 및 벤치마크 데이터 기반)
💡 팁: 문제가 해결되지 않으면 GitHub Issues에서 유사 사례를 검색하세요. 버그 리포트 시에는 claude --version, OS 버전, 에러 메시지를 포함하면 빠른 답변을 받을 수 있습니다.
진단 플로우차트
문제 발생 시 다음 순서로 진단하세요.
버전 확인:claude --version → 최신 버전인지 확인
인증 확인:claude auth status → 로그인 상태 확인
네트워크 확인:curl -s https://api.anthropic.com → API 접근 가능 여부
서비스 상태:status.anthropic.com → 장애 여부 확인
컨텍스트:/context → 토큰 사용량 확인
권한:/permissions → 도구 실행 권한 확인
로그: 에러 메시지 전문으로 GitHub Issues 검색
다음 (마지막) 편에서는 최신 업데이트 추적 방법을 다룹니다. Changelog 모니터링부터 신기능 활용까지 정리합니다.
