> ## Content Index
> Fetch the complete content index at: https://zerodraftlab.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# 클로드 코드 설치 방법: Mac·Windows 명령어와 막히는 오류
- URL: https://zerodraftlab.com/claude-code-install-guide/
- Published: 2026-11-01T01:38:32.000Z
- Updated: 2026-11-02T04:20:47.000Z
- Description: 클로드 코드 설치 명령어를 Mac, Windows, Linux별로 정리했다. 무료 계정 제한, PATH 오류, PowerShell과 CMD 혼동까지 2026년 11월 공식 문서로 확인했다.
- Author: JooMong
- Tags: 무료

클로드 코드(Claude Code)는 터미널에 명령어 한 줄을 붙여 넣으면 설치된다. 설치보다 자주 막히는 곳은 그다음이다. 무료 계정으로는 쓸 수 없고, Windows에서는 PowerShell과 CMD의 명령어가 다르다. 아래 내용은 2026년 11월 1일에 [Anthropic 공식 설치 문서](https://code.claude.com/docs/en/setup?ref=zerodraftlab.com)에서 확인했다.

본문의 "Astra 첨언"은 OpenAI Codex의 GPT-6 Astra가 이 글을 읽고 남긴 말이다. 사람의 사용 경험담이 아니라 코딩 에이전트 관점의 판단이다.

## 클로드 코드 설치 전에 확인할 조건

- **운영체제:** macOS 13.0 이상, Windows 10 1809 이상 또는 Windows Server 2019 이상, Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상.
- **하드웨어:** RAM 4GB 이상, x64 또는 ARM64 프로세서.
- **인터넷:** 연결이 필요하다.
- **계정:** Pro, Max, Ultra, Team, Enterprise 또는 Console 계정이 필요하다. 무료 claude.ai 플랜에는 Claude Code가 포함되지 않는다.

요금이 고민이라면 [클로드 코드 가격 정리](https://zerodraftlab.com/claude-code-pricing-plans/)를 먼저 보면 된다.

## 운영체제별 클로드 코드 설치 명령어

공식 문서가 권장하는 방식은 네이티브 설치다. 터미널을 열고 자기 환경에 맞는 줄만 실행한다.

**macOS, Linux, WSL**

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

**Windows PowerShell** (프롬프트가 `PS C:\`로 시작한다)

```powershell
irm https://claude.ai/install.ps1 | iex
```

**Windows CMD** (프롬프트가 `PS` 없이 `C:\`로 시작한다)

```batch
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

설치 명령은 다운로드 중에 진행 상황을 보여 주지 않는다. 멈춘 것처럼 보여도 끝날 때까지 기다린다.

Alpine Linux는 예외가 있다. 기본 설치에 없는 `bash`와 `curl`이 설치 명령에 필요하고, 실행에는 `libgcc`, `libstdc++`, `ripgrep`이 필요하다. 설정에 `USE_BUILTIN_RIPGREP=0`도 넣어야 한다. 절차는 [공식 문서의 Alpine 항목](https://code.claude.com/docs/en/setup?ref=zerodraftlab.com#alpine-linux-and-musl-based-distributions)에 있다.

## Homebrew, WinGet, npm으로 설치하기

패키지 관리자를 쓰고 싶다면 아래 명령을 쓴다.

```bash
brew install --cask claude-code
winget install Anthropic.ClaudeCode
npm install -g @anthropic-ai/claude-code
```

방식마다 업데이트가 다르다.

- **네이티브 설치:** 백그라운드에서 자동 업데이트된다.
- **Homebrew:** 기본으로 자동 업데이트되지 않는다. `brew upgrade claude-code`를 직접 실행한다. `claude-code` 캐스크는 안정 채널이라 보통 약 일주일 늦다. 최신판은 `claude-code@latest`다.
- **WinGet:** 기본으로 자동 업데이트되지 않는다. `winget upgrade Anthropic.ClaudeCode`를 직접 실행한다.
- **npm:** Node.js 22 이상이 필요하다. Node.js 18이라고 적힌 글은 현재 공식 문서와 다르다. 공식 문서는 `sudo npm install -g`를 쓰지 말라고 경고한다. 권한 문제와 보안 위험이 생길 수 있기 때문이다.

## Windows 설치는 네이티브와 WSL 중 하나를 고른다

네이티브 Windows는 관리자 권한 없이 설치된다. Git for Windows는 선택 사항이지만 공식 문서가 권장한다. 필수라고 적힌 글도 있는데, 2026년 11월 1일 공식 문서에서는 필수가 아니다. 있으면 Claude Code가 Git Bash로 Bash 도구를 쓰고, 없으면 PowerShell로 명령을 실행한다.

명령을 격리해 실행하는 샌드박스 기능이 필요하면 WSL 2로 간다. 네이티브 Windows와 WSL 1은 샌드박스를 지원하지 않는다. WSL에 설치했다면 `claude`도 PowerShell이 아니라 WSL 터미널 안에서 실행해야 한다.

> **Astra 첨언.** 에이전트를 실행할 환경은 프로젝트의 빌드와 테스트가 이미 돌아가는 쪽에 맞추는 편이 낫다. 환경을 함께 바꾸면 코드 문제와 개발 환경 문제를 한 번에 추적해야 한다.

## 설치됐는지 확인하기

새 터미널 창을 열고 버전을 확인한다.

```bash
claude --version
```

버전 번호 뒤에 `(Claude Code)`가 붙어 나오면 설치된 것이다. 더 자세히 보려면 `claude doctor`를 실행한다. 세션을 시작하지 않고 설치 상태와 설정 파일 오류를 읽기 전용으로 보여 준다.

> **Astra 첨언.** 설치 확인과 프로젝트 실행 확인은 따로 한다. 첫 수정 전에 프로젝트의 기존 테스트 명령을 실행해 결과를 남겨 두면, 나중에 생긴 실패가 에이전트의 변경 때문인지 구분하기 쉽다.

## 첫 실행과 로그인

작업할 프로젝트 폴더에서 실행한다.

```bash
cd 프로젝트_폴더
claude
```

처음 실행하면 브라우저가 열리고 로그인을 안내한다. 로그인 정보는 저장되므로 다음부터는 다시 묻지 않는다. 다른 계정으로 바꿀 때는 실행 중인 세션에서 `/login`을 입력한다.

구독자는 환경 변수 하나를 조심해야 한다. `ANTHROPIC_API_KEY`가 설정된 상태에서 Claude Code가 묻는 사용 여부를 승인하면 구독 대신 그 API 키를 쓴다. 그러면 플랜에 포함된 사용량이 아니라 API 요금이 나간다.

## 자주 만나는 오류

| 화면에 나온 말                                          | 뜻                          | 할 일                                                                                                   |
| ------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------- |
| command not found 또는 claude를 인식하지 못함              | 설치 폴더가 PATH에 아직 없다         | 새 터미널을 연다. 그래도 안 되면 공식 문제 해결 문서의 Fix your PATH를 따른다                                                   |
| The token '&&' is not a valid statement separator | CMD용 명령을 PowerShell에서 실행했다 | PowerShell용 명령을 쓴다                                                                                    |
| 'irm' is not recognized                           | PowerShell용 명령을 CMD에서 실행했다 | CMD용 명령을 쓴다                                                                                           |
| syntax error near unexpected token '<' 또는 403     | 설치 명령이 실패했다                | [공식 문제 해결 문서](https://code.claude.com/docs/en/troubleshoot-install?ref=zerodraftlab.com)에서 같은 오류를 찾는다 |

지역 조건도 있다. Claude Code는 Anthropic이 지원하는 국가에서만 쓸 수 있다.

## 터미널이 낯설다면, 그리고 지우고 싶다면

터미널이 낯설면 데스크톱 앱으로 시작해도 된다. 공식 문서는 macOS, Windows, Linux용 앱을 안내한다. VS Code를 쓴다면 [공식 VS Code 확장](https://code.claude.com/docs/en/vs-code?ref=zerodraftlab.com)도 있다.

네이티브 설치를 지우는 명령은 macOS, Linux, WSL 기준으로 아래와 같다.

```bash
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
```

설정까지 지우려면 `~/.claude`와 `~/.claude.json`도 삭제한다. 이때 설정, MCP 서버 구성, 세션 기록이 함께 사라진다. 필요한 것이 있으면 지우기 전에 복사해 둔다.

설치를 마쳤다면 다음은 [클로드 코드 사용법](https://zerodraftlab.com/claude-code-usage-guide/)이다.

설치가 끝나면 에이전트가 "완료했다"고 보고하기 시작한다. 내 사이트는 그 보고 뒤에서 100일 넘게 깨져 있었다. [무료로 사건 읽기](https://zerodraftlab.com/agent-verified-site-down/)