Claude Code 설치 가이드

PowerShell 명령어 한 줄이면 끝

PowerShell 창(프롬프트가 PS로 시작)에 아래를 붙여넣고 Enter만 누르면 됩니다. 내 계정의 PATH에만 추가하는 안전한 방식이에요.

① 모델명 → ② 세션 경과시간 → ③ 컨텍스트 사용률 %(50% 미만 초록 · 50~79% 노랑 · 80% 이상 빨강) → ④ 세션 누적 비용 $ → ⑤ 5시간/7일 사용량 한도 %/% → ⑥ 5시간 한도 리셋 시각 → ⑦ git 브랜치명(저장소 아니면 생략) → ⑧ 세션 이름(없으면 생략) → ⑨ 서브에이전트 이름(메인 세션이면 생략) → ⑩ 로그인 계정 이메일 → ⑪ git 변경 파일 수 +스테이징~수정(변경 없으면 생략)

Node.js가 없다면 — WinGet으로 설치 (한 줄)

'node'은(는) 내부 또는 외부 명령... 이 아닙니다가 나왔다면 아직 없는 것입니다. CMD · PowerShell 어디서든 아래 한 줄이면 끝나요.

WinGet이 없다면 nodejs.org에서 설치 파일(LTS 버전)을 직접 받아 '다음'만 눌러도 됩니다. 설치가 끝나면 터미널을 완전히 닫고 새로 열어야 node 명령이 인식됩니다.

원인 PowerShell용 명령(irm …)을 CMD 창에 입력했어요.
해결 PowerShell을 새로 열거나(⊞ Win + X), 위의 CMD용 curl 명령을 사용하세요.

원인 CMD용 명령(curl … && …)을 PowerShell 창에 입력했어요.
해결 PowerShell용 명령(irm https://claude.ai/install.ps1 | iex)을 사용하세요.
참고 이 오류는 구형 5.1에서만 납니다. 최신 PowerShell 7은 &&를 지원해서 오류가 나지 않아요. 그래도 PowerShell에서는 PowerShell용 명령을 쓰는 게 가장 안전합니다.

아래 Q3~Q7처럼 구형 5.1 특유의 오류가 계속되면 PowerShell 7을 설치해 보세요. 필수는 아니지만 잔오류들이 대부분 사라집니다. 아래 한 줄이면 끝나요.

WinGet이 없다면 설치 파일(MSI)을 직접 받아 ‘다음’만 누르면 됩니다 → aka.ms/powershell
설치 후 ⊞ Win + R → pwsh 입력 → 확인 (또는 시작 메뉴에서 ‘PowerShell 7’ 검색, Windows 11 터미널이면 상단 ∨ 화살표 → PowerShell).

원인 Windows의 기본 보안 설정(실행 정책)이 .ps1 스크립트 파일 실행을 막고 있습니다. 주로 npm으로 설치했을 때 npm.ps1 · claude.ps1에서 발생해요.
해결 1 (권장) 내 계정에만 적용되는 안전한 설정으로 바꿉니다. 아래를 붙여넣고 Y + Enter.

해결 2 claude 대신 claude.cmd, npm 대신 npm.cmd를 입력해도 됩니다(실행 정책이 적용되지 않는 파일).
해결 3 아예 네이티브 설치(irm … | iex)로 바꾸세요. 이 방식은 스크립트 파일을 만들지 않아 실행 정책의 영향을 받지 않습니다.
※ 학교 PC에서 그룹 정책으로 잠겨 있어 위 명령이 거부되면 정보 담당 선생님께 문의하세요.

원인 구형 5.1 콘솔의 기본 글꼴·문자표(코드 페이지)가 한글 UTF-8과 맞지 않아서입니다.
해결 1 (임시) 창을 열 때마다 아래를 한 번 실행 — 그 창에서만 적용됩니다.

해결 2 (창 설정) 창 제목 표시줄 오른쪽 클릭 → 속성 → 글꼴에서 맑은 고딕이나 MS Gothic으로 바꿉니다.
해결 3 (근본) Windows 터미널 + PowerShell 7로 옮기면 이 문제가 거의 사라집니다. → 위 PowerShell 7로 업그레이드 안내 참고

원인 맥·리눅스용 curl -fsSL … | bash 명령을 구형 PowerShell에 붙여넣었어요. 구형 5.1에서는 curl이 진짜 curl이 아니라 Invoke-WebRequest의 별명이라 -fsSL 옵션을 못 알아듣습니다. ('bash'은(는) cmdlet … 이 아닙니다도 같은 원인)
해결 PowerShell용 명령 irm https://claude.ai/install.ps1 | iex를 쓰세요. 꼭 진짜 curl을 써야 한다면 curl.exe라고 확장자까지 입력하면 됩니다.

원인 2025년 12월 9일 이후 Windows 보안 업데이트(CVE-2025-54100)로, 구형 5.1의 Invoke-WebRequest가 웹 내용을 해석하기 전에 사용자 확인을 받도록 바뀌었습니다. Windows 10 · 11 모두 해당됩니다.
해결 1 설치용 irm … | iex는 대개 그대로 진행됩니다. 확인 창이 뜨면 내용을 확인하고 진행하세요.
해결 2 직접 작성한 스크립트에서 계속 뜬다면 -UseBasicParsing을 붙이거나, 창 맨 처음에 아래 한 줄을 실행해 두면 더 이상 묻지 않습니다.

원인 시작 메뉴에는 Windows PowerShell과 Windows PowerShell (x86) 두 개가 있는데, (x86)으로 열면 64비트 PC에서도 이 오류가 납니다. 컴퓨터가 32비트라서가 아닙니다.
해결 아래로 내 PC를 확인하고(True면 정상), 창을 닫은 뒤 (x86)이 없는 ‘Windows PowerShell’로 다시 열어 설치하세요.

해결 설치 직후 가장 흔한 증상이에요. 터미널 창을 완전히 닫고 새로 열면 대부분 해결됩니다. 그래도 안 되면 컴퓨터를 재시작해 보세요.

원인 설치 프로그램이 PATH 등록을 놓친 알려진 문제이거나, 예전에 npm으로 설치한 것이 남아 충돌하는 경우입니다.
해결 1 새 창을 열고 where.exe claude로 실제 위치를 확인 → 여러 줄이 나오면 충돌입니다.
해결 2 예전 npm 설치본을 지운 뒤 네이티브로 다시 설치합니다.

해결 3 그래도 안 되면 위 05 · PATH 설정 섹션의 한 줄 등록을 실행하고 창을 새로 여세요.

원인 앞선 설치 시도가 아직 돌고 있거나, 백신 프로그램(V3 등)이 내려받는 중인 파일을 검사하며 붙잡고 있어서입니다. 학교 PC에서 자주 나옵니다.
해결 다른 PowerShell 창을 모두 닫고 1~2분 기다린 뒤, 아래로 임시 폴더를 지우고 다시 설치하세요.

원인 학교 방화벽·보안 장비가 설치 스크립트 대신 차단 안내 웹페이지(HTML)를 돌려줘서, 그 내용을 명령으로 잘못 실행한 것입니다.
해결 네트워크가 막힌 상태이므로 명령을 고쳐도 소용없습니다. 아래 Q13의 방화벽 해결을 먼저 진행하세요.

해결 무료 플랜 계정은 Claude Code를 쓸 수 없습니다. Pro · Max · Team 등 유료 플랜인지 확인하세요. 브라우저가 열리지 않으면 다른 브라우저를 기본으로 설정해 보세요.

해결 학교 방화벽이나 보안 프로그램이 다운로드를 막는 경우가 있어요. 정보 담당 선생님께 claude.ai 접속 허용을 요청하거나, 다른 네트워크에서 시도해 보세요.
먼저 확인 아래로 서버까지 닿는지 봅니다. 200이 나오면 네트워크는 정상이에요.

프록시를 쓰는 학교라면 주소를 알려주면 이렇게 설정한 뒤 설치할 수 있습니다(proxy.example.com:8080 부분을 학교 주소로 교체).