254 lines
6.0 KiB
Markdown
254 lines
6.0 KiB
Markdown
# 설치
|
|
|
|
> 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로 실행하지 않음)에서만 작동합니다.
|