Claude Code 설치 방법 완전 정복 – 2026년 최신 가이드

macOS, Linux, Windows에서 Claude Code 설치하는 방법을 단계별로 안내합니다. 네이티브 설치, npm, Homebrew, 인증, MCP 설정, AnyCap 에이전트 기능 추가까지 완벽 해설.

어두운 모니터에 초록색 성공 메시지와 함께 Claude Code CLI 설치 화면을 보여주는 개발자 터미널

Claude Code는 Anthropic이 만든 터미널 기반 AI 코딩 에이전트입니다. 코드베이스를 읽고, 실제 파일을 편집하고, 셸 명령을 실행하며, git을 관리합니다—모두 커맨드 라인에서. 브라우저 탭도 복사 붙여넣기도 필요 없습니다.

이 가이드는 모든 설치 방법(네이티브, npm, Homebrew), 인증, 설정, 그리고 가장 중요한—설치 후 무엇을 해야 하는지를 다룹니다. Claude Code를 단순한 코딩 어시스턴트에서 이미지 생성, 동영상, 웹 검색, 클라우드 스토리지를 갖춘 완전한 멀티모달 에이전트로 탈바꿈시키는 방법을 알려드립니다.

사전 요구사항

설치 전 다음을 확인하세요:

운영 체제: macOS 13+(Ventura), Ubuntu 20.04+ / Debian 10+, 또는 WSL이 포함된 Windows 10(1809+)
RAM: 최소 4 GB, 대형 코드베이스에는 8 GB 권장
인터넷 연결: 모든 AI 처리는 Anthropic의 클라우드 인프라에서 실행됩니다—연결 없이는 Claude Code를 사용할 수 없습니다
Anthropic 계정: Claude Pro(월 $20), Max(월 $100–200), Teams, Enterprise, 또는 Console(API) 계정. 무료 Claude.ai 플랜은 Claude Code를 포함하지 않습니다. 플랜 선택 도움말은 Claude Code 요금제 비교를 참조하세요.
터미널: Bash, Zsh, 또는 PowerShell
Node.js 18+: npm 설치 방법에만 필요

GPU는 필요하지 않습니다. 여러분의 컴퓨터는 가벼운 CLI 클라이언트만 실행하며, 모든 AI 연산은 서버에서 처리됩니다.

1단계: Node.js 설치 (npm 방법만 해당)

네이티브 설치 프로그램을 사용할 계획이라면—현재 Anthropic이 권장하는 방법—이 단계를 완전히 건너뛰세요. 네이티브 설치 프로그램은 의존성이 없습니다.

npm 사용자는 Node 버전을 확인하세요:

node --version

출력이 v18.0.0 이상이면 2단계로 이동하세요. 그렇지 않으면 권한 문제를 피하기 위해 nvm(Node Version Manager)을 통해 설치하세요:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

터미널을 닫았다가 다시 열고:

nvm install 22
nvm use 22
node --version  # Should show v22.x.x

Node.js 22는 현재 LTS 릴리스로 Claude Code와 완벽하게 호환됩니다.

2단계: Claude Code 설치

세 가지 설치 방법이 있습니다. 하나를 선택하세요.

옵션 A: 네이티브 설치 프로그램 (권장)

의존성 없음. 백그라운드에서 자동 업데이트. Anthropic이 주로 테스트하고 지원하는 방법입니다.

macOS 및 Linux:

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

Windows (PowerShell, 관리자로 실행):

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

설치 프로그램이 claude 바이너리를 PATH에 추가하고 자동 업데이트를 구성합니다. 처음부터 끝까지 1분 이내입니다.

옵션 B: Homebrew (macOS / Linux)

brew install --cask claude-code

주의 사항: Homebrew 설치는 자동으로 업데이트되지 않습니다. brew upgrade claude-code를 주기적으로 실행하세요.

옵션 C: npm

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

sudo를 사용하지 마세요. EACCES 권한 오류가 발생하면 해결책은 nvm입니다—npm을 root로 실행하는 것이 아닙니다. root 소유의 npm 디렉터리는 연쇄 권한 문제를 일으킵니다.

확인

설치가 성공했는지 확인하세요:

claude --version

전체 환경 진단:

claude doctor

3단계: 인증

claude

첫 실행 시 Claude Code가 OAuth 인증을 위해 브라우저를 엽니다. Anthropic 계정에 로그인하고 CLI를 승인하면 연결됩니다.

인증 옵션

브라우저 OAuth (기본값): 개인 컴퓨터에 최적. Pro, Max, Teams, Enterprise 계정과 호환. 승인 후 세션 토큰이 로컬에 저장됩니다.

API 키 (CI/CD 및 헤드리스): 브라우저를 사용할 수 없는 서버, 컨테이너, 파이프라인의 경우:

export ANTHROPIC_API_KEY=sk-ant-your-key-here
claude

키는 console.anthropic.com에서 생성하세요. API 사용은 Anthropic의 표준 요금으로 토큰당 청구됩니다. 구독과 API 청구의 전체 비교는 Claude Code 요금 가이드를 참조하세요.

어떤 청구 모델을 선택할까요? 구독(Pro/Max)은 일상적인 사용에 더 간단하며 월간 플랜에 Claude Code가 포함됩니다. API 청구는 변동적이거나 자동화된 워크로드에 대한 세밀한 제어를 제공합니다.

4단계: 첫 번째 Claude Code 세션

아무 프로젝트 디렉터리로 이동하세요:

cd ~/my-project
claude

Claude Code가 프로젝트 구조를 읽고 대화형 REPL로 진입합니다. 위험 부담이 낮은 것부터 시작하세요:

> Explain the architecture of this project

파일을 스캔하고, 스택을 파악하고, 구조적 요약을 제공합니다. 그런 다음 실제 결과가 있는 작업을 시도해 보세요:

> Add input validation to the user registration form

Claude Code가 관련 파일을 식별하고, 변경 사항을 제안하고, 확인을 기다립니다. 수락하기 전에 diff 뷰에서 각 변경 사항을 검토할 수 있습니다—파일을 무작위로 덮어쓰지 않습니다.

대화형 모드에 진입하지 않고 일회성 작업을 수행하려면 -p (print) 플래그를 사용하세요:

claude -p "Write unit tests for the auth module"

작업을 실행하고, 결과를 출력하고, 종료합니다. 스크립팅과 CI/CD 파이프라인에 적합합니다.

5단계: Claude Code 설정

모델 선택

Claude Code는 기본적으로 최신 사용 가능한 모델을 사용합니다. 재정의하려면:

# 기본 모델 설정
claude config set model claude-opus-4-7

# 또는 단일 세션의 경우
claude --model claude-sonnet-4-6

권한

Claude Code는 파일 쓰기나 명령 실행 전에 확인을 요청합니다. 특정 프로젝트를 신뢰한다면:

claude config set permissions.auto-accept-edits true

속도를 위해 유용합니다. 프로덕션 코드 작업 시에는 덜 유용합니다. 모든 권한 모드, 서브에이전트, 훅에 대한 심층 분석은 Claude Code 고급 기능 가이드를 참조하세요.

프로젝트 수준 설정

팀 공유 구성을 위해 프로젝트 루트에 .claude/settings.json을 생성하세요(이 파일을 커밋하세요):

{
  "permissions": {
    "allow": ["read", "write", "shell"],
    "deny": ["shell:rm -rf *"]
  },
  "model": "claude-sonnet-4-6",
  "environment": {
    "NODE_ENV": "development"
  }
}

커밋하지 않아야 하는 개인 재정의는 .claude/settings.local.json을 사용하세요.

CLAUDE.md

가장 영향력 있는 설정입니다. 프로젝트 루트에 CLAUDE.md 파일을 만들어 Claude에 영구적인 컨텍스트를 제공하세요: 빌드 명령, 코드 규칙, 아키텍처 결정. Claude Code 내에서 /init을 실행하면 자동으로 생성되며, 그 후 커스터마이징하세요.

좋은 CLAUDE.md는 간결합니다—50–100줄을 목표로 하세요. 각 줄에 대해 "이것을 제거하면 Claude가 실수를 할까?"라고 물어보세요. 그렇지 않다면 삭제하세요.

플랫폼별 안내

macOS

Apple Silicon(M1–M4)과 Intel Mac 모두 지원됩니다. 네이티브 설치 프로그램이 가장 깔끔한 방법입니다:

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

Linux

Ubuntu 20.04+, Debian 10+, 그리고 대부분의 현대 배포판에서 작동합니다. macOS와 동일한 네이티브 설치 프로그램을 사용하세요. 구형 배포판에서는 nvm과 함께 npm을 사용하세요.

Windows

옵션 1: 네이티브 PowerShell 설치 프로그램

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

옵션 2: WSL (완전한 Linux 호환성을 위해 권장)

wsl --install
# 재부팅 후, WSL 터미널에서:
curl -fsSL https://claude.ai/install.sh | bash

Docker

FROM node:22-alpine
RUN npm install -g @anthropic-ai/claude-code

런타임 시 API 키를 환경 변수로 전달하세요—이미지에 하드코딩하지 마세요.

CI/CD (GitHub Actions 예시)

- name: AI Code Review
  run: |
    npx @anthropic-ai/claude-code -p "Review this PR for bugs" --output-format json
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

IDE 통합

Claude Code는 터미널 우선이지만, IDE 플러그인으로 네이티브 diff 보기를 제공합니다.

VS Code: 확장 프로그램 패널에서 "Claude Code"를 설치하거나:

code --install-extension anthropic.claude-code

JetBrains: 설정 → 플러그인 → Marketplace → "Claude Code" 검색 → 설치. 변경 사항이 IDE의 네이티브 diff 뷰어에 표시됩니다.

설치 그 이상: Claude Code에 에이전트 기능 추가하기

대부분의 설정 가이드는 여기서 멈춥니다. Claude Code가 설치되고, 인증되고, 실행 중입니다—하지만 기본 CLI가 제공하는 것(파일 편집, 셸 명령, git 작업)에 제한됩니다.

Claude Code가 기본적으로 할 수 없는 것:

이미지 생성 또는 사진 편집
동영상 생성 또는 분석
실시간 웹 검색
클라우드 스토리지에 파일 저장 및 검색
웹에 콘텐츠 게시

이러한 기능에는 MCP 서버(Model Context Protocol)가 필요합니다. MCP는 AI 에이전트가 외부 도구에 연결할 수 있게 해주는 개방형 표준입니다. Claude Code는 MCP를 기본으로 지원합니다—서버를 구성하면 Claude가 직접 호출할 수 있습니다. 전체 안내는 MCP로 Claude Code에 기능 추가하기 가이드를 참조하세요.

빠른 방법: AnyCap Agent CLI

개별 MCP 서버를 하나씩 구성하는 대신, 단일 CLI로 Claude Code에 완전한 에이전트 기능 세트를 제공할 수 있습니다:

npx -y skills add anycap-ai/anycap -a claude-code

이것은 AnyCap의 에이전트 기능 런타임을 설치하여 Claude Code가 다음에 접근할 수 있게 합니다:

기능	설명	예시
이미지 생성	텍스트 프롬프트로 이미지 생성 및 편집	"랜딩 페이지용 히어로 이미지 생성해줘"
동영상 생성	텍스트나 이미지로 동영상 제작	"제품 데모 워크스루 영상 만들어줘"
웹 검색	실시간 인터넷 검색 및 크롤링	"최신 API 변경 사항 조사해줘"
클라우드 스토리지	파일 업로드, 공유 및 검색	"프로젝트 자산 저장하고 공유 링크 생성해줘"
웹 게시	웹에 콘텐츠 배포	"변경 로그를 웹 페이지로 게시해줘"

하나의 CLI. 하나의 인증 흐름. 모든 기능. 이미지 생성, 동영상, 검색, 스토리지를 위한 별도의 API 키를 관리할 필요가 없습니다—AnyCap이 단일 설치를 통해 모든 것을 처리합니다. 수동 서버 구성 옵션을 포함한 MCP 통합에 대한 심층 분석은 MCP 기능 가이드를 참조하세요.

수동 MCP 구성

MCP 서버를 개별적으로 구성하려면 프로젝트 루트의 .mcp.json에 추가하세요:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"]
    }
  }
}

또는 대화형으로 추가하세요:

claude mcp add github -- npx -y @modelcontextprotocol/server-github
claude mcp list
claude mcp get github

문제 해결

문제	해결 방법
"command not found: claude"	새 터미널 창을 여세요. 그래도 안 되면 설치 프로그램을 다시 실행하거나 PATH를 확인하세요.
Node.js 버전이 너무 낮음	`nvm install 22 && nvm use 22`
npm EACCES 오류	절대 `sudo`를 사용하지 마세요. 대신 nvm을 사용하세요.
인증을 위한 브라우저가 열리지 않음	API 키 사용: `export ANTHROPIC_API_KEY=sk-ant-...`
설치 중 네트워크 오류	프록시 설정 확인. npm 레지스트리 설정: `npm config set registry https://registry.npmjs.org/`
Claude Code가 느리게 실행됨	Anthropic API에 대한 네트워크 지연. `status.anthropic.com` 확인. VPN이 활성화된 경우 연결 해제.

수동 디버깅에 시간을 쓰기 전에 claude doctor를 실행하세요—대부분의 구성 문제를 자동으로 감지합니다.

Claude Code 업데이트 유지하기

네이티브 설치 프로그램: 업데이트가 자동으로 이루어집니다. 별도 작업 필요 없음. claude --version으로 버전을 확인하세요.

npm: npm update -g @anthropic-ai/claude-code

Homebrew: brew upgrade claude-code

다음 단계

Claude Code가 설치되었습니다. 다음 단계:

CLAUDE.md 생성 — Claude Code 내에서 /init을 실행하여 영구적인 프로젝트 컨텍스트를 제공하세요.
에이전트 기능 추가 — AnyCap을 설치하여 Claude Code에 이미지 생성, 동영상, 검색, 스토리지를 추가하세요. MCP 기능 가이드를 참조하세요.
실제 작업 시도 — 보통 20분 걸리는 작업을 선택하여 Claude가 어떻게 처리하는지 확인해 보세요.

Claude Code 설치 및 설정 완전 가이드 (2026)