Claude Code 설치부터 설정까지 — Mac·Windows 터미널 세팅 완벽 정리
Claude Code 설치, 네 가지 방법 중 뭘 고를지부터 로그인·설정까지 Mac과 Windows 기준으로 한 번에 정리했습니다. 처음 터미널에 깔 때 막히는 지점도 함께 짚습니다.
터미널에 뭔가를 깔려다가 에러 한 줄 보고 그냥 창을 닫아버린 적, 다들 한 번쯤 있으시죠. Claude Code도 "설치가 어렵다"는 선입견 때문에 미루는 분이 꽤 됩니다. 그런데 막상 해보면 명령어 한 줄이면 끝나는 경우가 대부분이에요. 문제는 그 '한 줄'이 내 환경에 맞는 한 줄인지를 모른다는 데 있습니다.
Claude Code는 터미널에서 돌아가는 AI 코딩 도구라, 설치 방식이 네 가지나 됩니다. 어느 걸 골라야 할지부터 헷갈리는 게 당연해요. 그래서 이 글은 '뭘 깔지 고민하는 시간'을 줄이는 데 초점을 맞췄습니다.
설치 전에 — 내 PC가 되는 환경인지부터
제일 흔한 삽질이 "일단 명령어부터 붙여넣고 보는" 겁니다. 그 전에 두 가지만 확인하세요.
하나는 운영체제 버전입니다. macOS는 13.0(Ventura) 이상, Windows는 10의 1809 빌드 이상(또는 Server 2019+), 리눅스는 Ubuntu 20.04·Debian 10·Alpine 3.19 이상이면 됩니다. 메모리는 4GB 이상, CPU는 x64든 ARM64든 상관없어요. 요즘 쓰는 노트북이면 거의 다 통과합니다.
둘은 계정입니다. 이게 의외로 발목을 잡아요. Claude Code는 무료 claude.ai 계정으로는 못 씁니다. Pro나 Max 같은 유료 구독, 혹은 사용량만큼 과금되는 Console(API) 계정이 있어야 로그인이 됩니다. 설치는 다 해놓고 로그인 단계에서 "왜 안 되지" 하는 분들 사연이 대개 여기서 나옵니다. 깔기 전에 결제 수단부터 정리해 두는 게 순서예요.
설치 — 네 가지 길, 하나만 고르면 된다
Claude Code를 까는 방법은 네 가지인데, 결론부터 말하면 대부분은 1번(네이티브 설치)이 정답입니다.
- 네이티브 설치 (권장) — Node.js 같은 사전 준비가 필요 없고, 업데이트도 백그라운드에서 알아서 됩니다.
- Mac·Linux·WSL:
curl -fsSL https://claude.ai/install.sh | bash
- Windows PowerShell:
irm https://claude.ai/install.ps1 | iex
- Homebrew (Mac) — 이미 brew를 쓰고 있다면:
brew install --cask claude-code
- WinGet (Windows) — 윈도우 패키지 관리자가 익숙하면:
winget install Anthropic.ClaudeCode
- npm — Node.js 22 이상이 깔려 있어야 합니다:
npm install -g @anthropic-ai/claude-code
여기서 꼭 짚고 갈 게 하나 있어요. brew·winget으로 깔면 자동 업데이트가 꺼진 상태입니다. CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 환경 변수를 따로 걸어줘야 최신 버전을 따라갑니다. npm 설치도 마찬가지로 수동 업데이트 영역이고요. Claude Code는 업데이트가 잦은 도구라, 이 차이가 몇 주 지나면 체감됩니다. 특별한 이유가 없다면 네이티브 설치를 권하는 이유가 여기 있습니다.
첫 실행과 로그인 — 진짜 관문은 여기
설치가 끝났으면 터미널에 그냥 이렇게 칩니다.
claude작업하려는 프로젝트 폴더 안에서 실행하는 걸 추천합니다. Claude Code는 현재 디렉터리를 작업 공간으로 잡거든요. 처음 켜면 로그인 안내가 뜨고, 필요하면 /login을 직접 쳐서 인증을 시작할 수 있습니다.
로그인 방식은 두 갈래입니다. claude.ai 구독(Pro·Max)으로 붙거나, Console 계정으로 API 요금제에 붙거나. 둘 다 브라우저가 열리면서 인증이 진행돼요. 인증이 끝나면 자격 증명이 안전한 곳에 저장됩니다 — macOS는 키체인, 리눅스는 ~/.claude/.credentials.json(권한 0600), 윈도우는 %USERPROFILE%\.claude\.credentials.json에요. 여기까지 왔으면 설치의 90%는 끝난 셈입니다.
설정 — 알아두면 하루가 편해지는 것들
로그인까지 했으면 바로 쓸 수 있지만, 몇 가지만 손봐두면 훨씬 편합니다.
설정은 계층으로 겹쳐집니다. 우선순위가 높은 순서대로 ① 환경 변수 → ② 프로젝트별 .claude/settings.json(지금 폴더) → ③ 사용자 전역 ~/.claude/settings.json → ④ 조직이 강제하는 관리 정책. 쉽게 말해, 이 프로젝트에서만 바꾸고 싶은 건 프로젝트 폴더의 settings.json에, 모든 프로젝트에 공통으로 적용하고 싶은 건 홈 디렉터리의 settings.json에 적으면 됩니다.
실무에서 제일 먼저 만지게 되는 건 두 가지예요. 하나는 /model 명령으로 쓰는 모델을 바꾸는 겁니다. 무거운 작업엔 더 똑똑한 모델을, 가벼운 반복 작업엔 빠른 모델을 붙이는 식으로 상황에 맞춰 쓰면 비용과 속도의 균형이 잡힙니다. 다른 하나는 프로젝트 루트에 두는 CLAUDE.md 파일입니다. 여기에 프로젝트 규칙·컨벤션·자주 쓰는 명령을 적어두면 Claude Code가 세션마다 그걸 읽고 들어와요. 같은 지시를 매번 반복하지 않아도 되니, 길게 갈 프로젝트라면 이 파일 한 장이 체감 생산성을 크게 바꿉니다.
설정 항목 자체는 140개가 넘고 환경 변수도 300개 이상이라 처음부터 다 볼 필요는 없습니다. 쓰다가 "이건 바꾸고 싶다" 싶을 때 공식 문서에서 그 항목만 찾아보는 편이 현실적이에요.
자주 막히는 지점과 해결
- 설치는 됐는데 로그인이 안 된다 → 십중팔구 계정 문제입니다. 무료 플랜인지, 결제가 유효한지부터 확인하세요.
- npm으로 깔았더니 명령이 안 먹힌다 → Node.js 버전이 22 미만이면 그렇습니다.
node -v로 확인하고, 애매하면 네이티브 설치로 갈아타는 게 빠릅니다. - 한참 썼는데 버전이 옛날 그대로 → brew·winget·npm 설치는 자동 업데이트가 아닙니다. 위에서 말한 환경 변수를 걸거나 수동으로 업데이트하세요.
- Windows인데 자꾸 막힌다 → PowerShell에서 네이티브 설치(
irm ... | iex)가 가장 말썽이 적습니다. CMD보다 PowerShell이나 WSL을 권합니다.
한국 개발자 입장에서 한마디 보태자면, 사내 네트워크나 프록시 환경이 설치의 진짜 복병인 경우가 많습니다. 공용 와이파이나 회사망에서 curl·브라우저 인증이 막히면 설치 명령 자체는 멀쩡해도 끝까지 안 가거든요. 회사 PC라면 개인 네트워크나 테더링으로 한 번 깔아보고, 사내망 제약이 걸리면 보안팀에 Claude 관련 도메인 허용을 요청하는 쪽이 혼자 삽질하는 것보다 빠릅니다. 또 하나, 설치 경로를 고민할 땐 "앞으로 업데이트를 챙길 여유가 있느냐"를 기준으로 삼으면 선택이 간단해집니다. 혼자 쓰는 개인 PC면 네이티브 설치로 묻어두고 잊어버리는 게 편하고, 패키지 관리를 통일하고 싶은 팀 환경이면 brew·winget으로 통제하되 자동 업데이트 변수를 꼭 챙기는 게 맞습니다. 국내 팀들이 사내 표준 세팅을 만들 때 이 지점을 안 적어두면, 나중에 "누구는 최신인데 누구는 몇 달 전 버전"인 상황이 꼭 생깁니다.
한 번에 정리
- 설치 전 확인: OS 버전 + 유료 또는 Console 계정 (무료 계정은 불가)
- 설치: 고민되면 네이티브 설치 한 줄 (
install.sh/install.ps1) - 첫 실행: 프로젝트 폴더에서
claude, 안 되면/login - 설정:
/model로 모델 선택,CLAUDE.md로 프로젝트 맥락 고정 - 막히면: 계정 → Node 버전 → 업데이트 방식 → 네트워크 순으로 점검
터미널 공포증만 이겨내면 Claude Code 설치는 생각보다 싱겁게 끝납니다. 명령어 한 줄과 로그인, 그리고 CLAUDE.md 한 장이면 오늘부터 바로 쓸 수 있어요. 여러분은 네 가지 설치 방법 중 어떤 걸 쓰고 계신가요? 네이티브 설치로 묻어두는 쪽인지, 아니면 패키지 관리자로 묶어두는 쪽을 선호하는지 궁금하네요.
참고
댓글 0
댓글을 불러오는 중…