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

AI Free API Team

•2026년 3월 16일•22 분 소요•Claude Code

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

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

Claude Code는 Anthropic의 터미널 기반 AI 코딩 에이전트로, 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하고, git을 관리합니다. 이 모든 것이 명령줄에서 이루어집니다. 2026년 3월 현재, 권장 설치 방법은 네이티브 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(레거시), Windows CMD, WSL. 네이티브 설치 프로그램만 자동 업데이트를 지원합니다.
첫 실행: 터미널에서 claude를 실행하고, 브라우저를 통해 인증하면 바로 시작할 수 있습니다.

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

Claude Code 설치 전 필요 사항

Claude Code의 네이티브 CLI, Homebrew, WinGet, npm, CMD, WSL 옵션을 보여주는 6가지 설치 방법 비교

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

시스템 요구 사항

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

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

Windows에서는 버전 10 빌드 1809 이상이 필요하며, 이는 Windows 10 October 2018 Update부터 Windows 11을 포함한 모든 이후 버전을 포함합니다. 대부분의 가이드에서 간과하는 중요한 전제 조건은 네이티브 Windows 설치 프로그램이 먼저 Git for Windows를 설치해야 한다는 것입니다. 이것이 없으면 설치 프로그램이 무성으로 실패하거나 혼란스러운 오류 메시지를 표시합니다. git-scm.com에서 Git for Windows를 다운로드하고, 기본 설정으로 설치 프로그램을 실행한 후, 터미널을 다시 시작하여 PATH가 새로운 git 명령어를 인식하도록 하세요. CI/CD 사용 사례를 위해 Windows Server 2019 이상도 지원됩니다.

Linux에서는 Ubuntu 20.04 이상이 공식적으로 지원되며, glibc 2.31 이상을 제공하는 대부분의 최신 배포판도 지원됩니다. Debian 11+, Fedora 36+, Arch Linux 모두 문제없이 작동합니다. 설치 프로그램이 아키텍처(x86_64 또는 ARM64)를 자동으로 감지하므로 추가 구성이 필요 없습니다. Windows 머신의 WSL에서 Linux를 실행하는 경우, Linux 설치 방법이 동일하게 작동합니다. 이에 대해서는 아래 Windows 섹션에서 자세히 설명합니다.

모든 플랫폼에서 최소 4GB RAM(8GB 권장)과 초기 다운로드 및 인증을 위한 안정적인 인터넷 연결이 필요합니다. 설치된 바이너리는 비교적 작으므로(100MB 미만) 디스크 공간은 거의 문제가 되지 않습니다.

올바른 계정 선택

이것이 많은 개발자들이 예상치 못한 벽에 부딪히는 부분입니다. 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 런타임을 실행해야 했던 npm 기반 버전보다 더 빠르게 시작되고 안정적으로 실행됩니다. 관리해야 할 의존성이 없고, Node.js나 nvm과의 버전 충돌도 없으며, 업데이트가 백그라운드에서 자동으로 이루어집니다.

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

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

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

이 스크립트는 Claude Code 바이너리를 다운로드하고, 시스템에서 접근 가능한 위치에 배치하며, 셸 PATH를 업데이트하여 claude 명령어를 전역에서 사용할 수 있게 합니다. 양호한 인터넷 연결에서 전체 과정은 약 30초 정도 소요됩니다. 설치 후 새 터미널 창을 열거나(macOS에서는 source ~/.zshrc, Linux에서는 source ~/.bashrc를 실행) 셸이 새 PATH 항목을 인식하도록 하세요.

네이티브 설치 프로그램의 가장 큰 장점은 자동 업데이트입니다. Claude Code를 실행할 때마다 새 버전을 확인하고 백그라운드에서 원활하게 업데이트를 적용합니다. 설치 프로그램을 다시 실행하거나 업데이트를 확인할 필요가 없습니다. 항상 최신 상태를 유지합니다. 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를 사용하는 대부분의 개발자에게는 익숙한 패키지 관리자 내에서 머무르는 편의성이 수동 업데이트 단계보다 중요합니다.

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

bash
claude --version

나중에 업데이트하려면:

bash
brew upgrade claude-code

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

설치 확인

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

bash
which claude
claude --version

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

Windows에서 Claude Code 설치하기

네이티브 PowerShell, WinGet, WSL 경로를 보여주는 Windows 설치 의사 결정 트리

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

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

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

먼저 Git for Windows가 설치되어 있는지 확인하세요. PowerShell을 열고 git --version을 실행합니다. 버전 번호가 표시되면 준비된 것입니다. 그렇지 않으면 git-scm.com에서 기본 설정으로 Git을 다운로드하여 설치한 후 PowerShell을 다시 시작하세요.

Git이 확인되면 PowerShell(CMD가 아님)에서 설치 프로그램을 실행하세요:

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

이것은 네이티브 바이너리를 다운로드하고 설치하여 claude 명령어를 전역에서 사용할 수 있게 합니다. PATH가 업데이트되도록 설치 후 새 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

wsl --install

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

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

WSL 사용 시 흔한 실수는 Windows 측에는 Node.js가 설치되어 있지만 WSL 환경 내부에는 없는 경우입니다. WSL을 통해 npm 설치 방법을 사용하는 경우, WSL 내부에 Node.js가 설치되어 있어야 합니다. Windows Node.js 설치는 WSL에서 보이지 않습니다. 네이티브 설치 프로그램은 Node.js 의존성이 없으므로 이 문제를 완전히 피할 수 있습니다.

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

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

이전에 npm install -g @anthropic-ai/claude-code를 사용하여 Claude Code를 설치한 경우, 네이티브 설치 프로그램으로 마이그레이션해야 합니다. npm 방법은 2026년 초부터 공식적으로 지원이 중단되었으며, 현재까지는 작동하지만 결국 업데이트를 받지 못하게 됩니다. 네이티브 설치 프로그램은 시작이 더 빠르고, 의존성이 전혀 없으며, 업데이트를 자동으로 처리합니다.

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

bash
# 1단계: 현재 설치 방법 확인
which claude
# node_modules 또는 .npm-global 내의 경로를 반환하면 npm 사용 중

# 2단계: npm 버전 제거
npm uninstall -g @anthropic-ai/claude-code

# 3단계: 제거 확인
which claude  # "not found"를 반환해야 함

# 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 버전이 중단한 지점에서 그대로 이어받습니다.

Claude Code 전용으로 nvm이나 asdf를 사용하여 Node.js 버전을 관리하고 있었다면, 이제 Claude Code를 Node.js 의존성 체인에서 완전히 제거하여 설정을 단순화할 수 있습니다. 이는 npm 기반 설치를 괴롭히던 "Node 버전 불일치" 오류의 전체 클래스를 제거합니다.

마이그레이션의 미묘한 이점 중 하나는 네이티브 바이너리가 npm 버전보다 상당히 빠르게 시작된다는 것입니다. npm 패키지는 실행할 때마다 Node.js 런타임을 초기화해야 했으며, 시스템에 따라 500~1500밀리초의 시작 시간이 추가되었습니다. 네이티브 바이너리는 런타임 의존성이 없는 정적으로 컴파일된 실행 파일이므로 거의 즉시 시작됩니다. 하루에 수십 번 Claude Code를 시작할 수 있는 작업일 동안, 이 차이가 눈에 띄게 부드러운 경험으로 이어집니다.

팀 전체에서 Claude Code를 관리하는 경우, 마이그레이션은 더욱 중요합니다. npm 방법에서는 모든 팀원이 동일한 Node.js 버전을 설치해야 했고, 개발자 간의 버전 불일치가 "제 컴퓨터에서는 작동합니다" 문제의 지속적인 원인이었습니다. 네이티브 설치 프로그램은 이 의존성을 완전히 제거합니다. 로컬 Node.js 설정에 관계없이 모든 팀원이 동일한 바이너리를 받습니다.

인증 및 첫 실행

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 계정을 통해 토큰당 과금으로 이루어집니다. laozhang.ai와 같은 API 릴레이 서비스를 통해 Claude Code를 연결할 때도 이 방법을 사용합니다. 이러한 서비스는 경쟁력 있는 요금으로 Claude 모델에 대한 통합 접근을 제공하며, 토큰당 과금이 구독 기반 제한보다 예측 가능한 자동화 워크플로우에서 Claude Code를 실행하는 팀에게 특히 유용합니다.

서드파티 클라우드 제공자 — 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가 가장 잘못할 가능성이 높은 결정이기 때문입니다.

일반적인 설치 문제 해결

신규 사용자의 약 60%가 설치 또는 첫 실행 중 적어도 하나의 문제를 겪지만, 좋은 소식은 대부분의 문제가 5분 이내에 해결된다는 것입니다. 내장 진단 도구가 대부분의 구성 문제를 자동으로 포착합니다:

bash
claude doctor

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

"command not found: claude"

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

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

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

명령어가 여전히 찾을 수 없다면, 설치 프로그램이 실제로 PATH 항목을 추가했는지 확인하세요:

bash
grep -r "claude" ~/.zshrc ~/.bashrc ~/.profile 2>/dev/null

Windows에서는 PowerShell을 완전히 닫고 다시 여세요. 명령어가 여전히 찾을 수 없다면, Git for Windows가 설치되어 있는지 확인하고(git --version), 마지막 수단으로 컴퓨터를 재시작하세요.

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

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

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

또는 더 나은 방법으로, 이 전체 문제 클래스를 피할 수 있는 네이티브 설치 프로그램으로 전환하세요.

인증 실패

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

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

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

Windows 관련 문제

가장 일반적인 Windows 문제는 Git for Windows가 없어서 설치 프로그램이 실패하는 것입니다. 오류 메시지가 이 의존성에 대해 항상 명확하지는 않습니다. 항상 먼저 Git을 설치하고, 터미널을 다시 시작한 후, Claude Code 설치 프로그램을 실행하세요.

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 요금제 비교

적절한 요금제를 선택하면 과소비와 좌절스러운 속도 제한을 모두 방지할 수 있습니다. 결정은 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 통합 서비스와 특히 잘 작동합니다. 예를 들어, laozhang.ai는 다른 제공자와 함께 Claude 모델에 대한 접근을 제공하며, 여러 프로젝트에서 다양한 AI 도구를 실행할 때 결제를 단순화합니다. 단일 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 속도 제한 상세 가이드를 참조하세요.

설치 방법 한눈에 비교

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 18+	레거시 / 버전 고정
WSL	Windows	WSL 내 Linux 설치 프로그램	예 (Linux 경유)	WSL2	Linux 중심 개발자

네이티브 설치 프로그램은 대다수 사용자에게 권장되는 방법입니다. 의존성이 전혀 없고, 조용히 자동 업데이트되며, 가장 안정적인 경험을 제공합니다. Homebrew와 WinGet은 패키지 관리자를 통해 도구를 관리하는 것을 선호하고 수동으로 업데이트를 실행하는 것에 개의치 않는 경우 좋은 대안입니다. npm 방법은 여전히 작동하지만 지원이 중단되었습니다. 호환성을 위해 특정 Claude Code 버전을 고정해야 하는 경우에만 사용하세요.

자주 묻는 질문

Claude Code에 Node.js가 필요한가요? 아니요. 네이티브 설치 프로그램과 Homebrew 방법은 외부 의존성이 전혀 없습니다. 레거시 npm 방법만 Node.js 18 이상이 필요합니다.

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

Claude Code를 완전히 제거하려면 어떻게 하나요? 네이티브 설치 프로그램의 경우, 바이너리를 제거하고(which claude로 위치 확인) 구성 디렉토리를 삭제하세요(rm -rf ~/.claude). Homebrew의 경우 brew uninstall claude-code를 실행하세요. npm의 경우 npm uninstall -g @anthropic-ai/claude-code를 실행하세요.

구독 없이 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 비교에서 각 도구의 장점, 단점 및 이상적인 사용 사례에 대한 상세한 분석을 제공합니다. 이미 Claude Code를 사용하고 있고 사용량 제한에 부딪히는 개발자를 위해, Claude Code 속도 제한 관리 가이드에서 사용 가능한 쿼터를 최대화하기 위한 실용적인 전략을 다룹니다.

다양한 워크플로우에 맞는 AI 코딩 도구에 대한 더 넓은 관점이 필요하다면, API 제공자를 통한 AI 도구 연결 비교에서 Claude Code와 함께 작동하는 유연한 멀티 모델 접근 설정 방법을 다룹니다.

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(레거시), Windows CMD, WSL. 네이티브 설치 프로그램만 자동 업데이트를 지원합니다. - 첫 실행: 터미널에서 claude를 실행하고, 브라우저를 통해 인증하면 바로 시작할 수 있습니다.

Claude Code 설치 전 필요 사항

시스템 요구 사항

Windows에서는 버전 10 빌드 1809 이상이 필요하며, 이는 Windows 10 October 2018 Update부터 Windows 11을 포함한 모든 이후 버전을 포함합니다. 대부분의 가이드에서 간과하는 중요한 전제 조건은 네이티브 Windows 설치 프로그램이 먼저 Git for Windows를 설치해야 한다는 것입니다. 이것이 없으면 설치 프로그램이 무성으로 실패하거나 혼란스러운 오류 메시지를 표시합니다. git-scm.com에서 Git for Windows를 다운로드하고, 기본 설정으로 설치 프로그램을 실행한 후, 터미널을 다시 시작하여 PATH가 새로운 git 명령어를 인식하도록 하세요. CI/CD 사용 사례를 위해 Windows Server 2019 이상도 지원됩니다.

올바른 계정 선택

macOS 및 Linux에서 Claude Code 설치하기

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

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

이 스크립트는 Claude Code 바이너리를 다운로드하고, 시스템에서 접근 가능한 위치에 배치하며, 셸 PATH를 업데이트하여 claude 명령어를 전역에서 사용할 수 있게 합니다. 양호한 인터넷 연결에서 전체 과정은 약 30초 정도 소요됩니다. 설치 후 새 터미널 창을 열거나(macOS에서는 source ~/.zshrc, Linux에서는 source ~/.bashrc를 실행) 셸이 새 PATH 항목을 인식하도록 하세요.

Homebrew 대안

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

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

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

나중에 업데이트하려면:

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

설치 확인

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

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

Windows에서 Claude Code 설치하기

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

먼저 Git for Windows가 설치되어 있는지 확인하세요. PowerShell을 열고 git --version을 실행합니다. 버전 번호가 표시되면 준비된 것입니다. 그렇지 않으면 git-scm.com에서 기본 설정으로 Git을 다운로드하여 설치한 후 PowerShell을 다시 시작하세요.

Git이 확인되면 PowerShell(CMD가 아님)에서 설치 프로그램을 실행하세요:

이것은 네이티브 바이너리를 다운로드하고 설치하여 claude 명령어를 전역에서 사용할 수 있게 합니다. PATH가 업데이트되도록 설치 후 새 PowerShell 창을 여세요. macOS/Linux 네이티브 설치 프로그램과 마찬가지로, 이 버전은 백그라운드에서 자동 업데이트됩니다.

WinGet 대안

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

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

Windows CMD 설치 프로그램

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

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

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

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

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

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

이전에 npm install -g @anthropic-ai/claude-code를 사용하여 Claude Code를 설치한 경우, 네이티브 설치 프로그램으로 마이그레이션해야 합니다. npm 방법은 2026년 초부터 공식적으로 지원이 중단되었으며, 현재까지는 작동하지만 결국 업데이트를 받지 못하게 됩니다. 네이티브 설치 프로그램은 시작이 더 빠르고, 의존성이 전혀 없으며, 업데이트를 자동으로 처리합니다.

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

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

인증 및 첫 실행

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

첫 실행 시, 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 환경 변수를 설정하세요:

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

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

CLAUDE.md로 프로젝트 초기화

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

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

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

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

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

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

일반적인 설치 문제 해결

"command not found: claude"

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

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

명령어가 여전히 찾을 수 없다면, 설치 프로그램이 실제로 PATH 항목을 추가했는지 확인하세요:

Windows에서는 PowerShell을 완전히 닫고 다시 여세요. 명령어가 여전히 찾을 수 없다면, Git for Windows가 설치되어 있는지 확인하고(git --version), 마지막 수단으로 컴퓨터를 재시작하세요.

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

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

또는 더 나은 방법으로, 이 전체 문제 클래스를 피할 수 있는 네이티브 설치 프로그램으로 전환하세요.

인증 실패

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

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

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

Windows 관련 문제

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

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

네트워크 및 프록시 문제

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

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

설치 후 느린 성능

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

어떤 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 통합 서비스와 특히 잘 작동합니다. 예를 들어, laozhang.ai는 다른 제공자와 함께 Claude 모델에 대한 접근을 제공하며, 여러 프로젝트에서 다양한 AI 도구를 실행할 때 결제를 단순화합니다. 단일 Claude Code 명령어는 일반적으로 8~12개의 API 호출을 생성하므로, 집중 세션은 API 비용으로 $0.50~$2.00을 소비할 수 있어 가끔 사용하는 경우 구독보다 상당히 저렴합니다.

설치 방법 한눈에 비교

자주 묻는 질문

Claude Code에 Node.js가 필요한가요? 아니요. 네이티브 설치 프로그램과 Homebrew 방법은 외부 의존성이 전혀 없습니다. 레거시 npm 방법만 Node.js 18 이상이 필요합니다.

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

Claude Code를 완전히 제거하려면 어떻게 하나요? 네이티브 설치 프로그램의 경우, 바이너리를 제거하고(which claude로 위치 확인) 구성 디렉토리를 삭제하세요(rm -rf ~/.claude). Homebrew의 경우 brew uninstall claude-code를 실행하세요. npm의 경우 npm uninstall -g @anthropic-ai/claude-code를 실행하세요.

구독 없이 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는 동일한 인증과 구성을 공유하므로, 하나를 설치하면 둘 다 접근할 수 있습니다.

마무리 및 다음 단계

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

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

#Claude Code #설치 가이드 #AI 코딩 도구 #개발자 도구

laozhang.ai

One API, All AI Models

Docs

AI Image

Gemini 3 Pro Image

$0.05/img

80% OFF

AI Video

Sora 2 · Veo 3.1

$0.15/video

Async API

AI Chat

GPT · Claude · Gemini

200+ models

Official Price

Served 100K+ developers·No Charge on Failures·Enterprise Stable·Alipay/WeChat

|@laozhang_cn|Get $0.1