# 설치

> macOS, Linux, Windows(WSL 경유)에 Claude Code를 설치합니다. Node.js 18 이상이 필요합니다.

## 요구사항

- **Node.js 18 이상** — Claude Code는 시작 시 Node.js 버전을 확인하고, 18 미만이면 오류와 함께 종료합니다.
- **npm** — Node.js에 포함되어 있습니다.

현재 버전 확인:

```bash
node --version
npm --version
```

---

## Claude Code 설치

npm으로 전역 설치:

```bash
npm install -g @anthropic-ai/claude-code
```

설치 후 동작 확인:

```bash
claude --version
```

---

## 플랫폼별 안내

### macOS

macOS에서는 npm 전역 설치가 기본적으로 작동합니다. `npm install -g` 실행 시 권한 오류가 발생하면 두 가지 옵션이 있습니다:

**옵션 A: npm 권한 수정 (권장)**

홈 폴더의 디렉토리를 사용하도록 npm을 설정:

```bash
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
```

셸 프로파일(`~/.zshrc` 또는 `~/.bash_profile`)에 다음 추가:

```bash
export PATH=~/.npm-global/bin:$PATH
```

프로파일 다시 로드 후 설치:

```bash
source ~/.zshrc
npm install -g @anthropic-ai/claude-code
```

**옵션 B: Node 버전 관리자 사용**

[nvm](https://github.com/nvm-sh/nvm) 또는 [fnm](https://github.com/Schniz/fnm) 같은 도구는 홈 디렉토리에 Node.js를 설치해서 전역 권한 문제를 완전히 피할 수 있습니다:

```bash
# nvm 사용
nvm install --lts
nvm use --lts
npm install -g @anthropic-ai/claude-code
```

### Linux

대부분의 Linux 배포판에서 `npm install -g`는 `sudo` 또는 npm prefix 수정이 필요합니다. `sudo` 사용은 나중에 권한 문제를 일으킬 수 있으므로 권장하지 않습니다.

**권장: Node 버전 관리자 사용**

```bash
# nvm 설치
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 셸 다시 로드 후 Node.js 설치
nvm install --lts
nvm use --lts

# Claude Code 설치
npm install -g @anthropic-ai/claude-code
```

**대안: npm 전역 prefix 수정**

```bash
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code
```

### Windows (WSL)

Claude Code는 Windows Subsystem for Linux(WSL)를 통해 Windows에서 실행됩니다. 커맨드 프롬프트나 PowerShell에서 직접 실행하는 것은 지원되지 않습니다.

**1단계: WSL 설치**

관리자 권한으로 PowerShell 열고 실행:

```powershell
wsl --install
```

메시지가 나타나면 재시작. 기본적으로 Ubuntu와 함께 WSL 2가 설치됩니다.

**2단계: WSL 터미널 열기**

시작 메뉴에서 Ubuntu를 실행하거나, PowerShell에서 `wsl`을 실행합니다.

**3단계: WSL 안에 Node.js 설치**

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts
```

**4단계: Claude Code 설치**

```bash
npm install -g @anthropic-ai/claude-code
```

> 📝 항상 WSL 터미널 안에서 `claude`를 실행하세요 — Windows CMD나 PowerShell에서 실행하지 마세요. 프로젝트 파일은 WSL 파일시스템(`~/projects/` 등) 안에 있어야 최상의 성능을 발휘합니다. `/mnt/c/...`를 통한 Windows 파일 접근은 가능하지만 느립니다.

---

## 업데이트

최신 버전으로 업데이트:

```bash
npm update -g @anthropic-ai/claude-code
```

또는 Claude Code 내장 업데이트 커맨드 사용:

```bash
claude update
```

현재 버전 확인:

```bash
claude --version
```

---

## 제거

Claude Code 제거:

```bash
npm uninstall -g @anthropic-ai/claude-code
```

`claude` 바이너리가 제거됩니다. `~/.claude/`의 설정 파일은 자동으로 제거되지 않습니다. 삭제하려면:

```bash
rm -rf ~/.claude
```

---

## 문제 해결

### 설치 후 `claude` 커맨드를 찾을 수 없음

npm 전역 bin 디렉토리가 `PATH`에 없는 경우입니다.

npm이 전역 바이너리를 설치하는 위치 확인:

```bash
npm config get prefix
```

해당 경로의 `bin` 서브디렉토리를 `PATH`에 추가해야 합니다. 예를 들어 출력이 `/home/you/.npm-global`이면:

```bash
export PATH=/home/you/.npm-global/bin:$PATH
```

셸을 다시 로드(`source ~/.zshrc` 또는 새 터미널 열기) 후 다시 시도하세요.

### Node.js 버전이 18 미만

Claude Code는 Node.js 18 이상이 필요합니다. 시작 시 이 오류가 보이면:

```
Error: Claude Code requires Node.js version 18 or higher.
```

버전 관리자를 사용해 Node.js를 업그레이드하세요:

```bash
# nvm
nvm install --lts
nvm use --lts

# fnm
fnm install --lts
fnm use --lts
```

### npm install -g 시 권한 거부

`sudo npm install -g`를 사용하지 마세요 — root 소유 파일이 남아 추가 문제를 일으킬 수 있습니다. 대신 npm prefix를 사용자 쓰기 가능 디렉토리로 수정하세요:

```bash
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
npm install -g @anthropic-ai/claude-code
```

### 첫 실행 시 인증 실패

브라우저 기반 OAuth 흐름이 실패하거나 브라우저를 사용할 수 없는 경우, 환경 변수로 API 키를 직접 설정하세요:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
claude
```

셸 프로파일에 추가하면 영구적으로 설정됩니다. API 키는 [Anthropic Console](https://console.anthropic.com)에서 발급받을 수 있습니다.

### Docker 또는 CI 환경에서 실행

비대화형 환경에서는 환경 변수로 인증하세요:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
```

비대화형으로 실행하려면 `-p` 플래그 사용:

```bash
claude -p "테스트 스위트를 실행하고 실패를 보고해줘"
```

샌드박스 컨테이너에서 권한 프롬프트 없이 Claude Code를 작동시켜야 한다면 `--dangerously-skip-permissions` 플래그를 사용하세요. 이 플래그는 Claude Code의 샌드박스 안전 검사를 통과한 환경(인터넷 접근 없음, 컨테이너 외부에서 root로 실행하지 않음)에서만 작동합니다.