클로드 코드(Claude Code) 설치 오류 총정리 — 윈도우 7가지 원인과 해결
윈도우에서 클로드 코드 설치가 막히는 원인 7가지를 오류 메시지 기준으로 정리했습니다. irm 오류부터 PATH, 403, TLS, 백신 충돌까지 공식 문서 기반으로 바로 고치는 법.
클로드 코드(Claude Code) 깔다가 빨간 오류만 보고 창 닫으신 적 있나요? 이 글은 윈도우에서 설치가 막히는 원인 7가지를 오류 메시지 기준으로 찾아서 바로 고치는 가이드입니다. 필요한 건 10분이랑 PowerShell 창 하나뿐이에요.
윈도우 설치 오류의 절반 이상은 ①셸을 잘못 골랐거나 ②PATH 등록이 문제입니다. 이 두 개부터 확인하면 대부분 끝나요.
일단 올바른 설치 명령부터
다른거 다필요 없어요. 2026년 현재 공식 권장은 네이티브 설치라서, 예전 글들처럼 Node.js부터 깔 필요가 없습니다. npm으로 깔던 시절 가이드를 따라하다 꼬이는 분들이 의외로 많아요.
준비물은 딱 세 개입니다.
- [ ] PowerShell 또는 CMD — 윈도우 기본 내장 (무료)
- [ ] 클로드 계정 Pro 이상 — 무료 플랜은 클로드 코드를 못 씁니다 (유료)
- [ ] Git for Windows — 선택이지만 권장, Bash 도구가 활성화돼요 (무료)
일단 PowerShell을 여세요. 시작 메뉴에서 "PowerShell" 검색하면 나옵니다. 그리고 아래 한 줄이 공식 설치 명령입니다.
irm https://claude.ai/install.ps1 | iex
CMD(명령 프롬프트)를 쓰신다면 명령이 다릅니다.
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
둘 다 싫으면 winget 한 줄로도 됩니다: winget install Anthropic.ClaudeCode
원인 1. 셸을 잘못 골라서 명령어부터 튕김
설치 오류 1등 원인이 이겁니다. PowerShell 명령을 CMD에 붙여넣거나, 그 반대거나요.
'irm'은(는) 내부 또는 외부 명령이 아닙니다→ 지금 CMD에 계세요. PowerShell 명령을 붙여넣으신 겁니다.The token '&&' is not a valid statement separator→ 지금 PowerShell인데 CMD 명령을 붙여넣으셨어요.'bash' is not recognized또는-fsSL파라미터 오류 → 맥·리눅스용 명령을 윈도우에 붙여넣으신 경우예요.
구분법은 간단합니다. 프롬프트가 PS C:\로 시작하면 PowerShell, 그냥 C:\면 CMD예요. 지금 열린 창에 맞는 명령을 다시 붙여넣으면 끝납니다.
PowerShell / CMD는 둘 다 윈도우에서 명령어를 치는 창이에요. CMD가 구형, PowerShell이 신형이라고 보면 편합니다. 생김새가 비슷해서 헷갈리는데, 서로 문법이 달라 남의 명령을 붙여넣으면 튕겨요.
오류 메시지로 바로 찾기
바로 본인 오류부터 찾고 싶은 분들을 위해 정리했습니다. 환경에 따라 잘 걸리는 원인이 달라서, 먼저 내 상황부터 찾아보세요.
원인 ①(셸)과 ②(PATH)만 보면 대부분 해결됩니다. 네트워크 계열은 건너뛰어도 돼요.
원인 ③(설치 충돌)부터 확인하세요. 옛 설치본이 남아 버전이 꼬이는 케이스가 많아요.
원인 ④(프록시)·⑤(TLS 인증서) 가능성이 압도적입니다. IT팀 문의가 필요할 수 있어요.
증상별 표는 아래와 같습니다. 위젯에서 증상을 눌러도 같은 답이 나와요.
| 오류 메시지 / 증상 | 원인 | 해결 요약 |
|---|---|---|
'irm'은(는) 내부 또는 외부 명령이 아닙니다 |
① 셸 불일치 | PowerShell을 열고 다시 실행 |
'claude'은(는) 내부 또는 외부 명령이 아닙니다 |
② PATH 미등록 | .local\bin을 PATH에 추가 |
claude 치면 데스크톱 앱이 열림 |
③ 설치 충돌 | 클로드 데스크톱 최신 업데이트 |
403 오류·HTML 코드가 주르륵 |
④ 지역·프록시 차단 | winget 대체 설치, 재시도 |
SSL/TLS secure channel 오류 |
⑤ TLS·회사망 | TLS 1.2 강제 후 재설치 |
The process cannot access the file |
⑥ 파일 잠김 | 다운로드 폴더 비우고 재시도 |
does not support 32-bit Windows |
⑦ x86 PowerShell | (x86) 없는 PowerShell로 |
설치는 됐는데 실행이 안 될 때
설치 프로그램은 분명 성공했다는데 claude를 치면 모른다고 하는 경우, 원인은 둘 중 하나입니다.
원인 2. PATH에 등록이 안 됐다
'claude'은(는) 내부 또는 외부 명령... 이 아닙니다가 뜨는 경우예요. 설치 자체는 %USERPROFILE%\.local\bin 폴더에 잘 됐는데, 윈도우가 그 폴더를 못 찾는 상태입니다.
PowerShell에 아래 두 줄을 순서대로 붙여넣으세요.
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
그리고 터미널을 완전히 껐다가 다시 여세요. 이거 안 해서 "고쳤는데도 안 된다"는 분이 정말 많습니다. 새 창에서 claude --version이 버전 숫자를 뱉으면 성공이에요.
PATH는 윈도우가 명령어를 찾아보는 폴더 목록이에요. 여기 등록 안 된 폴더의 프로그램은 이름만 쳐서는 실행이 안 됩니다. "설치는 됐는데 인식이 안 돼요"의 팔할이 이 목록 문제예요.
원인 3. 옛 설치·데스크톱 앱과 충돌
예전에 npm으로 깔았던 흔적이나 다른 설치본이 남아 있으면 버전이 꼬입니다. where.exe claude를 쳐서 경로가 두 개 이상 나오면 정리가 필요해요. npm 흔적은 npm uninstall -g @anthropic-ai/claude-code로 지우고 네이티브 설치본 하나만 남기는 게 공식 권장입니다.
하나 더, claude를 쳤는데 CLI가 아니라 데스크톱 앱이 열리는 경우가 있어요. 구버전 클로드 데스크톱이 Claude.exe로 명령을 가로채는 알려진 증상인데, 데스크톱 앱을 최신 버전으로 업데이트하면 풀립니다.
다운로드 자체가 실패할 때
명령은 맞게 쳤는데 다운로드 단계에서 죽는 경우입니다. 회사 컴퓨터라면 십중팔구 여기예요.
원인 4. 403 오류·HTML 덩어리 (지역·프록시 차단)
Invoke-Expression: Missing argument in parameter list나 403 오류가 뜨면, 설치 스크립트 대신 HTML 페이지가 내려온 겁니다. "App unavailable in region"이 보이면 지원 국가 문제고요 — 한국은 지원 국가라 국내에선 보통 프록시·네트워크 필터가 원인입니다.
해결은 두 가지 중 하나예요. 몇 분 뒤 재시도하거나(일시 장애가 은근 많습니다), winget install Anthropic.ClaudeCode로 우회 설치하는 겁니다. 회사 프록시망이면 $env:HTTPS_PROXY = 'http://프록시주소:포트'를 먼저 설정하고 설치 명령을 실행하세요.
원인 5. TLS/SSL 보안 채널 오류
Could not establish trust relationship for the SSL/TLS secure channel 계열 오류는 암호화 연결 자체가 실패한 경우입니다. PowerShell에서 TLS 1.2를 강제하고 다시 설치해보세요.
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex
CRYPT_E_NO_REVOCATION_CHECK 오류가 뜨는 회사망이라면 CMD의 curl 방식 대신 위 PowerShell 설치기나 winget을 쓰는 게 답이에요. 보안 검사 장비가 끼어 있는 사내망은 unable to get local issuer certificate가 뜨기도 하는데, 이건 IT팀에서 사내 인증서 파일을 받아야 풀립니다.
마지막 두 가지 함정
여기까지 왔는데도 안 되면, 좀 억울한 유형 두 가지가 남았습니다.
원인 6. 다운로드 파일 잠김 (백신)
The process cannot access the file ... because it is being used by another process — 백신이 받다 만 파일을 검사하느라 잡고 있거나, 이전 설치 창이 어딘가 살아 있는 경우예요. 다른 PowerShell 창을 다 닫고 아래처럼 다운로드 폴더를 비운 뒤 재시도하면 됩니다.
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex
원인 7. 32비트 PowerShell(x86)로 실행
Claude Code does not support 32-bit Windows가 떴는데 내 컴퓨터는 분명 64비트인 경우요. 시작 메뉴에 PowerShell이 두 개 있는데, Windows PowerShell (x86) 쪽을 여신 겁니다. x86 안 붙은 쪽으로 다시 열어 실행하면 끝나요. 긴가민가하면 [Environment]::Is64BitOperatingSystem을 쳐보세요 — True면 OS는 문제 없다는 뜻입니다.
⚠️ 주의: 진짜 32비트 윈도우(구형 PC)라면 클로드 코드는 설치가 안 됩니다. 64비트 OS가 최소 조건이에요.
설치 확인과 로그인까지
설치가 됐는지 확인은 두 줄이면 충분합니다. claude --version이 버전 숫자를 찍고, claude doctor가 진단 결과를 보여주면 정상이에요. doctor는 설치 상태랑 설정 파일 오류까지 훑어주니까, 뭔가 애매하면 일단 이것부터 돌려보세요.
로그인은 claude 실행 후 브라우저 안내를 따라가면 되는데, 한 가지 중요한 게 있습니다. 무료 플랜으로는 클로드 코드를 못 씁니다. Pro(월 $20)부터 열려요. 설치가 멀쩡한데 로그인에서 막힌다면 오류가 아니라 플랜 문제일 수 있습니다.
Git for Windows를 깔았는데 클로드 코드가 Git Bash를 못 찾는다고 하면, 설정 파일(.claude/settings.json)에 경로를 직접 알려주면 됩니다.
{
"env": {
"CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
}
}
여기까지 하고도 안 풀리는 케이스는 공식 GitHub 이슈에 같은 증상이 있는지 검색해보는 게 빠릅니다. 설치가 끝났다면 다음 관문은 MCP 연결인데, 권한을 어디까지 열지는 제가 정리해둔 MCP 보안 설정 가이드를 참고하세요.
내 생각
솔직히 클로드 코드 설치 오류의 대부분은 도구 탓이 아니라 안내 탓이라고 봅니다. 저의 경우 이 블로그 운영 자체를 윈도우 11에서 클로드 코드로 돌리고 있는데, 처음 셋업할 때 제일 헷갈렸던 것도 결국 PowerShell이냐 CMD냐, PATH가 잡혔냐 이 두 개였어요. 오류 메시지가 영어라 겁부터 나지, 막상 뜯어보면 별거 아닌 게 많습니다.
한 가지 경계할 점은, 검색하면 나오는 2025년 이전 글들이에요. Node.js 깔고 npm으로 설치하라는 가이드가 아직 상위에 많이 보이는데, 지금은 네이티브 설치가 기본이라 굳이 그 길로 갈 이유가 없습니다. 옛 글 따라하다가 오히려 원인 3(설치 충돌)을 만드는 케이스가 제일 안타깝죠.
클로드 코드는 업데이트가 워낙 빨라서 오류 메시지 문구도 종종 바뀝니다. 이 글과 문구가 다르면 claude doctor 먼저 돌려보고, 공식 트러블슈팅 문서를 확인하는 습관을 들이시길. 그럼 이만~
참고 자료
'AI 리뷰 & 가이드' 카테고리의 다른 글
| 지금 그래픽카드 사도 될까 — RTX 50 슈퍼 지연·VRAM값 폭등 2026 구매 타이밍 (0) | 2026.07.19 |
|---|---|
| 구글(Google) Tensor SDK 베타 — Pixel 10 로컬 AI가 달라지는 점 (0) | 2026.07.15 |
| MCP 보안 설정 가이드 2026 — GitHub·파일 권한 어디까지 열까 (0) | 2026.07.07 |
| 6월 GitHub 핫 트렌드 분석: 지금 전 세계 개발자들이 주목하는 오픈소스 AI 도구 TOP 3 (0) | 2026.06.18 |
| RTX 5090 품귀 현상 속 대안? 글카 가격으로 본체를 통째로 사는 완본체 핫딜(ABS Kaze 2) 분석 (1) | 2026.06.15 |