Claude Code가 안 될 때 — 설치·인증·연결 문제 해결 가이드

Claude Code가 설치되지 않거나 로그인이 안 될 때, 원인은 대부분 정해진 몇 가지 범주에 들어갑니다. 이 글은 Claude 공식 문제 해결 문서에서 확인된 항목만 추려 정리합니다. (명령·요건은 변동될 수 있으니 공식 문서에서 최신 정보를 확인하세요.)

먼저 확인할 기본

• Node 버전: 2026년 9월 기준 공식 setup 문서의 시스템 요구사항에는 Node.js가 없습니다 — 네이티브 설치(권장)는 Node.js 없이 동작합니다. npm install -g로 설치하는 경우에만 v2.1.198부터 Node.js 22 이상을 요구하며, 더 낮은 버전에서는 설치 시 EBADENGINE 경고가 뜨지만 설치·실행 자체는 됩니다(실행 파일이 네이티브 바이너리라 Node를 쓰지 않음). node -v로 확인하세요.
• 서비스 상태: 광범위한 장애가 의심되면 status.claude.com에서 상태를 확인하세요.
• 인터넷 연결: Claude Code는 Anthropic 서버에 접속해야 동작합니다.

설치 문제

• "command not found" / claude 명령이 안 잡힘: 설치가 PATH에 claude를 추가했지만 현재 셸이 아직 반영하지 못한 경우입니다. 새 터미널을 열거나 source ~/.zshrc(또는 ~/.bashrc)를 실행하세요. Windows는 PowerShell을 닫았다 다시 엽니다.
• 권한 오류: 보통 sudo로 설치했거나 글로벌 npm 디렉토리가 root 소유일 때 발생합니다. sudo를 쓰지 마세요. 대신 native installer를 쓰거나, npm prefix를 ~/.npm-global로 바꾸고 그 bin 경로를 PATH에 추가하세요.
• Node 버전이 낮음: nvm install --lts로 최신 LTS를 설치하거나, 자체 런타임을 번들하는 native installer를 쓰면 이 문제를 피할 수 있습니다.
• 다운로드가 막힘: 회사 네트워크가 다운로드 호스트를 차단했을 수 있습니다. 프록시를 먼저 설정(export HTTPS_PROXY=...)한 뒤 재설치하거나, IT팀에 오프라인 패키지를 요청하세요.
• 회사 인증서: 사내에서 자체 인증서를 주입하면 Node가 인증서를 거부할 수 있습니다. export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem로 사내 CA 번들을 가리키게 하고, 셸 프로필에 추가해 유지하세요.
• WSL에서 Windows Node가 실행됨: WSL에서 claude가 Linux Node 대신 Windows Node를 잡는 경우가 있습니다. Windows PATH가 WSL로 새어 들어와 nvm을 덮어쓴 것으로, ~/.bashrc에 Linux node를 PATH 앞쪽에 추가하세요: export PATH="$HOME/.nvm/versions/node/$(nvm current)/bin:$PATH"

# Node 버전 확인 (npm 설치일 때만, 22 이상)
node -v

# sudo 없이 설치 (권한 오류 회피). 둘 중 하나:
curl -fsSL https://claude.ai/install.sh | bash      # native installer
npm config set prefix ~/.npm-global                 # 또는 npm prefix 수정

# 회사 네트워크: 프록시 / 사내 인증서
export HTTPS_PROXY=http://proxy.example.com:port
export NODE_EXTRA_CA_CERTS=/path/to/company-ca.pem

# API 키가 인식되는지 확인
echo $ANTHROPIC_API_KEY

인증·로그인 문제

• 브라우저가 자동으로 안 열림: 로그인 중 브라우저가 안 열리면 c를 눌러 OAuth URL을 클립보드에 복사한 뒤, 아무 브라우저에서 열어 로그인하세요.
• localhost 콜백이 막힘: 원격 SSH·devcontainer·엄격한 방화벽 환경에서 흔합니다. 자동 흐름 대신 수동 흐름을 쓰세요 — 터미널에 출력된 URL을 복사해 브라우저에서 로그인하고, 반환된 코드를 다시 터미널에 붙여넣습니다. 헤드리스 환경(CI/CD·Docker)이면 ANTHROPIC_API_KEY를 설정해 OAuth를 우회할 수 있습니다.
• API 키가 인식되지 않음: 공식 문서는 세 가지 흔한 원인을 듭니다. ① 키가 다른 셸에서 export되었을 수 있으니 echo $ANTHROPIC_API_KEY로 현재 셸에서 보이는지 확인합니다. ② 이전에 /login으로 로그인한 OAuth 세션이 우선권을 가지는 경우 — 먼저 /logout을 실행하세요. ③ 키가 Console 키인데 조직이 SSO 로그인을 요구하는 경우입니다.
• Bedrock·Vertex 자격증명 오류: Claude Code는 표준 제공자 SDK를 쓰므로, 일반 AWS/GCP CLI 도구와 같은 방식으로 고칩니다. Bedrock은 aws sts get-caller-identity가 동작하는지, AWS_REGION이 해당 모델을 쓸 수 있는 리전인지 확인합니다. Vertex는 gcloud auth application-default login을 실행했는지, GOOGLE_CLOUD_PROJECT가 설정됐는지 확인하세요.
• 그래도 안 되면 깨끗한 재인증: 로그인이 실패하고 원인이 불분명하면, 재인증으로 대부분 해결됩니다. claude를 다시 실행해 인증 과정을 처음부터 다시 진행하세요.
• IDE에서만 안 됨: 터미널에선 되는데 VS Code·JetBrains 확장에서 안 되면, IDE 프로세스가 셸 환경변수를 상속하지 못한 경우입니다. IDE 자체 설정에 환경변수를 지정하거나, 변수가 이미 export된 터미널에서 IDE를 실행하세요.
• 설치는 됐는데 403 / "model not available": 계정은 있으나 Claude Code가 요청하는 모델 접근 권한이 없는 경우입니다. Enterprise는 조직 관리자 설정에서 좌석이 활성인지 확인하고, Bedrock·Vertex는 해당 리전·프로젝트에서 그 Claude 모델이 활성화됐는지 확인합니다. 빠른 우회로는 /model을 실행해 접근 가능한 모델을 고르는 것입니다.

성능·안정성

공식 문제 해결 문서는 높은 CPU/메모리 사용과 명령이 멈추거나 얼어붙는(hang/freeze) 경우도 별도 항목으로 다룹니다. 일반적인 예방책으로는 Node를 최신으로 유지하고, 안정적인 인터넷을 쓰고, 막혔을 때 세션을 재시작하는 것이 권장됩니다. 구체적인 진단·해법은 환경에 따라 다르므로 공식 문서의 해당 섹션을 참고하세요.

정리

핵심 점검 순서: ① 설치 방식(네이티브면 Node 불필요, npm이면 Node 22 이상)·서비스 상태·인터넷부터 확인, ② 설치 문제는 PATH 새로고침 → sudo 금지 → native installer, ③ 인증 문제는 수동 OAuth 흐름 또는 API 키, 안 되면 재인증, ④ 성능 문제는 Node 최신화·세션 재시작. 더 자세한 항목은 Claude Code 공식 문제 해결 문서를 참고하세요.

자주 묻는 질문

Claude Code 설치가 안 됩니다.

설치 후 명령을 못 찾으면 PATH를 새로고침하세요. sudo로 설치하는 것은 권장되지 않으며, 막히면 native installer를 사용하는 것이 공식 권장 순서입니다. (네이티브 설치는 Node.js 불필요)

로그인(인증)이 안 됩니다.

수동 OAuth 흐름을 쓰거나 API 키로 인증하세요. 그래도 안 되면 재인증(로그아웃 후 다시 로그인)을 시도합니다.

Node는 어떤 버전이 필요한가요?

2026년 9월 기준 공식 문서에서 Node.js는 시스템 요구사항이 아닙니다. 네이티브 설치는 Node.js 없이 동작하고, npm 설치 경로만 v2.1.198부터 Node.js 22 이상을 요구합니다(낮은 버전은 경고만 뜨고 설치·실행은 됨). 예전 문서의 "Node 18 이상" 기준은 더 이상 유효하지 않습니다.

진단 도구가 있나요?

claude doctor를 실행하면 진단 리포트가 출력됩니다. 이 리포트를 지원 티켓에 첨부하면 원인 파악이 빨라집니다.

Claude Code가 느리거나 멈춥니다.

공식 문서는 높은 CPU/메모리 사용과 멈춤(hang/freeze)을 별도 항목으로 다룹니다. Node를 최신으로 유지하고, 안정적인 인터넷을 쓰고, 막혔을 때 세션을 재시작하는 것이 일반적 예방책입니다.

더 알아보기: Claude Code 권한 설정으로 allow·deny 규칙과 권한 모드를 통제할 수 있습니다.

이 글의 해법은 Claude 공식 문서(support.claude.com, code.claude.com)에서 확인한 항목만 담았습니다. 환경(OS·네트워크·IDE)에 따라 증상과 해법이 다를 수 있으므로, 해결되지 않으면 공식 문서와 지원 채널을 이용하세요. (공식 출처: support.claude.com, code.claude.com)

처음이라면: 에러 메시지 읽는 법 (입문)

지금 막힌 증상부터 찾으세요 — 5분 안에 해결되는 체크리스트

아래 표에서 지금 보이는 증상을 찾아 해당 섹션으로 바로 이동하세요. 사전지식 없어도 순서대로 따라 하면 대부분 해결됩니다.

① command not found — PATH 확인 2단계

1. 터미널에서 npm 전역 설치 경로를 확인합니다.
   

   npm root -g

   출력 예: /usr/local/lib/node_modules → 여기서 한 단계 위 /usr/local/bin이 PATH에 있어야 합니다.
2. PATH에 해당 경로가 없으면 쉘 설정 파일(~/.zshrc 또는 ~/.bashrc)에 아래 줄을 추가하고 터미널을 재시작합니다.
   

   export PATH="$(npm bin -g):$PATH"

   성공 확인: claude --version 입력 시 버전 번호가 출력되면 정상입니다.

② 권한 오류(EACCES) — sudo 없이 해결하기

sudo로 npm install을 실행하지 마세요. 대신 nvm(Node Version Manager)으로 Node를 다시 설치하면 권한 문제 없이 전역 패키지를 사용할 수 있습니다. nvm 설치 방법은 nvm 공식 저장소를 참고하세요.

③ Node 버전 — npm 설치라면 22 이상인지 확인

node --version

npm으로 설치했다면 v22.x.x 이상이 출력되어야 합니다(네이티브 설치는 Node.js 무관). 낮으면 nvm으로 버전을 올리거나 Node.js 공식 사이트에서 LTS 버전을 새로 설치하세요. 최소 버전 요건은 변동될 수 있으니 공식 문서에서 확인하세요.

④ 로그인 실패 — OAuth 브라우저 콜백 문제

로그인 명령 실행 후 브라우저가 열리지 않거나 인증 후 터미널로 돌아오지 않을 때:

• 기본 브라우저가 설정되어 있는지 확인하세요.
• 사내 방화벽·프록시 환경이라면 IT 담당자에게 localhost 콜백 포트 허용을 요청하세요 (정확한 포트는 실행 시 터미널 출력 메시지에서 확인).
• 그래도 안 되면 API 키 방식으로 대체할 수 있습니다(⑤ 참고).

⑤ API 키 미인식 — 환경변수 확인

API 키를 직접 사용할 경우, 환경변수 이름을 화면의 오류 메시지 또는 공식 문서에서 정확히 확인한 뒤 쉘 설정 파일에 추가하세요. 환경변수명은 업데이트로 바뀔 수 있어 단정 표기를 피합니다.

설치나 로그인 단계에서 막혔다면 별도로 정리한 Claude Code 설치·로그인 오류 해결 가이드를 먼저 확인해 보세요.

관련 글

• Claude Code가 느리거나 멈출 때 — 성능·안정성 문제 해결과 /doctor 진단
• Claude Code 에러 메시지 읽는 법 — 초보자용 쉬운 안내
• Claude Code 설치·로그인 오류 완전 해결 가이드
• Claude Code 스킬 인식 오류 해결 가이드 — 스킬이 작동하지 않을 때 점검할 것들
• Claude Code 설치 가이드: native vs npm, Windows까지