클로드 코드 설치 오류, 문구별 해결법

이 글은 클로드 코드 왕초보 시리즈의 네 번째 편입니다. 설치 편을 그대로 따라 했는데도 빨간 글씨가 나왔을 때 무엇을 보면 되는지 정리했습니다. 설치가 잘 끝나신 분은 이 편을 건너뛰고 다음 편으로 가셔도 됩니다.

먼저 마음을 편히 가지셔도 됩니다. 이 단계에서 나는 오류는 대부분 명령을 잘못 넣었거나, 창을 새로 열지 않았거나, 인터넷 쪽이 잠시 막힌 것 셋 중 하나입니다. 컴퓨터가 망가지는 일은 없습니다.

무엇부터 해 볼까요

문구를 찾기 전에 아래 세 가지를 먼저 해 보십시오. 절반 이상은 여기서 해결됩니다.

1. 창을 완전히 닫았다가 새로 엽니다. 설치를 한 그 창은 설치 전의 상태를 그대로 들고 있습니다. 새로 생긴 프로그램을 알아보지 못합니다.
2. 내 컴퓨터에 맞는 명령인지 봅니다. 윈도우 PowerShell은 irm으로 시작하는 줄, 맥은 curl로 시작하는 줄입니다. 서로 바꿔 넣으면 무조건 오류가 납니다.
3. 몇 분 기다렸다 다시 합니다. 내려받는 쪽이 잠시 붐비면 이상한 글자가 쏟아질 수 있습니다. 시간을 조금 두고 같은 명령을 한 번 더 넣어 보십시오.

claude를 못 찾겠다고 나올 때

설치는 끝났다고 했는데 claude --version을 넣으면 이런 글이 나오는 경우입니다. 쓰시는 컴퓨터에 따라 문구가 조금씩 다릅니다.

• 맥: zsh: command not found: claude
• 윈도우 PowerShell: claude : The term 'claude' is not recognized as the name of a cmdlet
• 윈도우 CMD: 'claude' is not recognized as an internal or external command

이것은 프로그램이 안 깔린 것이 아니라, 컴퓨터가 그 프로그램이 어디 있는지 모르는 상태입니다. 창을 새로 열어도 그대로라면 위치를 직접 알려 주면 됩니다.

윈도우에서는 PowerShell에 아래 두 줄을 한 줄씩 넣습니다.

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')

[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

맥에서는 터미널에 아래 두 줄을 한 줄씩 넣습니다.

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

source ~/.zshrc

넣은 뒤에는 창을 다시 열고 claude --version을 한 번 더 해 보십시오.

윈도우에서 명령을 잘못 넣었을 때

윈도우에는 글자를 넣는 창이 두 가지 있습니다. 창을 잘못 골랐거나 다른 운영체제용 명령을 넣으면 아래 문구가 나옵니다.

화면에 나온 문구	뜻과 해결
'irm' is not recognized	지금 창이 CMD입니다. PowerShell을 열어 같은 명령을 넣으십시오.
The token '&&' is not a valid statement separator	지금 창은 PowerShell인데 CMD용 명령을 넣었습니다. irm으로 시작하는 줄을 쓰십시오.
A parameter cannot be found that matches parameter name 'fsSL'	맥·리눅스용 명령을 윈도우에 넣었습니다. irm으로 시작하는 줄을 쓰십시오.
'bash' is not recognized as the name of a cmdlet	위와 같은 경우입니다. 윈도우용 명령으로 바꾸십시오.
글자가 잔뜩 찍히기만 하고 설치가 안 됨	명령을 반 토막만 넣었습니다. | iex까지 빠짐없이 붙여 넣어야 합니다.

지금 어느 창인지는 줄 맨 앞을 보면 압니다. PS C:\로 시작하면 PowerShell, PS 없이 C:\로 시작하면 CMD입니다.

설치 주소가 이상한 것을 돌려줄 때

명령은 맞게 넣었는데 화면에 웹페이지 조각 같은 것이 쏟아지는 경우가 있습니다. 다음 문구가 보이면 이 경우입니다.

• syntax error near unexpected token '<'
• <!DOCTYPE html>이라는 글자
• curl: (22) The requested URL returned error: 403
• PowerShell에서 ParserError와 함께 HTML 조각이 인용되어 나오는 경우

설치 파일이 와야 할 자리에 웹페이지가 온 것입니다. 대개 잠깐의 문제이니 몇 분 뒤 같은 명령을 다시 해 보십시오. 그래도 같다면 다른 방법으로 설치할 수 있습니다. 윈도우는 winget install Anthropic.ClaudeCode, 맥은 brew install --cask claude-code입니다. 다만 이 방법으로 설치하면 자동 업데이트가 되지 않아 가끔 직접 갱신해 주어야 합니다.

만약 화면에 App unavailable in region이라고 나온다면 지금 계신 나라에서 서비스가 열리지 않은 경우입니다. 이때는 설치 방법을 바꿔도 해결되지 않습니다.

그 밖에 자주 보는 문구

화면에 나온 문구	해결
Claude Code does not support 32-bit Windows	시작 메뉴에서 Windows PowerShell (x86)을 연 경우입니다. 창을 닫고 (x86)이 없는 Windows PowerShell을 열어 다시 하십시오.
The process cannot access the file	앞서 하던 설치가 아직 남아 있거나 백신이 파일을 붙잡고 있습니다. 다른 PowerShell 창을 모두 닫고 Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"를 넣은 뒤 설치를 다시 하십시오.
Could not establish trust relationship for the SSL/TLS secure channel	안전한 연결을 맺지 못한 경우입니다. 먼저 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12를 넣고 설치 명령을 다시 하십시오.
running scripts is disabled on this system	Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser를 넣은 뒤 다시 하십시오.
Claude Code on Windows requires either Git for Windows ... or PowerShell	쓸 수 있는 창을 하나도 찾지 못한 경우입니다. git-scm.com/downloads/win에서 Git for Windows를 설치하고, 설치 중 PATH에 추가하는 항목을 고르십시오.
맥에서 dyld: cannot load 또는 built for Mac OS X 13.0	맥 운영체제가 오래됐습니다. macOS 13.0 이상으로 업데이트해야 합니다. 다른 설치 방법으로는 해결되지 않습니다.
맥에서 claude를 넣으면 클로드 앱이 열림	클로드 데스크톱 앱을 최신 버전으로 업데이트하면 해결됩니다.

그래도 막히면 진단을 돌려 보세요

클로드 코드에는 스스로 상태를 점검하는 기능이 있습니다. claude --version은 되는데 그다음이 이상할 때 써 보시면 좋습니다. 터미널이나 PowerShell에 아래 한 줄을 넣습니다.

claude doctor

클로드 코드가 이미 실행 중이라면 입력칸 맨 앞에서 /doctor라고 넣어도 같은 점검을 합니다. 결과에 나오는 영어는 다 읽지 않으셔도 됩니다. 문제가 있는 줄만 표시해 주니, 그 문구를 위 표에서 찾아보시면 됩니다.

자주 묻는 질문

함께 보면 좋은 글

• 클로드 코드 왕초보 시리즈 전체 목차 — 윈도우 설치 편과 맥 설치 편을 먼저 보시고 이 글로 돌아오시면 됩니다.

참고: 공식 문서 설치 및 로그인 문제 해결 · 공식 문서 빠른 시작