# Claude Code 설치 방법 2026: Mac, Windows, Linux 완전 가이드

> Claude Code는 네이티브 CLI 설치 프로그램을 사용하여 의존성 없이 macOS, Linux, Windows에서 2분 이내에 설치됩니다. 이 가이드에서는 네이티브, Homebrew, WinGet, npm, Windows CMD, WSL을 포함한 6가지 설치 방법을 모두 다룹니다. 어떤 Claude 요금제가 적합한지, 인증 방법, CLAUDE.md 설정, 일반적인 오류 해결, 터미널에서 AI 코딩을 시작하는 방법을 알아보세요.

- URL: https://blog.laozhang.ai/ko/posts/how-to-install-claude-code
- Published: 2026-03-16
- Updated: 2026-10-16
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ko/about)
- Topic: Claude Code
- Tags: Claude Code, 설치 가이드, AI 코딩 도구, 개발자 도구

---
Claude Code는 Anthropic의 터미널 기반 AI 코딩 에이전트로, 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, git을 관리합니다. 이 모든 것이 명령줄에서 이루어집니다. 2026년 10월 현재, 권장 설치 방법은 네이티브 CLI 설치 프로그램입니다. 의존성이 전혀 필요 없고, 백그라운드에서 자동 업데이트되며, macOS, Linux, Windows 모두에서 작동합니다. Claude Code를 처음 설정하든 기존 npm 기반 설치에서 마이그레이션하든, 이 가이드에서는 2026년에 사용할 수 있는 모든 옵션을 안내하여 몇 시간이 아닌 몇 분 만에 AI 코딩을 시작할 수 있도록 도와드립니다.

## 핵심 요약

Claude Code는 모든 주요 플랫폼에서 단일 명령어로 설치됩니다. 전체 가이드를 읽기 전에 알아야 할 핵심 사항은 다음과 같습니다:

- **macOS / Linux**: `curl -fsSL https://claude.ai/install.sh | bash`
- **Windows PowerShell**: `irm https://claude.ai/install.ps1 | iex`
- **요구 사항**: macOS 13+, Windows 10 1809+, 또는 Ubuntu 20.04+. Claude Pro 구독($20/월) 이상이 필수이며, 무료 요금제에는 Claude Code 접근 권한이 포함되지 않습니다.
- **6가지 방법 존재**: 네이티브 설치 프로그램(권장), Homebrew, WinGet, npm(고급 옵션, Node.js 22 이상), Windows CMD, WSL. 네이티브 설치는 백그라운드에서 자동 업데이트되고, npm 전역 설치도 전역 폴더에 쓰기 권한이 있으면 자동 업데이트됩니다. Homebrew와 WinGet은 기본적으로 직접 업그레이드해야 합니다.
- **첫 실행**: 터미널에서 `claude`를 실행하고, 브라우저를 통해 인증하면 바로 시작할 수 있습니다.

명령어만 필요하고 다른 설명은 필요 없다면, 해당 플랫폼용 명령어를 복사한 후 [인증 및 첫 실행](#인증-및-첫-실행) 섹션으로 건너뛰세요. 설치 방법 간의 차이점을 이해하거나 Windows 예외 상황을 처리하거나 적절한 Claude 요금제를 선택하고 싶다면 계속 읽어주세요.

## Claude Code 설치 전 필요 사항


설치 명령어를 실행하기 전에 두 가지를 확인해야 합니다: 운영체제가 최소 요구 사항을 충족하는지, 그리고 올바른 종류의 Anthropic 계정을 보유하고 있는지입니다. 이 단계를 건너뛰는 것이 개발자들이 실패한 설치에 시간을 낭비하는 가장 큰 원인입니다.

### 시스템 요구 사항

Claude Code는 세 가지 주요 플랫폼을 지원하지만, 버전 요구 사항은 대부분의 CLI 도구보다 엄격합니다. 이전 운영체제 버전에서 실행하면 설치 또는 인증 중에 무성 오류가 발생할 수 있으므로, 먼저 버전을 확인하세요.

macOS에서는 버전 13.0(Ventura) 이상이 필요합니다. Apple Silicon과 Intel 머신 모두 네이티브 설치 프로그램을 통해 지원됩니다. 버전이 확실하지 않다면 Apple 메뉴를 클릭하고 "이 Mac에 관하여"를 선택하세요. Xcode 호환 설정을 실행하는 대부분의 개발자는 이미 이 요구 사항을 충족하지만, macOS Monterey(12) 이하를 실행하는 구형 MacBook 하드웨어를 사용하는 사람들은 해당될 수 있습니다. macOS에 기본 제공되는 터미널 앱으로 완벽하게 작동합니다. iTerm2나 다른 서드파티 터미널이 필요하지 않지만, 사용해도 문제없습니다.

Windows에서는 버전 10 빌드 1809 이상이 필요하며, 이는 Windows 10 October 2018 Update부터 Windows 11을 포함한 모든 이후 버전을 포함합니다. Git for Windows는 2026년 10월 기준 필수 전제 조건이 아니라 선택 사항입니다. 설치하지 않으면 Claude Code가 PowerShell 도구로 셸 명령을 실행하고, 설치하면 Git Bash가 생겨 Bash 도구를 쓸 수 있습니다. Bash 기반 스크립트를 자주 다룬다면 [git-scm.com](https://git-scm.com/downloads/win)에서 내려받아 설치 중 "Add to PATH"를 선택하고 터미널을 다시 시작하세요. 설치 명령은 관리자 권한 없이 실행하면 됩니다. CI/CD 사용 사례를 위해 Windows Server 2019 이상도 지원됩니다.

Linux에서 공식 지원 목록에 오른 배포판은 Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상입니다. 그 밖의 배포판은 공식 지원 목록에 없습니다. 다만 Fedora·RHEL용 dnf 저장소와 Alpine용 apk 저장소는 따로 제공됩니다. 설치 프로그램이 아키텍처(x86_64 또는 ARM64)를 자동으로 감지하므로 추가 구성이 필요 없습니다. Windows 머신의 WSL에서 Linux를 실행하는 경우, Linux 설치 방법이 동일하게 작동합니다. 이에 대해서는 아래 Windows 섹션에서 자세히 설명합니다.

모든 플랫폼에서 4GB 이상의 RAM, x64 또는 ARM64 프로세서, 그리고 인터넷 연결이 필요합니다. 바이너리 크기는 macOS Apple Silicon용 2.1.301 기준 약 250MB이고, 네이티브 설치 프로그램은 최신 두 버전 정도를 디스크에 남겨 두므로 수백 MB의 여유 공간을 확보해 두세요.

### 올바른 계정 선택

이것이 많은 개발자들이 예상치 못한 벽에 부딪히는 부분입니다. Claude Code는 무료 Claude.ai 요금제에서 사용할 수 없습니다. Claude Code를 인증하고 사용하려면 다음 계정 유형 중 하나가 필요합니다:

| 계정 유형 | 월 비용 | 적합 대상 | Claude Code 접근 |
|----------|---------|----------|-----------------|
| Claude Pro | $20/월 ($17 연간) | 개인 개발자 | 가능 — Sonnet 4.6 |
| Claude Max 5x | $100/월 | 일일 대량 사용자 | 가능 — Opus 4.6 + 5배 제한 |
| Claude Max 20x | $200/월 | 파워 유저, 팀 | 가능 — Opus 4.6 + 20배 제한 |
| Teams Standard | $25/시트/월 | 소규모 팀 | 가능 — 시트당 Pro 수준 |
| Anthropic Console | 사용량 기반 | API 중심 / CI/CD | 가능 — API 키 사용 |

Claude Code를 처음 사용해보신다면, 월 $20의 Pro 요금제가 가장 합리적인 시작점입니다. 터미널과 웹 인터페이스에서 Claude Code를 사용할 수 있으며, 집중적인 코딩 세션 중 속도 제한에 도달하면 나중에 Max로 업그레이드할 수 있습니다. 여러 개발자에 걸쳐 Claude Code를 평가하는 팀의 경우, Teams 요금제가 중앙 집중식 결제 및 관리자 컨트롤을 제공합니다. Anthropic Console 옵션은 CI/CD 파이프라인에서만 Claude Code를 사용하거나 월간 구독보다 토큰당 과금을 선호하는 경우에 이상적입니다. Console 계정으로 처음 로그인하면 비용 추적을 위한 "Claude Code" 워크스페이스가 자동으로 생성됩니다.

## macOS 및 Linux에서 Claude Code 설치하기

macOS와 Linux에서의 설치는 두 플랫폼이 동일한 설치 스크립트를 공유하기 때문에 간단합니다. 네이티브 설치 프로그램은 플랫폼과 아키텍처에 맞는 단일 실행 파일을 내려받으므로 Node.js를 설치할 필요가 없고, Node.js나 nvm 버전과 충돌할 일도 없으며, 업데이트가 백그라운드에서 자동으로 이루어집니다. 참고로 2.1.113(2026년 4월 17일)부터는 npm 패키지도 같은 네이티브 바이너리를 설치하므로, npm으로 설치한 `claude`도 실행할 때 Node.js를 거치지 않습니다. Node.js 위에서 JavaScript로 실행되던 것은 2.1.112 이하의 npm 버전입니다.

### 네이티브 설치 프로그램 (권장)

터미널을 열고 단일 명령어를 실행하세요:

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

이 스크립트는 Claude Code 바이너리를 내려받아 `~/.local/bin/claude`에 배치합니다(실제 파일은 `~/.local/share/claude/versions/` 아래에 있고, `~/.local/bin/claude`는 그쪽을 가리키는 심볼릭 링크입니다). 다운로드 중에는 진행 표시가 나오지 않습니다. 설치 프로그램은 PATH를 직접 바꾸지 않습니다. `~/.local/bin`이 PATH에 없으면 출력의 `Setup notes:` 아래에 `Native installation exists but ~/.local/bin is not in your PATH.`와 해결 명령이 표시되니 그대로 실행하세요. 설치 후에는 새 터미널 창을 열거나 `source ~/.zshrc`(macOS) 또는 `source ~/.bashrc`(Linux)로 셸 설정을 다시 불러옵니다.

네이티브 설치 프로그램의 가장 큰 장점은 자동 업데이트입니다. Claude Code는 시작할 때와 실행 중에 주기적으로 새 버전을 확인하고, 백그라운드에서 내려받아 다음 실행부터 적용합니다. 설치 프로그램을 다시 실행할 필요가 없습니다. 업데이트 채널은 `/config`의 Auto-update channel에서 고르며, 기본값 `latest`는 새 버전을 바로 받고 `stable`은 보통 약 1주 늦게 큰 회귀가 있는 버전을 건너뜁니다. 지금 당장 업데이트하려면 `claude update`를 실행하세요. Anthropic이 매주 Claude Code 개선 사항을 배포하고, 이전 버전은 때때로 API와의 호환성을 잃기 때문에 이는 특히 중요합니다.

보안 관점에서 스크립트를 bash로 직접 파이프하는 것이 불편하다면, 먼저 스크립트를 다운로드하고 검토한 후 수동으로 실행할 수 있습니다. 이것은 완벽하게 유효한 방법입니다:

```bash
curl -fsSL https://claude.ai/install.sh -o install-claude.sh
less install-claude.sh  # 스크립트 검토
bash install-claude.sh
```

### Homebrew 대안

Homebrew를 통해 도구를 관리하는 것을 선호하는 개발자를 위해, Claude Code는 cask로 제공됩니다:

```bash
brew install --cask claude-code
```

이 방법은 macOS와 Linux(Linuxbrew를 통해) 모두에서 작동합니다. 단점은 Homebrew 설치가 자동 업데이트되지 않는다는 것입니다. 새 기능과 보안 수정을 받으려면 주기적으로 `brew upgrade claude-code`를 실행해야 합니다. 이미 모든 것에 Homebrew를 사용하는 대부분의 개발자에게는 익숙한 패키지 관리자 내에서 머무르는 편의성이 수동 업데이트 단계보다 중요합니다.

cask는 두 가지입니다. `claude-code`는 stable 채널을 따라가므로 보통 약 1주 늦게 업데이트되고, 새 버전을 바로 받고 싶다면 `brew install --cask claude-code@latest`로 설치한 뒤 `brew upgrade claude-code@latest`로 올립니다.

설치된 버전을 확인하려면:

```bash
claude --version
```

나중에 업데이트하려면:

```bash
brew upgrade claude-code
```

Homebrew 설치는 Apple Silicon Mac에서는 `/opt/homebrew/bin/`에, Intel Mac에서는 `/usr/local/bin/`에 Claude Code를 배치합니다. 나중에 자동 업데이트를 위해 네이티브 설치 프로그램으로 전환하기로 결정하면, 먼저 `brew uninstall --cask claude-code`로 Homebrew 버전을 제거하여 다른 위치에 바이너리가 두 개 있어서 어떤 버전이 실행되는지 혼란을 야기하는 것을 방지하세요.

### 설치 확인

어떤 방법을 선택했든, 다음을 실행하여 Claude Code가 접근 가능한지 확인하세요:

```bash
which claude
claude --version
```

`which claude`가 경로를 반환하고 `claude --version`이 `2.1.301 (Claude Code)`처럼 버전 번호를 표시하면 설치가 완료된 것입니다. "command not found"가 표시되면 아래의 문제 해결 섹션을 확인하세요.

## Windows에서 Claude Code 설치하기

![네이티브 PowerShell, WinGet, WSL 경로를 보여주는 Windows 설치 의사 결정 트리](https://blog.laozhang.ai/posts/ko/how-to-install-claude-code/img/windows-decision.webp)

Windows 설치는 macOS나 Linux보다 하나의 결정이 더 필요합니다: Claude Code를 Windows에서 네이티브로 실행할지, WSL(Windows Subsystem for Linux) 내에서 실행할지 선택해야 합니다. 올바른 선택은 개발 워크플로우에 따라 다르며, 잘못 선택하면 좌절감을 느끼게 됩니다. 결정 과정을 먼저 살펴본 후 각 경로를 자세히 설명하겠습니다.

주로 Windows를 대상으로 하는 코드를 작성하는 경우 — .NET 애플리케이션, PowerShell 스크립트, Windows 네이티브 도구 체인 — 네이티브 PowerShell 설치 프로그램을 사용하세요. Windows에서 직접 실행되고, 별도 전제 조건이 없으며, Git for Windows는 Bash 도구가 필요할 때만 추가하면 됩니다. 주로 Linux 배포를 위한 코드를 작성하는 경우 — Node.js 서버, Python 백엔드, Docker 컨테이너 — WSL은 Claude Code가 macOS 및 Linux 설정과 동일하게 동작하는 진정한 Linux 환경을 제공합니다. 확실하지 않다면 네이티브 설치 프로그램부터 시작하세요. 나중에 언제든 WSL을 추가할 수 있습니다.

### 네이티브 PowerShell 설치 프로그램 (대부분의 사용자에게 권장)

Git for Windows는 선택 사항입니다. PowerShell에서 `git --version`을 실행해 버전 번호가 나오면 Claude Code가 Git Bash를 Bash 도구로 쓰고, 없으면 PowerShell 도구로 명령을 실행합니다. Bash 도구가 필요하면 [git-scm.com](https://git-scm.com/downloads/win)에서 Git을 설치하고 "Add to PATH"를 선택한 뒤 PowerShell을 다시 시작하세요.

PowerShell(CMD가 아님)에서 설치 프로그램을 실행하세요. 관리자 권한은 필요 없습니다. 프롬프트가 `PS C:\`로 시작하면 PowerShell입니다:

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

이것은 네이티브 바이너리를 `%USERPROFILE%\.local\bin\claude.exe`에 설치합니다. 이 폴더가 PATH에 없으면 설치 프로그램이 `Setup notes:` 아래에 안내를 출력하니 그대로 따르고, 설치 후 새 PowerShell 창을 여세요. macOS/Linux 네이티브 설치 프로그램과 마찬가지로, 이 버전은 백그라운드에서 자동 업데이트됩니다.

### WinGet 대안

WinGet(Windows 11 및 최신 Windows 10 빌드에 기본 제공되는 Windows 패키지 관리자)을 사용하는 경우, Claude Code는 공식 저장소를 통해 사용할 수 있습니다:

```powershell
winget install Anthropic.ClaudeCode
```

이것은 PowerShell 설치 프로그램과 기능적으로 동일하지만 Windows 패키지 관리 시스템을 사용합니다. WinGet 설치는 자동 업데이트되지 않으므로 주기적으로 `winget upgrade Anthropic.ClaudeCode`를 실행해야 합니다. 조직에서 Windows 패키지 관리자 정책을 통해 소프트웨어를 관리하는 경우 WinGet이 좋은 선택입니다.

### Windows CMD 설치 프로그램

PowerShell이 제한된 환경의 경우, CMD 호환 설치 프로그램도 있습니다:

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

이것은 덜 일반적이지만, 엄격한 PowerShell 실행 정책을 가진 기업 환경에서 유용합니다.

**WSL 경로 (Linux 중심 개발자용)**

Windows에서 완전한 Linux 개발 환경을 선호하는 경우, 먼저 WSL을 설치한 다음 그 안에서 표준 Linux 설치 방법을 사용하세요:

```powershell
# 1단계: WSL 설치 (관리자 권한의 PowerShell에서)
wsl --install

# 2단계: 메시지가 나타나면 컴퓨터를 재부팅

# 3단계: WSL 터미널 열기 (기본적으로 Ubuntu)
# 4단계: Linux 방법으로 Claude Code 설치
curl -fsSL https://claude.ai/install.sh | bash
```

WSL 사용 시 흔한 실수는 Windows 측에는 Node.js가 설치되어 있지만 WSL 환경 내부에는 없는 경우입니다. WSL은 기본적으로 Windows PATH를 가져오므로, WSL 안에서 npm 방법을 쓰면 Windows의 `npm`과 Node.js가 잡혀 플랫폼 감지 오류나 `exec: node: not found`가 날 수 있습니다. `which npm`과 `which node`의 결과가 `/mnt/c/`로 시작하면 Windows 쪽 파일이니, 배포판 패키지 관리자나 nvm으로 WSL 안에 Linux용 Node.js 22 이상을 설치하세요. 네이티브 설치 프로그램은 Node.js가 필요 없으므로 이 문제를 완전히 피할 수 있습니다.

최적의 WSL 성능을 위해, 프로젝트 파일이 Windows 파일시스템(예: `/mnt/c/Users/...`)이 아닌 WSL 파일시스템(예: `~/projects/`) 내에 위치하도록 하세요. WSL/Windows 경계를 넘는 파일 작업은 상당히 느리고 Claude Code에서 시간 초과를 유발할 수 있습니다.

## npm에서 네이티브 설치 프로그램으로 마이그레이션

이전에 `npm install -g @anthropic-ai/claude-code`로 Claude Code를 설치했다면, 네이티브 설치 프로그램으로 옮기는 것은 필수가 아니라 선택입니다. 2026년 10월 기준 공식 설치 문서는 npm 설치를 "고급 설치 옵션"으로 계속 안내하며 지원 중단이라고 하지 않습니다. 권장 방식은 여전히 네이티브 설치 프로그램입니다. 2.1.15(2026년 1월 21일)에 npm 설치 사용자에게 지원 중단 안내를 띄우는 기능이 추가된 적이 있지만, 2.1.301 바이너리에는 그 안내 문구가 없습니다. 옮기면 설치를 하나로 정리할 수 있고, Node.js가 필요 없으며, 업데이트가 자동으로 처리됩니다.

마이그레이션 과정은 약 2분 정도 소요되며 기존 구성을 보존합니다:

```bash
# 1단계: PATH에 있는 모든 claude 사본 확인
which -a claude
# node_modules 또는 .npm-global 내의 경로가 보이면 npm 설치
npm -g ls @anthropic-ai/claude-code

# 2단계: npm 버전 제거
npm uninstall -g @anthropic-ai/claude-code
rm -rf ~/.claude/local  # 예전 로컬 npm 설치가 있을 때만

# 3단계: 제거 확인
which -a claude  # 아무것도 출력되지 않아야 함

# 4단계: 네이티브 버전 설치
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# 또는
irm https://claude.ai/install.ps1 | iex  # Windows PowerShell

# 5단계: 새 터미널을 열고 확인
claude --version
```

인증 토큰과 구성 파일(`~/.claude/`에 저장)은 이 마이그레이션 전반에 걸쳐 보존됩니다. 재인증하거나 재구성할 필요가 없습니다. 네이티브 바이너리는 npm 버전이 중단한 지점에서 그대로 이어받습니다.

`which -a claude`에 경로가 둘 이상 나오면 하나만 남기고 나머지를 지우세요. 설치가 여러 개면 어떤 버전이 실행되는지 헷갈리고, 예상치 못한 동작이 생깁니다. 예전 npm 사본이 PATH에 남아 `Error: Cannot find module './yoga.wasm'`를 낸다면 [Claude Code Cannot find module yoga.wasm 해결: 2.0.25 이하 복사본 정리](https://blog.laozhang.ai/ko/posts/claude-code-cannot-find-module-yoga-wasm)를 보세요.

Claude Code 전용으로 nvm이나 asdf를 사용하여 Node.js 버전을 관리하고 있었다면, 네이티브 설치로 옮긴 뒤에는 Claude Code 때문에 Node.js를 유지할 필요가 없습니다. 2.1.112 이하의 npm 버전은 Node.js 위에서 JavaScript로 실행됐기 때문에 시작 시간이 Node.js 초기화에 영향을 받았고, 팀원마다 Node.js 버전이 다르면 동작이 달라질 수 있었습니다. 2.1.113부터는 npm 패키지도 같은 네이티브 바이너리를 설치하므로, 지금 npm 최신 버전을 쓰고 있다면 이런 차이는 사라졌습니다.

npm을 계속 쓰려면 다음 세 가지를 지키세요:

- 설치할 때 Node.js 22 이상을 씁니다. 더 낮은 버전에서는 `EBADENGINE` 경고가 나오지만 설치는 끝나고 `claude`도 실행됩니다.
- 업데이트는 `npm install -g @anthropic-ai/claude-code@latest`로 합니다. `npm update -g`는 처음 설치할 때의 버전 범위를 따르므로 최신 버전으로 올라가지 않을 수 있습니다.
- `--omit=optional`이나 `--ignore-scripts`를 붙이지 마세요. 플랫폼별 바이너리가 선택적 의존성과 설치 후 스크립트로 들어오기 때문에, 이를 건너뛰면 실행 시 `Error: claude native binary not installed.`가 나옵니다.

## 인증 및 첫 실행

Claude Code가 설치되면 다음 단계는 인증입니다. 프로젝트 디렉토리로 이동하여 다음을 실행하세요:

```bash
cd /path/to/your/project
claude
```

첫 실행 시, Claude Code는 기본 웹 브라우저에서 Anthropic OAuth 페이지를 엽니다. Claude Pro, Max 또는 Teams 계정으로 로그인하고, CLI를 승인하면 브라우저가 다시 리디렉션되어 성공을 확인합니다. 세션 토큰이 `~/.claude/`에 로컬로 저장되므로 이 작업은 한 번만 수행하면 됩니다.

### 인증 방법

Claude Code는 세 가지 인증 경로를 지원하며, 각각 다른 사용 사례에 적합합니다.

**브라우저 OAuth**는 기본값이며 대부분의 개발자에게 적합합니다. `claude`를 처음 실행하면 자동으로 브라우저가 열립니다. Claude Pro나 Max를 사용하는 경우 가장 간단한 경로입니다. 구독이 모든 결제를 처리하며, 요금제 등급에 연결된 사용량 제한을 받게 됩니다.

**API 키 인증**은 헤드리스 환경 — CI/CD 파이프라인, Docker 컨테이너, 브라우저가 없는 원격 서버 — 을 위해 설계되었습니다. Claude Code를 실행하기 전에 `ANTHROPIC_API_KEY` 환경 변수를 설정하세요:

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

API 키를 사용하면 결제가 Anthropic Console 계정을 통해 토큰당 과금으로 이루어집니다.

**서드파티 클라우드 제공자** — Amazon Bedrock, Google Vertex AI, Microsoft Foundry — 는 환경 변수를 통해 지원됩니다:

```bash
# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project-id
```

이러한 옵션은 이미 클라우드 제공자 계약을 보유하고 있으며 기존 인프라를 통해 AI 트래픽을 라우팅하는 것을 선호하는 기업에서 주로 사용됩니다.

### CLAUDE.md로 프로젝트 초기화

인증 후, 가장 효과적인 단일 작업은 프로젝트 루트에 `CLAUDE.md` 파일을 생성하는 것입니다. 이 마크다운 파일은 Claude에게 코드베이스에 대한 지속적인 컨텍스트를 제공합니다 — 빌드 명령어, 코드 규칙, 아키텍처 결정, 테스팅 지침 등 Claude가 코드만으로는 추론할 수 없는 모든 것을 포함합니다. 이것이 없으면 Claude는 프로젝트의 고유한 패턴을 이해하지 못한 채 매 세션을 시작합니다.

`CLAUDE.md`를 자동으로 생성하세요:

```bash
# Claude Code 세션 내에서 실행:
/init
```

이 명령어는 코드베이스를 분석하고 감지된 빌드 시스템, 테스트 프레임워크, 코드 패턴이 포함된 `CLAUDE.md`를 생성합니다. 좋은 `CLAUDE.md`는 간결합니다 — 50~100줄을 목표로 하세요. 각 줄에 대해 "이것을 제거하면 Claude가 실수할까?"라고 자문하세요. 그렇지 않다면 삭제하세요. 모노레포의 경우 하위 디렉토리에 추가 `CLAUDE.md` 파일을 추가하세요. Claude는 계층적으로 로드합니다 — 루트 수준 규칙은 어디서나 적용되고, 하위 수준 규칙은 해당 디렉토리에서 작업할 때만 적용됩니다.

`/init` 명령어는 또한 권한 제어 및 선호하는 텍스트 서식 지정과 같은 필수 Claude Code 기능 설정을 안내합니다. 약 1분이 소요되며 Claude가 코드와 작업하는 정확도에 눈에 띄는 차이를 만듭니다.

다음은 일반적인 Next.js 프로젝트에 대한 잘 구조화된 `CLAUDE.md`의 예입니다:

```markdown
# CLAUDE.md

## Commands
- `npm run dev` - 포트 3000에서 개발 서버 시작
- `npm run build` - 프로덕션 빌드
- `npm test` - Jest 테스트 실행
- `npm run lint` - ESLint 검사

## Architecture
- Next.js 15 with App Router
- PostgreSQL with Drizzle ORM
- Clerk을 통한 인증
- 모든 API 라우트는 src/app/api/에 위치

## Conventions
- 기본적으로 서버 컴포넌트 사용; 필요할 때만 "use client" 사용
- TypeScript strict 모드; any 타입 금지
- 커밋 메시지: 명령형, 72자 미만
```

핵심 통찰은 `CLAUDE.md`가 Claude에게 코드를 직접 읽어서는 알아낼 수 없는 것을 알려줘야 한다는 것입니다. 빌드 명령어, 네이밍 규칙, 아키텍처 결정이 가장 가치 있는 포함 항목입니다. 이것들이 명시적인 안내 없이 Claude가 가장 잘못할 가능성이 높은 결정이기 때문입니다.

## 일반적인 설치 문제 해결

설치나 첫 실행에서 문제가 생겨도 대부분은 몇 분 안에 해결됩니다. 먼저 내장 진단 도구로 상태를 확인하세요:

```bash
claude doctor
```

무언가 이상할 때마다 이 명령어를 실행하세요. 설치 무결성, 인증 상태, 구성 유효성, 네트워크 연결을 확인하고 발견한 내용을 보고합니다. 아래는 가장 일반적인 문제와 해결 방법입니다.

### "command not found: claude"

이것은 설치 후 가장 빈번한 오류이며, 셸이 새 PATH 항목을 인식하지 못했다는 것을 의미합니다. 해결 방법은 플랫폼에 따라 다릅니다:

macOS와 Linux에서는 새 터미널 창을 여세요. 그래도 안 되면 셸 구성을 수동으로 다시 로드하세요:

```bash
source ~/.zshrc   # macOS (Catalina 이후 Zsh가 기본)
source ~/.bashrc  # Linux (대부분의 배포판)
```

명령어를 여전히 찾을 수 없다면, 설치 프로그램은 PATH를 직접 바꾸지 않으므로 `~/.local/bin`이 PATH에 들어 있는지 확인하고 없으면 추가하세요:

```bash
ls -la ~/.local/bin/claude                                   # 바이너리가 있는지 확인
echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"        # 출력이 없으면 PATH에 없음
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc       # Linux Bash는 ~/.bashrc
source ~/.zshrc
```

macOS에서 Bash를 쓴다면 `~/.bashrc` 대신 `~/.bash_profile`에 추가합니다.

Windows에서는 PowerShell을 완전히 닫고 다시 여세요. 그래도 찾을 수 없다면 `Test-Path "$env:USERPROFILE\.local\bin\claude.exe"`로 바이너리가 있는지 확인하고, `True`인데 실행되지 않으면 사용자 PATH에 `%USERPROFILE%\.local\bin`을 추가한 뒤 터미널을 다시 시작하세요. 편집기 안의 터미널은 편집기의 PATH를 물려받으므로 편집기도 다시 시작해야 합니다.

### EACCES 권한 오류 (npm 방법만 해당)

npm 설치 방법을 선택하고 EACCES 권한 오류가 발생하면, 절대 `sudo npm install -g`를 사용하지 마세요. npm과 함께 sudo를 실행하면 npm 디렉토리에 root 소유의 파일이 생성되어 향후 모든 npm 글로벌 설치에 대한 연쇄적인 권한 문제를 일으킵니다.

공식 문제 해결 문서가 npm 권한 오류에 먼저 권하는 방법은 네이티브 설치 프로그램으로 전환하는 것입니다(`curl -fsSL https://claude.ai/install.sh | bash`). 이미 npm으로 설치했다면 `claude install`로도 전환할 수 있습니다. npm을 계속 쓰려면 sudo가 필요 없는 사용자 폴더를 전역 설치 위치로 지정하세요:

```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@latest
```

전역 폴더에 쓰기 권한이 없으면 npm 설치는 자동 업데이트도 하지 못합니다. 이때 Claude Code는 시작할 때 한 번 안내를 띄우고, `claude doctor`가 위의 세 가지 해결 방법(`claude install`, sudo 없이 쓰는 nvm 등의 npm, `npm config set prefix ~/.npm-global`)을 보여 줍니다.

### 인증 실패

OAuth 중에 브라우저 리디렉션이 작동하지 않는 경우:

1. 열리는 브라우저에서 [claude.ai](https://claude.ai)에 로그인되어 있는지 확인하세요
2. 계정이 유료 요금제에 있는지 확인하세요 — Pro, Max, Teams 또는 Enterprise
3. 로그아웃 후 다시 로그인해 보세요: `claude auth logout` 다음에 `claude auth login`(세션 안에서는 `/logout`)
4. 프록시 구성이 있는 기업 네트워크의 경우, `HTTPS_PROXY` 환경 변수를 설정해야 할 수 있습니다

브라우저를 사용할 수 없는 CI 환경에서는 위의 인증 섹션에 설명된 대로 API 키 인증으로 전환하세요.

**Windows 관련 문제**

`Claude Code on Windows requires either Git for Windows (for bash) or PowerShell`이 표시되면 Git Bash와 PowerShell을 둘 다 찾지 못했다는 뜻입니다. Git for Windows는 선택 사항이라 이것만 없는 것으로는 이 오류가 나지 않습니다. PowerShell이 PATH에서 빠졌다면 기본 위치인 `C:\Windows\System32\WindowsPowerShell\v1.0\`을 PATH에 추가하거나 PowerShell 7(`pwsh`)을 설치하세요. Git Bash를 쓰고 싶다면 Git for Windows를 설치할 때 "Add to PATH"를 선택하고 터미널을 다시 시작합니다.

PowerShell에서 실행 정책 오류가 표시되면, 스크립트 실행을 일시적으로 허용해야 할 수 있습니다:

```powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
```

느린 파일 작업을 경험하는 WSL 사용자의 경우, 프로젝트 파일을 Windows 파일시스템(`/mnt/c/...`)에서 WSL 파일시스템(`~/projects/`)으로 이동하세요. WSL을 통한 교차 파일시스템 접근은 상당한 지연 시간을 추가하며, Claude Code의 빈번한 파일 읽기와 함께 복합적으로 작용합니다.

**네트워크 및 프록시 문제**

프록시 서버가 있는 기업 네트워크는 설치 스크립트나 OAuth 인증 흐름을 차단할 수 있습니다. 설치 중 `curl`이 시간 초과되면, 설치 프로그램을 실행하기 전에 프록시 설정을 구성하세요:

```bash
export HTTPS_PROXY=http://proxy.yourcompany.com:8080
export HTTP_PROXY=http://proxy.yourcompany.com:8080
curl -fsSL https://claude.ai/install.sh | bash
```

프록시 뒤에서 인증이 실패하는 경우, 동일한 환경 변수가 일반적으로 문제를 해결합니다. 일부 기업 방화벽은 Claude Code가 실시간 통신에 사용하는 WebSocket 연결을 특별히 차단합니다. 이 경우 IT 부서에 `claude.ai` 및 `api.anthropic.com` 도메인을 허용 목록에 추가하도록 요청하세요.

**설치 후 느린 성능**

Claude Code는 시작되지만 느리게 응답하는 경우, 가장 일반적인 원인은 과부하된 컨텍스트 윈도우입니다. 세션 내에서 `/compact`를 실행하면 대화 기록을 압축하고 컨텍스트 공간을 확보합니다. 매우 큰 코드베이스를 가진 프로젝트의 경우, `.claudeignore` 파일(`.gitignore`와 유사)을 생성하면 Claude가 작업과 관련 없는 디렉토리를 스캔하는 것을 방지합니다. 예를 들어 `node_modules`, `dist` 또는 대용량 바이너리 에셋 폴더 등입니다.

## 어떤 Claude Code 요금제가 적합한가요?

![Pro, Max 5x, Max 20x, API 옵션의 가격 및 기능을 보여주는 Claude Code 요금제 비교](https://blog.laozhang.ai/posts/ko/how-to-install-claude-code/img/plan-comparison.webp)

적절한 요금제를 선택하면 과소비와 좌절스러운 속도 제한을 모두 방지할 수 있습니다. 결정은 Claude Code를 얼마나 자주 사용하는지와 가장 강력한 모델이 필요한지에 따라 달라집니다.

**월 $20의 Claude Pro**는 대부분의 개인 개발자의 시작점입니다. 터미널과 웹 인터페이스에서 Claude Sonnet 4.6에 접근할 수 있으며, 사용량은 5시간 롤링 윈도우로 측정됩니다. 코드 리뷰, 버그 수정, 소규모 기능에 하루에 몇 번 Claude Code를 사용하는 개발자에게 Pro가 충분합니다. 커뮤니티 추정에 따르면, Pro 사용자는 일반적으로 주당 40~80 Sonnet 시간을 얻으며, 이는 적당한 일일 사용을 편안하게 커버합니다.

**월 $100의 Claude Max** (5x 등급)는 Pro에서 정기적으로 속도 제한에 도달하는 경우에 적합합니다. 일반적으로 근무일 내내 Claude Code를 활성 페어 프로그래머로 실행하는 개발자입니다. 5배 배수는 주당 약 140~280 Sonnet 시간으로 변환되며, 라인업에서 가장 강력한 모델인 Claude Opus 4.6에도 접근할 수 있습니다. Pro에서 일주일에 한두 번 이상 속도 제한 초기화를 기다리는 경우, Max 5x로 업그레이드하면 일반적으로 회복된 생산성으로 충분한 가치를 제공합니다.

**월 $200의 Claude Max** (20x 등급)는 여러 프로젝트에 걸쳐 동시에 Claude Code를 실행하는 파워 유저와 리더를 위한 것입니다. 주당 약 240~480 Sonnet 시간으로, 속도 제한에 도달할 가능성이 거의 없습니다. 이 등급은 대규모 리팩토링, 자동화된 테스팅, 지속적인 코드 리뷰 워크플로우에 Claude Code를 광범위하게 사용하는 개발자들 사이에서도 인기가 있습니다.

**Anthropic Console** (사용량 기반 API)는 사용이 산발적이거나 주로 CI/CD 파이프라인에서 Claude Code를 실행하는 경우 최선의 선택입니다. 월간 구독 대신 크레딧을 충전하고 소비한 토큰당 지불합니다. Claude Sonnet 4.6의 현재 가격은 입력 토큰 100만 당 $3.00, 출력 토큰 100만 당 $15.00입니다(Anthropic Console, 2026년 3월). 이 옵션은 API 통합 서비스와 특히 잘 작동합니다. 단일 Claude Code 명령어는 일반적으로 8~12개의 API 호출을 생성하므로, 집중 세션은 API 비용으로 $0.50~$2.00을 소비할 수 있어 가끔 사용하는 경우 구독보다 상당히 저렴합니다.

Claude Code를 평가하는 팀의 경우, 시트당 월 $25($20 연간)의 Teams Standard 요금제가 중앙 집중식 관리와 함께 Pro 수준 접근을 제공합니다. 팀이 업그레이드를 결정하면, 시트당 월 $125($100 연간)의 Teams Premium 요금제가 Max에 비견되는 5배 사용량 제한을 추가합니다. 속도 제한을 효과적으로 관리하는 방법에 대한 자세한 내용은 [Claude Code 속도 제한 상세 가이드](https://blog.laozhang.ai/ko/posts/claude-code-rate-limit-reached)를 참조하세요.

## 설치 방법 한눈에 비교

Claude Code를 설치하는 6가지 방법이 있으므로, 나란히 비교해 보는 것이 도움이 됩니다. 아래 표는 환경에 맞는 올바른 방법을 선택할 수 있도록 주요 차이점을 요약합니다:

| 방법 | 플랫폼 | 명령어 | 자동 업데이트 | 의존성 | 적합 대상 |
|------|--------|--------|-------------|--------|----------|
| 네이티브 CLI | macOS, Linux, WSL | `curl -fsSL https://claude.ai/install.sh \| bash` | 예 | 없음 | 대부분의 사용자 |
| 네이티브 PowerShell | Windows | `irm https://claude.ai/install.ps1 \| iex` | 예 | 없음 (Git for Windows는 선택) | Windows 사용자 |
| Homebrew | macOS, Linux | `brew install --cask claude-code` | 아니요 | Homebrew | Homebrew 사용자 |
| WinGet | Windows | `winget install Anthropic.ClaudeCode` | 아니요 | WinGet | Windows 패키지 관리 |
| npm | 모든 플랫폼 | `npm install -g @anthropic-ai/claude-code` | 예 (전역 폴더에 쓰기 가능할 때) | Node.js 22+ (설치 시) | npm으로 도구를 관리하는 경우 / 버전 고정 |
| WSL | Windows | WSL 내 Linux 설치 프로그램 | 예 (Linux 경유) | WSL2 | Linux 중심 개발자 |

네이티브 설치 프로그램은 대다수 사용자에게 권장되는 방법입니다. 의존성이 전혀 없고, 조용히 자동 업데이트되며, 가장 안정적인 경험을 제공합니다. Homebrew와 WinGet은 패키지 관리자를 통해 도구를 관리하는 것을 선호하고 수동으로 업데이트를 실행하는 것에 개의치 않는 경우 좋은 대안입니다. npm 방법은 2026년 10월 기준으로도 공식 문서에 고급 설치 옵션으로 올라 있고, 2.1.113부터는 네이티브 설치와 같은 바이너리를 설치합니다. 이미 npm으로 도구를 관리하거나 특정 버전을 고정해야 할 때 쓰되, 업데이트는 `npm install -g @anthropic-ai/claude-code@latest`로 하세요.

**자주 묻는 질문**

**Claude Code에 Node.js가 필요한가요?** 네이티브 설치 프로그램, Homebrew, WinGet으로 설치하면 필요 없습니다. npm 방법은 설치할 때 Node.js 22 이상이 필요하지만(더 낮은 버전은 `EBADENGINE` 경고만 나옴), 설치된 `claude` 바이너리는 실행할 때 Node.js를 쓰지 않습니다.

**Apple Silicon에서 Claude Code를 사용할 수 있나요?** 예. 네이티브 설치 프로그램이 아키텍처를 자동으로 감지하고 Apple Silicon Mac용 ARM64 바이너리를 다운로드합니다.

**Claude Code를 완전히 제거하려면 어떻게 하나요?** 설치한 방법별로 지웁니다. 네이티브 설치(macOS, Linux, WSL)는 `rm -f ~/.local/bin/claude`와 `rm -rf ~/.local/share/claude`, Windows PowerShell은 `%USERPROFILE%\.local\bin\claude.exe`와 `%USERPROFILE%\.local\share\claude` 폴더를 삭제합니다. Homebrew는 `brew uninstall --cask claude-code`(latest cask는 `claude-code@latest`), WinGet은 `winget uninstall Anthropic.ClaudeCode`, npm은 `npm uninstall -g @anthropic-ai/claude-code`입니다. `claude uninstall` 같은 명령은 없습니다. 지운 뒤에도 `claude`가 실행되면 `which -a claude`로 남은 사본을 찾으세요. 설정과 대화 기록이 담긴 `~/.claude` 폴더는 이 과정에서 지워지지 않으므로, 완전히 정리하려면 마지막에 따로 `rm -rf ~/.claude`를 실행합니다. 이 폴더를 지우면 설정과 기록이 모두 사라집니다.

**구독 없이 Claude Code를 사용할 수 있나요?** 표준 설치를 통해서는 불가능합니다. 유료 Claude 구독(Pro, Max, Teams, Enterprise) 또는 API 크레딧이 있는 Anthropic Console 계정이 필요합니다. Claude Code 자체에는 무료 등급이 없지만, Console 옵션을 사용하면 사용한 만큼만 지불할 수 있습니다.

**Claude Code가 VS Code에서 작동하나요?** 예. Claude Code는 이 가이드에서 다루는 터미널 CLI 외에도 VS Code 확장 프로그램과 JetBrains 플러그인으로 사용할 수 있습니다. 여기의 설치 방법은 IDE 확장 프로그램이 기반으로 하는 핵심 CLI를 설정합니다. VS Code 마켓플레이스에서 "Claude Code"를 검색하고 설치를 클릭하여 확장 프로그램을 설치하세요. 방금 설치한 동일한 CLI 바이너리에 연결됩니다.

**Claude Code 데스크톱 앱이 있나요?** 예. Anthropic은 터미널 기능과 함께 그래픽 인터페이스를 제공하는 Claude Code 데스크톱 앱을 출시했습니다. 로그인 후 claude.ai에서 다운로드할 수 있습니다. 데스크톱 앱과 터미널 CLI는 동일한 인증과 구성을 공유하므로, 하나를 설치하면 둘 다 접근할 수 있습니다.

## 마무리 및 다음 단계

2026년에 Claude Code를 설치하는 것은 불과 1년 전에 비해 놀라울 정도로 간단해졌습니다. 네이티브 설치 프로그램은 대부분의 설치 문제를 야기하던 Node.js 의존성을 제거했고, WinGet 및 CMD 설치 프로그램의 추가로 Windows 사용자에게 적절한 일급 지원을 제공했습니다. 한 줄 네이티브 설치 프로그램, Homebrew, WinGet 중 무엇을 선택했든 어려운 부분은 끝났습니다.

이제 Claude Code가 머신에서 실행되고 있으므로 가장 가치 있는 다음 단계를 소개합니다. 첫째, Claude Code 내에서 `/init`을 실행하여 프로젝트의 `CLAUDE.md`를 생성하세요. 이 단일 단계만으로 코드베이스에 대한 지속적인 컨텍스트를 제공하여 Claude의 응답 품질을 극적으로 향상시킵니다. 둘째, `/help`를 입력하여 내장 슬래시 명령어를 탐색하세요. 코드 리뷰, 커밋 생성, 테스트 작성과 같은 일반적인 워크플로우에 대한 단축키를 찾을 수 있습니다. 셋째, MCP(Model Context Protocol) 서버를 연결하여 Claude Code에 도구와 데이터 소스에 대한 직접 접근을 제공하는 것을 고려하세요. 이를 통해 코딩 어시스턴트에서 제대로 된 개발 에이전트로 전환할 수 있습니다.

다른 AI 코딩 도구와 함께 Claude Code를 평가하고 있다면, [Claude Code와 OpenClaw 비교](https://blog.laozhang.ai/ko/posts/openclaw-vs-claude-code)에서 각 도구의 장점, 단점 및 이상적인 사용 사례에 대한 상세한 분석을 제공합니다. 이미 Claude Code를 사용하고 있고 사용량 제한에 부딪히는 개발자를 위해, [Claude Code 속도 제한 관리 가이드](https://blog.laozhang.ai/ko/posts/claude-code-rate-limit-reached)에서 사용 가능한 쿼터를 최대화하기 위한 실용적인 전략을 다룹니다.

다양한 워크플로우에 맞는 AI 코딩 도구에 대한 더 넓은 관점이 필요하다면, [API 제공자를 통한 AI 도구 연결 비교](https://blog.laozhang.ai/ko/posts/openclaw-api-guide)에서 Claude Code와 함께 작동하는 유연한 멀티 모델 접근 설정 방법을 다룹니다.

AI 지원 코딩의 미래는 여기에 있으며, 여러분의 터미널에서 실행됩니다. 즐거운 코딩 되세요.

## 참고 자료

이 글이 링크한 외부 페이지를 본문에 나온 순서대로 정리했습니다. 마지막 업데이트: 2026-10-16.

- [git-scm.com](https://git-scm.com/downloads/win) (git-scm.com)
- [claude.ai](https://claude.ai/) (claude.ai)