설치는 끝났다고 나왔는데 claude를 쳤을 때 아무 일도 일어나지 않는다면, 대부분은 프로그램이 망가진 것이 아니다. 막힌 층이 어디인지만 가려내면 처방은 거의 정해져 있다. 이 글은 Windows에서 처음 실행할 때 나오는 오류를 증상 문구별로 모아 정리한 것이다. 앞의 여섯 항목은 공식 문서에서 확인한 내용이고 링크를 함께 달았다. 뒤의 세 항목은 우리가 이 컴퓨터에서 직접 겪은 것이라 공식 문서에는 없다. 어느 쪽인지 항목마다 밝혀 두었다.
어떤 문구가 떴는가
지금 화면에 나온 문구와 가장 비슷한 항목으로 바로 가면 된다. 초보일 때는 원인을 몰라도 괜찮다. 증상만 알면 충분하다.
- 1.
claude를 쳤는데 명령을 찾을 수 없다고 나온다 (공식 문서) - 2. 설치는 성공했다는데 새 창에서만 되거나, 옛 버전이 나온다 (공식 문서)
- 3. 설치 명령 자체가 오류를 낸다 —
bash,fsSL,&&,irm(공식 문서) - 4.
Claude Code does not support 32-bit Windows가 나온다 (공식 문서) - 5.
running scripts is disabled on this system이 나온다 (공식 문서) - 6. 켜지기는 하는데 로그인이 안 된다 (공식 문서)
- 7. 점검 도구가 한글 콘솔에서 통째로 멈춘다 —
cp949(우리 실측) - 8. 분명히 설치했는데 자동 점검이 미설치라고 한다 (우리 실측)
- 9. 어제까지 되던 명령이 셸을 바꾸니 사라졌다 (우리 실측)
1. claude를 쳤는데 명령을 찾을 수 없다고 나온다
증상. 화면에 command not found: claude 또는 'claude' is not recognized가 나온다. 설치는 분명히 끝났는데 명령만 없는 것처럼 보인다.
왜 그런가. 공식 문서는 이렇게 설명한다. 설치는 됐지만 설치 폴더가 PATH에 없다는 뜻이고, 셸은 PATH에 적힌 폴더만 뒤져서 프로그램을 찾는다. Windows에서 설치 파일이 놓이는 자리는 %USERPROFILE%\.local\bin\claude.exe다.
확인 명령. PowerShell에서 그 폴더가 PATH에 들어 있는지 본다.
$env:PATH -split ';' | Select-String '\.local\\bin'
처방. 위 명령이 아무것도 출력하지 않으면 PATH에 없는 것이다. 공식 문서가 안내하는 대로 사용자 PATH에 추가한다.
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
공식 문서는 여기에 한 줄을 덧붙인다. “Restart your terminal for the change to take effect.” 즉 창을 다시 열어야 반영된다.
확인 방법. 새 터미널 창을 열고 claude --version을 실행한다. 공식 문서 기준으로 정상 설치라면 2.1.211 (Claude Code)처럼 버전 번호가 찍힌다.
한 가지 주의할 점이 문서에 따로 적혀 있다. VS Code 확장만 설치한 경우에는 claude가 그 자리에 놓이지 않는다. 확장은 자기 채팅 창을 위해 CLI 사본을 확장 폴더 안에 따로 두고 PATH에 추가하지 않기 때문이다. 터미널에서 claude를 쓰려면 별도 설치가 필요하다.
2. 설치는 성공했다는데 새 창에서만 되거나, 옛 버전이 나온다
증상. 설치 로그는 성공인데 방금 설치한 그 창에서만 claude를 못 찾는다. 또는 분명히 새로 설치했는데 옛 버전 번호가 찍힌다.
왜 그런가. 공식 문서의 설명은 짧고 분명하다. “the session you installed from keeps its old PATH.” 설치 프로그램이 PATH를 바꿔도 이미 열려 있던 창은 예전 PATH를 그대로 들고 있다. 고객지원 문서도 Windows에서는 “Close and reopen PowerShell”이라고 안내한다.
확인 명령. 지금 창에서 실패하는지, 새 창에서도 실패하는지를 나눠서 본다.
claude --version
처방. 창을 완전히 닫고 새 창을 열어 같은 명령을 다시 실행한다. 이것만으로 끝나는 경우가 많다.
확인 방법. 새 창에서 버전 번호가 찍히면 해결된 것이다. 새 창에서도 여전히 못 찾으면 1번 항목의 PATH 문제로 넘어간다.
3. 설치 명령 자체가 오류를 낸다
증상. Claude Code를 켜기도 전에 설치 명령이 튕긴다. 공식 문서가 열거한 문구는 이렇다.
'bash' is not recognized as the name of a cmdlet
A parameter cannot be found that matches parameter name 'fsSL'
The token '&&' is not valid
'irm' is not recognized
왜 그런가. 공식 문서는 이 네 가지를 모두 같은 원인으로 묶는다. 다른 셸이나 다른 운영체제용 설치 명령을 복사해 온 것이다. 예를 들어 curl -fsSL ... | bash는 macOS와 Linux용인데, Windows PowerShell에서는 curl이 Invoke-WebRequest의 별칭이라서 -fsSL 같은 옵션을 거부한다.
확인 명령. 내가 지금 어느 셸에 있는지부터 확인한다. 공식 문서가 알려주는 구분법은 프롬프트 모양이다. “Your prompt shows PS C:\ when you’re in PowerShell and C:\ without the PS when you’re in CMD.”
처방. 셸에 맞는 설치 명령을 쓴다. 공식 문서에 적힌 그대로다.
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
설치 명령을 쳤는데 스크립트 내용만 화면에 쭉 출력되고 아무것도 설치되지 않는 경우도 있다. 공식 문서는 이것을 명령의 앞부분만 실행한 상태로 설명한다. irm https://claude.ai/install.ps1만 쓰면 내려받은 스크립트를 화면에 인쇄하고 끝난다. 실행까지 하려면 | iex를 붙여야 한다.
확인 방법. 새 터미널을 열고 claude --version으로 버전 번호를 확인한다.
4. Claude Code does not support 32-bit Windows가 나온다
증상. 64비트 컴퓨터를 쓰는데도 32비트를 지원하지 않는다는 오류가 나온다.
왜 그런가. 공식 문서의 설명은 이렇다. 시작 메뉴에는 PowerShell 항목이 두 개 있다. Windows PowerShell과 Windows PowerShell (x86)이다. x86 항목은 32비트 프로세스로 실행되며, 문서 표현대로 “triggers this error even on a 64-bit machine”이다. 즉 컴퓨터가 아니라 창을 잘못 연 것이다.
확인 명령. 오류가 난 바로 그 창에서 실행한다.
[Environment]::Is64BitOperatingSystem
처방. True가 나오면 운영체제는 문제가 없다. 그 창을 닫고 (x86)이 붙지 않은 Windows PowerShell을 열어 설치 명령을 다시 실행한다. False가 나오면 32비트 Windows를 쓰는 것이고, 이 경우에는 64비트 운영체제가 필요하다. 공식 시스템 요건은 Windows 10 1809 이상 또는 Windows Server 2019 이상, 4GB 이상 메모리, x64 또는 ARM64 프로세서다.
확인 방법. x86이 아닌 창에서 설치한 뒤 claude --version으로 버전 번호를 확인한다.
5. running scripts is disabled on this system이 나온다
증상. npm으로 설치했거나 npm으로 설치한 claude를 실행할 때 보안 오류가 난다. 공식 문서가 실은 원문은 이렇다.
npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts
is disabled on this system.
+ CategoryInfo : SecurityError: (:) [], PSSecurityException
원문 메시지 끝에는 마이크로소프트의 실행 정책 문서를 가리키는 주소가 한 줄 더 붙는다. 위 인용에서는 그 주소만 덜어냈고, 같은 문서를 이 글 맨 아래 출처에 링크해 두었다.
왜 그런가. 공식 문서는 원인을 이렇게 짚는다. PowerShell의 실행 정책이 npm이 만들어 놓은 .ps1 실행 스크립트를 막고 있는 것이다. 같은 오류가 claude.ps1 이름으로도 나온다. 문서는 이 정책이 스크립트 파일에만 적용되므로 PowerShell 설치 명령 irm https://claude.ai/install.ps1 | iex에는 영향을 주지 않는다고 덧붙인다. 내려받은 글자를 바로 실행하는 방식이라 그렇다.
실행 정책이 무엇인지는 마이크로소프트 공식 문서에 정의돼 있다. 문서는 실행 정책을 “a safety feature that controls the conditions under which PowerShell loads configuration files and runs scripts”라고 설명한다. 이 글에서 쓰는 RemoteSigned는 문서 표현으로 “Requires a digital signature from a trusted publisher on scripts and configuration files that are downloaded from the internet”이고 “Doesn’t require digital signatures on scripts that are written on the local computer and not downloaded from the internet”이다. 즉 인터넷에서 받은 스크립트만 서명을 요구하고, 내 컴퓨터에서 만들어진 스크립트는 그대로 실행한다.
한 가지 헷갈리기 쉬운 대목이 있어 그대로 옮긴다. 같은 문서는 RemoteSigned를 “The default execution policy for Windows computers”라고 적으면서, 동시에 “If no execution policy is set in any scope, the effective execution policy is Restricted, which is the default for Windows clients”라고도 적는다. 두 문장이 함께 있으니, 내 컴퓨터가 지금 어떤 상태인지는 추측하지 말고 직접 확인하는 편이 정확하다.
확인 명령. 현재 적용 중인 정책을 범위별로 본다.
Get-ExecutionPolicy -List
처방. 공식 문서가 제시하는 방법은 세 가지다. 첫째, 내 계정 범위에서 로컬 스크립트를 허용한다.
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
둘째, .ps1 대신 .cmd 실행 파일을 부른다. 문서 설명대로 npm.cmd와 claude.cmd는 같은 일을 하고 정책 적용 대상이 아니다. 셋째, npm 대신 PowerShell 설치 명령을 쓴다. 스크립트가 아니라 실행 파일을 설치하는 방식이다. 마이크로소프트 문서는 Set-ExecutionPolicy의 변경이 즉시 적용되며 PowerShell을 다시 시작할 필요가 없다고 적는다.
확인 방법. Get-ExecutionPolicy -Scope CurrentUser가 RemoteSigned를 돌려주는지 보고, 이어서 claude --version으로 버전 번호를 확인한다.
6. 켜지기는 하는데 로그인이 안 된다
증상. claude는 켜지는데 로그인 단계에서 멈춘다. 브라우저가 저절로 열리지 않거나, OAuth error: Invalid code가 나오거나, 로그인 뒤에 403 Forbidden이 나온다.
먼저 확인할 것. 공식 문서는 계정 조건을 명확히 적어 두었다. Claude Code는 Pro, Max, Team, Enterprise, Console 계정이 필요하고 “The free Claude.ai plan does not include Claude Code access.” 무료 요금제로는 접근이 되지 않으니, 설치 문제로 오래 헤매기 전에 계정 종류부터 확인하는 편이 빠르다.
확인 명령. Claude Code 안에서 현재 어떤 인증 방식이 쓰이는지 본다.
/status
처방. 공식 문서가 안내하는 순서는 이렇다. 원인이 분명하지 않을 때는 로그인을 깨끗하게 다시 한다. /logout으로 완전히 로그아웃하고, Claude Code를 닫고, claude로 다시 시작해 인증을 처음부터 진행한다. 브라우저가 저절로 열리지 않으면 c를 눌러 인증 주소를 복사한 뒤 브라우저에 직접 붙여 넣는다. 터미널이 좁아 주소가 여러 줄로 잘려 클릭이 안 될 때도 같은 방법을 쓴다.
OAuth error: Invalid code. Please make sure the full code was copied가 나오는 경우, 문서는 코드가 만료됐거나 복사 과정에서 잘렸다고 설명한다. 브라우저가 열린 뒤 지체 없이 로그인을 마치는 것이 처방이다.
로그인은 됐는데 403 Forbidden이 나오는 경우에는 환경 변수를 본다. 문서 설명대로 ANTHROPIC_API_KEY가 설정돼 있고 그 키를 승인해 둔 상태라면, Claude Code는 구독 계정의 인증 대신 그 키를 쓴다. Windows에서는 PowerShell 프로필($PROFILE)과 사용자 환경 변수에서 ANTHROPIC_API_KEY를 확인하라고 안내한다.
확인 방법. /status로 지금 활성화된 인증 방식이 의도한 것과 같은지 확인한다.
7. 점검 도구가 한글 콘솔에서 통째로 멈춘다
여기서부터 세 항목은 공식 문서에 없다. 우리가 이 컴퓨터에서 직접 겪은 것이다.
증상. 설치 상태를 점검하려고 돌린 진단 스크립트가 아래 오류를 내고 그 자리에서 죽었다. 점검 결과를 한 줄도 못 봤다.
UnicodeEncodeError: 'cp949' codec can't encode character '\u2014'
무엇이 문제였나. 정확히 밝혀 둔다. 죽은 것은 Claude Code 본체가 아니라 우리가 만든 파이썬 진단 스크립트였다. 원인은 프로그램 논리가 아니라 글자였다. 한국어 Windows 콘솔의 기본 인코딩은 cp949이고, 여기에는 줄표(U+2014, em dash)를 표현할 자리가 없다. 진단 결과를 출력하는 문장에 줄표가 한 글자 들어 있었고, 그 한 글자를 인코딩하는 순간 예외가 나면서 진단이 통째로 중단됐다. 설치 상태는 아무 문제가 없었다.
확인 명령. 지금 파이썬이 어떤 인코딩으로 출력하는지 본다.
python -c "import sys; print(sys.stdout.encoding)"
처방. 우리가 실제로 쓴 방법은 출력 인코딩을 UTF-8로 고정하는 것이었다. 파이썬은 환경 변수로 이것을 지정할 수 있다.
$env:PYTHONUTF8 = "1"
$env:PYTHONIOENCODING = "utf-8"
덧붙이자면, 겪고 나서 우리가 코드에 남긴 교훈은 다른 쪽이었다. 진단 도구의 출력 문장은 예쁜 기호를 쓰지 않는 편이 낫다는 것이다. 줄표 대신 붙임표를 쓰면 이 고장 자체가 생기지 않는다. 도구가 멈추면 정작 확인하려던 사실을 아무것도 못 보게 된다.
확인 방법. 같은 스크립트를 다시 돌려 끝까지 출력이 나오는지 본다. 위 확인 명령이 utf-8을 돌려주면 인코딩은 잡힌 것이다.
8. 분명히 설치했는데 자동 점검이 미설치라고 한다
증상. 파일 탐색기로 확인하면 실행 파일이 그 자리에 분명히 있다. 그런데 우리가 만든 자동 점검이 그 CLI를 미설치로 판정했다.
무엇이 문제였나. 실행 파일은 실재했고, 문제는 점검을 수행한 쪽의 PATH였다. 우리 자동 점검은 별도 프로세스를 띄워서 명령을 찾는데, 그 프로세스가 물려받은 PATH에 해당 폴더가 들어 있지 않았다. 그래서 파일이 있는데도 없다고 보고했다. 사람이 직접 창을 열어 실행하면 되는데 자동 점검만 실패하는 상태였고, 우리는 이 차이를 알아채기까지 시간을 썼다.
이 오판정은 1번 항목과 뿌리가 같다. 셸이든 자동화든 프로그램을 찾는 방법은 PATH뿐이라, PATH를 물려받지 못한 프로세스에게는 그 파일이 존재하지 않는 것과 같다. 다른 점은 하나다. 1번은 사람이 오류 문구를 보고, 8번은 자동화가 조용히 잘못된 결론을 남긴다.
확인 명령. 지금 이 창에서 찾을 수 있는지, 그리고 파일이 실재하는지를 따로 확인한다. 둘의 답이 갈리면 PATH 문제다.
where.exe claude
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
처방. 파일은 있는데 where.exe가 못 찾으면 1번 항목의 PATH 추가를 적용한다. 자동화 쪽이라면 자동화가 띄우는 프로세스의 PATH에 그 폴더가 들어가는지를 따로 확인해야 한다. 사람이 쓰는 창에서만 고쳐 놓으면 자동 점검은 계속 미설치라고 답한다.
확인 방법. where.exe claude가 경로를 출력하고, 자동 점검을 다시 돌렸을 때 같은 결론이 나오는지 본다. 사람과 자동화의 답이 일치하는 상태가 정상이다.
9. 어제까지 되던 명령이 셸을 바꾸니 사라졌다
증상. 잘 쓰던 CLI가 어느 날 없는 명령이 됐다. 우리 경우에는 셸을 바꿔서 새로 열었을 때였다.
무엇이 문제였나. 정확히 적어 둔다. 이때 사라진 것은 Claude Code가 아니라, 같은 컴퓨터에 npm 전역 설치로 넣어 둔 다른 CLI였다. 그 컴퓨터에는 Node 버전 관리자(fnm)가 깔려 있었고, npm 전역 설치는 버전 관리자가 셸마다 만들어 주는 경로 아래로 들어갔다. 그 경로는 셸 세션에 딸린 임시 경로여서, 셸이 바뀌자 그대로 사라졌다. 파일이 지워진 것이 아니라 그 경로를 아무도 안 보게 된 것이다.
처방. 우리가 쓴 해법은 셸에 딸리지 않는 안정된 절대경로에 실행 지점을 고정하는 것이었다. 구체적으로는 ~/.local/bin 아래에 작은 실행 파일을 두고 그것을 부르게 했다. 그 뒤로는 셸이 바뀌어도 같은 자리에서 실행된다.
Claude Code에는 이 문제가 애초에 덜 생긴다. 공식 문서에 따르면 기본 설치 방식은 %USERPROFILE%\.local\bin\claude.exe라는 고정된 자리에 실행 파일을 놓기 때문이다. npm 전역 설치를 택할 때만 위와 같은 상황을 고려하면 된다. 참고로 공식 문서는 npm 설치에 대해 “Do NOT use sudo npm install -g“라고 경고하고, npm 패키지도 결국 같은 네이티브 실행 파일을 설치한다고 설명한다.
확인 방법. 셸을 바꿔 새 창을 열고 where.exe claude가 같은 경로를 출력하는지 본다. 셸에 따라 결과가 달라지면 아직 휘발성 경로에 물려 있는 것이다.
정리
아홉 가지를 봤지만 실제로 층은 네 개다. 설치 명령을 셸에 맞게 골랐는가, 설치 폴더가 PATH에 있는가, 지금 창이 새 PATH를 들고 있는가, 정책과 계정이 막고 있지는 않은가. 이 네 가지를 순서대로 짚으면 대부분 끝난다.
마지막으로 점검 명령 하나를 적어 둔다. 공식 문서는 설치와 설정을 자세히 보려면 claude doctor를 실행하라고 안내한다. 문서 설명으로는 세션을 시작하지 않고 읽기 전용 진단만 출력하며, 설치 상태와 설정 파일 오류, 권장 조치가 함께 나온다.
claude doctor
우리가 겪은 세 가지에서 남은 교훈은 하나로 모인다. 프로그램이 없다는 메시지는 대체로 프로그램이 없다는 뜻이 아니고, 그것을 찾는 쪽이 어디를 보는지의 문제였다. 그리고 점검 도구는 자기가 먼저 멈추지 않아야 쓸모가 있다.
출처
- Claude Code 공식 문서, 설치와 로그인 문제 해결: https://code.claude.com/docs/en/troubleshoot-install — PATH 확인과 추가, 셸 세션, 잘못된 설치 명령, 32비트 오류, 실행 정책, 로그인 문제
- Claude Code 공식 문서, 고급 설치: https://code.claude.com/docs/en/setup — 시스템 요건, 운영체제별 설치 명령,
claude --version과claude doctor, 계정 요건 - Claude 고객지원 문서, 설치와 인증 문제 해결: https://support.claude.com/en/articles/14552646-troubleshoot-claude-code-installation-and-authentication — Windows에서 PowerShell을 닫고 다시 열라는 안내
- Microsoft Learn, about_Execution_Policies: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies — 실행 정책의 정의,
RemoteSigned의 의미, 범위와 우선순위, 변경 즉시 적용
7번부터 9번까지는 2026년 9월에 우리 환경에서 직접 확인한 것이며 공식 문서의 내용이 아니다. 나머지 항목의 문구와 명령은 위 출처에서 인용했다.