설치·로그인 문제 해결
기준일: 2026-07-26
난이도: 초급
공식 기준: Troubleshoot installation and login
설치 실패·로그인 불가 시 이 페이지의 증상 표와 진단 절차를 따릅니다. 런타임 문제는 Troubleshooting, 설정/훅은 Debug your configuration.
터미널을 건너뛰려면 Desktop 앱 (macOS/Windows 다운로드, Linux는 apt).
개요 — 증상 → 해결 매핑
| 보이는 증상 | 해결 방향 |
|---|---|
command not found: claude / not recognized |
PATH 수정 |
syntax error near unexpected token '<' / iex가 HTML·CSS 파싱 |
설치 스크립트가 HTML 반환 |
curl: (22) ... 403 |
지역 미지원 또는 프록시 차단 |
curl: (23) / (56) Failure writing output |
연결 또는 대체 설치 |
Killed / exit 137 |
메모리 확보·swap |
| TLS/SSL 오류 | CA 인증서·프록시 |
Failed to fetch version |
네트워크·프록시 |
irm 미인식 / && 무효 / -fsSL 파라미터 오류 |
Windows 셸별 명령 |
| Homebrew cask unavailable | brew update |
| Windows: bash/PowerShell 필요 | 셸 설치 |
| 32-bit Windows | x86이 아닌 64-bit PowerShell |
| 파일 사용 중 (Windows) | downloads 폴더 삭제 후 재시도 |
| shared library / Illegal instruction / dyld / Exec format | 바이너리·아키텍처·WSL1 |
claude update/doctor hang |
shell config 경로가 디렉터리인 경우 |
running scripts is disabled |
ExecutionPolicy 또는 .cmd |
claude native binary not installed |
npm optional/postinstall |
App unavailable in region |
지원 국가 |
| OAuth / 403 / credentials not loading | 로그인·프로바이더 인증 |
목록에 없으면 아래 진단 체크 순회.
핵심 개념 — 진단 체크
네트워크
curl -sI https://downloads.claude.ai/claude-code-releases/latest
# PowerShell: curl.exe -sI ...
HTTP/2 200: 서버 도달403: 프록시/필터 또는 지역 미지원5xx: 일시 장애- resolve/timeout: 방화벽·지역·TLS
프록시:
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
PowerShell:
$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex
PATH
설치 위치: macOS/Linux ~/.local/bin/claude, Windows %USERPROFILE%\.local\bin\claude.exe.
VS Code 확장은 PATH에
claude를 넣지 않습니다. 터미널용은 독립 설치 필요.
# macOS/Linux
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # 또는 ~/.bashrc
source ~/.zshrc
claude --version
$env:PATH -split ';' | Select-String '\.local\bin'
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
# 터미널 재시작
충돌 설치 정리
which -a claude
ls -la ~/.local/bin/claude # native
ls -la ~/.claude/local/ # legacy local npm
npm -g ls @anthropic-ai/claude-code 2>/dev/null
권장: native 하나만 유지.
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local
brew uninstall --cask claude-code # macOS
# Windows: winget uninstall Anthropic.ClaudeCode
권한·바이너리
test -w ~/.local/bin && echo writable || echo not
sudo mkdir -p ~/.local/bin && sudo chown -R $(whoami) ~/.local
ls -la "$(command -v claude)"
ldd "$(command -v claude)" | grep "not found" # Linux
claude --version
상세 — 설치 이슈
설치 스크립트가 HTML
증상: syntax error near unexpected token '<', iex ParserError, bare 403.
해결: Homebrew brew install --cask claude-code / WinGet winget install Anthropic.ClaudeCode / 수 분 후 재시도. "App unavailable in region"이면 국가 확인.
command not found after install
PATH 섹션 참조.
curl (56)/(23)
다운로드 중단. 연결 테스트 후 brew/winget 대체.
Homebrew cask 없음/오래됨
brew update && brew install --cask claude-code
# 최신 채널: brew install --cask claude-code@latest
stable cask는 보통 최신보다 약 1주 지연.
TLS/SSL
- Ubuntu:
sudo apt-get install ca-certificates - Windows TLS 1.2:
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex
- 기업 CA:
curl --cacert ..., 런타임NODE_EXTRA_CA_CERTS - revocation 차단(
CRYPT_E_NO_REVOCATION_CHECK): PowerShell installer 또는 winget (curl--ssl-revoke-best-effort만으로는 스크립트 내부 다운로드 실패)
Windows 잘못된 설치 명령
| 오류 | 원인 | 조치 |
|---|---|---|
irm not recognized |
CMD | PowerShell로 전환 또는 CMD installer |
&& not valid |
PowerShell에서 CMD 명령 | irm ... | iex |
-fsSL 파라미터 |
PowerShell curl 별칭 | PowerShell installer |
| bash not recognized | Linux 명령을 Windows에서 실행 | PowerShell installer |
CMD installer:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
ExecutionPolicy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# 또는 npm.cmd / claude.cmd 사용, 또는 native PowerShell installer
Windows downloads 잠금
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex
Linux OOM (exit 137)
설치 약 512MB 여유 메모리. 2GB swap 추가 또는 프로세스 종료. 시스템 요구: 최소 4GB RAM.
Docker hang
WORKDIR /tmp 설정 후 설치. Docker Desktop 메모리 한도 상향.
update/doctor hang
shell config 경로가 파일 대신 디렉터리면 v2.1.214 미만에서 hang. ls -ld ~/.zshrc ~/.bashrc ... 확인 후 디렉터리 이동 또는 재설치 스크립트로 업데이트.
Desktop이 claude 가로챔 (Windows)
구버전 Claude Desktop이 WindowsApps Claude.exe를 PATH 우선. Desktop 최신으로 업데이트.
Windows 셸 없음
Git Bash 또는 PowerShell 필요. PowerShell 기본 경로 추가 또는 Git for Windows. 커스텀 경로:
{
"env": {
"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
}
}
v2.1.116+는 파일시스템 직접 확인(엔드포인트 보안 우회 개선).
32-bit / musl·glibc / Illegal instruction / dyld / WSL1
- 32-bit: Start 메뉴에서 x86 아닌 Windows PowerShell
- musl/glibc 오탐:
ldd --version, Alpine은apk add libgcc libstdc++ ripgrep - Illegal instruction: 아키텍처 불일치 또는 AVX 미지원 CPU (pre-2013 등). issue #50384
- dyld: macOS 13.0+ 필요
- WSL1 Exec format:
wsl --set-version <Distro> 2또는 ld-linux 래퍼
WSL npm 이슈
- Windows npm 혼입 시
npm config set os linux후--force(sudo 금지) which node가/mnt/c/면 Linux Node/nvm 설치- nvm 로더를 shell rc에 추가.
appendWindowsPath=false비권장
npm native binary 없음
optional dep + postinstall 필요. --omit=optional/--ignore-scripts 금지. 수동:
node node_modules/@anthropic-ai/claude-code/install.cjs
플랫폼: darwin-arm64/x64, linux-x64/arm64(+musl), win32-x64/arm64. FreeBSD 미지원(v2.1.205+ 명확 보고).
상세 — 로그인·인증
재로그인
/logout → 종료 → claude 재시작. 브라우저 미오픈 시 c로 OAuth URL 복사.
Invalid code
코드 만료/잘림. 빠르게 재시도, 원격/SSH는 로컬 브라우저에 URL 붙여넣기.
403 after login
- Pro/Max: claude.ai/settings 구독 확인
- Console: Claude Code/Developer 역할
- 프록시: network-config
organization disabled + 활성 구독
ANTHROPIC_API_KEY가 구독 OAuth를 덮어씀. unset ANTHROPIC_API_KEY 후 shell profile에서 제거. /status로 활성 인증 확인.
WSL2/SSH/컨테이너 OAuth
브라우저 리다이렉트가 콜백에 못 닿음 → 로그인 코드를 터미널에 붙여넣기. BROWSER를 Windows 브라우저로 지정 가능. paste 실패 시 claude auth login.
토큰 만료
/login. 시스템 시계 정확도. 병렬 세션 갱신 레이스: v2.1.211 이전 sleep 복귀 시 전원 재로그인. macOS Keychain: claude doctor, security unlock-keychain.
Bedrock / Agent Platform / Foundry credentials
aws sts get-caller-identity
gcloud auth application-default login
az login
IDE는 shell env 미상속 → IDE 설정에 프로바이더 변수 설정.
여전히 안 되면
- GitHub issues
claude doctor- 세션 내
/feedback - 계정 문제: claude.ai / platform.claude.com → Get help
체크리스트
- 증상 표에서 매칭 항목을 찾았다
-
downloads.claude.ai연결·PATH·단일 설치본을 확인했다 - Windows/WSL/macOS 전용 함정을 검토했다
- 로그인 문제는 OAuth·API key 우선순위·프로바이더 CLI를 확인했다