2강. 설치와 초기 설정 | 클로드 코드 완벽 마스터 30강 · 입문 — NUGUNA

🎯 학습 목표

이 강에서는 내 컴퓨터에 클로드 코드를 설치하고, 계정을 연결하고, 제대로 설치됐는지 확인하는 과정을 처음부터 끝까지 따라 합니다. 설치 방법이 여러 가지라서 처음에는 헷갈리기 쉬운데, 이 강을 마치면 어떤 방법을 왜 고르는지까지 판단할 수 있습니다.

내 운영체제가 클로드 코드의 시스템 요구사항을 충족하는지 확인할 수 있습니다.
공식 권장 방식인 네이티브 설치로 macOS·Linux·Windows에 설치할 수 있습니다.
구독 로그인과 API 키 인증의 차이를 이해하고 알맞은 방식을 고를 수 있습니다.
claude --version과 claude doctor로 설치 상태를 점검할 수 있습니다.

참고: 예전 자료에는 "Node.js를 설치한 뒤 npm으로 설치"하는 방법이 먼저 나옵니다. 현재 공식 문서는 Node.js가 필요 없는 네이티브 설치를 권장하며, npm 설치는 대안으로 안내합니다. 이 강은 최신 공식 문서 기준으로 설명합니다.

🖥️ 설치 전 확인: 시스템 요구사항

이 섹션에서는 설치 전에 확인해야 할 조건을 살펴보겠습니다. 설치 실패의 상당수는 명령어 문제가 아니라 환경 조건을 놓쳐서 생깁니다.

항목	공식 요구사항
운영체제	macOS 13.0 이상, Windows 10 1809 이상 또는 Windows Server 2019 이상, Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상
하드웨어	RAM 4GB 이상, x64 또는 ARM64 프로세서
네트워크	인터넷 연결 필수
셸	Bash, Zsh, PowerShell, CMD
지역	앤트로픽이 서비스하는 국가

계정 조건도 중요합니다. 공식 문서는 클로드 코드를 쓰려면 Pro, Max, Team, Enterprise 또는 Console 계정이 필요하며, 무료 Claude.ai 요금제에는 클로드 코드가 포함되지 않는다고 명시합니다. 회사에서 Amazon Bedrock, Google Cloud, Microsoft Foundry 같은 클라우드 제공자를 쓴다면 그 계정으로도 연결할 수 있습니다.

Windows 사용자는 한 가지를 먼저 정해야 합니다. Windows에서 바로 실행할지, WSL(Windows Subsystem for Linux) 안에서 실행할지입니다. Windows용 프로젝트라면 네이티브가 편하고, Linux 도구를 주로 쓰거나 명령 실행을 격리하는 샌드박스 기능이 필요하면 WSL 2를 선택합니다. 공식 문서 기준으로 샌드박스는 WSL 2에서만 지원되고 네이티브 Windows와 WSL 1에서는 지원되지 않습니다.

📦 설치 방법별 따라 하기

이 섹션에서는 운영체제별 설치 명령을 실제로 입력해 보겠습니다. 가장 먼저 권장되는 방법은 공식 설치 스크립트를 쓰는 네이티브 설치입니다.

# 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

첫 번째 명령은 curl로 설치 스크립트를 내려받아 바로 bash에 넘겨 실행합니다. 두 번째는 PowerShell의 irm(Invoke-RestMethod)으로 스크립트를 받아 iex(Invoke-Expression)로 실행합니다. 세 번째는 CMD용으로, 파일을 받아 실행한 뒤 삭제합니다. 관리자 권한으로 실행할 필요는 없습니다.

자주 하는 실수는 PowerShell과 CMD를 혼동하는 것입니다. The token '&&' is not a valid statement separator가 보이면 PowerShell에서 CMD 명령을 입력한 것이고, 'irm' is not recognized가 보이면 그 반대입니다. 프롬프트가 PS C:\로 시작하면 PowerShell입니다. 또 네이티브 Windows에서는 Git for Windows 설치를 권장합니다. 설치돼 있으면 클로드 코드가 Git Bash로 Bash 도구를 쓰고, 없으면 PowerShell로 명령을 실행합니다. WSL은 필요 없습니다.

패키지 관리자를 선호한다면 다음 방법도 있습니다. 이때는 자동 업데이트 동작이 다르다는 점을 꼭 기억해야 합니다.

방법	명령	업데이트
네이티브(권장)	위 설치 스크립트	백그라운드 자동 업데이트
Homebrew	`brew install --cask claude-code`	수동: `brew upgrade claude-code`
WinGet	`winget install Anthropic.ClaudeCode`	수동: `winget upgrade Anthropic.ClaudeCode`
npm	`npm install -g @anthropic-ai/claude-code`	수동: 같은 명령에 `@latest`

npm 방식은 v2.1.198부터 Node.js 22 이상을 요구합니다. npm 패키지도 결국 네이티브 바이너리를 내려받아 연결하는 구조라, 실행 중에는 Node.js를 쓰지 않습니다. 공식 문서는 권한 문제와 보안 위험 때문에 sudo npm install -g를 절대 쓰지 말라고 경고합니다. 업그레이드할 때 npm update -g는 처음 설치한 버전 범위를 따라가 최신으로 올라가지 않을 수 있으니 피해야 합니다.

🔐 첫 실행과 계정 인증

이 섹션에서는 설치 후 처음 실행하고 계정을 연결하는 과정을 살펴보겠습니다.

cd ~/my-project
claude

작업할 프로젝트 폴더로 이동한 뒤 claude를 입력하면 대화형 세션이 열립니다. 처음 실행하면 브라우저 창이 열리고 로그인을 요청합니다. 브라우저가 자동으로 열리지 않으면 터미널에서 c를 눌러 로그인 주소를 복사해 직접 붙여 넣으면 됩니다. WSL2, SSH 접속, 컨테이너 환경에서는 브라우저가 로그인 후 터미널로 돌아오지 못하고 코드를 보여 주는 경우가 많습니다. 이때는 그 코드를 터미널의 Paste code here if prompted 칸에 붙여 넣습니다. 완료되면 Login successful이 표시됩니다.

인증 방식은 크게 두 갈래입니다. 개인 개발자라면 Pro·Max 구독 계정으로 로그인하는 방식이 기본입니다. 사용량에 따라 비용을 내는 API 방식을 원하면 Claude Console에서 발급한 키를 ANTHROPIC_API_KEY 환경 변수로 설정합니다. 이 변수가 있으면 클로드 코드는 브라우저 로그인을 건너뛰고 키 사용을 한 번 승인할지 묻습니다.

여기서 현장에서 정말 흔한 사고가 있습니다. 구독으로 로그인했는데 예전에 설정해 둔 API 키가 환경 변수에 남아 있는 경우입니다. 공식 문서의 인증 우선순위에서 ANTHROPIC_API_KEY는 구독 로그인보다 앞서므로, 승인하면 키가 쓰여 API 요금이 청구되거나 만료된 조직의 키라면 인증 오류가 납니다. 구독을 쓰려면 unset ANTHROPIC_API_KEY로 변수를 지우고, 세션 안에서 /status로 현재 어떤 인증이 쓰이는지 확인합니다. 로그아웃하고 다시 로그인하려면 /logout을 입력합니다.

인증 정보는 macOS에서는 암호화된 키체인에, Linux에서는 ~/.claude/.credentials.json(권한 0600)에, Windows에서는 %USERPROFILE%\.claude\.credentials.json에 저장됩니다. 이 파일을 다른 사람과 공유하거나 저장소에 올리면 안 됩니다.

✅ 설치 확인과 업데이트 관리

이 섹션에서는 설치가 제대로 됐는지 점검하고, 업데이트 방식을 설정하는 방법을 살펴보겠습니다. 아래는 WSL(Ubuntu)에 네이티브 설치한 환경에서 실제로 실행한 결과입니다.

$ claude --version
2.1.272 (Claude Code)

$ claude doctor
Claude Code doctor

Running: native (2.1.272)
Commit: 013cad548b76
Platform: linux-x64
Path: /home/chung/.local/share/claude/versions/2.1.272
Config install method: native
Search: OK (bundled)
Auto-updates: enabled
Auto-update channel: latest
Last update attempt: success → 2.1.272 (2026-09-15)
Managed settings (remote): not fetched — requires an Enterprise or Team subscription
Organization policy: not applicable to Pro and Max accounts

Remote Control
Control this session from claude.ai/code or the Claude mobile app

No installation issues found.

For a full setup checkup that can also fix issues, run /doctor in a Claude Code session.

claude --version이 버전 번호를 출력하면 설치 성공입니다. claude doctor는 세션을 시작하지 않고 설치 상태를 읽기 전용으로 진단합니다. Running: native는 설치 방식, Search: OK는 코드 검색 도구 정상, Auto-updates: enabled는 자동 업데이트가 켜져 있다는 뜻입니다. 마지막 줄처럼 세션 안에서 /doctor를 쓰면 문제를 고치는 것까지 도와줍니다. 여러분의 버전 번호는 설치 시점에 따라 다르게 나옵니다.

command not found가 나오면 대부분 실행 파일 경로가 PATH에 없는 경우입니다. 네이티브 설치는 macOS·Linux에서 ~/.local/bin/claude에 실행 파일 링크를 만들므로, 새 터미널을 열거나 이 경로가 PATH에 있는지 확인합니다. 설치 방법을 바꿨는데 이전 버전이 계속 실행된다면 설치가 두 개 겹친 경우이니 which claude로 위치를 확인합니다.

업데이트는 autoUpdatesChannel 설정으로 조절합니다. 기본값 "latest"는 새 기능을 바로 받고, "stable"은 보통 약 일주일 지난 버전을 쓰면서 큰 문제가 있던 릴리스를 건너뜁니다. 업무용으로 안정성을 우선한다면 세션에서 /config로 들어가 채널을 stable로 바꾸는 것을 고려해 보세요. 기다리지 않고 바로 최신으로 올리려면 claude update를 실행합니다.

📝 핵심 요약

체크	내용
☐ 요구사항	지원 OS, RAM 4GB 이상, 유료 요금제 또는 Console 계정(무료 요금제 불가)
☐ 설치	네이티브 설치 권장, npm은 Node.js 22 이상·sudo 금지
☐ 인증	구독 로그인 또는 `ANTHROPIC_API_KEY`, 남은 키 확인은 `/status`
☐ 점검	`claude --version`, `claude doctor`
☐ 업데이트	네이티브는 자동, 패키지 관리자는 수동, 채널은 latest/stable

다음 3강에서는 설치한 클로드 코드로 첫 번째 대화를 시작하고, 프롬프트 입력·중단·세션 이어 가기 같은 기본 조작을 익혀 보겠습니다.

설치와 초기 설정