Claude Code 설치·로그인 문제 해결

설치 실패나 로그인이 안 될 때 원인별 해결법을 정리한 페이지입니다. Claude Code가 정상 동작한 뒤의 런타임 문제는 Troubleshooting, 설정이 반영되지 않는 등 설정 문제는 Debug your configuration을 보세요. 에러 메시지·증상을 아래 표에 매칭해서 해결책으로 이동하면 됩니다.

출처: 공식문서

본문

주요 에러 한눈에 보기

증상	해결책
`command not found: claude` / `'claude' is not recognized`	PATH 수정
`curl: (22) ... 403`	설치 스크립트가 HTML 반환
`TLS connect error` / `SSL/TLS secure channel`	CA 인증서 갱신
Linux `Killed` / exit code 137	메모리 확보 또는 swap 추가
`OAuth error` / `403 Forbidden`	인증 수정

어떤 항목에 해당하지 않으면 아래 진단 체크를 순서대로 진행하세요. 터미널을 아예 건너뛰고 싶다면 Claude Code Desktop 앱을 사용해도 됩니다.

진단 체크

네트워크 연결 확인

인스톨러는 downloads.claude.ai에서 내려받습니다.

# macOS/Linux
curl -sI https://downloads.claude.ai/claude-code-releases/latest
# Windows PowerShell (curl 대신 curl.exe 명시)
curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

첫 줄이 200이면 서버에 도달한 것입니다. 403은 프록시·네트워크 필터 차단이나 지역 미지원, 5xx는 일시적 서비스 문제를 뜻합니다. 출력이 없거나 타임아웃이면 방화벽·프록시가 단절한 것입니다. 회사 프록시 뒤라면 설치 전에 HTTPS_PROXY·HTTP_PROXY를 프록시 주소로 설정하세요:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

PATH 확인

설치는 macOS/Linux의 ~/.local/bin/claude, Windows의 %USERPROFILE%\.local\bin\claude.exe에 둡니다. PATH에 없으면 추가하세요.

# macOS/Linux (zsh 기본)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Windows PowerShell — User PATH에 추가
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

검증은 claude --version으로 합니다. 참고로 VS Code 확장은 CLI를 이 경로에 두지 않고 확장 디렉터리에 개인 복사본을 묶습니다 — 확장만 설치했다면 ~/.local/bin/claude는 없습니다. 독립 설치로 진행하세요.

충돌 설치 확인

여러 설치가 버전 불일치를 낳을 수 있습니다. which -a claude(Windows는 where.exe claude)로 PATH의 바이너리를 나열하고, ~/.local/bin/claude(네이티브), ~/.claude/local/(구식 npm), npm -g ls @anthropic-ai/claude-code 세 위치를 확인하세요. 네이티브 설치가 권장됩니다. 제거:

npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local
brew uninstall --cask claude-code   # macOS Homebrew
winget uninstall Anthropic.ClaudeCode   # Windows WinGet

디렉터리 권한 확인

macOS/Linux 인스톨러는 ~/.local/bin/, ~/.claude/에 쓰기 권한이 필요합니다.

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

바이너리 동작 확인

claude --version이 버전을 출력하는데 시작 시 크래시·행이 걸리면: ls -la "$(command -v claude)", Linux에선 ldd "$(command -v claude)" | grep "not found"로 누락 공유라이브러리를 확인하세요.

흔한 설치 문제

설치 스크립트가 HTML을 반환할 때

bash: line 1: syntax error near unexpected token '<' 또는 PowerShell의 iex 파싱 오류가 나면 설치 URL이 스크립트 대신 HTML 페이지(또는 403)를 반환한 것입니다. "App unavailable in region"이면 해당 국가 미지원(지원 국가). 해결책:

# macOS — Homebrew
brew install --cask claude-code
# Windows — WinGet
winget install Anthropic.ClaudeCode

claude --version이 2.1.211 (Claude Code) 같은 버전을 출력하는지 확인하고, 새 터미널 창을 열어 재시도하세요(기존 세션은 이전 PATH 유지). 문제는 일시적인 경우가 많아 몇 분 후 원래 명령으로 재시도해도 됩니다.

`command not found: claude` after installation

설치 후에도 claude가 안 되는 것은 설치 디렉터리가 PATH에 없어서입니다. 플랫폼별 에러: macOS zsh: command not found: claude, Linux bash: claude: command not found, PowerShell claude : The term 'claude' is not recognized as the name of a cmdlet. 위 PATH 확인을 따르세요.

Homebrew cask을 못 찾거나 오래됐을 때

Error: Cask 'claude-code' is unavailable: No Cask with this name exists는 로컬 cask 인덱스가 오래돼서입니다.

brew update
brew install --cask claude-code

claude-code cask는 안정 채널을 따라 최신 릴리스보다 약 1주 늦습니다. 최신 버전은 brew install --cask claude-code@latest를 쓰세요.

TLS·SSL 연결 오류

curl: (35) TLS connect error, schannel: next InitializeSecurityContext failed, PowerShell의 Could not establish trust relationship for the SSL/TLS secure channel는 TLS 핸드셰이크 실패입니다.

시스템 CA 인증서 갱신: Ubuntu/Debian sudo apt-get update && sudo apt-get install ca-certificates. macOS는 Keychain 신뢰 저장소 사용.

Windows는 설치 전 TLS 1.2 활성화:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

TLS 검사하는 회사 프록시면 unable to get local issuer certificate, SELF_SIGNED_CERT_IN_CHAIN 발생. 설치 시 curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash로 프록시 CA를 신뢰. 설치된 Claude Code 자체에는 NODE_EXTRA_CA_CERTS 설정.
Windows에서 폐기(reovocation) 확인이 차단되면 CRYPT_E_NO_REVOCATION_CHECK (0x80092012)·CRYPT_E_REVOCATION_OFFLINE (0x80092013). curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd로 재시도하거나, 붕괴 검증을 아예 건너뛰는 PowerShell 설치기(irm https://claude.ai/install.ps1 | iex)나 winget install Anthropic.ClaudeCode 사용.

Windows에서 잘못된 설치 명령

irm is not recognized: CMD에서 PowerShell 설치기를 써야 합니다. CMD라면 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd 사용.
&& is not valid: PowerShell인데 CMD 명령을 실행 — irm https://claude.ai/install.ps1 | iex.
A parameter cannot be found ... 'fsSL': PowerShell의 curl은 Invoke-WebRequest 별칭 — PowerShell 설치기 사용.
bash not recognized: Windows에서 macOS/Linux 설치기 실행 — PowerShell 설치기 사용.
명령이 설치 대신 스크립트 텍스트를 출력: 파이프 실행부가 빠진 것. irm https://claude.ai/install.ps1 | iex로 파이프.

어떤 설치기든 새 터미널에서 claude --version으로 확인하세요.

`running scripts is disabled on this system`

Windows npm 설치 시 PowerShell 실행 정책이 npm이 만든 .ps1 런처를 차단해서 SecurityError: (:) [], PSSecurityException가 납니다. 해결책:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

또는 npm.cmd/claude.cmd 런처 호출, 또는 .ps1 대신 바이너리를 설치하는 PowerShell 설치기 사용.

Windows 설치 중 `The process cannot access the file`

%USERPROFILE%\.claude\downloads에 쓰지 못하면 이전 설치 시도가 돌고 있거나 백신이 부분 다운로드 파일을 검사 중인 것. 다른 설치 창을 닫고 백신이 풀기를 기다린 뒤 디렉터리를 지우고 재설치:

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

저용량 메모리 Linux에서 설치가 종료됨 (Killed)

Killed 메시지와 exit code 137은 OOM killer가 설치를 종료한 것입니다. 설치에 약 512MB, 실행에는 그 이상이 필요합니다(시스템 요구사항). 해결책:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

다른 프로세스를 닫거나 가능하면 더 큰 인스턴스(최소 4GB RAM)를 쓰세요.

Docker에서 설치가 멈출 때

루트로 /에서 설치하면 파일시스템 전체를 스캔해 메모리를 과다 사용합니다.

WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash

Docker Desktop은 Settings > Resources에서 메모리 상향 후 재빌드.

`Raw mode is not supported`

조직 서버 관리 설정이 보안 승인 대화상자를 요구할 때, v2.1.246 미만 버전은 claude install 중 대화상자를 표시하려다 파이프 stdin에서는 실패합니다. v2.1.246 이상은 claude install/claude update 중 대화상자를 안 띄웁니다. 재실행하면 최신 릴리스 install 명령을 쓰므로 해결됩니다. forceRemoteSettingsRefresh로 설정 fetch 대기를 켠 설정이면 여전히 실패할 수 있습니다.

`claude update`·`claude doctor`가 멈출 때

두 명령은 셸 설정 파일(~/.zshrc, ~/.bashrc, ~/.config/fish/config.fish, macOS의 ~/.bash_profile 등)에서 오래된 claude 별칭을 스캔합니다. 그 경로 중 하나가 디렉터리면 v2.1.214 이전 버전에서 행이 걸렸습니다. ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish로 디렉터리를 찾아 옮기거나 v2.1.214+로 업데이트하세요(업데이트가 멈추므로 설치 스크립트로 재실행).

Claude Desktop이 Windows에서 `claude` 명령을 덮어쓸 때

구버전 Claude Desktop이 WindowsApps에 Claude.exe를 등록해 CLI보다 PATH 우선순위를 갖는 경우. Claude Desktop을 최신 버전으로 업데이트하세요.

Windows에서 Git for Windows 또는 PowerShell 필요

Git Bash가 없으면 Claude Code는 PowerShell 도구를 사용하므로 둘 다 없으면 이 오류가 납니다. PowerShell이 PATH에 없으면 C:\Windows\System32\WindowsPowerShell\v1.0\ 추가 또는 PowerShell 7(pwsh) 설치. Git for Windows를 설치하려면 git-scm.com에서 받아 "Add to PATH" 선택. 특정 Git 설치를 지정하려면 where.exe git로 찾아 bin\bash.exe를 CLAUDE_CODE_GIT_BASH_PATH로 설정:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

이 변수는 bash.exe, sh.exe, bash, sh 이름의 파일만 인정하며(v2.1.219+), 이름이 맞아도 AppLocker·그룹 정책·EDR이 방해할 수 있습니다.

32-bit Windows 미지원

Windows PowerShell (x86)로 실행하면 64비트 머신에서도 이 오류가 납니다. [Environment]::Is64BitOperatingSystem가 True면 OS는 정상 — x86 없는 Windows PowerShell로 재실행. False면 Claude Code는 64비트 OS가 필요합니다.

Linux musl/glibc 바이너리 불일치

libstdc++.so.6·libgcc_s.so.1 누락은 glibc 시스템인데 musl 바이너리가 받아진 것. ldd --version 2>&1 | head -1로 확인 후, glibc면 제거·재설치, 정말 musl(Alpine)이면 apk add libgcc libstdc++ ripgrep.

`Illegal instruction`

아키텍처 불일치(예: ARM 서버에 x86 바이너리) 또는 CPU가 AVX 없음(주로 2013년 이전 Intel/AMD, VM이 AVX 미전달). grep -m1 -ow avx /proc/cpuinfo로 확인. 네이티브 바이너리 워크어라운드는 없고 이슈 #50384를 추적하세요.

macOS `dyld: cannot load`

dyld: Symbol not found(libicucore 참조)나 dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)·Abort trap: 6는 macOS 버전이 너무 오래된 것. Claude Code는 macOS 13.0 이상 필요. macOS를 업데이트하세요.

WSL1에서 `Exec format error`

WSL1 네이티브 바이너리 회귀(이슈 #38788). WSL2로 전환(wsl --set-version <DistroName> 2)하거나, WSL1 유지 시 ~/.bashrc에:

claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

WSL에서 npm 설치 오류

WSL이 Windows npm을 집는 경우 npm config set os linux 후 npm install -g @anthropic-ai/claude-code --force(sudo 금지). /mnt/c/ 경로는 Windows 바이너리. nvm 버전 충돌은 ~/.bashrc에 nvm 로더 추가, Windows가 우선이면 export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH". appendWindowsPath = false 비활성화·Windows Node 제거는 피하세요.

설치 중 권한 오류

native 인스톨러 권한 오류는 디렉터리 권한 확인. npm 권한 오류면 native 인스톨러로 전환(curl -fsSL https://claude.ai/install.sh | bash).

npm 설치 후 네이티브 바이너리 없음

Error: claude native binary not installed.는 플랫폼별 선택 의존성이 다운로드되지 않았거나 postinstall이 안 돌았기 때문. 원인별: ① --omit=optional 제거(native binary는 선택 의존성으로만 제공), ② --ignore-scripts 제거 후 node node_modules/@anthropic-ai/claude-code/install.cjs로 수동 실행, ③ 미지원 플랫폼(지원: darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64, win32-arm64), ④ 회사 npm 미러가 8개 플랫폼 패키지를 모두 미러링하는지 확인.

npm `ENOTEMPTY` 오류

기존 설치 위에 npm install -g @anthropic-ai/claude-code 시 이전 인터럽트가 남긴 디렉터리 때문에 발생. npm error path가 가리키는 디렉터리와 옆의 .claude-code-* 잔여물을 삭제 후 재설치:

rm -rf "$(npm root -g)/@anthropic-ai/claude-code"
rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*
npm install -g @anthropic-ai/claude-code

로그인·인증

로그인 초기화

/logout으로 완전 로그아웃 → 2. Claude Code 닫기 → 3. claude로 재시작해 다시 인증. 브라우저가 자동으로 안 열리면 c를 눌러 OAuth URL을 클립보드에 복사해 수동으로 붙여넣으세요.

OAuth error: Invalid code

OAuth error: Invalid code. Please make sure the full code was copied는 로그인 코드가 만료되거나 복사 중 잘렸다는 것. Enter로 재시도, c로 전체 URL 복사, SSH 원격에선 터미널의 URL을 로컬 브라우저에서 여세요.

로그인 후 403 Forbidden

Claude Pro/Max: claude.ai/settings에서 구독 활성 확인.
Anthropic Console: 계정에 "Claude Code" 또는 "Developer" 역할 확인(Settings → Members).
프록시 뒤: 네트워크 구성.

유효 구독인데 "이 조직은 비활성화됨"

ANTHROPIC_API_KEY 환경변수가 구독 OAuth 대신 키를 우선해 구독을 무시하는 것. 키를 unset하고 셸 프로필에서 제거하세요:

unset ANTHROPIC_API_KEY
claude

~/.zshrc, ~/.bashrc, ~/.profile에서 export ANTHROPIC_API_KEY=... 줄 제거. /status로 활성 인증 방법 확인.

WSL2·SSH·컨테이너에서 OAuth 로그인 실패

브라우저가 다른 호스트에서 열려 로컬 콜백 서버에 리다이렉트가 못 닿습니다. 로그인 후 코드가 표시되면 Paste code here if prompted 프롬프트에 붙여넣으세요. WSL2에서 브라우저가 안 열리면 export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe". 붙여넣기가 입력 필드에 안 닿으면 claude auth login(표준 입력에서 코드 읽음) 사용.

로그인 안 됨 또는 토큰 만료

/login으로 재인증. 자주 발생하면 시스템 시계가 정확한지 확인(토큰 검증이 타임스탬프 의존). macOS는 로그인 자격 증명을 Keychain에 저장합니다. Keychain 쓰기가 거부되면(SSH 세션에서 잠긴 경우 등) 일반 텍스트 ~/.claude/.credentials.json에 저장합니다. Keychain을 다시 쓰게 하려면 claude doctor로 확인, security unlock-keychain ~/Library/Keychains/login.keychain-db로 잠금 해제, 안 되면 Keychain Access > Change Password로 재동기화, 마지막으로 /logout 후 /login(로그아웃은 저장된 자격증명·MCP 로그인·플러그인 비밀값을 모두 지우므로 재인증 필요).

Bedrock·Agent Platform·Foundry 자격 증명 로딩 안 됨

Amazon Bedrock: aws sts get-caller-identity로 AWS 자격 증명 확인.
Google Cloud Agent Platform: ANTHROPIC_VERTEX_PROJECT_ID·CLOUD_ML_REGION 설정 후 gcloud auth application-default login.
Microsoft Foundry: ANTHROPIC_FOUNDRY_API_KEY 설정 또는 az login.

IDE 확장에서만 안 되면 IDE가 셸 환경변수를 못 물려받은 것 — IDE 자체 설정에 변수를 설정하거나 셸에서 IDE를 실행.

더 알아보기

해결이 안 되면: GitHub 저장소(issues) 확인·새 이슈에 OS·설치 명령·전체 에러 출력 첨부, claude doctor 실행, 세션 시작이 가능하면 /feedback, 계정 문제는 claude.ai(Console: platform.claude.com)에서 Get help. 지원 절차 전체를 참조하세요.

Claude Code 설치·로그인 문제 해결