Claude Code를 macOS에서 처음 설치해 쓰려는 분을 위해, 공식 문서 여섯 건을 2026년 11월 11일(KST)에 직접 열어 설치부터 첫 질문, 첫 코드 수정 승인까지 순서대로 정리했습니다. 공식 문서는 터미널에 명령 한 줄을 붙여 넣는 네이티브 설치를 권장하고, Homebrew와 npm은 다른 설치 방식으로 안내합니다. 설치를 마친 뒤 프로젝트 폴더에서 claude를 실행하고 브라우저로 로그인하는 것이 첫 실행의 기본 흐름입니다. 이 글에는 설치 방식 비교표, 단계별 방법, 막혔을 때 확인할 지점, 점검 체크리스트를 담았고, 직접 설치해 본 경험담은 쓰지 않고 공식 문서에 적힌 내용만 옮겼습니다.
한눈에 보기: 설치 조건과 설치 방식 비교
표 1은 설치 전에 확인할 조건이고, 표 2는 설치 방식 세 가지의 차이입니다. 두 표의 내용은 Claude Code 공식 문서의 설치 페이지와 퀵스타트에서 직접 확인한 항목입니다.
| 항목 | 공식 문서에 적힌 내용 |
|---|---|
| 운영체제 | macOS 13.0 이상 |
| 하드웨어 | RAM 4GB 이상, x64 또는 ARM64 프로세서 |
| 네트워크 | 인터넷 연결 필요 |
| 셸 | Bash, Zsh, PowerShell, CMD 지원 (macOS 기본 셸은 Zsh라고 터미널 가이드가 설명) |
| 계정 | Claude Pro, Max, Team, Enterprise 구독 또는 Claude Console 계정, 혹은 지원되는 클라우드 공급자를 통한 접근. 무료 Claude.ai 플랜은 Claude Code 접근에 포함되지 않음 |
| 지역 | Anthropic 지원 국가 |
| 작업 대상 | 코드 프로젝트 하나 (퀵스타트의 준비물) |
계정 조건은 설치 전에 확인해 둘 만한 항목입니다. 무료 Claude.ai 플랜에는 Claude Code 접근이 포함되지 않는다고 공식 설치 문서가 밝히고 있어, 설치를 마쳐도 로그인할 수 있는 계정이 없으면 다음 단계로 넘어갈 수 없습니다. 플랜별 가격과 한도 비교는 Claude·ChatGPT·Gemini 유료 요금제 비교 글에서 따로 다뤘으며, 이 글의 사실 근거로는 쓰지 않았습니다.
| 설치 방식 | 명령 | 자동 업데이트 | 직접 업데이트 |
|---|---|---|---|
| 네이티브 설치 (권장) | curl -fsSL https://claude.ai/install.sh | bash | 백그라운드에서 자동으로 업데이트 | claude update |
| Homebrew | brew install --cask claude-code (안정 채널) 또는 brew install --cask claude-code@latest (최신 채널) | 자동 업데이트 없음 | brew upgrade claude-code 또는 brew upgrade claude-code@latest |
| npm (Node.js 18 이상) | npm install -g @anthropic-ai/claude-code | 백그라운드 업데이트가 동작하지만, 전역 디렉터리에 쓸 수 없으면 알림이 표시됨 | npm install -g @anthropic-ai/claude-code@latest |
공식 표기만 보면 기본 선택지는 네이티브 설치입니다. 설치 문서는 네이티브 설치를 권장으로 표시하고, npm 방식은 고급 옵션 영역에서 소개합니다. Homebrew는 퀵스타트에도 소개되어 있으며 자동 업데이트가 없다는 점이 네이티브 설치와 다릅니다. 이 글은 어느 방식이 더 낫다는 판단은 하지 않고 공식 표기만 전합니다.
근거: Claude Code 설치(setup) 문서 · Claude Code 퀵스타트 · 터미널 가이드 · mac.install.guide Brew Install Claude Code(보조)
단계별 방법: macOS에서 설치부터 첫 수정까지
아래 번호는 처음 설치하는 분이 따라갈 순서입니다. 키 조합이나 버튼 이름이 나오는 곳은 공식 문서의 표기 그대로 적었습니다.
- 터미널을 엽니다. 터미널 가이드는
Cmd + Space로 Spotlight 검색을 열고Terminal을 입력한 뒤Enter를 누르라고 안내합니다. 커서가 깜박이는 창이 터미널입니다. - 아래 설치 명령을 붙여 넣고(
Cmd + V)Enter를 누릅니다. 다운로드하는 동안 진행 표시가 나오지 않으므로 창을 닫지 않고 기다립니다. - 설치가 끝나면 새 터미널 창을 열어
claude --version을 실행해 버전 번호가 출력되는지 확인합니다. - 작업할 프로젝트 폴더로 이동(
cd)한 뒤claude를 실행합니다. - 첫 실행에서 나오는 로그인 안내에 따라 브라우저에서 인증을 마칩니다.
- 프로젝트에 대한 질문(예:
what does this project do?)으로 읽기 동작을 먼저 확인합니다. - 작은 수정(예:
add a hello world function to the main file)을 요청하고, 변경 전에 승인을 물으면 Yes를 선택합니다. - 끝낼 때는
/exit를 입력하거나Ctrl + D를 두 번 누릅니다.
설치 명령 세 가지
네이티브 설치는 터미널에 아래 한 줄을 붙여 넣어 실행합니다. 터미널 가이드에 따르면 이 명령은 다운로드 중 진행 상황을 보여 주지 않고, 설치가 끝나면 Claude Code successfully installed! 안내가 나옵니다.
curl -fsSL https://claude.ai/install.sh | bash
설치 뒤에는 새 터미널 창에서 버전을 확인합니다. 정상 설치 시 버전 번호가 출력되고, 퀵스타트는 버전 번호 뒤에 (Claude Code)가 붙는다고 설명합니다. macOS와 Linux에서 설치 프로그램은 claude를 ~/.local/bin/claude 위치에 둡니다. 더 자세한 점검이 필요하면 claude doctor를 실행합니다.
claude --version
Homebrew를 쓰는 경우에는 아래 명령을 씁니다. cask는 두 가지로, claude-code는 안정 채널을, claude-code@latest는 최신 채널을 따릅니다. 퀵스타트는 안정 채널이 보통 약 일주일 늦고 큰 회귀가 있는 릴리스는 건너뛴다고 설명합니다. Homebrew 설치는 자동으로 업데이트되지 않으므로 brew upgrade로 직접 올려야 합니다. 보조 출처로 대조한 mac.install.guide도 두 cask 이름과 자동 업데이트가 없다는 점을 같게 적고 있습니다.
brew install --cask claude-code
npm 방식은 Node.js 18 이상이 필요하다고 안내되어 있고, 공식 문서는 sudo npm install -g를 쓰지 말라고 경고합니다. 업데이트는 npm install -g @anthropic-ai/claude-code@latest로 하고 npm update -g는 피하라고 안내합니다.
npm install -g @anthropic-ai/claude-code
첫 실행과 로그인
설치가 끝났으면 작업할 프로젝트 폴더에서 Claude Code를 시작합니다. 퀵스타트 예시의 경로 자리에 본인 프로젝트의 경로를 넣습니다.
cd /path/to/your/project
claude
첫 실행에서는 로그인 안내가 나옵니다. Claude 구독이나 Console 계정이면 안내에 따라 브라우저에서 인증을 마칩니다. 한 번 로그인하면 인증 정보가 저장되어 다시 로그인할 필요가 없고, 계정을 바꾸거나 다시 인증할 때는 실행 중인 세션 안에서 /login을 입력합니다. 퀵스타트가 소개하는 로그인 가능 계정은 네 가지입니다.
- Claude Pro, Max, Team, Enterprise 구독 (퀵스타트에서 권장으로 표시)
- Claude Console 계정 (선결제 크레딧으로 쓰는 API 접근이며, 첫 로그인 때 Console에 Claude Code 워크스페이스가 자동으로 만들어짐)
- Amazon Bedrock, Google 클라우드, Microsoft Foundry 같은 클라우드 공급자
- 조직이 운영하는 Claude apps 게이트웨이
ANTHROPIC_API_KEY 환경 변수를 설정해 두었고 Claude Code가 그 키를 쓸지 물을 때 승인하면 로그인 안내를 건너뜁니다. Anthropic 고객센터의 Pro·Max 플랜 안내는 이 환경 변수가 설정되어 있으면 구독 대신 API 키로 인증하며 API 요금이 청구된다고 설명합니다. 현재 어떤 인증 방식이 쓰이는지는 세션 안에서 /status로 확인할 수 있다고 공식 문제 해결 문서가 안내합니다.
터미널이 낯설다면 공식 터미널 가이드가 소개하듯 데스크톱 앱으로 터미널 없이 시작할 수도 있고, 웹, VS Code, JetBrains 확장으로도 쓸 수 있습니다. VS Code 확장만 설치한 경우에는 터미널에서 쓸 claude가 ~/.local/bin/claude에 만들어지지 않으므로 별도 설치가 필요하다고 공식 문제 해결 문서가 설명합니다.
첫 질문과 첫 수정
프롬프트가 뜨면 프로젝트에 대한 질문부터 해 보라고 퀵스타트는 안내합니다. Claude Code가 필요한 프로젝트 파일을 알아서 읽으므로 맥락을 직접 붙여 넣을 필요가 없다고 적혀 있습니다. 퀵스타트의 예시 질문은 다음과 같습니다.
what does this project do?
what technologies does this project use?
where is the main entry point?
explain the folder structure
이어서 작은 수정을 요청합니다. 퀵스타트의 예시는 아래 문장입니다. Claude Code가 알맞은 파일을 찾아 변경 내용을 보여 주고, 변경 전에 승인을 물으면 Yes를 선택해 승인합니다. 터미널 가이드는 터미널에서 마우스로 클릭할 수 없고 화살표 키로 이동한다고 설명하며, 승인 창에서는 Enter를 눌러 Yes를 고를 수 있다고 안내합니다. 실행 중인 Claude를 멈추려면 Esc를 누릅니다.
add a hello world function to the main file
퀵스타트는 Git 작업도 대화로 요청할 수 있다고 소개합니다. 예시로는 바뀐 파일 확인(what files have I changed?)과 변경 사항 커밋(commit my changes with a descriptive message)이 나옵니다.
권한 모드와 승인 창
권한 모드는 세션에서 Claude가 묻지 않고 할 수 있는 작업의 범위를 정합니다. 공식 문서의 모드 표에서 일상 작업에 해당하는 네 가지를 옮기면 표 3과 같습니다.
| 모드 (화면 표시 이름) | 묻지 않고 실행하는 작업 | 공식 문서가 적은 용도 |
|---|---|---|
| Manual (설정값 default) | 읽기만 | 모든 작업을 직접 검토할 때, 민감한 작업 |
| Edit automatically (설정값 acceptEdits) | 읽기, 파일 편집, mkdir·touch·mv·cp 같은 흔한 파일 시스템 명령 | 검토하면서 코드를 고쳐 나갈 때 |
| Plan (설정값 plan) | 읽기 (자동 모드를 쓸 수 있을 때는 분류기가 승인한 명령 포함) | 코드를 바꾸기 전에 둘러볼 때 |
| Auto (설정값 auto) | 모든 작업, 백그라운드 안전 점검 병행 | 긴 작업, 승인 창 줄이기 |
세션 중 Shift+Tab을 누르면 모드가 순환합니다. auto에서 한 번 누르면 default로 바뀌고, 이후 default, acceptEdits, plan 순으로 돕니다. 시작 모드는 버전에 따라 다릅니다. 공식 문서에 따르면 Claude Code v2.1.283 이상에서는 대화형 터미널 세션이 auto 모드로 시작합니다. 이전 버전에서는 Pro, Max, Team 플랜의 일부 세션에서만 auto로 시작하고 그 외에는 default로 시작합니다. 같은 요청에도 승인 창이 뜨는 정도가 버전과 설정에 따라 다를 수 있다는 뜻입니다.
bypassPermissions 모드는 모든 작업을 묻지 않고 실행하는 모드입니다. 공식 문서는 컨테이너, VM, 개발 컨테이너처럼 격리된 환경에서만 쓰라고 안내하고, 프롬프트 인젝션이나 의도치 않은 동작을 막아 주지 못한다고 밝힙니다. 승인 창을 줄이고 싶다면 백그라운드 안전 점검이 있는 auto 모드를 쓰라고도 적혀 있습니다.
자주 쓰는 명령
| 입력하는 곳 | 명령 | 하는 일 |
|---|---|---|
| 터미널(셸) | claude | 대화형 모드 시작 |
| 터미널(셸) | claude -c | 현재 디렉터리의 가장 최근 대화 이어가기 |
| 터미널(셸) | claude -r | 이전 대화 다시 열기 |
| 터미널(셸) | claude -p 뒤에 질문 | 한 번만 질문하고 종료 |
| 터미널(셸) | claude update | 업데이트를 바로 적용 |
| 터미널(셸) | claude doctor | 설치 상태 점검 |
| Claude Code 세션 안 | /help | 사용할 수 있는 명령 보기 |
| Claude Code 세션 안 | /clear | 대화 기록 지우기 |
| Claude Code 세션 안 | /resume | 이전 대화 이어가기 |
| Claude Code 세션 안 | /login | 계정 전환, 다시 인증 |
| Claude Code 세션 안 | /exit 또는 Ctrl + D 두 번 | 종료 |
근거: Claude Code 퀵스타트 · 터미널 가이드 · Permission modes · Claude Code 설치(setup) 문서 · Anthropic 고객센터, Pro·Max 플랜으로 Claude Code 쓰기
자주 막히는 지점
표 5는 공식 설치 문제 해결 문서와 터미널 가이드에 실린 오류 가운데 macOS에서 마주칠 만한 것을 골랐습니다. 이 글은 직접 오류를 재현해 보지 않았고, 증상과 해결 방법은 공식 문서의 설명을 옮긴 것입니다.
| 증상 | 공식 문서가 설명하는 원인과 대응 |
|---|---|
command not found: claude | 설치 디렉터리(~/.local/bin)가 PATH에 없는 경우입니다. 설치 프로그램은 설치 끝의 Setup notes:에 PATH 안내를 출력하지만 PATH를 직접 바꾸지는 않습니다. 아래 Zsh 명령을 실행하고 새 터미널 창을 엽니다. |
zsh: permission denied: /Users/you/.zshrc | 설정 파일에 쓸 권한이 없어 PATH 설정이 저장되지 않은 상태입니다. ls -l ~/.zshrc로 소유자를 확인해, 다른 사용자(root 등)가 소유자면 소유권을 바꾸고(관리자 권한 필요), 본인이 소유자면 읽기 전용이므로 chmod u+w ~/.zshrc로 쓰기 권한을 줍니다. |
dyld: cannot load 또는 built for Mac OS X 13.0 | macOS 버전이 지원 범위보다 낮은 경우입니다. 애플 메뉴의 About This Mac에서 버전을 확인하고 13.0보다 낮으면 Software Update로 올립니다. |
| 설치 중 syntax error near unexpected token 오류, 또는 터미널에 HTML 코드가 출력됨 | 설치 주소가 설치 스크립트 대신 웹 페이지를 돌려준 경우입니다. 페이지에 App unavailable in region이라고 나오면 해당 국가에서 Claude Code를 쓸 수 없는 것입니다. 그렇지 않으면 명령을 다시 실행하고, 계속되면 Homebrew로 설치하라고 터미널 가이드가 안내합니다. |
세션 하단에 Auto-update failed · Run claude doctor | 자동 업데이트가 실패한 상태입니다. 셸에서 claude update를 실행하면 업데이트를 마치거나 오류를 확인할 수 있습니다. |
| 예상과 다른 버전이 실행됨 | 설치 방식을 섞어 쓴 경우를 의심합니다. 문제 해결 문서는 which -a claude 등으로 설치 위치를 확인하고, 여러 개가 있으면 하나만 남기라고 안내합니다. 네이티브 설치(~/.local/bin/claude)를 남기는 쪽이 권장입니다. |
claude doctor에 macOS Keychain is not writable 경고 | 키체인이 쓰기를 거부하는 경우이며, 같은 보고서에 제안된 해결 방법이 함께 표시됩니다. |
터미널 가이드가 소개하는 PATH 설정 명령은 아래와 같습니다. 첫 줄은 설정을 새 터미널마다 유지하도록 저장하고, 둘째 줄은 지금 열려 있는 창에 바로 적용합니다. macOS 기본 셸인 Zsh 기준이며, Bash를 쓴다면 문제 해결 문서의 macOS Bash 안내를 따라야 합니다.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
그래도 claude를 찾지 못하면 ls -la ~/.local/bin/claude로 파일이 있는지 확인합니다. 파일이 없다면 설치가 끝나지 않은 것이므로 설치 명령을 다시 실행해야 합니다.
근거: 설치 문제 해결(Troubleshoot installation and login) · 터미널 가이드 · Claude Code 퀵스타트
설치 후 점검 체크리스트
- ☐ macOS가 13.0 이상이고 인터넷에 연결되어 있으며, 지원 국가에서 설치하는가
- ☐ Pro, Max, Team, Enterprise 구독이나 Console 계정처럼 로그인에 쓸 계정이 있는가 (무료 Claude.ai 플랜은 Claude Code 접근에 포함되지 않음)
- ☐ 설치 방식을 하나만 골랐는가 (여러 방식을 섞으면 예상과 다른 버전이 실행될 수 있음)
- ☐ 새 터미널 창에서
claude --version을 실행해 버전 번호가 출력되는가 - ☐ 변경 사항을 되돌릴 수 있도록 Git으로 관리되는 폴더에서 시작했는가 (이 글의 제안이며 공식 문서의 요구 사항은 아님)
- ☐ 첫 수정 요청에서 승인 창에 표시된 변경 내용을 확인한 뒤 Yes를 선택했는가
- ☐ ANTHROPIC_API_KEY가 설정되어 있지 않은지 확인했고,
/status로 현재 인증 방식을 확인했는가
자주 묻는 질문
무료 Claude 계정으로도 Claude Code를 쓸 수 있나요
공식 설치 문서에는 Claude Code가 Pro, Max, Team, Enterprise 또는 Console 계정을 요구하고 무료 Claude.ai 플랜은 Claude Code 접근에 포함되지 않는다고 적혀 있습니다. Amazon Bedrock, Google Vertex AI, Microsoft Foundry 같은 서드파티 API 공급자를 통해 쓰는 방법도 안내되어 있습니다.
네이티브, Homebrew, npm 중 무엇을 골라야 하나요
공식 문서는 네이티브 설치를 권장으로 표시하며, 백그라운드 자동 업데이트가 되는 방식도 네이티브 설치입니다. Homebrew 설치는 자동 업데이트가 없어 직접 brew upgrade를 해야 하고, npm 방식은 Node.js 18 이상이 필요합니다. 어떤 방식이 개인 환경에 더 맞는지는 공식 문서만으로 판단할 수 없어 이 글은 우열을 정하지 않았습니다.
사용량 한도는 Claude 앱과 따로 계산되나요
Anthropic 고객센터의 Pro·Max 플랜 안내는 Pro, Max, Ultra 개인 구독에서 Claude와 Claude Code의 모든 활동이 같은 한도에 합산된다고 설명합니다. 같은 안내에서 Pro와 Max에는 5시간 세션 한도와 주간 한도가 있다고 적혀 있습니다. Team과 Enterprise는 별도 문서를 보라고 안내되어 있어 이 글에서는 다루지 않았습니다.
설치한 Claude Code를 지우려면 어떻게 하나요
공식 설치 문서가 안내하는 macOS 삭제 명령은 설치 방식마다 다릅니다. 네이티브 설치는 아래 두 줄로 지우고, Homebrew는 brew uninstall --cask claude-code(최신 cask라면 claude-code@latest), npm은 npm uninstall -g @anthropic-ai/claude-code를 씁니다.
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
설정과 캐시 데이터까지 지우는 단계는 선택 사항입니다. 공식 문서는 사용자 설정과 상태를 담은 홈 디렉터리의 .claude 폴더와 .claude.json 파일을 지우면 설정, 허용한 도구, MCP 서버 구성, 세션 기록이 모두 삭제된다고 경고합니다. 삭제한 뒤에도 claude가 실행된다면 다른 설치 방식이 남았거나 셸 별칭이 남아 있을 수 있다고 안내합니다.
확인 시점: 2026년 11월 11일(KST). 설치 명령, 지원 환경, 계정 조건, 권한 모드의 시작 기본값은 Claude Code가 업데이트되면서 바뀔 수 있고, 확인한 공식 문서 대부분에는 게시일이나 갱신일이 적혀 있지 않았습니다. 설치 전에는 공식 문서의 현재 내용을 다시 확인해 주세요.
이 글은 아래 공식 출처의 페이지를 직접 열어 확인해 작성했고, 정리와 번역에 AI 도구를 사용했습니다. 직접 설치하거나 오류를 재현해 본 내용은 포함되어 있지 않으며, 모든 명령과 조건의 확인 기준 시점은 2026년 11월 11일(KST)입니다. 사실과 다른 내용이 있으면 댓글로 알려 주시면 확인한 뒤 본문을 고치고 수정 사실을 밝히겠습니다.
참고한 출처
- [공식] Claude Code Docs, Quickstart — 필자·게시일 미표기
- [공식] Claude Code Docs, Advanced setup (System requirements) — 필자·게시일 미표기
- [공식] Claude Code Docs, Terminal guide for new users — 필자·게시일 미표기
- [공식] Claude Code Docs, Troubleshoot installation and login — 필자·게시일 미표기, 문서가 길어 필요한 절만 확인
- [공식] Claude Code Docs, Permission modes — 필자·게시일 미표기, 문서 끝부분 약 14,000자는 읽지 못함
- [공식] Anthropic 고객센터, Use Claude Code with your Pro or Max plan — 필자·게시일 미표기
- [보조] mac.install.guide, Brew Install Claude Code — 2026년 6월 갱신으로 표기, Homebrew cask 이름과 업데이트 방식을 공식 문서와 대조하는 용도로만 사용
위 일곱 건 가운데 여섯 건은 Anthropic이 직접 운영하는 공식 페이지이고, 한 건은 Homebrew 항목을 대조하기 위한 보조 출처입니다. 언론 보도는 사용하지 않았고, 같은 도메인의 공식 문서 다섯 건과 고객센터 한 건은 서로 다른 페이지이므로 각각 따로 열어 확인했습니다.

답글 남기기