설치와 초기 설정: Mac과 Windows 한 번에

앞 편 Claude Code 시작하기에서 도구의 성격을 봤으니, 이번 편에서는 실제로 내 컴퓨터에 설치합니다. Mac과 Windows 각각의 한 줄 설치 명령, 대체 경로, 설치 확인 방법, 그리고 우리 수업에서 실제로 자주 마주친 오류의 대처법까지 다룹니다. 읽고 나면 claude --version에 버전이 찍히는 상태가 되고, 다음 편 로그인과 인증 설정으로 넘어갈 수 있습니다.

핵심 요약

• 설치는 네이티브 설치 프로그램 한 줄이면 끝납니다. Mac은 curl, Windows는 PowerShell의 irm 명령입니다.
• Node.js나 Python을 먼저 깔 필요가 없습니다. 인터넷의 오래된 글이 알려 주는 npm 방식은 대체 경로일 뿐입니다.
• 설치 확인은 claude --version, 더 자세한 점검은 claude doctor입니다.
• 네이티브 설치는 백그라운드에서 자동 업데이트됩니다. Homebrew, WinGet, npm 설치는 직접 올려야 합니다.
• 설치 직후 할 일 두 가지는 프로젝트 지침 파일(CLAUDE.md) 만들기와 권한 모드 이해하기입니다.

설치 전에 준비할 것

공식 시스템 요구사항은 macOS 13.0 이상, Windows 10 1809 이상 또는 Windows Server 2019 이상, Ubuntu 20.04 이상, Debian 10 이상, Alpine 3.19 이상이며, RAM 4GB 이상과 인터넷 연결이 필요합니다. 셸은 Bash, Zsh, PowerShell, CMD 모두 지원합니다. 계정은 Pro, Max, Team, Enterprise 구독 또는 Claude Console 계정이 필요하고, 무료 플랜으로는 Claude Code를 쓸 수 없습니다.

우리 2주차에서 강조하는 준비물이 하나 더 있습니다. 작업 폴더입니다. 내 사용자 폴더 아래에, 영문 이름으로, OneDrive 같은 클라우드 동기화 폴더 바깥에 만듭니다. 한글이나 공백이 든 경로와 동기화 폴더는 나중에 원인을 알 수 없는 오류의 단골입니다.

# Mac (터미널)
mkdir ~/work
cd ~/work

# Windows (PowerShell)
mkdir C:\Users\내이름\work
cd C:\Users\내이름\work

설치 방법 한눈에 비교

네 방법 모두 같은 네이티브 바이너리를 내려받으며 npm 방식도 실행 시 Node를 쓰지 않습니다. 특별한 이유가 없으면 네이티브 설치를 고릅니다.

Mac에 설치하기

네이티브 설치 (추천)

Spotlight에서 "터미널"을 검색해 열고 아래 한 줄을 그대로 붙여 넣습니다.

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

설치 프로그램은 ~/.local/bin/claude에 실행 파일을 두고 버전 파일은 ~/.local/share/claude/versions/에 관리합니다. 설치 후 터미널을 닫았다 열어 PATH를 새로 읽게 합니다. 안정 채널은 명령 끝에 -s stable을 붙입니다.

npm 경유 설치 (대체)

Node.js 22 이상이 이미 설치돼 있다면 npm으로도 설치할 수 있습니다.

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

sudo npm install -g는 권한 문제와 보안 위험을 만들므로 쓰지 않습니다. 업그레이드는 npm update -g가 아니라 npm install -g @anthropic-ai/claude-code@latest로 합니다. 전자는 원래 설치의 버전 범위를 존중해 최신으로 안 올라갈 수 있습니다.

Windows에 설치하기

Windows는 네이티브 Windows와 WSL 두 갈래가 있습니다. Windows 프로젝트와 Windows 도구를 쓰면 네이티브, Linux 도구 체인이나 샌드박스 명령 실행이 필요하면 WSL 2입니다. 우리 초급 과정은 네이티브 Windows로 진행합니다.

PowerShell로 설치하기 (추천)

시작 메뉴에서 "PowerShell"을 검색해 실행합니다(x86 항목이 아닌 일반 항목). 관리자 권한은 필요 없습니다.

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

실행 파일은 %USERPROFILE%\.local\bin\claude.exe에 놓입니다. Git for Windows를 함께 설치하면 Claude Code가 Git Bash를 Bash 도구로 쓰고, 없으면 PowerShell 도구로 셸 명령을 실행합니다. Git for Windows는 선택 사항이지만 Bash 기반 스크립트를 다룰 일이 많다면 설치를 권합니다.

명령 프롬프트로 설치하기

CMD를 써야 한다면 전용 명령이 있습니다.

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

프롬프트가 PS C:\로 시작하면 PowerShell, C:\로만 시작하면 CMD입니다. 두 명령을 서로 바꿔 넣으면 irm is not recognized 또는 The token '&&' is not valid 오류가 납니다.

WSL 경유 설치

WSL 배포판(Ubuntu 등)을 열고 Mac과 같은 Linux 설치 명령을 실행합니다. PowerShell이 아니라 WSL 터미널 안에서 설치하고 실행해야 합니다. WSL 1에서는 네이티브 바이너리 실행 오류가 보고돼 있으므로 wsl --set-version <배포판이름> 2로 WSL 2로 바꾸는 것이 깔끔합니다.

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

npm 경유 설치 (대체)

Windows에서도 Node.js 22 이상이 있다면 npm install -g @anthropic-ai/claude-code로 설치할 수 있습니다. 회사 npm 미러를 쓰는 환경이라면 @anthropic-ai/claude-code-win32-x64 같은 플랫폼별 패키지 8종이 모두 미러링돼 있어야 바이너리가 내려옵니다.

설치가 잘 됐는지 확인하기

새 터미널을 열고 버전을 확인합니다.

claude --version

버전 번호가 찍히면 성공입니다. 더 자세히 보려면 claude doctor를 실행합니다. 설치 상태, 설정 파일 검증 오류, 최근 자동 업데이트 시도 결과를 세션을 열지 않고 보여 줍니다. 우리 1주차 설치 완료 체크리스트는 세 줄입니다. Claude 데스크톱에서 대화가 된다, 터미널에서 claude --version에 버전이 나온다, claude 실행 후 로그인이 끝나 프롬프트가 뜬다.

초기에 해두면 좋은 두 가지

1. 프로젝트 지침 파일 만들기

작업 폴더에 CLAUDE.md 파일이 있으면 Claude Code는 세션을 시작할 때 그 파일부터 읽습니다. 우리 2주차에서는 첫 지침서를 세 줄로 시작합니다. 존댓말로 쓴다, 고객 실명은 홍OO 형태로만 쓴다, 확실하지 않은 수치는 지어내지 않는다. 창을 껐다 켜도 다음 세션이 같은 규칙으로 일합니다. 이 세 줄이 프롬프트가 아니라 시스템으로 가는 첫걸음입니다. /init을 입력하면 프로젝트를 훑어 초안을 만들어 주기도 합니다.

2. 권한 모드 이해하기

Claude Code는 파일 편집이나 명령 실행 전에 승인을 묻는데, 얼마나 자주 묻는지를 권한 모드가 정합니다. 기본값 default(화면에는 Manual로 표시)는 읽기만 묻지 않고 나머지는 전부 묻습니다. Shift+Tab을 누르면 acceptEdits(파일 편집은 자동 승인), plan(읽고 계획만 세우고 편집 금지) 순으로 바뀝니다. 처음 2주는 기본 모드 그대로 두고, 승인 창에 뜨는 내용을 읽는 습관부터 들이는 것이 우리 방식입니다.

자주 겪는 문제와 대처법

커맨드를 찾을 수 없는 경우 (공통)

설치는 됐는데 command not found: claude(Mac) 또는 'claude' is not recognized(Windows)가 나오면 설치 폴더가 PATH에 없는 것입니다. 먼저 터미널을 완전히 닫았다 다시 엽니다. 그래도 안 되면 PATH에 추가합니다.

# Mac (zsh 기본)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Windows PowerShell
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Windows는 명령 실행 후 터미널을 다시 시작해야 반영됩니다. VS Code 확장만 설치한 경우에는 ~/.local/bin/claude가 아예 없으므로 위의 독립 설치를 따로 해야 합니다.

원격 서버에서 로그인 창이 안 열리는 경우 (공통)

SSH 접속한 서버, WSL2, 컨테이너에서는 브라우저가 다른 머신에서 열려 로컬 콜백에 닿지 못합니다. 이때 c를 눌러 로그인 URL을 복사해 내 PC 브라우저에서 열고, 브라우저가 보여 주는 코드를 터미널의 Paste code here if prompted 자리에 붙여 넣습니다. 붙여넣기가 먹지 않으면 claude auth login이 표준 입력에서 코드를 읽어 줍니다.

Mac에서 권한 오류가 나는 경우

설치 프로그램은 ~/.local/bin/과 ~/.claude/에 쓰기 권한이 필요합니다. test -w ~/.local/bin && echo writable로 확인하고, 안 되면 sudo mkdir -p ~/.local/bin && sudo chown -R $(whoami) ~/.local로 소유자를 내 계정으로 바꿉니다. npm으로 설치하다 권한 오류가 났다면 네이티브 설치로 갈아타는 것이 빠릅니다.

Mac에 npm 버전이 이미 설치돼 있는 경우

which -a claude로 claude가 몇 군데 있는지 봅니다. ~/.local/bin/claude(네이티브), ~/.claude/local/(옛 로컬 npm), npm -g ls @anthropic-ai/claude-code(전역 npm) 세 곳을 확인하고 하나만 남깁니다. 권장은 네이티브이며, npm 쪽은 npm uninstall -g @anthropic-ai/claude-code, 옛 로컬 설치는 rm -rf ~/.claude/local로 제거합니다.

Windows에서 실행 정책 오류가 나는 경우

공식 한 줄 명령(irm ... | iex)은 스크립트 파일이 아니라 메모리에서 실행되므로 보통 실행 정책에 걸리지 않습니다. running scripts is disabled on this system 오류는 install.ps1을 파일로 내려받아 실행했거나 회사 정책으로 프로필 스크립트까지 막힌 경우에 나옵니다. 이때는 관리자 권한 없이 현재 사용자 범위만 완화하고 원래의 한 줄 명령으로 다시 시도합니다.

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
irm https://claude.ai/install.ps1 | iex

TLS 오류(SSL/TLS secure channel)가 함께 나오면 설치 전에 [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12를 먼저 실행합니다.

Windows 백신 프로그램이 설치를 차단하는 경우

The process cannot access the file ... being used by another process는 백신이 %USERPROFILE%\.claude\downloads의 다운로드 중인 바이너리를 검사하고 있을 때 나옵니다. 다른 PowerShell 창을 닫고 검사가 끝나길 기다린 뒤 다운로드 폴더를 지우고 재시도합니다.

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

회사 보안 소프트웨어(AppLocker, EDR)가 계속 막으면 claude.exe와 bash.exe, cmd.exe를 허용 목록에 넣어 달라고 IT 팀에 요청합니다. 그래도 안 되면 winget install Anthropic.ClaudeCode가 curl을 전혀 쓰지 않는 우회 경로입니다.

정리

• Mac은 curl -fsSL https://claude.ai/install.sh | bash, Windows는 irm https://claude.ai/install.ps1 | iex 한 줄입니다.
• Node.js 없이 설치되며, npm과 Homebrew, WinGet은 대체 경로입니다.
• claude --version으로 확인하고 claude doctor로 점검합니다.
• 설치 직후 CLAUDE.md 세 줄과 권한 모드 개념을 잡아 둡니다.
• 오류가 나면 PATH, 셸 종류, 중복 설치 세 가지부터 의심합니다.

자주 묻는 질문