Claude Code 배포 오류: 자주 발생하는 문제와 10분 수정 가이드

# 아래 세 가지 중 하나가 표시되면 API 키 문제입니다
Error: ANTHROPIC_API_KEY is not set
AuthenticationError: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}
Error: Your API key is invalid.

# 1. 현재 셸에 키가 설정되어 있는지 확인
echo $ANTHROPIC_API_KEY

# 2. 임시 설정 (현재 세션에만 적용)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxx"

# 3. 설정 파일에 영구 저장 (zsh: ~/.zshrc, bash: ~/.bashrc)
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

# 4. 형식 확인: sk-ant-api로 시작해야 함
claude --version

SyntaxError: Unexpected token '?'
engine "node" is incompatible with this module. Expected version ">=18". Got "16.x.x"
Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.

# 1. 현재 Node 버전 확인
node -v

# 2a. nvm으로 버전 전환 (권장)
nvm install 22
nvm use 22
nvm alias default 22

# 2b. macOS Homebrew 사용 시
brew install node@22
brew link --overwrite node@22

# 3. Node 업그레이드 후 Claude Code 재설치
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

npm ERR! Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
Error: Permission denied (tool: bash)
EPERM: operation not permitted, unlink

# 글로벌 패키지 디렉토리를 홈 디렉토리로 변경 (sudo 불필요)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

# 도구를 명시적으로 허용하여 실행
claude --allowedTools "bash,read,write,edit"

# 또는 CLAUDE.md에서 설정 (프로젝트 수준 영구 설정)
# CI 서버에서는 --dangerously-skip-permissions로 대화형 확인 건너뛰기
# 주의: 신뢰할 수 있는 환경에서만 사용
claude --dangerously-skip-permissions -p "your prompt here"

FetchError: request to https://api.anthropic.com/v1/messages failed, reason: connect ETIMEDOUT
Error: Network request failed: ENOTFOUND api.anthropic.com
ProxyError: tunneling socket could not be established, cause=connect ECONNREFUSED

# 1. 직접 연결 테스트
curl -v https://api.anthropic.com/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
  -d '{"model":"claude-opus-4-5","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# 2. HTTP 프록시 설정
export HTTPS_PROXY="http://proxy.company.com:8080"
export HTTP_PROXY="http://proxy.company.com:8080"
export NO_PROXY="localhost,127.0.0.1"

# 3. 인증이 필요한 프록시
export HTTPS_PROXY="http://username:password@proxy.company.com:8080"

# 4. 커스텀 베이스 URL (기업 내부 게이트웨이)
export ANTHROPIC_BASE_URL="https://your-internal-gateway.company.com"

FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed - JavaScript heap out of memory
Killed (signal 9)   ← Linux OOM Killer에 의한 강제 종료
RangeError: Maximum call stack size exceeded

# 1. Node.js 힙 메모리 한도 증가 (MB 단위)
export NODE_OPTIONS="--max-old-space-size=4096"
claude

# 2. 현재 메모리 사용량 확인
free -h          # Linux
vm_stat          # macOS

# 3. 대규모 코드베이스용 .claudeignore 생성
# node_modules/
# dist/
# .next/
# *.lock

# 4. 긴 대화에서 /clear로 컨텍스트 초기화