클로드 코드 설치가 안 되는 흔한 원인은 명령을 못 찾는 PATH 문제, 창에 맞지 않는 명령, 설치 파일 대신 웹페이지가 온 경우, 네트워크 차단, 로그인과 계정 문제 다섯 가지입니다. 화면에 뜬 오류 문구로 어느 쪽인지 가릴 수 있습니다.
앞의 넷은 공식 「설치 및 로그인 문제 해결」 문서의 「일반적인 설치 문제」 절에서, 다섯째는 「로그인 및 인증」 절에서 골랐습니다. 2026년 10월 21일 공식 Claude Code 문서를 직접 읽고 증상과 고치는 법을 짝지었습니다.
1. 클로드 코드 설치가 안 되는 이유는 무엇인가요?
PATH, 엇갈린 명령, 웹페이지 응답, 네트워크, 로그인 다섯 가지를 먼저 봅니다. 공식 문서는 맨 앞에 「표시되는 내용」과 「해결책」을 짝지은 표를 두고, 내 화면의 오류 문구를 그 표에서 찾으라고 안내합니다.
터미널(글자로 명령을 입력하는 창)에 뜬 영어 문구를 그대로 복사해 두면 찾기 쉽습니다.
오류 문구가 없고 그냥 안 되는 것 같다면, 먼저 새 터미널 창을 열고 claude --version을 입력해 봅니다. 버전 번호가 나오면 설치는 된 것이고, 아래 다섯 가지 중 어디에 해당하는지 좁혀 가면 됩니다.
2. 원인 1. 설치는 됐는데 claude를 못 찾습니다
맥은 zsh: command not found: claude, 윈도우는 'claude' is not recognized가 뜹니다. 공식 문서는 원인을 이렇게 적었습니다.
설치가 성공했지만 claude를 실행할 때 command not found 또는 not recognized 오류가 발생하면 설치 디렉터리가 PATH에 없습니다.
PATH는 터미널이 명령을 찾아보는 폴더 목록입니다. 먼저 창을 새로 열어 봅니다. 이미 열려 있던 창과 편집기 안의 터미널은 예전 PATH를 그대로 쓰기 때문입니다.
새 창에서도 안 되면 설치 폴더를 PATH에 넣습니다. 맥은 맥 설치 글에, 윈도우는 윈도우 설치 글에 공식 명령을 그대로 옮겨 두었습니다.
VS Code 확장(편집기에 덧붙이는 기능)만 깔았다면 터미널에서는 claude가 없는 것이 정상입니다. 공식 문서는 확장이 자기 안에 따로 복사본을 두고 PATH에 넣지 않는다고 설명합니다. 터미널에서 쓰려면 설치 명령을 따로 실행합니다.
3. 원인 2. 창과 명령이 엇갈렸습니다
윈도우에서 자주 납니다. 설치 명령은 PowerShell용, CMD용, 맥·리눅스용이 따로 있고, 다른 창에 넣으면 오류가 납니다. 오류 문구로 어느 쪽인지 알 수 있습니다.
'irm' is not recognized— CMD에 PowerShell 명령을 넣었습니다The token '&&' is not a valid statement separator— PowerShell에 CMD 명령을 넣었습니다A parameter cannot be found that matches parameter name 'fsSL'— PowerShell에 맥·리눅스 명령을 넣었습니다
윈도우라면 PowerShell을 열고 irm https://claude.ai/install.ps1 | iex를 넣으면 세 경우가 모두 풀립니다. 명령 앞부분만 넣으면 설치 없이 스크립트 글자만 화면에 찍히니, 한 줄을 통째로 붙여넣습니다.
4. 원인 3. 설치 파일 대신 웹페이지가 왔습니다
맥에서 syntax error near unexpected token '<', 윈도우에서 HTML 태그가 섞인 오류, 또는 403 오류가 보이면 이 경우입니다. 설치 주소가 설치 스크립트가 아니라 웹페이지나 오류 응답을 돌려준 것입니다.
오류에 「App unavailable in region」이 보이면 클로드 코드를 쓸 수 없는 국가입니다. 그 밖에는 회사 프록시·방화벽, 지역 경로, 일시적인 서비스 중단이 원인일 수 있다고 공식 문서는 적었습니다.
공식 해결책은 두 가지입니다. 몇 분 뒤 같은 명령을 다시 실행하거나, 맥은 brew install --cask claude-code, 윈도우는 winget install Anthropic.ClaudeCode로 다른 설치 방법을 씁니다.
이 문제는 일시적인 경우가 많아, 다른 방법을 찾기 전에 몇 분 기다렸다 같은 명령을 다시 넣어 보는 것이 먼저입니다.
5. 원인 4. 네트워크가 다운로드를 막고 있습니다
Failed to fetch version은 설치 프로그램이 다운로드 서버인 downloads.claude.ai에 닿지 못했다는 뜻입니다. 회사 방화벽이나 프록시(회사 인터넷이 거쳐 가는 중계 서버)가 흔한 원인입니다.
TLS connect error는 보안 연결이 실패했다는 뜻입니다. 공식 문서는 시스템 인증서 업데이트를 먼저 권하고, 회사 프록시도 원인이 될 수 있다고 적었습니다.
회사 네트워크라면 공식 문서는 설치 전에 HTTPS_PROXY와 HTTP_PROXY를 프록시 주소로 설정하라고 안내합니다. 프록시 주소를 모르면 회사 IT 담당자에게 묻습니다.
오래된 Windows 10에서 Could not create SSL/TLS secure channel이 뜨면 TLS 1.2를 켜는 줄을 먼저 실행합니다. 이 명령은 윈도우 설치 글에 적어 두었습니다.
6. 원인 5. 로그인과 계정에서 막힙니다
설치는 끝났는데 로그인에서 멈추는 경우도 있습니다. 먼저 계정을 확인합니다. 클로드 코드는 Pro, Max, Team, Enterprise 또는 Console 계정이 필요하고, 무료 claude.ai 플랜에는 포함되지 않습니다.
로그인 뒤 API Error: 403 Request not allowed가 뜨면 Pro·Max 사용자는 claude.ai 설정에서 구독이 활성 상태인지 봅니다. 회사 프록시 뒤에 있으면 프록시가 요청을 막을 수도 있습니다.
원인이 분명하지 않으면 공식 문서의 로그인 재설정 순서를 따릅니다. /logout으로 로그아웃하고, 클로드 코드를 닫고, claude로 다시 시작해 로그인합니다. 브라우저가 안 열리면 c를 눌러 로그인 주소를 복사합니다.
7. 그래도 모르겠다면 claude doctor부터
claude --version이 된다면 claude doctor를 실행합니다. 세션을 시작하지 않고 설치 상태와 설정 오류, 고칠 방법을 한 번에 보여 줍니다.
오류 문구를 그대로 복사해 두면 공식 문서의 표에서 원인을 찾기도, 다른 사람에게 도움을 청하기도 쉬워집니다. 계정 문제라면 claude.ai에 로그인해 왼쪽 아래 이니셜에서 도움말 받기로 Anthropic 지원팀에 문의할 수 있습니다.
터미널이 계속 낯설다면 터미널 없이 쓰는 클로드 데스크톱 앱으로 시작하는 길도 공식 문서에 있습니다.
처음부터 다시 깔려면 클로드 코드 설치 윈도우나 클로드 코드 설치 mac을, 전체 흐름은 클로드 코드 사용방법 총정리를 보세요.
VS Code에서 헤맨 경험담은 클로드 코드를 VS Code에 설치하면서 헤맸던 지점들에 있습니다.
참고자료 (모두 2026년 10월 21일 확인)
- Claude Code 문서 「설치 및 로그인 문제 해결」 — code.claude.com/docs/ko/troubleshoot-install
- Claude Code 문서 「고급 설정」 — code.claude.com/docs/ko/setup
- Claude Code 문서 「새로운 사용자를 위한 터미널 가이드」 — code.claude.com/docs/ko/terminal-guide
#클로드코드 #클로드코드설치 #클로드코드오류 #설치문제해결 #AI코딩도구
