클로드 코드(Claude Code)는 터미널에서 대화하듯 코드를 읽고 고치게 하는 Anthropic의 코딩 도구입니다. 설치는 명령 한 줄이면 끝납니다. 다만 운영체제마다 명령이 다르고 무료 계정으로는 로그인 단계에서 막힙니다. 2026년 10월 22일 Anthropic 공식 문서와 요금제 페이지를 다시 확인해 설치 명령, 지원 운영체제, 필요한 요금제, 첫 작업까지 순서대로 정리했습니다. 이 맥에 설치된 버전에서 claude --version과 claude --help를 직접 실행해 본 출력도 함께 담았습니다.
1. 클로드 코드 설치 전에 확인할 두 가지
명령을 붙여 넣기 전에 내 컴퓨터가 지원 대상인지와 로그인할 계정이 있는지를 먼저 봐야 합니다. 설치는 누구나 되지만 계정 조건을 못 맞추면 첫 실행에서 더 나아가지 못합니다.
1.1. 지원 운영체제와 사양
공식 문서 「고급 설정」의 시스템 요구사항은 이렇습니다.
| 항목 | 요구사항 |
|---|---|
| macOS | macOS 13.0 이상 |
| Windows | Windows 10 1809 이상 또는 Windows Server 2019 이상 |
| Linux | Ubuntu 20.04 이상, Debian 10 이상, Alpine Linux 3.19 이상 |
| 하드웨어 | RAM 4GB 이상, x64 또는 ARM64 프로세서 |
| 셸 | Bash, Zsh, PowerShell 또는 CMD |
| 네트워크·위치 | 인터넷 연결 필수, Anthropic 지원 국가에서 사용 |
Windows는 그대로 설치해도 되고 WSL 안에 설치해도 됩니다. 문서는 명령 실행을 격리하는 샌드박싱이 WSL 2에서만 지원된다고 적고 있습니다. 리눅스 도구를 주로 쓰거나 샌드박싱이 필요하면 WSL 2를 고르세요.
1.2. 클로드 코드를 쓸 수 있는 요금제
설치 문서의 인증 항목에는 Pro, Max, Team, Enterprise 또는 Console 계정이 필요하고 무료 claude.ai 플랜에는 Claude Code 액세스가 포함되지 않는다고 적혀 있습니다. 요금제 페이지 FAQ도 Claude Code가 모든 유료 플랜에 포함된다고 설명합니다. 2026년 10월 22일 요금제 페이지(한국에서 접속, 부가세 10% 포함 표시) 기준으로 개인 플랜을 추리면 이렇습니다.
| 플랜 | Claude Code | 표시 요금 |
|---|---|---|
| Free | 아니요 | $0 |
| Pro | 예 | 월별 결제 $22, 연간 결제 시 월 $18(선불 $220) |
| Max 5x | 예 | 월 $110 |
| Max 20x | 예 | 월 $220 |
구독 대신 Claude Console 계정으로 로그인하면 선불 크레딧에서 API 요금이 빠져나갑니다. 유료 플랜에서는 웹·데스크톱·모바일 채팅과 Claude Code가 같은 사용 한도를 나눠 씁니다. 무료로 Claude를 어디까지 쓸 수 있는지는 이 글의 범위를 넘으므로 여기서는 “무료 플랜으로는 로그인이 안 된다”는 점만 기억하면 됩니다.
2. 운영체제별 클로드 코드 설치 명령
공식 문서가 권장하는 방법은 네이티브 설치 프로그램입니다. 관리자 권한은 필요 없습니다. 설치하는 동안 진행 표시가 나오지 않으니 끝날 때까지 기다리면 됩니다.
2.1. macOS, Linux, WSL
터미널을 열고 아래 한 줄을 붙여 넣습니다.
curl -fsSL https://claude.ai/install.sh | bash
설치 프로그램은 macOS와 Linux에서 실행 파일을 ~/.local/bin/claude에 둡니다. 이 맥에서 확인해 보니 ~/.local/bin/claude가 ~/.local/share/claude/versions/2.1.307을 가리키는 바로가기(심볼릭 링크)였습니다. versions 폴더에는 2.1.294, 2.1.306 같은 이전 버전도 남아 있었습니다. 문서 설명대로 자동 업데이트가 새 버전을 받아 두고 바로가기만 바꾸는 구조입니다.
2.2. Windows PowerShell과 CMD
Windows에서는 지금 열린 창이 PowerShell인지 CMD인지에 따라 명령이 다릅니다. 프롬프트 앞에 PS C:\가 보이면 PowerShell, PS 없이 C:\만 보이면 CMD입니다.
- 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 명령을 서로 바꿔 입력하면 다음 오류가 납니다. The token '&&' is not a valid statement separator가 뜨면 PowerShell에서 CMD용 명령을 넣은 것이고, 'irm' is not recognized가 뜨면 그 반대입니다. Git for Windows는 선택 사항입니다. 설치돼 있으면 Git Bash로 명령을 실행하고 없으면 PowerShell을 씁니다.
2.3. Homebrew, WinGet, npm으로 설치할 때
패키지 관리자로도 설치할 수 있습니다. 차이는 업데이트 방식에 있습니다.
| 방법 | 설치 명령 | 자동 업데이트 |
|---|---|---|
| 네이티브(권장) | 위 2.1·2.2의 명령 | 백그라운드에서 자동 |
| 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 | Node.js 22 이상 필요, sudo 사용 금지 |
Homebrew의 claude-code는 약 1주일 늦게 따라가는 안정 채널입니다. 새 버전을 바로 받으려면 claude-code@latest를 설치합니다. Debian, Fedora, RHEL, Alpine에서는 apt, dnf, apk로도 설치할 수 있습니다.
3. 클로드 코드 설치 확인과 PATH 오류
3.1. claude –version으로 확인하기
설치가 끝나면 새 터미널 창을 열고 버전을 물어봅니다. 기존 창에는 바뀐 PATH가 아직 반영되지 않았을 수 있습니다.
claude --version
2026년 10월 22일 이 맥(macOS 26.5.2, Apple 실리콘)에서 직접 실행한 결과는 2.1.307 (Claude Code)였습니다. 공식 문서도 정상 설치라면 버전 번호 뒤에 (Claude Code)가 붙는다고 설명합니다. 숫자는 설치 시점에 따라 다르니 형식만 맞으면 됩니다.
3.2. command not found가 나올 때
command not found: claude나 'claude' is not recognized가 나오면 설치 폴더가 PATH에 없는 경우입니다. 설치 프로그램은 이 상황을 알아채고 출력의 Setup notes: 아래에 알려 주지만 PATH를 직접 고치지는 않습니다. macOS 기본 셸(zsh)이라면 문제 해결 문서의 명령대로 아래 줄을 셸 설정에 추가한 뒤 새 창을 엽니다.
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
설치와 설정 상태를 한 번에 보려면 claude doctor를 실행합니다. 세션을 열지 않고 설치 상태, 설정 파일 오류, 경고와 수정 방법을 읽기 전용으로 보여 줍니다.
4. 클로드 코드 첫 실행과 로그인
작업할 프로젝트 폴더로 이동한 뒤 claude를 입력하면 대화형 세션이 열립니다.
cd /path/to/your/projectclaude
처음 실행하면 로그인을 요청합니다. 브라우저에서 인증을 마치면 자격 증명이 저장돼 다음부터는 묻지 않습니다. 로그인할 수 있는 계정은 네 갈래입니다.
- Claude Pro, Max, Team, Enterprise 구독: 공식 문서가 권장하는 방식
- Claude Console: 선불 크레딧으로 API 요금을 내는 방식. 첫 로그인 때 Console에 “Claude Code” 워크스페이스가 자동으로 생깁니다.
- Amazon Bedrock, Google Cloud, Microsoft Foundry: 회사가 이미 쓰는 클라우드 계정으로 연결
- Claude apps gateway: 조직이 운영하는 게이트웨이에서 회사 SSO로 로그인
로그인이 끝나면 입력창 위에 버전, 현재 모델, 작업 폴더가 표시됩니다. 계정을 바꾸려면 세션 안에서 /login을 입력합니다.
터미널이 낯설다면 데스크톱 앱이나 VS Code·JetBrains 확장으로 시작해도 됩니다. 브라우저에서 쓰는 방식은 Claude Code 웹 버전 출시 글에 정리해 두었습니다.
5. 클로드 코드로 하는 첫 작업
5.1. 고치기 전에 먼저 묻기
빠른 시작 문서는 처음에 프로젝트가 어떤 일을 하는지 물어보라고 권합니다. Claude Code는 필요한 파일을 알아서 읽으므로 파일을 직접 붙여 넣을 필요가 없습니다.
what does this project do?: 프로젝트가 하는 일을 요약where is the main entry point?: 실행이 시작되는 파일 찾기explain the folder structure: 폴더 구조 설명
한국어로 물어도 됩니다. 문서에서도 증상과 위치를 구체적으로 적어야 결과가 좋다고 안내합니다. “버그 수정”보다 “잘못된 비밀번호를 넣으면 빈 화면이 뜨는 로그인 버그 수정”이 낫다는 뜻입니다.
5.2. 첫 코드 변경과 권한 확인
add a hello world function to the main file처럼 작은 수정부터 맡겨 봅니다. 파일을 바꾸기 전에 변경 내용을 보여 주고 확인을 요청하면 Yes로 승인합니다. 어디까지 묻지 않고 진행할지는 권한 모드가 정합니다. Shift+Tab을 누를 때마다 모드가 바뀝니다. 처음에는 하나씩 승인하면서 무엇을 고치는지 지켜보는 편이 안전합니다.
5.3. /init으로 CLAUDE.md 만들기
명령 참조 문서는 저장소에서 처음 세션을 열었을 때 /init으로 CLAUDE.md를 만들고 /memory로 다듬으라고 권합니다. 빌드 명령, 코드 규칙처럼 매번 설명하던 내용을 이 파일에 적어 두면 다음 세션부터 따로 말하지 않아도 됩니다. Git 작업도 what files have I changed?, commit my changes with a descriptive message처럼 말로 맡길 수 있습니다.
6. 클로드 코드 기본 명령 정리
명령마다 입력할 곳이 다릅니다. 셸 명령은 터미널에, 세션 명령은 Claude Code 세션 안에 입력합니다. 아래 표는 빠른 시작 문서의 필수 명령에 이 맥에서 claude --help로 직접 확인한 옵션 설명을 더한 것입니다.
| 입력하는 곳 | 명령 | 하는 일 |
|---|---|---|
| 터미널 | claude | 대화형 세션 시작 |
| 터미널 | claude "task" | 첫 요청을 넣고 세션 시작 |
| 터미널 | claude -p "query" | 한 번 답하고 종료(파이프에 쓰기 좋음) |
| 터미널 | claude -c | 현재 폴더의 가장 최근 대화 이어 가기 |
| 터미널 | claude -r | 이전 대화를 골라 재개 |
| 터미널 | claude --model sonnet | 모델을 별칭(sonnet, opus 등)으로 지정 |
| 세션 안 | /help | 사용할 수 있는 명령 보기 |
| 세션 안 | /clear | 대화 기록 지우기 |
| 세션 안 | /usage | 사용량 확인(/cost도 같은 명령) |
| 세션 안 | /exit 또는 Ctrl+D 두 번 | 종료 |
claude --help 출력에는 update(업데이트 확인과 설치), doctor(설치 점검), mcp(MCP 서버 관리), plugin(플러그인 관리) 같은 하위 명령도 함께 나옵니다. 처음 쓸 때는 위 표에 나온 명령만 알아도 됩니다.
마무리
클로드 코드 설치는 macOS·Linux·WSL이면 curl -fsSL https://claude.ai/install.sh | bash, Windows면 PowerShell의 irm 명령 한 줄이면 됩니다. 새 창에서 claude --version으로 확인한 뒤 프로젝트 폴더에서 claude를 실행하고 로그인하세요. 로그인에는 Pro 이상 유료 플랜이나 Console 계정이 필요합니다. 첫 작업은 프로젝트 설명을 묻는 질문으로 시작하고 수정은 작은 것부터 하나씩 승인해 보세요.
자주 묻는 질문
무료 계정으로 클로드 코드를 쓸 수 있나요?
설치는 되지만 로그인 단계에서 쓸 수 없습니다. 공식 설치 문서에 무료 claude.ai 플랜에는 Claude Code 액세스가 포함되지 않는다고 적혀 있습니다. Pro 이상 구독이나 선불 크레딧을 쓰는 Console 계정이 필요합니다.
설치한 뒤 업데이트는 직접 해야 하나요?
네이티브 설치 프로그램으로 설치했다면 백그라운드에서 자동으로 업데이트되고 다음 실행 때 적용됩니다. Homebrew, WinGet, apt, dnf, apk로 설치했다면 자동 업데이트가 기본으로 꺼져 있어 각 패키지 관리자의 업그레이드 명령을 직접 실행해야 합니다.
Node.js를 먼저 설치해야 하나요?
권장 방식인 네이티브 설치에는 Node.js가 필요 없습니다. npm으로 설치할 때만 Node.js 22 이상이 필요하고, 설치된 claude 실행 파일 자체는 Node를 쓰지 않습니다.
참고한 공식 자료
- Claude Code Docs: 고급 설정(시스템 요구사항, 설치, 업데이트)
- Claude Code Docs: 빠른 시작
- Claude Code Docs: 설치 및 로그인 문제 해결
- Claude Code Docs: 명령 참조
- Claude Code 제품 페이지
- Claude 플랜 및 요금제
 | AX 100배의 법칙 – 나와 조직의 능력을 100배 높이는 AI 경영의 실제 도서 구매 |
함께 읽으면 좋은 글:
디지털 트랜스포메이션: 조직의 습관을 바꾸는 일, 도서 구매
