클로드 코드 설치법 완벽 가이드
Mac · Windows · VS Code 한 번에 끝내기

안녕하세요, 인프런입니다!

“클로드 코드가 그렇게 편하다던데, 일단 깔아보자” 하고 공식 문서를 켜셨다가, macOS / Windows / Linux / WSL / VS Code 확장이 섞여 나오는 문서 앞에서 멈추신 적 없으세요?

마케터인 저도 처음엔 그랬답니다... 비개발자 입장에서는 그래서 터미널이 뭔데... 검은 화면에서 머리가 하얘져서 멍때리게 되더라고요. 그래서 진짜 찐!! 터미널을 아예 켜본 적도 없던 분들을 대상으로, 설치 앞뒤로 자주 부딪히는 지점을 OS별로 정리하고, 자주 보이는 에러까지 담았어요.

설치 전 필수 준비물

설치 자체는 명령어 한 줄이면 끝나지만, 계정과 환경을 먼저 점검하지 않으면 “설치는 됐는데 로그인이 안 돼요” 상황을 꽤 자주 만나요. 네 가지만 확인하고 가실게요!

운영체제 · 하드웨어

• macOS 13.0 이상
• Windows 10 1809 이상 또는 Windows Server 2019 이상
• 하드웨어 4GB 이상 RAM, x64 또는 ARM64

Anthropic 계정과 구독 플랜

클로드 코드는 Pro / Max / Team / Enterprise 계정이 필요해요.

단, 무료 Claude.ai 계정으로는 클로드 코드를 쓸 수 없습니다!!!ㅠㅠ 설치 후 No subscription found 에러를 만났다면 99% 이 문제예요. 하루 3시간 이상 쓴다면 Max로 올리시면 됩니다. (플랜별 비교는 https://www.inflearn.com/pages/how-to-use-claudecode 에서 확인해 주세요!)

Node.js : npm 방식에만 필요해요.

네이티브 인스톨러, Homebrew, WinGet 을 쓰신다면 Node.js는 필요 없습니다. npm 으로 설치하신다면 Node.js 18 이상이 필요해요.

Git for Windows : Windows 네이티브 전용

Windows 네이티브 설치에서는 Git for Windows 가 꼭 깔려 있어야 해요. 링크로 들어가서 꼭 설치해주세요. 클로드 코드가 내부적으로 Git Bash 를 사용하기 때문이에요. WSL로 설치하신다면 필요 없어요!

Mac 설치 : brew · npm · Native

macOS 에서는 공식적으로 세 가지 방식을 제공합니다. 

방법 1. Native Installer : 공식 권장

가장 최신 버전을 받고, 백그라운드 자동 업데이트까지 붙어있어요. 터미널(맥 Spotlight에서 “터미널” 검색)을 켜고 아래의 한 줄만 붙여넣으시면 됩니다.

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

특정 채널이나 버전을 명시하고 싶다면 뒤에 인자를 붙이시면 됩니다. bash -s stable 은 안정 채널(약 1주 지연, 리그레션 스킵), bash -s 2.1.89 는 특정 버전이에요.

방법 2. Homebrew : 개발자 선호

brew 가 손에 익다면 이 방식이 제일 깔끔해요. cask 가 두 가지 있는데 claude-code 는 안정 채널(권장), claude-code@latest 는 최신 채널이에요.

brew install --cask claude-code

Homebrew 는 자동 업데이트가 안 됩니다. 주기적으로 brew upgrade claude-code 를 실행해주셔야 최신 기능과 보안 패치를 받아가요.

방법 3. npm : Node 생태계

이미 Node.js 기반으로 작업 중이라면 제일 익숙한 경로예요. Node.js 18 이상이 있으면 한 줄로 끝납니다.

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

sudo npm install -g 는 절대 쓰지 마세요! 권한 및 보안 문제가 발생합니다. 권한 오류가 나면 npm prefix 를 홈 디렉토리로 바꾸는 것이 정답이에요.

설치 확인

claude --version

이 명령어를 썼을 때 버전이 표시가 되면 설치 성공이에요. 설치 · 설정 진단이 필요하면 claude doctor 로 전체 리포트를 확인할 수 있습니다. 혹시 command not found 가 뜨면, 아래의 §7 트러블슈팅으로 가주세요.

Windows 설치 : npm · winget · PowerShell

Windows 는 Native Windows · WSL 2 · WSL 1 세 가지 경로가 있고 각각 기능이 달라요. 샌드박싱이 필요하시면 WSL 2 를, Windows 네이티브 프로젝트를 주로 다루신다면 Native 를 선택하시면 됩니다.

방법 1. Native Installer (PowerShell)

Windows 검색창에서 PowerShell을 검색해서 여시고, 아래 명령을 붙여넣으세요. 관리자 권한은 필요 없어요.

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

CMD(명령 프롬프트)를 쓰신다면 명령어가 달라요.

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

PowerShell 인지 CMD 인지 구분하는 법 : 프롬프트가 PS C:\> 로 시작하면 PowerShell, C:\> 만 보이면 CMD 예요.

방법 2. WinGet

Microsoft 공식 패키지 매니저로 한 줄 설치가 가능해요.

winget install Anthropic.ClaudeCode

단, 업데이트는 소식이 있을 때마다 실행하셔야 합니다(자동 업데이트 미지원). winget upgrade Anthropic.ClaudeCode 를 주기적으로 실행해주세요.

방법 3. npm

macOS 와 동일해요. Node.js 18 이상이 있으시면 npm install -g @anthropic-ai/claude-code 을 입력해서 실행해주세요.

방법 4. WSL 로 설치

샌드박싱이나 Linux 툴체인이 필요하다면 WSL 경로가 가장 강력해요. WSL 터미널을 열고 Linux 설치 명령을 그대로 실행하시면 됩니다.

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

주의. WSL 로 설치한 claude 는 WSL 터미널에서만 실행하세요. PowerShell 이나 CMD 에서는 동작하지 않아요.

VS Code 연동 설정

VS Code 확장은 GUI 패널로 Claude 를 직접 조작할 수 있게 해줍니다. 확장 자체에 CLI 가 포함되어 있어서 CLI 를 따로 설치하지 않아도 돼요.

사전 요구사항

• VS Code 1.98.0 이상
• Anthropic 계정 (처음 열 때 브라우저에서 로그인)

확장 설치 방법

VS Code 에서 Cmd + Shift + X (Mac) 또는 Ctrl + Shift + X (Windows) 로 Extensions 뷰를 열어주시거나, 왼쪽 사이드바에서 블럭 모양 아이콘을 클릭해 열어주세요. “Claude Code” 를 검색해 Anthropic 공식 배포본의 Install 을 눌러주세요. Cursor를 쓰신다면 Cursor 마켓플레이스에서 설치하시면 됩니다.

확장이 안 보이면 Cmd + Shift + P / Ctrl + Shift + P 에서 “Developer: Reload Window” 를 한 번 실행해주세요.

Spark 아이콘(✱)으로 Claude 열기

아래 사진에서 클로드 아이콘을 확인한 후 주황색 스파크 아이콘을 눌러주세요. 만약 뜨지 않는다면, VScode에서 폴더나 프로젝트가 열려있는 상태인지 확인해주세요. 아무것도 열려있지 않은 상태에서는 아이콘이 노출되지 않아요!!

설치가 끝나면 VS Code 곳곳에서 Spark 아이콘(✱) 이 Claude Code 진입점 역할을 해요.

• Editor Toolbar 에디터 우상단, 파일이 열려있을 때만 표시
• Activity Bar 좌측 사이드바, 항상 표시 (세션 리스트)
• Status Bar 우하단 ✱ Claude Code, 파일이 없어도 동작
• Command Palette  Cmd + Shift + P → “Claude Code”

핵심 단축키

설정 파일 위치

확장과 CLI 는 설정을 공유합니다. 한쪽에서 MCP 서버를 등록하면 다른 쪽에서도 바로 쓸 수 있어요. 설정 파일은 macOS / Linux / Windows 모두 ~/.claude/settings.json 경로입니다.

첫 실행 & 로그인

Step 1. 작업 폴더로 이동 & 실행

빈 폴더여도 괜찮아요. 실습용으로 하나 만들어 들어가시면 됩니다! 터미널도 좋지만, 저는 코드를 보는 가독성을 위해서 Vscode나 Antigravity, Cursor 같은 IDE 툴을 추천드려요.
Vscode나 Antigravity라면, Terminal - New Terminal을 클릭해서, 열린 터미널에서 claude 를 열면 됩니다.

Step 2. 브라우저에서 OAuth 로그인

기본 브라우저가 자동으로 열리고 Anthropic OAuth 동의 페이지가 뜹니다. 가입하신 Claude 계정으로 로그인 → 권한 승인하면 끝!

브라우저가 자동으로 안 열리는 환경(SSH · 원격 서버 등)이라면 터미널에 뜨는 OAuth URL 을 c 키로 복사해서 브라우저에 붙여넣으시면 됩니다.

Step 3. 자동 로그인 저장

인증이 끝나면 자격증명이 OS Keychain / Credential Manager 에 자동 저장돼요. 이후 실행부터는 자동 로그인되니 따로 로그인할 필요가 없습니다!

재로그인이 필요할 때

토큰이 만료되거나 계정을 바꾸고 싶다면 /logout 및 /login 을 실행해주세요.

클로드 코드 설치 오류가 생겼어요...! FAQ

공식 트러블슈팅 가이드와 실제 사용자 제보에서 빈도 높은 순으로 정리했어요. 한 번씩 훑어보시고 실제로 부딪혔을 때 다시 오시면 됩니다.

뭐가 문제인지 모르겠을 때는 claude doctor 부터 실행해주세요. 설치 경로, 인증 상태, 권한, Node 버전까지 한 번에 진단해줍니다. 대부분의 “갑자기 안 돼요” 상황은 여기서 원인이 드러나요.

여기까지 따라오셨다면 설치는 이미 끝나있을 거예요. 설치까지만 하면, 그 이후는 일사천리를 보장할게요. 이제부터가 진짜 재미있는 구간이거든요. 클로드 코드를 ‘자동완성 도구’가 아니라 ‘함께 계획하고 대화로 고치는 내 옆의 비서’로 써보실 때 진가가 드러나거든요!

설치 다음 단계가 궁금하시다면

🧭 사용법부터 첫 프로젝트까지 클로드 코드 사용법 완벽 가이드에서 이어집니다.
📊 다른 AI 코딩 도구와 비교 AI 코딩 도구 TOP 5를 참고해 주세요.

👇 클로드 코드로 실무 프로젝트까지 완성하는 강의 👇

이 글에서 다룬 설치를 실제 강의 안에서 더 깊이 활용해보실 수 있어요.