클로드코드(Claude Code) 윈도우 설치 오류 2026 해결 총정리: ‘claude’ is not recognized, 스크립트 실행 차단, npm 권한, Git Bash 경로

Q: 클로드코드 설치에 관리자 권한으로 PowerShell 을 열어야 하나요?

아니요, 설치 위치가 사용자 폴더(%USERPROFILE%) 안이라 일반 권한으로 충분해요. npm 도 sudo 나 관리자 권한으로 설치하지 말라고 공식 문서에 명시돼 있어요.

Q: 클로드코드 설치에 Node.js 를 꼭 설치해야 하나요?

네이티브 설치나 WinGet 이면 필요 없어요. npm 으로 설치할 때만 Node 22 이상이 필요해요.

Q: 클로드코드는 Git for Windows 없이도 되나요?

돼요. Git Bash 가 없으면 PowerShell 도구로 명령을 실행해요. 다만 Bash 스크립트 기반 도구를 쓰려면 Git for Windows 를 설치하는 것이 편해요.

Q: 클로드코드는 WSL 에 설치할까요, 윈도우에 바로 설치할까요?

프로젝트가 윈도우 폴더에 있으면 윈도우 네이티브가 빨라요. 리눅스 툴체인이나 샌드박스 실행이 필요할 때만 WSL 2 를 쓰고, 그때는 리눅스용 설치 명령을 WSL 터미널 안에서 실행해요.

Q: 클로드코드를 완전히 제거하고 다시 설치하려면요?

네이티브는 %USERPROFILE%\.local\bin\claude.exe 와 .local\share\claude 폴더를 삭제하면 돼요. 설정과 대화 기록까지 지우려면 %USERPROFILE%\.claude 와 .claude.json 도 삭제하는데, 세션 기록이 전부 사라지니 신중하게 하세요.

최종 업데이트: 2026-09-11

윈도우에서 클로드코드(Claude Code)는 PowerShell 에서 irm https://claude.ai/install.ps1 | iex 한 줄로 설치되고, 관리자 권한은 필요 없어요. 설치 오류는 대부분 세 갈래예요. 다른 셸용 명령을 복사했거나(‘irm’ is not recognized, The token ‘&&’ is not valid), 설치 폴더가 PATH 에 없거나(‘claude’ is not recognized), 윈도우 보안이 막았거나(running scripts is disabled on this system, SSL/TLS secure channel)예요. 아래 11개 항목은 전부 Claude Code 공식 문서에 있는 오류 문구와 해결법이에요.

저는 윈도우 10 Home 에서 클로드코드로 자동매매 봇, AI 비서, 블로그 자동화를 매일 돌리는 사용자예요. 처음엔 npm 으로 설치했고 지금은 Git Bash 와 PowerShell 을 같이 쓰는 구성이에요. 직접 겪은 것과 공식 설치·트러블슈팅 문서를 합쳐 정리했어요. 설치 이후 첫 사용법은 클로드코드 사용방법 2026에 있어요.

클로드코드 윈도우 설치 요구사항과 설치 방법 3가지는?

2026년 9월 기준 공식 요구사항이에요.

항목	조건
운영체제	윈도우 10 1809 이상 또는 Windows Server 2019 이상. 64비트만 지원(32비트 불가)
메모리	4GB 이상
계정	Pro·Max·Team·Enterprise 또는 API 콘솔 계정. 무료 플랜은 클로드코드 불가
Git for Windows	선택. 있으면 Bash 도구, 없으면 PowerShell 도구로 동작
Node.js	네이티브 설치는 불필요. npm 설치일 때만 Node 22 이상(v2.1.198 부터)

클로드코드(Claude Code) 윈도우 설치 명령 3종: PowerShell irm, CMD curl, WinGet

# 1. PowerShell (권장, 프롬프트가 PS C:\ 로 시작)
irm https://claude.ai/install.ps1 | iex

# 2. CMD (프롬프트가 C:\ 로 시작)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# 3. WinGet (1번이 403·HTML 오류로 실패할 때 대안)
winget install Anthropic.ClaudeCode

# 확인 : 새 터미널을 열고
claude --version        # 2.1.268 (Claude Code) 처럼 나오면 성공
claude doctor           # 설치·설정 진단

방법	명령	자동 업데이트	언제
네이티브 (권장)	PowerShell 에서 irm … \| iex	자동	대부분의 경우
WinGet	winget install Anthropic.ClaudeCode	수동 (winget upgrade Anthropic.ClaudeCode)	네이티브가 403·HTML 오류로 실패할 때
npm	npm install -g @anthropic-ai/claude-code	자동 (npm 전역 폴더에 쓰기 권한이 있을 때)	Node 환경이 이미 있고 익숙할 때

npm 으로 설치해도 결국 같은 네이티브 실행 파일을 내려받아요. 그래서 네이티브 한 줄이 제일 덜 꼬여요. 어느 방법이든 설치 후엔 새 터미널을 열고 claude –version 을 실행하세요. 설치한 창은 옛 PATH 를 그대로 들고 있어서 안 잡히는 게 정상이에요.

에러 문구로 30초 만에 원인 갈래를 찾는 방법은?

클로드코드(Claude Code) 설치 오류 30초 진단: 셸 혼동, PATH 누락, 윈도우 보안 차단 세 갈래

에러 문구의 첫 단어만 보면 갈래가 갈려요. irm·&&·bash 가 나오면 셸 혼동, claude 가 나오면 PATH, running scripts·SSL·cannot access 가 나오면 윈도우 차단이에요. 어느 갈래에도 없으면 claude doctor 를 실행하세요. 세션을 열지 않고 설치 상태, 설정 파일 오류, 검색 도구 상태를 읽기 전용으로 보여줘요.

트러블슈팅: 클로드코드 윈도우 설치 오류 11가지 해결 방법

클로드코드(Claude Code) 설치 오류별 PowerShell 해결 명령: PATH 추가, 실행 정책, TLS 1.2, downloads 폴더 삭제

# 'claude' is not recognized → PATH 에 설치 폴더 추가 후 터미널 재시작
$p = [Environment]::GetEnvironmentVariable('PATH','User')
[Environment]::SetEnvironmentVariable('PATH', "$p;$env:USERPROFILE\.local\bin", 'User')

# running scripts is disabled on this system → 내 계정만 스크립트 허용
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# SSL/TLS secure channel 오류 → TLS 1.2 켜고 다시 설치
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

# The process cannot access the file → 받다 만 파일 지우고 재설치
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"

# 설치가 두 개 (npm + 네이티브) → 어디 있는지 보고 하나만 남기기
where.exe claude
npm uninstall -g @anthropic-ai/claude-code

‘irm’ is not recognized / The token ‘&&’ is not valid / ‘bash’ is not recognized / A parameter cannot be found that matches parameter name ‘fsSL’
원인: 다른 셸용 명령을 복사했어요. irm 이 안 되면 지금 CMD 이고, && 가 안 되면 지금 PowerShell 이에요. bash 나 fsSL 오류는 macOS·리눅스 명령을 윈도우에 붙인 거예요.
해결: 프롬프트 앞에 PS 가 있으면 PowerShell 명령, 없으면 CMD 명령을 쓰세요. 명령을 실행했는데 스크립트 본문이 화면에 출력되면 뒤쪽 | iex 를 빼먹은 거예요.
‘claude’ is not recognized as an internal or external command
원인: 설치는 됐는데 설치 폴더(%USERPROFILE%\.local\bin)가 PATH 에 없거나, 설치한 터미널을 그대로 쓰고 있어요.
해결: 먼저 새 터미널을 여세요. 그래도 안 되면 위 코드의 PATH 추가 명령을 실행하고 터미널을 다시 여세요. VS Code 확장만 설치했다면 터미널용 claude 는 아예 없는 상태라 네이티브 설치를 따로 해야 해요.
running scripts is disabled on this system (SecurityError, PSSecurityException)
원인: npm 설치 시 npm.ps1 이나 claude.ps1 런처를 PowerShell 실행 정책이 막았어요. 네이티브 설치 명령(irm | iex)은 파일이 아니라 이 정책에 걸리지 않아요.
해결: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser 한 번. 정책을 바꾸기 싫으면 claude.cmd 처럼 .cmd 런처를 호출하면 돼요.
syntax error near unexpected token ‘<‘ / PowerShell 에서 HTML 태그가 섞인 ParserError / curl: (22) The requested URL returned error: 403
원인: 설치 URL 이 스크립트 대신 웹페이지나 403 을 돌려줬어요. 지역 제한(App unavailable in region), 회사 프록시, 일시 장애가 원인이에요.
해결: 몇 분 뒤 재시도. 계속 실패하면 winget install Anthropic.ClaudeCode 로 우회하세요. 지원 국가가 아니면 어떤 방법도 안 돼요.
Could not establish trust relationship for the SSL/TLS secure channel / schannel: next InitializeSecurityContext failed
원인: TLS 핸드셰이크 실패. 오래된 윈도우 설정이거나 회사 프록시가 TLS 를 검사하는 경우예요.
해결: PowerShell 에서 TLS 1.2 를 켜고 설치 명령을 다시 실행하세요. 회사 PC 라면 프록시 CA 인증서를 윈도우 인증서 저장소에 넣어야 해요. CRYPT_E_NO_REVOCATION_CHECK (0x80092012) 가 뜨면 CMD 의 curl 에 –ssl-revoke-best-effort 를 붙이거나 PowerShell 설치로 바꾸세요.
Failed to download binary: The process cannot access the file … because it is being used by another process
원인: 이전 설치가 아직 실행 중이거나, 백신이 받다 만 파일을 검사 중이라 %USERPROFILE%\.claude\downloads 에 쓸 수 없어요.
해결: 다른 PowerShell 창을 닫고 downloads 폴더를 삭제한 뒤 다시 설치하세요.
Claude Code does not support 32-bit Windows
원인: 시작 메뉴의 “Windows PowerShell (x86)” 을 열었어요. 64비트 PC 에서도 이 창은 32비트로 실행돼요.
해결: [Environment]::Is64BitOperatingSystem 이 True 면 (x86) 없는 PowerShell 을 다시 여세요. False 면 32비트 윈도우라 설치가 안 돼요.
claude 를 실행했는데 Claude 데스크톱 앱이 열림
원인: 구버전 Claude Desktop 이 WindowsApps 폴더에 Claude.exe 를 등록해서 PATH 우선순위를 가져갔어요.
해결: Claude Desktop 을 최신으로 업데이트하면 해결돼요.
Claude Code on Windows requires either Git for Windows (for bash) or PowerShell
원인: Git Bash 도 PowerShell 도 못 찾은 상태예요. Git 이 기본 경로(C:\Program Files\Git)가 아닌 곳에 있거나, PowerShell 이 PATH 에서 빠진 경우예요.
해결: Git 이 있으면 settings.json 에 CLAUDE_CODE_GIT_BASH_PATH 로 bin\bash.exe 경로를 지정하세요(아래 코드). 파일 이름이 bash.exe 나 sh.exe 가 아니면(git-bash.exe 등) 무시돼요. Git 이 없으면 git-scm.com 에서 설치할 때 “Add to PATH” 를 선택하면 돼요.
npm WARN EBADENGINE / Error: claude native binary not installed
원인: v2.1.198 부터 npm 패키지는 Node 22 이상을 요구해요. EBADENGINE 은 경고라 설치도 실행도 돼요. native binary 오류는 –ignore-scripts 나 pnpm 설정 때문에 postinstall 이 실행되지 않아 실행 파일이 놓이지 않은 거예요.
해결: Node 를 22 이상으로 올리고 npm install -g @anthropic-ai/claude-code@latest 로 다시 설치. 업데이트할 때 npm update -g 는 원래 버전 범위에 묶여 최신으로 올라가지 않으니 쓰지 마세요.
버전이 오락가락하거나 업데이트해도 옛 버전이 실행됨
원인: npm 설치와 네이티브 설치가 둘 다 있어요. 제 PC 도 npm 으로 설치한 실행 파일이 AppData\Roaming\npm 에 있어서 where.exe claude 를 치면 두 줄이 나와요.
해결: where.exe claude 로 위치를 확인하고 하나만 남기세요. 공식 권장은 네이티브(%USERPROFILE%\.local\bin\claude.exe)이고, npm 쪽은 npm uninstall -g @anthropic-ai/claude-code 로 제거해요.

클로드코드(Claude Code) Git Bash 경로 지정: settings.json 의 CLAUDE_CODE_GIT_BASH_PATH

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

설치는 됐는데 클로드코드 로그인이 안 될 때는?

클로드코드는 무료 플랜으로는 로그인이 안 돼요. Pro·Max·Team·Enterprise 또는 API 콘솔 계정이 필요해요. claude 를 실행하면 브라우저가 열리고 거기서 로그인하면 끝이에요. 브라우저가 열리지 않으면 터미널에 출력된 URL 을 직접 복사해서 여세요.

환경변수에 ANTHROPIC_API_KEY 가 설정돼 있으면 브라우저 대신 “이 키를 사용할까요?” 를 한 번 물어요. 구독 계정으로 쓰려는데 이 질문이 뜨면 그 환경변수를 제거하고 다시 시작하세요. 구독 계정과 API 키는 과금 방식이 달라요. 자세한 내용은 클로드 사용량 한도 2026 정리에 있어요.

설치 확인과 업데이트 명령은?

명령	동작
claude –version	버전 출력. “2.1.268 (Claude Code)” 처럼 나오면 정상
claude doctor	설치 상태·설정 파일 오류·검색 도구·최근 업데이트 결과 진단. 세션은 열지 않음
claude update	즉시 업데이트. 네이티브는 백그라운드 자동 업데이트도 켜져 있음

네이티브 설치는 시작 시와 실행 중 주기적으로 업데이트를 확인하고, 다음 실행부터 새 버전이 적용돼요. 업데이트를 막으려면 settings.json 의 env 에 “DISABLE_AUTOUPDATER”: “1” 을 넣으면 돼요. WinGet 은 winget upgrade Anthropic.ClaudeCode 를 직접 실행해야 하고, 클로드코드가 실행 중이면 파일 잠금 때문에 실패하니 종료 후 실행하세요.

윈도우 10 실사용 환경에서 실제로 겪은 문제는?

제 PC 는 윈도우 10 Home, Node 24, 클로드코드 2.1.268 이에요. npm 으로 설치해서 실행 파일이 AppData\Roaming\npm 에 있고, Git for Windows 를 함께 설치해 Bash 도구와 PowerShell 도구를 둘 다 써요.

Git Bash 와 PowerShell 문법이 섞여 실패한 경우가 가장 많았어요. PowerShell 5.1 은 && 를 인식하지 못하고, Git Bash 는 $env:VAR 를 인식하지 못해요. 클로드코드가 어느 셸로 명령을 보내는지 확인하면 대부분 해결돼요.
플러그인 설정 JSON 에 BOM 이 붙어 로드되지 않은 경우가 있었어요. VS Code 에서 “UTF-8 (BOM 없음)” 으로 다시 저장하니 해결됐어요.
설치 자체는 한 번도 막히지 않았어요. 막힌 건 전부 설치 이후의 셸·경로·설정 문제였어요.

그래서 처음 설치하는 분께는 네이티브 한 줄 + Git for Windows 조합을 권해요. npm 보다 확인할 것이 적어요.

자주 묻는 질문 (FAQ)

Q. 관리자 권한으로 PowerShell 을 열어야 하나요?
아니요, 설치 위치가 사용자 폴더(%USERPROFILE%) 안이라 일반 권한으로 충분해요. npm 도 sudo 나 관리자 권한으로 설치하지 말라고 공식 문서에 명시돼 있어요.

Q. Node.js 를 꼭 설치해야 하나요?
네이티브 설치나 WinGet 이면 필요 없어요. npm 으로 설치할 때만 Node 22 이상이 필요해요.

Q. Git for Windows 없이도 되나요?
돼요. Git Bash 가 없으면 PowerShell 도구로 명령을 실행해요. 다만 Bash 스크립트 기반 도구를 쓰려면 Git for Windows 를 설치하는 것이 편해요.

Q. WSL 에 설치할까요, 윈도우에 바로 설치할까요?
프로젝트가 윈도우 폴더에 있으면 윈도우 네이티브가 빨라요. 리눅스 툴체인이나 샌드박스 실행이 필요할 때만 WSL 2 를 쓰고, 그때는 리눅스용 설치 명령을 WSL 터미널 안에서 실행해요.

Q. 완전히 제거하고 다시 설치하려면요?
네이티브는 %USERPROFILE%\.local\bin\claude.exe 와 .local\share\claude 폴더를 삭제하면 돼요. 설정과 대화 기록까지 지우려면 %USERPROFILE%\.claude 와 .claude.json 도 삭제하는데, 세션 기록이 전부 사라지니 신중하게 하세요.

참고 자료

Advanced setup (Claude Code 공식 문서, 시스템 요구사항·설치·업데이트·제거)
Troubleshoot installation and login (오류 문구별 해결)
Troubleshooting (실행 중 문제)
Git for Windows 다운로드

2026년 9월 11일, 클로드코드 2.1.268 기준이에요. 설치 방식과 오류 문구는 버전마다 바뀌니 막히면 claude doctor 결과를 먼저 보세요. 설치 후 오류는 클로드 오류 해결 방법 2026, 한도 문제는 클로드 사용량 한도 2026을 참고하세요.

tede

전체보기