대상 독자: 이제부터 Claude Code를 사용하기 시작하는 입문자 / 환경 구축을 정확하게 갖추고 싶은 개발자·팀 도입 담당자

전제 지식: 특별히 없음 (터미널을 조금 다뤄본 적이 있다면 읽기 쉽습니다)

이 기사에서 할 수 있는 것: 자신의 OS에 Claude Code를 올바르게 설치하고, 로그인·최초 기동까지 완료하여 첫 세션을 실행할 수 있음

Claude Code를 「아직 아무것도 설치하지 않은 상태」에서 「첫 세션이 작동하는 상태」까지 이끌어주는 셋업(Setup) 완전판입니다. 입문자는 바로 아래의 「10분·최단 루트」를 위에서부터 실행하면 작동합니다. 개발자를 위한 심층 내용(설치 방식의 선택, 인증·설정의 우선순위, 모델 선택, 업데이트 제어, 언인스톨)은 이후의 본편(제2층)에 정리했습니다. 읽고 나면 자신의 OS(macOS / Windows / Linux)에 맞는 방법으로 설치하고, 로그인하여 claude를 실행하며, 기본 설정·업데이트·언인스톨(Uninstall)까지 파악할 수 있습니다.

전제로, 유료 플랜 또는 Console 계정이 필요합니다. Pro / Max / Team / Enterprise 중 하나, 또는 Claude Console 계정이 필요합니다. 무료 Claude.ai 플랜에는 Claude Code가 포함되지 않습니다. 요금 기준(2026-06-27 시점, 모두 세금 별도)은 Pro 월 20달러(연 결제 시 월 17달러) / Max 월 100달러부터 / Team(Standard 플랜) 1시트 월 25달러(연 결제 시 월 20달러)입니다. 공식 요금 페이지에도 「표시된 가격에 세금은 포함되지 않습니다(Prices shown don't include applicable tax)」라고 명시되어 있습니다.

특히 일본 사용자는 2026년 4월 1일부터 소비세 10%가 별도로 가산된다는 점에 주의하십시오 (청구 통화는 USD 그대로이며, 소비세액은 적격 청구서에 JPY로 기재됩니다. 개인은 매입세액 공제를 받을 수 없으므로 실질적으로 10% 증가하며, 법인은 공제 가능합니다). 금액이나 세금 취급은 변경될 수 있으므로, 신청 전에 반드시 공식 요금 페이지에서 다시 확인하시기 바랍니다.

아래의 ①~⑦을 위에서부터 순서대로 실행하면, 설치부터 첫 세션 시작까지 완료됩니다. 어려운 용어가 나와도 지금은 신경 쓰지 않아도 괜찮습니다.

① 계정을 확인한다

유료 플랜(Pro / Max / Team / Enterprise) 또는 Claude Console 계정을 준비합니다.

② 자신의 OS를 선택한다

macOS / Linux / WSL, Windows(PowerShell), Windows(CMD) 중 하나를 선택합니다. Windows에서 「어떤 셸인지 모르겠다」면, 우선 PowerShell을 열어주세요.

③ 네이티브 인스톨러로 설치한다

자신의 환경에 맞는 명령어를 단 하나만 실행합니다.

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows（PowerShell）
irm https://claude.ai/install.ps1 | iex

:: Windows（CMD）
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

⚠️ 이것들은 인터넷에서 취득한 스크립트를 그대로 실행합니다. URL이 공식(claude.ai)인지 확인하십시오. 잘 되지 않을 때는 공식 Advanced setup에서 명령어를 다시 복사하십시오 (설치 URL이나 명령어는 과거에 변경된 적이 있습니다). 내용을 확인한 후 실행하는 방법은 후술할 「설치 방식의 선택」에서 다룹니다.

④ 설치를 확인한다

claude --version

2.1.195 (Claude Code)와 같이 버전 번호가 표시되면 OK입니다 (번호는 빈번하게 바뀌므로, 다른 숫자라도 문제없습니다).

⑤ 작업용 폴더를 만들고 이동한다

처음에는 확실하게 만들 수 있는 연습용 폴더에서 시도하는 것이 안전합니다.

# macOS / Linux / WSL
mkdir -p ~/claude-code-sandbox && cd ~/claude-code-sandbox

Windows (PowerShell)

New-Item -ItemType Directory -Force "$env:USERPROFILE\claude-code-sandbox"; Set-Location "$env:USERPROFILE\claude-code-sandbox"

claude-code-sandbox

는 단순한 연습용 폴더입니다. 익숙해지면 실제 프로젝트 폴더에서 claude를 실행하세요.

⑥ 실행하기

claude

처음 실행 시 다음 순서로 진행됩니다.

• 브라우저가 열리며 로그인을 요청합니다 (열리지 않을 경우 c를 누르면 로그인 URL이 복사되므로, 브라우저에 붙여넣으세요).
• 이 폴더를 신뢰할 것인지 확인하는 창이 나타납니다. 내용을 확인하고 화면 안내에 따라 선택합니다.
• 프롬프트 상단에 버전 · 현재 모델 · 작업 디렉토리가 표시되면 세션이 시작된 것입니다.

⑦ 작동 여부 확인하기

세션 내에서 /help를 입력하면 사용할 수 있는 명령어 목록이 표시됩니다. 여기까지 완료했다면 성공입니다. 실행이 되었다면 이 프로젝트는 무엇을 하는 것인가요?와 같이 한국어로 말을 걸어보세요. Claude Code가 파일을 편집하려고 하면 default 모드에서는 허가를 요청하므로, 내용을 확인하고 승인하면서 조작감을 익힐 수 있습니다.

Claude Code는 코드베이스를 읽고, 파일을 편집하며, 명령어를 실행하고, 개발 도구와 연동하는 에이전트형 (Agentic) 코딩 도구입니다. 터미널, IDE, 데스크톱 앱, 브라우저에서 이용할 수 있습니다. '에이전트형'이란 AI 스스로가 '다음에 무엇을 해야 할지'를 판단하면서, 파일 편집이나 명령어 실행과 같은 여러 단계를 어느 정도 자율적으로 진행하는 형식을 말합니다. 단순히 채팅으로 답하는 것을 넘어, 직접 손을 움직여 작업까지 진행한다고 상상하시면 됩니다.

주요 기능으로는 테스트 및 Lint 수정, 머지 컨플릭트 (Merge Conflict) 해결, 의존성 업데이트 자동화, 자연어를 통한 기능 추가 및 버그 수정, 커밋/풀 리퀘스트 (PR) 생성 (git과 직접 연동), **MCP (Model Context Protocol, 외부 도구와 연동하기 위한 공통 프로토콜)**를 통한 도구 연결, CLAUDE.md/스킬/훅 (Hook)을 통한 커스터마이징, 에이전트 팀 실행 등이 있습니다. AI의 처리는 Anthropic 또는 사용 중인 클라우드 프로바이더 (Amazon Bedrock / Google Vertex AI / Microsoft Foundry)의 서버 측에서 이루어지며, 어떤 경우든 인터넷 연결이 필수입니다. 프롬프트 설계, 명령어, CLAUDE.md 등은 다음 회차에서 다룹니다.

출처: Overview / Authentication / Advanced setup (2026-06-27 확인)

현재는 네이티브 인스톨러 (Native Installer)가 권장되며, Node.js는 불필요합니다. '네이티브 바이너리 (Native Binary)'란 OS가 즉시 실행할 수 있는 단일 실행 파일을 의미합니다. 이전에는 npm install -g로 설치하고 전제 조건으로 Node.js를 설치하는 안내가 일반적이었으나, 현재 권장 방식은 스탠드얼론 (Standalone) 네이티브 바이너리이므로 Node.js와 npm이 필요하지 않습니다. 예전 절차를 기억하고 계신 분들은 이 부분을 먼저 업데이트하시기 바랍니다.

Claude Code의 실체는 이 네이티브 바이너리이며, 'Node.js 앱'이 아닙니다. 후술할 npm 설치 방식도 내부적으로는 동일한 바이너리를 배포하는 것뿐입니다. 이 차이는 CI 이미지를 만드는 방법이나 버전 고정, sudo npm -g를 권장하지 않는 이유를 이해하는 데 매우 중요합니다.

• Node.js: 권장되는 네이티브 설치 시 불필요. Node.js 18 이상이 필요한 경우는 npm으로 설치하는 방법을 선택했을 때뿐입니다.
• ripgrep: 코드 검색에 사용하는 ripgrep은 통상적으로 Claude Code에 동봉되어 있습니다.

대부분의 경우 제1층③의 네이티브 인스톨러(Native Installer)로 완료됩니다. 권장 방식은 네이티브 인스톨러이며, 이는 스탠드얼론(Standalone) 네이티브 바이너리를 설치하고 백그라운드에서 자동 업데이트를 수행하여 항상 최신 상태를 유지합니다. 다음은 다른 방식을 사용하고자 하는 개발자 및 팀을 위한 내용입니다.

curl ... | bash

또는

irm ... | iex

는 취득한 스크립트를 그대로 실행합니다. 감사(Audit)를 중시하는 분이나 사내 배포 담당자는 일단 파일로 저장한 뒤 내용을 읽어보고 실행할 수 있습니다.

curl -fsSL https://claude.ai/install.sh -o install.sh # 먼저 저장
less install.sh # 내용 확인
bash install.sh # 확인 후 실행

공식 Advanced setup에는 배포 매니페스트의 체크섬(Checksum) 검증 및 서명(Signature) 검증 절차도 마련되어 있습니다. 감사 및 사내 배포 시에는 이러한 검증을 거치거나, 패키지 매니저(Package Manager) 경유 또는 MDM(단말 관리)을 통한 배포가 바람직합니다. 검증 명령의 완전한 절차는 운영 및 팀 도입을 다루는 W13에서 상세히 설명하겠습니다.

선택 기준: 일반적인 이용은 네이티브 인스톨러. 배포를 통제하고 싶은 Linux는 apt / dnf / apk (서명된 리포지토리). Homebrew는 이미 brew로 툴을 운용하고 있는 팀만 해당.

대체 설치 상세 정보 (Homebrew / WinGet / npm / Linux 패키지 매니저 / Alpine)

Homebrew (macOS / Linux)

brew install --cask claude-code

cask는 두 가지가 있습니다. claude-code는 stable 채널(대략 1주일 정도 늦게 추종하며, 큰 리그레션(Regression)이 있는 릴리스는 건너뜀)이며, claude-code@latest는 latest 채널을 따릅니다. Homebrew는 자동 업데이트를 하지 않습니다.

WinGet (Windows)

winget install Anthropic.ClaudeCode

WinGet은 자동 업데이트를 하지 않습니다.

npm (모든 플랫폼 · 임의)

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

npm에는 Node.js 18 이상이 필요합니다. 단, 이 npm 패키지는 스탠드얼론 인스톨러와 동일한 네이티브 바이너리를 설치합니다 (플랫폼별 옵션 의존성, 예: @anthropic-ai/claude-code-darwin-arm64를 통해 취득). Node.js가 필요한 이유는 npm이 옵션 의존성을 해결하여 바이너리를 취득하는 '설치 시'에만 필요하기 때문입니다. 설치 후의 claude 바이너리 자체는 Node를 호출하지 않으므로, 실행 시에는 Node가 필요하지 않습니다.

⚠️

sudo npm install -g는 사용하지 마세요 (권한 및 보안상의 리스크). 업그레이드는 npm install -g @anthropic-ai/claude-code@latest를 사용하고, npm update -g는 피하십시오.

Linux 패키지 매니저 (apt / dnf / apk)

Debian/Ubuntu (apt), Fedora/RHEL (dnf), Alpine (apk)용으로 서명된 리포지토리가 제공되며, 각각 stable과 latest 채널이 있습니다. 이것들은 Claude Code를 통해 자동 업데이트되지 않으며, 시스템의 업그레이드 절차를 사용합니다. 정확한 서명 키의 URL이나 핑거프린트(Fingerprint)는 디스트리뷰션마다 다르므로, 반드시 공식 Advanced setup에서 확인하십시오. apt의 핵심 흐름은 다음과 같습니다 (키 취득 및 리포지토리 등록의 구체적인 명령은 공식 페이지를 따를 것).

# ① 서명 키를 취득 (키 URL은 공식 setup 페이지에서 확인)
# ② 채널 (stable / latest)을 포함하여 리포지토리 등록
# ③ 설치
...

Alpine / musl 환경의 추가 절차

Alpine (musl)에서는 네이티브 인스톨러에 추가로 libgcc, libstdc++, ripgrep이 필요합니다.

이 필요합니다. 다음과 같이 설치하고, 설정에서 USE_BUILTIN_RIPGREP=0을 지정합니다.

apk add libgcc libstdc++ ripgrep

Windows에서는 네이티브 Windows에서 실행하거나, WSL (Windows Subsystem for Linux, Windows 내에서 Linux 환경을 실행하는 공식 메커니즘) 내에서 실행하는 것 중 선택할 수 있습니다. 공식적으로는 다음 세 가지가 정리되어 있습니다.

여기서 **샌드박스 (Sandbox)**란, Claude Code의 동작(파일 조작 및 명령 실행)을 안전한 범위 내에 가두어 시스템 전체에 영향을 미치지 않도록 하는 격리 메커니즘입니다. 입문 단계에서는 "안전하게 테스트하고 싶다면 WSL 2가 유리하다"라고 기억해 두는 것으로 충분합니다.

네이티브 Windows에서는 Git for Windows 도입이 권장됩니다. 설치되어 있으면 Claude Code가 Bash 도구를 사용할 수 있고, 설치되어 있지 않으면 PowerShell 도구가 대신 사용됩니다. WSL 구성에서는 필요하지 않습니다. WSL을 사용하는 경우에는 WSL 터미널 내에서 Linux용 인스톨러를 실행하십시오 (PowerShell이나 CMD가 아닙니다). 실행 또한 WSL 내에서 claude를 실행합니다.

터미널을 사용하고 싶지 않은 분들을 위해 macOS 및 Windows용 GUI 데스크톱 앱도 준비되어 있습니다 (입수 방법 및 기타 이용처는 후술할 "IDE·에디터 연동"에서 소개합니다).

출처: Advanced setup (2026-06-27 확인)

일반적인 이용 시에는 "claude를 실행하면 브라우저가 열리므로, 자신의 계정으로 로그인한다"만으로 충분합니다 (제1층 ⑥에서 실행 완료). 다음은 인증 정보의 저장 위치나 우선순위를 제어하고 싶은 개발자 및 팀을 위한 상세 내용입니다.

로그인에 사용할 수 있는 계정은 다음과 같습니다.

• Claude Pro / Max 구독 (Claude.ai 계정으로 로그인)
• Claude for Teams / Enterprise
• Claude Console (사전 충전한 크레딧을 통한 API 액세스)
• 클라우드 프로바이더 (Cloud Provider) (Amazon Bedrock / Google Vertex AI / Microsoft Foundry) — 환경 변수를 설정하며, 브라우저 로그인은 불필요

claude의 첫 실행 시 브라우저가 열립니다 (열리지 않을 경우 c로 로그인 URL을 복사). WSL2 / SSH / 컨테이너 환경에서는 리다이렉트 대신 **로그인 코드 (Login Code)**가 표시될 수 있으며, 이 경우 코드 입력 프롬프트에 붙여넣습니다. 계정 전환 및 재인증은 세션 내에서 /login, 로그아웃은 /logout을 사용합니다. 처음 Console에서 로그인하면, 비용 집계를 일원화하기 위한 "Claude Code" 워크스페이스가 Console 내에 자동으로 생성됩니다.

인증 정보 저장 위치 (OS별):

• macOS: 암호화된 Keychain
• Linux: ~/.claude/.credentials.json (권한 0600)
• Windows: %USERPROFILE%\.claude\.credentials.json (사용자 프로필의 액세스 제어를 상속하며, 기본적으로 자신의 사용자 계정으로만 제한)

API에 직접 액세스하는 경우에는 환경 변수 ANTHROPIC_API_KEY를 사용합니다 (X-Api-Key로 전송). 대화형 모드에서는 첫 실행 시 한 번만 승인/거부를 묻고, 비대화형 모드 (-p)에서는 존재할 경우 항상 사용됩니다.

인증 우선순위는 다음과 같습니다 (높은 순). 일반적인 이용에는 가장 아래에 있는 /login (OAuth)으로 충분하며, 상위 항목은 클라우드나 환경 변수를 사용하는 경우에 해당합니다.

• 클라우드 제공업체의 인증 정보 (Bedrock / Vertex / Foundry)
  ANTHROPIC_AUTH_TOKEN

ANTHROPIC_API_KEY

apiKeyHelper

CLAUDE_CODE_OAUTH_TOKEN

/login을 통한 구독 (Subscription) OAuth

자주 발생하는 함정: 구독을 사용 중임에도 ANTHROPIC_API_KEY가 설정되어 있으면, 한 번 승인된 API 키가 우선되어 예상치 못한 실패를 초래할 수 있습니다. 구독 모드로 되돌리려면 unset ANTHROPIC_API_KEY를 실행하고, /status로 상태를 확인하십시오.

CI(지속적 통합) 용도로는 claude setup-token을 통해 1년간 유효한 OAuth 토큰을 발행하여 CLAUDE_CODE_OAUTH_TOKEN에 설정할 수 있습니다 (Pro/Max/Team/Enterprise 플랜 필요).

출처: Authentication / Quickstart (2026-06-27 확인)

가장 빠르게 실행하는 단계는 다음 3단계입니다.

# 단계 1: 설치 (제1층 ③의 명령어로 완료됨)
# 단계 2: 로그인 (claude를 실행하고 브라우저 안내를 따름)
# 단계 3: 첫 세션 시작
...

실행하면 프롬프트 상단에 버전 · 현재 모델 · 작업 디렉토리가 표시됩니다. /help로 명령어 목록을 볼 수 있으며, /resume으로 이전 대화를 재개할 수 있습니다.

새로운 프로젝트에서 처음 Claude Code를 실행하면, 해당 폴더를 신뢰할 것인지 확인하는 메커니즘이 작동합니다. 이는 로그인 시의 브라우저 인증과는 별개인, 새로운 프로젝트 디렉토리 고유의 확인 절차입니다. 동작 방식은 다음과 같습니다 (확인 다이얼로그의 정확한 문구는 공식적인 축자 인용이 없으므로, 화면의 안내를 따라주십시오).

• 비대화형 모드 (-p 플래그)로 실행할 경우, 신뢰 확인은 무효화됩니다.
• 홈 디렉토리에서 직접 실행하면 신뢰 승인은 해당 세션에만 국한되며 디스크에 저장되지 않아, 실행할 때마다 확인이 다시 표시됩니다 (영구 저장 설정은 없습니다).
• 프로젝트의 하위 디렉토리에서 실행하면 승인 내용이 디렉토리 단위로 저장됩니다.

default 모드에서는 Claude Code가 파일을 변경하기 전에 허가를 요청합니다. 변경 사항을 개별적으로 승인하거나, 세션 중에만 '모두 승인 (Accept all)'을 활성화할 수 있으며, Shift+Tab으로 권한 모드를 순차적으로 전환할 수 있습니다. acceptEdits · auto · bypassPermissions 등 다른 모드로 전환하면 자동 승인 범위가 넓어지므로, 입문 단계에서는 default 상태를 유지하는 것이 안전합니다. default 모드에서는 엄격한 읽기 전용 권한이 사용되며, ls, cat, git status와 같은 읽기 전용 내장 명령어는 확인 없이 실행되지만, 시스템을 변경할 수 있는 Bash 명령어에는 명시적인 허가가 필요합니다. 또한 Claude Code가 쓸 수 있는 범위는 실행한 폴더와 그 하위 폴더뿐이며, 상위 디렉토리의 파일은 명시적인 허가 없이는 변경할 수 없습니다 (읽기는 작업 디렉토리 외부에서도 가능합니다).

권한 모드는 설정의 defaultMode에서 지정할 수 있으며, 다음과 같은 종류가 있습니다.

⚠️ bypassPermissions는 '모든 확인을 건너뛰는' 모드가 아닙니다. 명시적인 ask 규칙이나 rm -rf /, rm -rf ~...

와 같은 위험한 명령어에는 계속해서 확인 절차가 나타납니다. 그렇기는 하지만 많은 확인 과정을 건너뛰므로, 격리된 컨테이너나 VM(Virtual Machine)에서만 사용해 주세요.

claude # 대화 모드로 실행
claude "작업 내용" # 일회성 작업 요청
claude -p "질문 내용" # 한 번만 실행하고 종료
...

세션 내에서는 /clear (대화 리셋), /help (도움말), /exit (종료, Ctrl+D도 가능)를 사용할 수 있습니다. /를 입력하면 모든 명령어와 스킬(Skill)이 목록으로 표시되며, Tab으로 자동 완성, ↑로 히스토리를 불러올 수 있습니다.

출처: Quickstart / Security / Permissions (2026-06-27 확인)

처음에는 아무것도 건드리지 않아도 작동합니다. "설정은 이런 곳에 있다", "모델은 default (또는 sonnet)면 된다"라고만 파악해 두고, 필요해지면 다시 돌아오세요. 다음은 개발자 및 팀을 위한 상세 내용입니다.

우선순위는 높은 순서대로 다음과 같습니다. 파일뿐만 아니라 커맨드라인 인자(Command-line argument)를 포함하여 정리하는 것이 포인트입니다.

--model과 같은 커맨드라인 인자는 settings.json의 각 파일보다 우선시되지만, 조직의 관리(Managed) 설정에는 이길 수 없습니다. CI나 팀 운영 시에는 이 "커맨드라인 인자 계층"을 간과하면 동작의 불일치가 발생하기 쉬우므로 주의하십시오.

대화형 설정 UI는 /config로 열 수 있습니다. 설정 파일은 변경하면 기본적으로 자동으로 재로드되지만, 일부 항목은 반영 타이밍이 다릅니다.

• model: 세션 중에 전환할 때는 /model 명령어를 사용합니다. 설정 파일의 model 값을 수정했을 경우에는 다음 실행 시에 유효합니다 (/clear로는 전환되지 않습니다).
• outputStyle: 시스템 프롬프트(System Prompt)의 일부로 다시 구성되기 때문에, 반영을 위해서는 /clear 또는 재시작이 필요합니다.

모델은 처음에는 default (또는 sonnet)로 설정되어 있어도 대부분의 경우 문제가 없습니다.

# 실행 시 지정
claude --model sonnet # default / opus / haiku / opusplan / fable 등도 가능
# 세션 내에서 지정 ( /model 만 입력하면 피커(Picker)가 열림)
...

이 외에도 환경 변수 ANTHROPIC_MODEL이나 설정의 model 필드로도 지정할 수 있습니다. v2.1.153 이후부터는 /model을 통한 선택이 새로운 세션의 기본값으로 저장됩니다.

에일리어스(Alias) 목록 · 해결 버전 · 버전 하한 (2026-06-27 기준 참고)

준비된 에일리어스는 default (계정에 권장되는 모델), best, fable, sonnet...

、opus

、haiku

、sonnet[1m]

、opus[1m]

、opusplan (계획 시에는 opus, 실행 시에는 sonnet)

: 계정에 권장되는 모델로 해결됩니다. default

실제 해결 대상은 계정 유형 및 이용 경로에 따라 다릅니다 (아래 표 참고). -
: 그 시점에서 가장 성능이 높은 모델로 해결되며, 새로운 모델이 등장하면 해결 대상이 변경됩니다. best

: Fable 계열의 모델을 가리킵니다 (예: fable, claude-fable-5). -
:sonnet[1m] / opus[1m] 의 [1m]은 컨텍스트 윈도우 (Context Window)가 100만 (1M) 토큰인 모델을 의미합니다. 긴 문맥을 한 번에 처리하고 싶을 때 사용합니다. -
: 계획 (plan) 시에는 opus, 실행 시에는 sonnet을 사용합니다. opusplan

새로운 에일리어스 (Alias)에는 사용에 필요한 Claude Code의 최소 버전이 있습니다. 예를 들어 opus (Opus 4.8)는 v2.1.154 이상, fable (Fable 5)은 v2.1.170 이상이 필요합니다. 오래된 버전에서 새로운 에일리어스를 지정하면 해결에 실패할 수 있으므로, claude doctor