Claude Code 오류 코드 문제 해결

흔한 원인: 설치 디렉터리가 PATH에 없거나, 현재 셸이 설정을 다시 불러오지 않았습니다.

해결 방법: 새 터미널을 열거나, Claude Code 설치 디렉터리를 PATH에 추가한 뒤 셸 설정을 다시 불러오세요.

export PATH="$PATH:$HOME/.local/bin"
source ~/.zshrc

흔한 원인: Node 버전이 공식 요구 사항보다 낮거나, WSL이 Windows 쪽 Node를 호출하고 있습니다.

해결 방법: Node를 업그레이드하거나 공식 네이티브 설치 프로그램을 사용하세요. WSL에서는 which node / which npm으로 경로가 Linux 환경의 것인지 확인하세요.

node -v
which node
which npm

흔한 원인: 전역 npm 디렉터리의 소유자가 root이거나, 이전에 sudo로 설치하면서 권한이 꼬였습니다.

해결 방법: sudo로 Claude Code를 설치하지 마세요. npm prefix를 사용자 디렉터리로 바꾸거나 네이티브 설치 프로그램을 사용하세요.

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

흔한 원인: 브라우저의 OAuth 콜백이 로컬 CLI까지 도달하지 못합니다. 원격 SSH, devcontainer, 엄격한 방화벽, localhost 콜백 차단 환경에서 흔히 발생합니다.

해결 방법: 브라우저와 CLI가 같은 컴퓨터에서 서로 통신할 수 있는지 확인하세요. 필요하면 로그아웃하고 Claude Code를 다시 시작한 뒤 인증을 다시 완료하세요.

/logout
# 关闭 Claude Code 后重新运行
claude

흔한 원인: 기업 프록시나 보안 게이트웨이가 Node가 기본적으로 신뢰하지 않는 자체 서명 CA를 주입하고 있습니다.

해결 방법: IT 부서에 기업 CA 번들을 요청하고 NODE_EXTRA_CA_CERTS로 지정하세요.

export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

흔한 원인: 프록시 변수가 잘못 설정되었거나, 프록시 프로토콜이 지원되지 않거나, NO_PROXY가 대상 도메인을 덮어쓰거나, 기업 방화벽이 접근을 차단하고 있습니다.

해결 방법: Claude Code는 표준 HTTP/HTTPS 프록시 환경 변수를 사용하며, 공식 문서에 따르면 SOCKS 프록시는 지원하지 않습니다. 먼저 HTTPS_PROXY로 다시 테스트하세요.

export HTTPS_PROXY=http://proxy.example.com:8080
echo $HTTPS_PROXY
echo $NO_PROXY

흔한 원인: 조직에서 Claude Code를 활성화하지 않았거나, 기업 허용 목록(allowlist)에 현재 출구가 없거나, 계정 / 지역 / 정책 제한에 걸렸거나, 프록시가 거부되고 있습니다.

해결 방법: 개인 계정은 먼저 지원 지역과 계정 상태를 확인하세요. 기업 계정은 관리자에게 Claude Code 권한, SSO, IP 허용 목록, 방화벽 규칙을 확인하도록 요청하세요.

흔한 원인: 요청이 너무 잦거나, 동시 실행 수가 너무 많거나, 계정 요금제 또는 조직의 속도 제한에 도달했습니다.

해결 방법: 외부 동시 실행 수를 줄이고, 재시도 루프를 멈추고, 제한이 초기화될 때까지 기다리세요. 여러 워커로 Claude Code를 감싸 강제로 속도를 높이지 마세요.

흔한 원인: API 키가 다른 셸에서 설정되었거나, Console 키가 OAuth 세션과 충돌하거나, 조직에서 SSO 로그인을 요구합니다.

해결 방법: 현재 셸에 ANTHROPIC_API_KEY가 설정되어 있는지 확인하세요. 기업 계정은 관리자가 요구하는 Console/SSO 로그인 절차를 따르세요.

echo $ANTHROPIC_API_KEY